Files
mixingx.deploy/docs/runbooks/db-change.md

13 KiB

生产数据库变更运行手册

适用环境:客户生产环境(如 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. 何时执行

更新中心里某个版本标记了「含数据库变更」,或发版通知中注明该服务带迁移脚本。未标记的版本不涉及本手册。

新客户首装:生产环境关闭了启动自动迁移,首次部署时数据库是空的——必须先按本手册对每个带库服务(sso/ultra/agent)执行一次初始脚本(幂等脚本支持空库,会创建全部表结构),再启动应用,否则应用会因缺表无法启动。首装时按「流程一→三→四→五」执行(流程二备份对空库可跳过),全部服务执行完再通知验收。

2. 准备

  1. 获取迁移脚本(随版本交付,幂等,可重复执行):

    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。先发现实际名称:

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 为例):

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:

kubectl get nodes -o wide   # 任取一台节点的 INTERNAL-IP

连接信息即:主机=<节点IP> 端口=<NodePort> 用户=postgres 密码=<见速查表> 数据库=<见速查表>。

变体(推荐用于纯命令行场景,不落集群状态):

kubectl -n mixingx port-forward svc/mixingx-sso-postgres-service 15432:5432
# 另开终端连接 localhost:15432;用毕 Ctrl+C 即关闭,跳过流程五

4. 流程二:备份(执行脚本前必做)

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. 流程三:执行迁移脚本

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. 流程四:验证

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 保证兼容):

    kubectl -n mixingx logs deploy/mixingx-sso --tail=50
    

7. 流程五:关闭通道

kubectl -n mixingx patch svc mixingx-sso-postgres-service \
  --type='json' -p='[{"op":"replace","path":"/spec/type","value":"ClusterIP"}]'

验证已恢复 ClusterIP 后,通知客户:可以到更新中心点击该服务的「更新」。

8. 故障恢复(脚本执行失败或升级后异常)

  1. 保持通道开启,停止对应应用(防止继续写入):

    kubectl -n mixingx scale deploy/mixingx-sso --replicas=0
    
  2. 用流程二的备份恢复:

    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 只准使用块内参数)

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 的上下文提示词(复制即用,尖括号内容由人填写)

你是 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(无需开任何端口)

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,然后逐服务执行:

pg_dump -h <节点IP> -p <该服务的NodePort> -U postgres -Fc -d <db> -f <db>-$TS.dump

10.4 备份验证与保管

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 为例)

# 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
  1. 版本对齐:还原后数据库回到了旧迁移版本,应用镜像也必须是配套的旧版本——到更新中心对该服务点「回滚」。不要出现「新镜像 + 旧库」的组合。
  2. 关闭通道(若开过),填写执行记录。

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)