docs(runbooks): add production db change runbook

This commit is contained in:
ximenchuifeng committed 2026-08-27 14:36:09 +08:00
1 parent 92fd12f1ed
commit 237e36516f
1 file changed
+309
+309
View File
@@ -0,0 +1,309 @@
# 生产数据库变更运行手册
> 适用环境:客户生产环境(如 mxlexus,namespace `mixingx`)。
> 决策依据:hub 仓库 `docs/adr/0074-per-service-release-and-two-phase-cd.md`(生产 DB 变更全人工,expand-contract 纪律)。
> 本手册随 `mixingx.deploy` 仓库 release 分支交付,执行时以现场拿到的版本为准。
## 0. 适用范围与铁律
| 服务 | 是否适用本手册 | 说明 |
|---|---|---|
| sso / ultra / agent | ✅ 适用 | .NET + EF Core,生产已关闭启动自动迁移,变更必须人工执行脚本 |
| audit | ❌ 不适用 | Node.js,自带幂等迁移 + advisory lock,启动时自动执行,无需人工 |
| edge | ❌ 不适用 | 数据在本地数据目录,不用 PostgreSQL |
| gateway | ❌ 不适用 | 无数据库 |
铁律(违反任何一条都可能造成生产事故):
1. **先库后应用**:先执行数据库脚本,确认成功后,再让客户在更新中心点「更新应用」。expand-contract 纪律保证新 schema 兼容旧应用,反着来则旧代码可能访问不到新结构。
2. **执行脚本前必先备份**,没有例外。
3. **一次只动一个服务**,不要并行开多个库操作。
4. **数据库通道用完立即关闭**,任何数据库端口不得常开。
5. **生产时段不动库**,与客户约定维护窗口。
## 1. 何时执行
更新中心里某个版本标记了「含数据库变更」,或发版通知中注明该服务带迁移脚本。未标记的版本不涉及本手册。
## 2. 准备
1. 获取迁移脚本(随版本交付,幂等,可重复执行):
```bash
git clone -b release https://gitee.com/mixing-tech/mixingx.deploy.git
cd mixingx.deploy/db-scripts
ls sso/ ultra/ agent/ # 按服务分目录,文件名即版本号,如 v1.0.4.sql
```
> 注:`db-scripts/` 由构建流水线生成(ADR-0074 实施阶段 2)。流水线改造完成前,脚本由开发随发版通知手动提供,后续流程相同。
2. 确认本次要执行的服务清单(可能只有一个,如 `sso/v1.0.4.sql`)。
3. 运维机器要求:能 `kubectl` 访问客户集群(kubeconfig 已配好);有 `psql`/`pg_dump` 客户端(PostgreSQL 17),或用下文「kubectl exec 变体」免除客户端安装。
## 3. 流程一:开启数据库通道
数据库 Service 命名规律:`<release名>-postgres-service`。先发现实际名称:
```bash
kubectl -n mixingx get svc | grep postgres-service
# 预期看到(示例):
# mixingx-sso-postgres-service ClusterIP ... 5432/TCP
# mixingx-ultra-postgres-service ClusterIP ... 5432/TCP
# mixingx-agent-mxlexus-postgres-service ClusterIP ... 5432/TCP
```
开 NodePort(以 sso 为例):
```bash
kubectl -n mixingx patch svc mixingx-sso-postgres-service \
--type='json' -p='[{"op":"replace","path":"/spec/type","value":"NodePort"}]'
kubectl -n mixingx get svc mixingx-sso-postgres-service
# 记下端口映射,如 5432:31543/TCP → NodePort = 31543
```
取节点 IP:
```bash
kubectl get nodes -o wide # 任取一台节点的 INTERNAL-IP
```
连接信息即:`主机=<节点IP> 端口=<NodePort> 用户=postgres 密码=<见速查表> 数据库=<见速查表>`。
**变体(推荐用于纯命令行场景,不落集群状态)**:
```bash
kubectl -n mixingx port-forward svc/mixingx-sso-postgres-service 15432:5432
# 另开终端连接 localhost:15432;用毕 Ctrl+C 即关闭,跳过流程五
```
## 4. 流程二:备份(执行脚本前必做)
```bash
pg_dump -h <节点IP> -p <NodePort> -U postgres -Fc \
-d sso-db -f sso-db-$(date +%Y%m%d-%H%M)-pre-v1.0.4.dump
```
- 命名规则:`<库名>-<日期时间>-pre-<目标版本>.dump`。
- 保存位置:运维机器本地 + 一份拷出场外(U 盘/文件服务器),**每个库至少保留最近 3 份**。
- 恢复期间数据说明:恢复 = 回到备份时刻,备份之后的写入会丢。执行前向客户确认这一点。
## 5. 流程三:执行迁移脚本
```bash
psql -h <节点IP> -p <NodePort> -U postgres -d sso-db -v ON_ERROR_STOP=1 -f sso/v1.0.4.sql
```
- 脚本是幂等的(`--idempotent` 生成,自动跳过已应用的迁移),执行中断或重复执行都安全,直接重跑即可。
- `ON_ERROR_STOP=1`:遇错立即停止,不要带病继续。
- 多服务时逐个重复流程四→五,一次一个。
## 6. 流程四:验证
```bash
psql -h <节点IP> -p <NodePort> -U postgres -d sso-db \
-c 'select migration_id from "__EFMigrationsHistory" order by migration_id desc limit 3;'
```
- 最上面一条应是本次目标迁移(与发版通知中写明的一致)。
- 旧应用仍在运行,确认其无报错(expand-contract 保证兼容):
```bash
kubectl -n mixingx logs deploy/mixingx-sso --tail=50
```
## 7. 流程五:关闭通道
```bash
kubectl -n mixingx patch svc mixingx-sso-postgres-service \
--type='json' -p='[{"op":"replace","path":"/spec/type","value":"ClusterIP"}]'
```
验证已恢复 `ClusterIP` 后,通知客户:可以到更新中心点击该服务的「更新」。
## 8. 故障恢复(脚本执行失败或升级后异常)
1. 保持通道开启,停止对应应用(防止继续写入):
```bash
kubectl -n mixingx scale deploy/mixingx-sso --replicas=0
```
2. 用流程二的备份恢复:
```bash
pg_restore -h <节点IP> -p <NodePort> -U postgres -d sso-db \
--clean --if-exists sso-db-20260826-2200-pre-v1.0.4.dump
```
> `--clean` 会删现有对象,确认备份文件无误后再执行。不确定时先恢复到临时库核对。
3. 恢复应用副本数,验证启动正常。
4. 如镜像已更新,到更新中心点「回滚」回到上一同步版本。
5. 关闭通道,填写执行记录,事故上报 MixingX 支持。
> 本节是迁移失败场景的快速路径;完整的还原流程(确认项、验证、版本对齐)见第 11 节。
## 9. AI 协同执行约定
允许运维借助 AI 工具(Kimi Code、Claude Code 等)执行本手册,但必须遵守以下分层模型。**「生产 DB 操作人为主」原则不因 AI 介入而改变:AI 是领航员,人是手和责任人。**
### 9.1 三层权限模型
| 层级 | 范围 | AI 权限 |
|---|---|---|
| L1 只读发现 | `kubectl get/describe/logs`、`pg_restore -l`、各种 `SELECT` 查询 | AI 可直接执行并解读输出 |
| L2 可逆操作 | 开/关 NodePort、`pg_dump` 备份、`psql -f` 执行迁移脚本、流程四验证 | AI 生成填好参数的命令,**人逐条审阅后亲手执行**,输出贴回给 AI 解读 |
| L3 不可逆操作(红线) | `pg_restore --clean`、`scale --replicas=0`、删库/删表、任何写入数据的 DML | AI 只准分析和起草,**人独立核对参数后执行**,AI 不得催促、不得代按 |
### 9.2 执行参数块(每次执行前由人填写,AI 只准使用块内参数)
```yaml
customer: mxlexus # 客户名
namespace: mixingx # 目标 namespace
service: sso # 本次操作的服务:sso / ultra / agent
target_version: v1.0.4 # 目标版本(还原场景填备份对应版本)
db_name: sso-db # 数据库名
pg_service: mixingx-sso-postgres-service
dump_file: "" # 还原时必填:备份文件名,由人确认时间点后填写
```
### 9.3 确认门(AI 必须停下等人工确认)
1. 执行迁移脚本前:AI 复述「服务 / 库 / 脚本文件 / 目标版本」,人确认后才给命令;
2. 还原前:AI 复述「备份文件名 + 备份时间点 + 将丢失该时间点之后的数据」,人明确同意;
3. 任何命令输出与预期不符时:停止推进,分析后再继续,禁止跳过。
### 9.4 给 AI 的上下文提示词(复制即用,尖括号内容由人填写)
```text
你是 MixingX 生产数据库运维助手。请严格按 mixingx.deploy 仓库
docs/runbooks/db-change.md 执行操作,并遵守:
1. 环境:K8s namespace=<namespace>,服务=<service>,库=<db_name>,
PG Service=<pg_service>,目标版本=<target_version>。
2. 铁律:先备份后执行;先库后应用;一次只动一个服务;通道用完即关。
3. 权限:L1 只读命令你可直接执行;L2 命令你生成后必须由我亲手执行;
L3(pg_restore --clean、scale replicas=0、任何删改数据的操作)你只起草,
参数由我独立核对,你不得代执行。
4. 流程:先做 L1 发现(service/pod/节点/当前迁移版本)→ 列出完整操作计划
→ 逐条给 L2 命令并等我贴回输出 → 每个确认门停下等我确认。
5. 禁止编造任何参数;不确定就停下来问我。
```
## 10. 数据库备份操作手册(例行/独立)
适用:发版前备份(流程二的展开)、日常例行备份、客户索要的定期留档。
**关键认知:每个服务的 PostgreSQL 是独立实例(各自 StatefulSet),不存在"一个端口备份所有库"——每个库走自己的通道或自己的 Pod。**
### 10.1 备份清单
| 数据库 | 所在 StatefulSet | 说明 |
|---|---|---|
| `sso-db` | `mixingx-sso-postgres` | 必备 |
| `ultra-db` | `mixingx-ultra-postgres` | 必备 |
| `agent-db` | `mixingx-agent-<id>-postgres`(每实例一个) | 必备 |
| `audit-db` | `mixingx-audit-postgres` | 审计日志,系统内已按月分区并保留 6 个月;是否额外备份由客户合规要求决定 |
### 10.2 推荐方式:kubectl exec(无需开任何端口)
```bash
TS=$(date +%Y%m%d-%H%M)
kubectl -n mixingx get pods | grep postgres # 先发现实际 Pod 名
kubectl -n mixingx exec mixingx-sso-postgres-0 \
-- pg_dump -U postgres -Fc sso-db > sso-db-$TS.dump
kubectl -n mixingx exec mixingx-ultra-postgres-0 \
-- pg_dump -U postgres -Fc ultra-db > ultra-db-$TS.dump
kubectl -n mixingx exec mixingx-agent-mxlexus-postgres-0 \
-- pg_dump -U postgres -Fc agent-db > agent-db-$TS.dump
```
### 10.3 NodePort 方式(大库或需要 GUI 工具时)
按「流程一」逐服务开 NodePort,然后逐服务执行:
```bash
pg_dump -h <节点IP> -p <该服务的NodePort> -U postgres -Fc -d <db> -f <db>-$TS.dump
```
### 10.4 备份验证与保管
```bash
pg_restore -l sso-db-$TS.dump | head -20 # 能列出归档目录即为有效备份
```
- 命名:`<库名>-<日期时间>[-pre-<版本>].dump`。
- 保管:本地 + 场外各一份,每库至少保留最近 3 份;介质故障时备份即无效,场外副本不是可选项。
## 11. 数据库还原操作手册(独立)
适用:整库灾难恢复、误操作回退。**迁移脚本执行失败的快速恢复走第 8 节,本节是完整流程。**
### 11.1 还原前三个确认(缺一不可)
1. 客户书面/聊天记录认可:**恢复到哪个时间点**,并接受该时间点之后的数据丢失;
2. 备份文件有效:`pg_restore -l <dump文件> | head` 能列出内容;
3. 当前处于维护窗口,应用侧已知情。
### 11.2 还原步骤(以 sso-db 为例)
```bash
# 1. 停应用,防止恢复期间写入
kubectl -n mixingx scale deploy/mixingx-sso --replicas=0
# 2a. exec 方式恢复(推荐,无需开端口)
cat sso-db-20260826-2200-pre-v1.0.4.dump | kubectl -n mixingx exec -i mixingx-sso-postgres-0 \
-- pg_restore -U postgres -d sso-db --clean --if-exists
# 2b. 或 NodePort 方式(先按流程一开篇)
pg_restore -h <节点IP> -p <NodePort> -U postgres -d sso-db \
--clean --if-exists sso-db-20260826-2200-pre-v1.0.4.dump
# 3. 验证:表回来了、行数合理、迁移版本与备份一致
kubectl -n mixingx exec mixingx-sso-postgres-0 -- psql -U postgres -d sso-db \
-c 'select migration_id from "__EFMigrationsHistory" order by migration_id desc limit 3;'
# 4. 恢复应用
kubectl -n mixingx scale deploy/mixingx-sso --replicas=2
kubectl -n mixingx rollout status deploy/mixingx-sso
```
5. **版本对齐**:还原后数据库回到了旧迁移版本,应用镜像也必须是配套的旧版本——到更新中心对该服务点「回滚」。不要出现「新镜像 + 旧库」的组合。
6. 关闭通道(若开过),填写执行记录。
### 11.3 红线
- 禁止未做 11.1 三项确认就执行 `--clean`;
- 禁止在生产时段还原;
- 还原多个库时逐库进行,一次一个。
## 12. 执行记录(每次必填)
| 字段 | 内容 |
|---|---|
| 日期/执行人 | |
| 客户/环境 | 如 mxlexus / mixingx |
| 服务与目标版本 | 如 sso v1.0.4 |
| 备份文件路径 | |
| 脚本执行结果 | 成功 / 失败(附报错) |
| 迁移版本验证 | `__EFMigrationsHistory` 最新 migration_id |
| 通道关闭确认 | 是 / 否 |
| 客户已点更新 | 是 / 否 / 时间 |
## 附录:速查表
| 项 | 值 |
|---|---|
| namespace | `mixingx` |
| PG Service | `<release名>-postgres-service`,用 `kubectl -n mixingx get svc \| grep postgres-service` 发现 |
| PG 端口 | 5432(集群内) |
| 用户名 | `postgres` |
| 密码 | chart 默认 `Admin12345`;如 `environments/<customer>/*-values.yaml` 覆盖了 `sharedInfra.postgres.password`,以覆盖值为准 |
| 数据库名 | sso → `sso-db`,ultra → `ultra-db`,agent → `agent-db`;以 `kubectl -n mixingx exec <postgres-pod> -- env \| grep POSTGRES_DB` 为准 |
| 迁移脚本 | release 分支 `db-scripts/<service>/<version>.sql` |
| 历史表 | `"__EFMigrationsHistory"` |
| 备选通道 | `kubectl -n mixingx port-forward svc/<pg-service> 15432:5432` |
| 免客户端变体 | `kubectl -n mixingx exec -it <postgres-pod> -- psql -U postgres -d <db>`(配合 `kubectl cp` 传脚本/dump) |