跳到主要内容

AOVIS Production Deploy SOP

This document is the formal release baseline for aovis.app.

It exists to stop the same class of deployment failures from recurring:

  • local code, Git, VM code, and live HTML drifting apart
  • tar/scp deployments bypassing Git as the release source
  • AI tools shipping unrelated changes together
  • successful builds that still leave old live HTML online
  • SEO, metadata, schema, canonical, and content changes going live without truth verification

1. Single Source of Truth​

The only valid production release source is a Git commit that exists on the remote repository.

Rules:

  • Do not deploy from uncommitted local changes.
  • Do not treat a local directory as release-ready unless the exact commit is pushed.
  • Do not use scp, tar archives, or ad hoc file sync as the primary release source.
  • If a hotfix must be applied on the VM, it must be committed back into Git immediately after stabilization.

Production release identity is:

  • repository
  • branch
  • commit hash

Every deployment must explicitly record:

  • branch name
  • full commit hash
  • target VM path
  • build result
  • PM2 restart result
  • live verification result

2. Pre-Deployment Checklist​

Before any release:

  1. Working tree must be clean.
  2. Release commit must be pushed to remote.
  3. npm run build must pass locally.
  4. Scope check must be run.
  5. High-risk paths must be reviewed explicitly.
  6. Release commit hash must be written into the deployment log / operator notes.

Use:

npm run deploy:preflight
npm run deploy:scope-check

Optional manifest-driven scope review:

npm run deploy:scope-check -- --manifest deploy/release-manifest.example.json

3. Standard Release Flow​

Default operator entrypoint:

pnpm release:prod

This command is intentionally not a black box:

  • it runs preflight
  • it runs scope-check
  • it prints the exact manual VM deploy sequence
  • it can run live verification afterward

Useful variants:

pnpm release:prod -- --prepare-only
pnpm release:prod -- --verify-only
pnpm release:prod -- --manifest deploy/release-manifest.example.json

For the current GCP VM deployment path, the standard release flow is:

  1. Complete local changes.
  2. Run npm run deploy:preflight.
  3. Run npm run deploy:scope-check.
  4. Commit and push the exact release commit to origin/main.
  5. Connect to the VM using gcloud compute ssh from the operator workstation.
  6. Pull the exact Git commit on the VM.
  7. Run install/build/generate steps on the VM.
  8. Restart PM2.
  9. Run live verification against https://aovis.app.

Recommended VM commands:

gcloud compute ssh aovis-store-staging-vm --zone us-west1-c --project aovis-site-1 --command 'cd /opt/aovis/aovis-store-staging && git fetch origin && git pull origin main && npm install && npx prisma generate && npm run build && pm2 restart aovis-store-staging --update-env'

If you are already inside the VM shell, use:

cd /opt/aovis/aovis-store-staging
git fetch origin
git rev-parse HEAD
git pull origin main
npm install
npx prisma generate
npm run build
pm2 restart aovis-store-staging --update-env

Then run from local or any machine with network access:

npm run deploy:verify

Or use the unified verification phase:

pnpm release:prod -- --verify-only

4. Prohibited Deployment Behavior​

These actions are not part of the release baseline:

  • deploying from uncommitted local edits
  • bulk overwriting VM code with tar/scp as the primary release source
  • using git add . without checking deployment scope
  • deploying while the working tree is dirty
  • shipping unrelated admin / DB / auth / SEO changes in a narrow UI task without explicit review
  • assuming npm run build means the live HTML is updated
  • overwriting /opt/aovis/aovis-store-staging/.env.production

The VM env file is a protected runtime secret file and is not part of code deployment.

4.1 External Tooling SSH Rule​

External AI tools and automation runners must follow the same deployment path as human operators:

  • use gcloud compute ssh aovis-store-staging-vm --zone us-west1-c --project aovis-site-1
  • do not guess or request the operator workstation SSH private key path
  • do not depend on a preloaded SSH agent on the automation host
  • do not substitute a handwritten ssh user@host command unless the operator explicitly provides that path
  • if gcloud compute ssh is unavailable, stop and ask the operator rather than inventing a different authentication method

The only acceptable local private key reference in the current operator environment is the Google Compute Engine key at:

  • /Users/guorui/.ssh/google_compute_engine

That path is for the operator workstation only. It is not a VM-side deploy key and should not be treated as a generic automation secret.

5. Scope Control​

Every release must answer:

  • what task is being shipped
  • which paths are expected to change
  • whether high-risk paths changed

Use npm run deploy:scope-check before every release.

High-risk path categories include:

  • app/robots.ts
  • app/sitemap.ts
  • prisma/
  • auth.ts
  • lib/auth-config.ts
  • lib/apple-client-secret.ts
  • app/admin/
  • payment / checkout / webhook routes
  • deployment / infra / PM2 / docs-vm files

If a release is meant to be narrow, use a manifest to define allowed paths. A warning means:

  • the release may be valid, but it is no longer a narrow-scope deploy
  • the operator must consciously accept the wider release

6. Post-Deploy Truth Verification​

Build success is not enough.

After every deployment, the live site must be verified against real HTML from https://aovis.app.

Required checks:

  • / returns 200
  • /robots.txt returns 200
  • /sitemap.xml returns 200
  • key public pages return 200
  • each key page has a canonical on https://aovis.app
  • title and description exist
  • expected content fragments exist
  • banned old fragments do not remain
  • FAQ schema still exists on FAQ page
  • Product JSON-LD is still absent on product page
  • Organization and WebSite schema remain present on the homepage

Use:

npm run deploy:verify

7. Rollback Principle​

Rollback is preferred when:

  • the live site is materially broken
  • the release changed more than intended
  • live verification fails on core pages
  • PM2 is running but the live HTML is not the expected version

Rollback is not “keep editing on the server”.

Rollback procedure:

  1. Identify the last known good commit.
  2. On the VM:
cd /opt/aovis/aovis-store-staging
git fetch origin
git checkout <known-good-commit>
npm install
npx prisma generate
npm run build
pm2 restart aovis-store-staging --update-env
  1. Run live verification again.
  2. Only resume forward-fixes after the site is stable.

If the issue is a bad release and not a runtime-only secret problem, rollback first and debug second.

8. Hotfix Rule​

A hotfix may move faster, but it still must follow these minimum rules:

  • branch/commit must be explicit
  • scope check must still run
  • local build must still pass
  • VM deploy must still come from Git
  • live verification must still run after restart

Hotfixes may shorten discussion, but they may not skip release identity or truth verification.

9. AI Tool Release Rules​

Any AI tool operating in this repo must follow this deployment contract:

  1. Never assume local edits are deployable until committed and pushed.
  2. Never bulk sync the repo onto the VM as the primary release method.
  3. Never overwrite .env.production.
  4. Always run preflight before claiming “ready to deploy”.
  5. Always run scope check before claiming “safe to deploy”.
  6. Always run live verification before claiming “live”.
  7. When a task is narrow, explicitly surface high-risk out-of-scope changes.

10. Current VM Usage Notes​

Current production target:

  • host: GCP VM
  • path: /opt/aovis/aovis-store-staging
  • process: aovis-store-staging
  • public origin: https://aovis.app

Use docs/vm-deploy.md for VM-specific operational details. Use this SOP for release discipline and truth verification.