Production Release Checklist

小虾 SaaS 生产发布前必须逐项确认。本清单用于首次生产 Alembic 接入和后续 v* tag 发布。

1. 发布前冻结

确认目标 commit 已在 develop 部署到 staging，并完成 smoke。
确认 staging /health healthy。
确认 staging alembic_version 等于当前 head。
确认 CI validate job 通过：format、lint、Bandit、Alembic offline SQL、schema metadata drift、pytest。
确认没有未提交的 schema 变更：models、Alembic revision、schema snapshot 必须一起提交。

2. 生产环境检查

/var/lib/xiaoxia-saas-production/.env 存在且权限正确。
APP_ENV=production。
DEBUG=false。
AUTO_CREATE_SCHEMA=false。
JWT_SECRET_KEY 已替换为生产强密钥。
DATABASE_URL 指向生产数据库。
REDIS_URL 指向生产 Redis。
OSS 配置已确认或明确保持本地 fallback。
GENERATED_FILES_HOST_DIR 生产环境不得指向 staging 目录。
本地校验文件：python scripts/validate_release_env.py /var/lib/xiaoxia-saas-production/.env --strict-external。
容器内校验已注入环境：docker exec xiaoxia-api-production python /app/scripts/validate_release_env.py --from-environ --strict-external。
外部服务 smoke：docker exec xiaoxia-api-production python /app/scripts/smoke_external_services.py --strict。
SMTP 真发信 smoke：docker exec xiaoxia-api-production python /app/scripts/smoke_external_services.py --strict --send-email-to <测试邮箱>。
如开启邮件/session：
- ENABLE_EMAIL_DELIVERY=true 前先验证 SMTP 凭证。
- ENABLE_REDIS_SESSIONS=true 前先验证 Redis 连通性。

3. 数据库备份

生产 Alembic 升级前必须创建数据库备份。优先使用脚本：

BACKUP_ROOT=/root/xiaoxia-backups \
POSTGRES_CONTAINER=xiaoxia-postgres \
POSTGRES_USER=xiaoxia \
POSTGRES_DB=xiaoxia_saas \
scripts/backup_postgres.sh

脚本会输出备份目录，并写入 manifest.txt 与 alembic_version.txt。

手动等价命令：

BACKUP_DIR=/root/xiaoxia-backups/$(date +%Y%m%d-%H%M%S)
mkdir -p "$BACKUP_DIR"
docker exec xiaoxia-postgres pg_dump -U xiaoxia -d xiaoxia_saas -Fc > "$BACKUP_DIR/xiaoxia_saas.dump"
docker exec xiaoxia-postgres psql -U xiaoxia -d xiaoxia_saas -Atc 'select version_num from alembic_version;' > "$BACKUP_DIR/alembic_version.txt" 2>/dev/null || true

确认备份非空：

test -s "$BACKUP_DIR/xiaoxia_saas.dump"
ls -lh "$BACKUP_DIR"

4. 首次 Alembic 接入判断

发布前只读检查生产库状态：

docker exec xiaoxia-api-production python /app/scripts/alembic_preflight.py

也可手动检查：

docker exec xiaoxia-postgres psql -U xiaoxia -d xiaoxia_saas -Atc "select to_regclass('public.alembic_version');"
docker exec xiaoxia-postgres psql -U xiaoxia -d xiaoxia_saas -Atc "select count(*) from pg_tables where schemaname='public' and tablename != 'alembic_version';"

脚本 recommended_action 判断规则：

已存在 alembic_version：执行 alembic upgrade head。
有业务表但没有 alembic_version：先执行 alembic stamp head，再执行 alembic upgrade head。
空库：执行 alembic upgrade head。

生产首次接入不允许使用 Base.metadata.create_all() 或历史 SQL 快照。

5. 发布执行

只能通过 v* tag 触发 production deploy。
发布期间持续观察 Gitea Actions deploy log。
部署后确认：

curl -fsS http://127.0.0.1:8000/health
docker ps --format '{{.Names}} {{.Status}}' | grep xiaoxia
docker exec xiaoxia-postgres psql -U xiaoxia -d xiaoxia_saas -Atc 'select version_num from alembic_version;'

6. Smoke 测试

生产发布后至少验证：

/health 返回 healthy。
注册/登录//auth/me 正常。
创建 workspace 正常。
核心视频生成链路可创建任务。
生成文件下载 URL 返回真实文件，不返回前端 HTML fallback。

7. 回滚策略

生成恢复计划（不会自动恢复数据库）：

scripts/restore_postgres_plan.sh /root/xiaoxia-backups/<backup-dir>

应用回滚：

若数据库未发生不可逆迁移，优先回滚到上一稳定 tag 并重新部署。
保留当前失败容器日志后再回滚。

数据库回滚：

Alembic downgrade 只有在 revision 明确支持且已验证时才能执行。
首次生产接入阶段默认使用备份恢复作为最终兜底。
恢复前必须二次确认备份路径、目标数据库、停机窗口。
恢复步骤必须先由 scripts/restore_postgres_plan.sh 生成并复核，不允许紧急状态下即兴拼命令。

8. 发布记录

每次生产发布后，在 docs/PHASE7-PROGRESS.md 或对应 release note 记录：

tag
commit
Alembic before/after version
backup path
smoke 结果
回滚是否需要/是否执行

4.8 KiB Raw Blame History Unescape Escape