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 | ❌ 不适用 | 无数据库 |
铁律(违反任何一条都可能造成生产事故):
- 先库后应用:先执行数据库脚本,确认成功后,再让客户在更新中心点「更新应用」。expand-contract 纪律保证新 schema 兼容旧应用,反着来则旧代码可能访问不到新结构。
- 执行脚本前必先备份,没有例外。
- 一次只动一个服务,不要并行开多个库操作。
- 数据库通道用完立即关闭,任何数据库端口不得常开。
- 生产时段不动库,与客户约定维护窗口。
1. 何时执行
更新中心里某个版本标记了「含数据库变更」,或发版通知中注明该服务带迁移脚本。未标记的版本不涉及本手册。
新客户首装:生产环境关闭了启动自动迁移,首次部署时数据库是空的——必须先按本手册对每个带库服务(sso/ultra/agent)执行一次初始脚本(幂等脚本支持空库,会创建全部表结构),再启动应用,否则应用会因缺表无法启动。首装时按「流程一→三→四→五」执行(流程二备份对空库可跳过),全部服务执行完再通知验收。
2. 准备
-
获取迁移脚本(随版本交付,幂等,可重复执行):
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)。流水线改造完成前,脚本由开发随发版通知手动提供,后续流程相同。 -
确认本次要执行的服务清单(可能只有一个,如
sso/v1.0.4.sql)。 -
运维机器要求:能
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. 故障恢复(脚本执行失败或升级后异常)
-
保持通道开启,停止对应应用(防止继续写入):
kubectl -n mixingx scale deploy/mixingx-sso --replicas=0 -
用流程二的备份恢复:
pg_restore -h <节点IP> -p <NodePort> -U postgres -d sso-db \ --clean --if-exists sso-db-20260826-2200-pre-v1.0.4.dump--clean会删现有对象,确认备份文件无误后再执行。不确定时先恢复到临时库核对。 -
恢复应用副本数,验证启动正常。
-
如镜像已更新,到更新中心点「回滚」回到上一同步版本。
-
关闭通道,填写执行记录,事故上报 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 必须停下等人工确认)
- 执行迁移脚本前:AI 复述「服务 / 库 / 脚本文件 / 目标版本」,人确认后才给命令;
- 还原前:AI 复述「备份文件名 + 备份时间点 + 将丢失该时间点之后的数据」,人明确同意;
- 任何命令输出与预期不符时:停止推进,分析后再继续,禁止跳过。
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 还原前三个确认(缺一不可)
- 客户书面/聊天记录认可:恢复到哪个时间点,并接受该时间点之后的数据丢失;
- 备份文件有效:
pg_restore -l <dump文件> | head能列出内容; - 当前处于维护窗口,应用侧已知情。
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
- 版本对齐:还原后数据库回到了旧迁移版本,应用镜像也必须是配套的旧版本——到更新中心对该服务点「回滚」。不要出现「新镜像 + 旧库」的组合。
- 关闭通道(若开过),填写执行记录。
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) |