Xiaoxia AI
119 lines
4.4 KiB
Markdown
119 lines
4.4 KiB
Markdown
# 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 结果
|
||
- 回滚是否需要/是否执行
|