# 生产数据库变更运行手册 > 适用环境:客户生产环境(如 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. 获取迁移脚本(随版本交付,幂等,可重复执行): ```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) |