XQKqueue/docs/backend-production-handoff.md

后端与数据库上线交接

本文件只描述应用/数据库基础交接，不替代运维团队的 Kubernetes、PostgreSQL、Redis、密钥和备份实施方案。

已实现的应用基础

• PostgreSQL 迁移使用嵌入式版本化 SQL、advisory lock 和 checksum 校验。
• 生产 API 不允许通过 MIGRATE_ON_START=true 自行执行 DDL；使用独立的 /usr/local/bin/migrate 迁移容器命令。
• 数据库连接池可由环境变量调节：DB_MAX_OPEN_CONNS、DB_MAX_IDLE_CONNS、DB_CONN_MAX_IDLE_TIME、DB_CONN_MAX_LIFETIME。
• 后台清理任务使用 PostgreSQL advisory lock，在多 Pod 下只允许一个清理事务执行；清理个人关联、过期幂等键、过期会话和超过保留期的审计记录。
• 手机号和姓氏仍以加密字段保存；清理后只保留不含个人信息的排队事实，公共状态页不再返回尾号。
• make test-db 使用临时 PostgreSQL 验证迁移幂等、清理约束和清理事务；make smoke-real 验证真实 API/数据库链路和隐私投影。

API Pod 的生产环境变量

生产环境至少需要通过外部 Secret/KMS 注入：

APP_ENV=production
DATABASE_URL=postgresql://...?...&sslmode=verify-full
DATA_ENCRYPTION_KEY_BASE64=<32-byte base64>
PHONE_HMAC_KEY_BASE64=<32-byte base64>
SESSION_COOKIE_SECURE=true
MIGRATE_ON_START=false
MAINTENANCE_INTERVAL=1h
MAINTENANCE_BATCH_SIZE=500

DATABASE_URL 必须使用 require、verify-ca 或 verify-full 之一；生产 API 会拒绝 sslmode=disable 和 MIGRATE_ON_START=true。

Kubernetes 发布顺序

1. 运维先执行数据库迁移 Job，容器命令为 /usr/local/bin/migrate。
2. 迁移成功后，通过一次性 Secret 执行 /usr/local/bin/bootstrap-admin 设置受保护管理员密码。
3. 密码设置成功后再滚动更新 API Deployment。
4. API Deployment 使用 MIGRATE_ON_START=false，通过 /readyz 检查数据库连通性和已应用迁移版本。
5. Redis 地址、TLS 和认证由运维接入；当前代码仍保留进程内事件降级，不能把进程内广播当作跨 Pod 事件总线。
6. PostgreSQL 的 PITR、加密备份、RPO ≤ 5 分钟、RTO ≤ 30 分钟和恢复演练由运维负责并记录结果。

禁止事项

• 生产环境不得运行 make seed 或 scripts/seed.sh。
• 不得把 server/.env、数据库 URL、数据密钥或 Redis 凭据写入镜像、Git 或普通 ConfigMap。
• 迁移失败时禁止强行启动 API；应保留旧版本并按运维回滚流程处理。