# 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 升级前必须创建数据库备份：

```bash
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
```

确认备份非空：

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

## 4. 首次 Alembic 接入判断

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

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

也可手动检查：

```bash
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。
- 部署后确认：

```bash
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 结果
- 回滚是否需要/是否执行