From 237e36516f88c375151e662fab8bf4c03e5786e5 Mon Sep 17 00:00:00 2001 From: ximenchuifeng Date: Wed, 26 Aug 2026 16:19:26 +0800 Subject: [PATCH] docs(runbooks): add production db change runbook --- docs/runbooks/db-change.md | 309 +++++++++++++++++++++++++++++++++++++ 1 file changed, 309 insertions(+) create mode 100644 docs/runbooks/db-change.md diff --git a/docs/runbooks/db-change.md b/docs/runbooks/db-change.md new file mode 100644 index 0000000..aadc7f0 --- /dev/null +++ b/docs/runbooks/db-change.md @@ -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 命名规律:`-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> 端口= 用户=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 -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 -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 -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 -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=,服务=,库=, + PG Service=,目标版本=。 +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--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 -f -$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 | 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 -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 | `-postgres-service`,用 `kubectl -n mixingx get svc \| grep postgres-service` 发现 | +| PG 端口 | 5432(集群内) | +| 用户名 | `postgres` | +| 密码 | chart 默认 `Admin12345`;如 `environments//*-values.yaml` 覆盖了 `sharedInfra.postgres.password`,以覆盖值为准 | +| 数据库名 | sso → `sso-db`,ultra → `ultra-db`,agent → `agent-db`;以 `kubectl -n mixingx exec -- env \| grep POSTGRES_DB` 为准 | +| 迁移脚本 | release 分支 `db-scripts//.sql` | +| 历史表 | `"__EFMigrationsHistory"` | +| 备选通道 | `kubectl -n mixingx port-forward svc/ 15432:5432` | +| 免客户端变体 | `kubectl -n mixingx exec -it -- psql -U postgres -d `(配合 `kubectl cp` 传脚本/dump) |