backend-production-deploy

后端生产部署 SOP

本 skill 蒸馏自实际生产经验，覆盖 NestJS + Prisma + PM2 + Nginx 的标准部署链路。所有 <PLACEHOLDER> 在新项目落地前需替换为真实值（建议放到 scripts/deploy-backend.sh 顶部变量段）。

强约束（不可违反）

1. 未经用户明确同意，禁止任何对生产的写操作 — rsync 上传 / pm2 restart / prisma db push / npm install / .env 修改 / nginx reload / 写生产 uploads 都属于"写操作"。本地代码完善随时可做，部署前必须 ask & wait。
2. 生产 .env 永远不被覆盖 — 只允许"追加缺失键"，禁止 rsync 同步 .env*。
3. dry-run 先于正式 rsync — 任何代码同步前先跑 rsync -n --itemize-changes 看实际要传的文件清单，向用户确认无意外。
4. uploads 必须双向补齐 — 本地与生产共享数据库但分别本地磁盘存上传文件，任意一方生成图片对方就 404；必须 --ignore-existing 双向 rsync。
5. buildNumber 重用风险 — 触发部署的客户端版本如果牵涉 iOS/Android，参考 ios-app-store skill 的版本号纪律。

6 步标准 SOP

1. git status --short            # 摸底：本次涉及哪些文件
2. rsync -n（dry-run）            # 看实际要传什么；用户审核
3. rsync 正式上传                 # 排除 .env / node_modules / uploads / dist / logs / ...
4. uploads 双向补齐               # remote→local，再 local→remote，都 --ignore-existing
5. 远程：npm install / db push / build / pm2 restart --update-env
6. 健康检查：curl 内网 + 外网 + pm2 logs 末 60 行无 error

每步对应模板见下文。

---

1. 配置变量（写在 scripts/deploy-backend.sh 顶部）

SSH_KEY="${SSH_KEY:-<SSH_KEY_PATH>}"          # 例：/tmp/prod_server_key
REMOTE_HOST="<REMOTE_USER>@<PROD_HOST>"        # 例：[email protected]
REMOTE_PATH="<REMOTE_PROJECT_PATH>"            # 例：/www/wwwroot/server
LOCAL_PATH="<LOCAL_PROJECT_PATH>/server"        # 例：/Users/me/code/myapp/server
PM2_APP_NAME="<PM2_APP_NAME>"                  # 例：myapp-api
PROD_DOMAIN="<PROD_DOMAIN>"                    # 例：myapp.com

校验：

if [[ ! -f "$SSH_KEY" ]]; then
  echo "❌ SSH 密钥不存在: $SSH_KEY"; exit 1
fi
chmod 600 "$SSH_KEY" 2>/dev/null || true

---

2. dry-run 模板（read-only，让用户先审）

rsync -avzn --itemize-changes -e "ssh -i $SSH_KEY -o StrictHostKeyChecking=no" \
  --exclude ".env" \
  --exclude ".env.*" \
  --exclude "*.backup-*" \
  --exclude ".DS_Store" \
  --exclude "node_modules/" \
  --exclude "dist/" \
  --exclude "coverage/" \
  --exclude "logs/" \
  --exclude "uploads/" \
  --exclude "keys/" \
  --exclude "scripts/rembg-env/" \
  --exclude "prisma/dev.db" \
  --exclude "prisma/test.db" \
  --exclude "prisma/prisma/" \
  --exclude "src/h5/public/downloads/*.apk" \
  --exclude "src/h5/public/downloads/*.aab" \
  "$LOCAL_PATH/" \
  "$REMOTE_HOST:$REMOTE_PATH/"