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_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-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';"

判断规则：

已存在 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. 回滚策略

应用回滚：

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

数据库回滚：

Alembic downgrade 只有在 revision 明确支持且已验证时才能执行。
首次生产接入阶段默认使用备份恢复作为最终兜底。
恢复前必须二次确认备份路径、目标数据库、停机窗口。
恢复步骤需按生产数据库实际容器名、DB 名、volume 策略另写一次性 runbook；不要在紧急状态下即兴拼命令。

8. 发布记录

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

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

4.3 KiB Raw Blame History Unescape Escape