brother7
c2a5281534
问题：移动网络共享出口 IP 会造成游客取号被误限流。 实现：移除公开取号 IP 限制，改用项目总量与手机号 HMAC 限流，并支持 Retry-After 倒计时。
58 lines
3.7 KiB
Markdown
58 lines
3.7 KiB
Markdown
# 后端与数据库上线交接
|
||
|
||
本文件只描述应用/数据库基础交接，不替代运维团队的 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 注入：
|
||
|
||
```text
|
||
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
|
||
PUBLIC_TICKET_PROJECT_LIMIT=1000
|
||
PUBLIC_TICKET_PHONE_LIMIT=5
|
||
PUBLIC_TICKET_RATE_WINDOW=1m
|
||
```
|
||
|
||
`DATABASE_URL` 必须使用 `require`、`verify-ca` 或 `verify-full` 之一；生产 API 会拒绝 `sslmode=disable` 和 `MIGRATE_ON_START=true`。
|
||
|
||
游客取号不按客户端 IP 拒绝请求，而是按项目总量和“项目 + 手机号 HMAC”限流。当前实现为单 Pod 进程内计数；如果 API 扩为多 Pod 且要求全局一致阈值，需要接入共享限流存储。手机号明文不得写入限流键、日志或外部缓存。
|
||
|
||
## 结构化接口日志
|
||
|
||
- 关键业务 API 的 `http request` 日志包含 `request`、`response`、状态码、耗时和 `request_id`；JSON 正文单向最多记录 64 KiB，超过后只记录字节数与 `body_truncated=true`。
|
||
- 手机号只保留后四位；账号名脱敏；密码、姓名/称谓、Cookie、Authorization、Token、内嵌私密链接及 Idempotency-Key 原值不得写入日志。
|
||
- 访客状态和公示屏请求使用路由模板记录路径，不记录真实 Token。
|
||
- SSE `/api/events` 与历史 CSV 导出不记录响应正文；CSV 可能包含个人信息，只记录请求筛选、状态码和正文省略原因。
|
||
- Ingress/Nginx 的 access log 也必须使用路由模板或关闭上述 Token 路径的 URI 记录，应用内脱敏无法清理上游代理已经写出的原始 URI。
|
||
|
||
## 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；应保留旧版本并按运维回滚流程处理。
|