Document local database production deployment

2026-04-28 09:04:03 +08:00
parent 8697aa3fbb
commit 21cb5c9c15
5 changed files with 252 additions and 12 deletions
@@ -2,6 +2,8 @@

 This runbook is the source of truth for taking the Eversolo Payload/Next.js site from a local database and media folder to a production deployment.

+For the command-level Chinese handoff guide, see `docs/local-db-to-production-deployment.md`.
+
 ## Release Inputs

 - Git commit to deploy.
@@ -28,16 +30,23 @@ Optional variables:

 ## Deployment Steps

-1. Restore the approved PostgreSQL dump into the production database.
-2. Copy `media/` and `files/` to the production persistent upload volume.
-3. Install dependencies with `npm ci`.
-4. Run `npm run generate:types` only during build validation, not as a production data mutation step.
-5. Run `npm run typecheck`.
-6. Run `npm run build`.
-7. Run `npm run payload:migrate`.
-8. Run `npm run payload:migrate:status` and confirm every migration is `Yes`.
-9. Start the app with `npm run start`.
-10. Run `npm run smoke -- "$NEXT_PUBLIC_SITE_URL"`.
+1. Run local release checks: `npm run lint`, `npm run typecheck`, `npm run build`, and `npm run payload:migrate:status`.
+2. Load the local release environment with `set -a; source .env; set +a`, then confirm the local release database has no dev marker:
+   `psql "$DATABASE_URI" -Atc "select count(*) from payload_migrations where batch = -1;"`.
+3. Export the approved PostgreSQL database:
+   `pg_dump --format=custom --no-owner --no-acl --file=eversolo.payload.dump "$DATABASE_URI"`.
+4. Export matching uploads:
+   `tar -czf eversolo.uploads.tgz media files`.
+5. Restore the approved PostgreSQL dump into the production database with `pg_restore --no-owner --no-acl`.
+6. Copy `media/` and `files/` to the production persistent upload volume.
+7. Install dependencies with `npm ci`.
+8. Run `npm run generate:types` only during build validation, not as a production data mutation step.
+9. Run `npm run typecheck`.
+10. Run `npm run build`.
+11. Run `npm run payload:migrate`.
+12. Run `npm run payload:migrate:status` and confirm every migration is `Yes`.
+13. Start the app with `npm run start`.
+14. Run `npm run smoke -- "$NEXT_PUBLIC_SITE_URL"`.

 ## Data Rules

@@ -0,0 +1,227 @@
+# 本地数据库导线上部署文档
+
+这份文档用于把当前本地 Payload/Next.js 站点完整搬到线上：代码、PostgreSQL 数据库、`media/` 图片库、`files/` 下载文件必须来自同一次导出。
+
+## 1. 上线前原则
+
+- 线上只使用迁移，不使用 schema push。
+- 线上启动不自动跑迁移，迁移必须作为单独发布步骤执行。
+- 本地导出的数据库和 `media/`、`files/` 目录必须成套，不要混用不同时间点的文件。
+- 导入线上后不要再跑 seed 脚本，seed/backfill 只应该在本地确认好，再随数据库 dump 一起带上去。
+- 如果启动或迁移时出现删除旧表、schema push、交互确认提示，先停止，不要继续确认。
+
+## 2. 线上环境变量
+
+线上 `.env` 至少需要：
+
+```bash
+NODE_ENV=production
+NEXT_PUBLIC_SITE_URL=https://www.eversolo.com
+PAYLOAD_SECRET=<用 openssl rand -base64 48 生成的长随机字符串>
+DATABASE_URI=postgres://<user>:<password>@<host>:5432/<database>
+PAYLOAD_DB_PUSH=false
+PAYLOAD_RUN_MIGRATIONS_ON_START=false
+```
+
+说明：
+
+- `PAYLOAD_SECRET` 不能用示例值，也不能和本地随便共用短值。
+- `PAYLOAD_DB_PUSH=false` 是为了避免 Payload 用当前 schema 直接改库。
+- `PAYLOAD_RUN_MIGRATIONS_ON_START=false` 是为了避免应用启动时弹迁移交互提示，迁移改用 `npm run payload:migrate` 手动执行。
+
+## 3. 本地导出前检查
+
+在本地项目目录执行：
+
+```bash
+set -a
+source .env
+set +a
+
+git status --short
+npm run lint
+npm run typecheck
+npm run build
+npm run payload:migrate:status
+```
+
+检查本地数据库里不能有 Payload dev schema push 标记：
+
+```bash
+psql "$DATABASE_URI" -Atc "select count(*) from payload_migrations where batch = -1;"
+```
+
+期望输出是：
+
+```text
+0
+```
+
+如果不是 `0`，说明这个库还带有开发期 schema push 记录。不要导出这个库去线上，先在本地对齐迁移状态后再导出。
+
+建议再跑一次本地 smoke：
+
+```bash
+npm run smoke -- http://localhost:3221
+```
+
+## 4. 导出本地数据库和上传目录
+
+在本地项目目录执行：
+
+```bash
+EXPORT_DIR="release-exports/$(date +%Y%m%d-%H%M%S)"
+mkdir -p "$EXPORT_DIR"
+
+pg_dump \
+  --format=custom \
+  --no-owner \
+  --no-acl \
+  --file="$EXPORT_DIR/eversolo.payload.dump" \
+  "$DATABASE_URI"
+
+tar -czf "$EXPORT_DIR/eversolo.uploads.tgz" media files
+
+shasum -a 256 "$EXPORT_DIR/eversolo.payload.dump" "$EXPORT_DIR/eversolo.uploads.tgz" \
+  > "$EXPORT_DIR/SHA256SUMS.txt"
+```
+
+导出目录里应该有：
+
+```text
+eversolo.payload.dump
+eversolo.uploads.tgz
+SHA256SUMS.txt
+```
+
+把整个目录传到服务器，例如：
+
+```bash
+rsync -av "$EXPORT_DIR/" deploy@your-server:/srv/eversolo-release/
+```
+
+## 5. 线上恢复数据库
+
+在服务器上进入发布目录，先确认校验和：
+
+```bash
+cd /srv/eversolo-release
+shasum -a 256 -c SHA256SUMS.txt
+```
+
+恢复到线上 PostgreSQL。
+
+如果是新空库：
+
+```bash
+pg_restore \
+  --no-owner \
+  --no-acl \
+  --dbname "$DATABASE_URI" \
+  eversolo.payload.dump
+```
+
+如果是替换已有测试库或预发布库，并且你已经确认可以清掉旧数据：
+
+```bash
+pg_restore \
+  --clean \
+  --if-exists \
+  --no-owner \
+  --no-acl \
+  --dbname "$DATABASE_URI" \
+  eversolo.payload.dump
+```
+
+恢复后检查迁移标记：
+
+```bash
+psql "$DATABASE_URI" -Atc "select count(*) from payload_migrations where batch = -1;"
+npm run payload:migrate:status
+```
+
+`batch = -1` 应该是 `0`，`payload:migrate:status` 应该显示迁移已应用。若代码里有比 dump 更新的迁移，再执行：
+
+```bash
+npm run payload:migrate
+npm run payload:migrate:status
+```
+
+## 6. 线上恢复媒体文件
+
+在服务器应用目录或持久化上传卷目录执行：
+
+```bash
+tar -xzf /srv/eversolo-release/eversolo.uploads.tgz -C /srv/eversolo-app/
+```
+
+如果线上使用单独的持久化 volume，把解压后的目录同步到 volume：
+
+```bash
+rsync -a --delete /srv/eversolo-app/media/ /srv/eversolo-uploads/media/
+rsync -a --delete /srv/eversolo-app/files/ /srv/eversolo-uploads/files/
+```
+
+确认应用运行时能从项目根目录或挂载目录访问：
+
+```text
+media/
+files/
+```
+
+数据库里 media/files 记录只保存文件名和元数据，文件本体必须在对应目录里。
+
+## 7. 构建和启动
+
+在服务器应用目录执行：
+
+```bash
+npm ci
+npm run typecheck
+npm run build
+npm run payload:migrate
+npm run payload:migrate:status
+npm run start
+```
+
+如果使用 PM2/systemd/Docker，由进程管理器执行 `npm run start`，但迁移步骤仍然要在启动前单独跑。
+
+健康检查：
+
+```bash
+curl -f "$NEXT_PUBLIC_SITE_URL/api/health"
+npm run smoke -- "$NEXT_PUBLIC_SITE_URL"
+```
+
+重点人工打开：
+
+```text
+/en
+/zh
+/en/products/dmp-a10
+/en/reviews
+/en/reviews?tab=reviews
+/en/support
+/en/support/tutorial
+/en/dealers
+/admin
+```
+
+## 8. 回滚
+
+回滚要成套回滚：
+
+1. 切回上一版代码。
+2. 恢复上一版数据库 dump。
+3. 恢复上一版 `media/` 和 `files/`。
+4. 重新启动并跑 smoke。
+
+线上不要默认执行 down migration 作为回滚方式；生产回滚优先恢复上一套数据快照。
+
+## 9. 禁止操作
+
+- 不要在线上设置 `PAYLOAD_DB_PUSH=true`。
+- 不要在线上用 `PAYLOAD_MIGRATING=true` 当常规启动方式。
+- 不要把数据库 dump 和不同时间点的 `media/`、`files/` 混用。
+- 不要导入线上后再跑 `npm run seed:import` 覆盖编辑内容。
+- 不要在生产已经跑过某个迁移后修改同名迁移文件；需要新建 forward migration。
@@ -7,6 +7,7 @@ Use this checklist before every production deployment.
 - [ ] Working tree is clean.
 - [ ] Latest commit is the intended release commit.
 - [ ] `npm ci` succeeds from a clean install.
+- [ ] Legacy tutorial redirects point to `/en/support/tutorial`.
 - [ ] `npm run typecheck` passes.
 - [ ] `npm run build` passes.
 - [ ] `npm run payload:migrate:status` shows all migrations as `Yes` on the release database.
@@ -21,6 +22,7 @@ Use this checklist before every production deployment.
 - [ ] `PAYLOAD_DB_PUSH=false` is set.
 - [ ] `PAYLOAD_RUN_MIGRATIONS_ON_START=false` is set unless a one-off controlled migration boot is intentionally planned.
 - [ ] Upload directories `media/` and `files/` are persistent and backed up.
+- [ ] Database dump and upload archive are generated from the same local release window.

 ## CMS Data