aiops/docs/database-migrations.md

数据库版本化迁移

服务进程启动时不会执行数据库结构变更。数据库升级必须在备份成功、单实例维护窗口内显式运行迁移命令，避免大 SQLite 库发生隐式重建和 WAL 写放大。 // Logan.Li

日常命令

# 查看已应用与待执行版本
./aiops migrate status --config /srv/aiops/config.yaml

# 全新空数据库：创建初始基线并执行后续迁移
./aiops migrate up --config /srv/aiops/config.yaml

# 已存在的旧数据库：人工核验、备份完成后，只写入基线记录，不改业务表
./aiops migrate baseline --config /srv/aiops/config.yaml

# 旧库完成 baseline 后，执行后续待迁移版本
./aiops migrate up --config /srv/aiops/config.yaml

baseline 会校验 iam_users、iam_roles、asset_servers、deploy_pipelines、monitor_agent_reports 等核心表；校验失败时拒绝登记，不能用它绕过不完整库的恢复或专项迁移。 // Logan.Li

已上线数据库的切换步骤

1. 停止写入或切换至维护窗口，并完成可恢复备份。
2. 运行 aiops migrate status，确认已有 0001_agent_credentials 记录仍然存在。
3. 运行 aiops migrate baseline，它只登记 0000_baseline_schema。
4. 再运行 aiops migrate up；0002_legacy_schema_patches 会把既有的兼容字段补丁作为可审计迁移执行。
5. 再次运行 status，确认所有版本均为 applied，然后启动服务。

线上已存在的 sys_schema_migrations(version, applied_at) 表保持兼容：迁移框架不会假设额外列，也不会重写既有 0001_agent_credentials 记录。 // Logan.Li

若旧业务库甚至尚无 sys_schema_migrations，migrate up 会零写入拒绝；只能由维护人员先完成备份并显式执行 migrate baseline。 // Logan.Li

新迁移规则

• 新版本只追加到 backend/migrations/ 和 migrations.All()，禁止修改或重命名已发布版本。
• 需要方言差异的 SQL 使用 <version>.<sqlite|mysql|postgres>.sql 三份脚本。
• 复杂或需调用 GORM 的变更使用 Go 迁移函数，但必须返回错误；禁止吞掉 DDL/DML 错误。
• MySQL DDL 可能隐式提交，执行迁移前必须备份；同一数据库同一时间只能运行一个迁移进程。
• SQLite 大表迁移与 VACUUM 必须在停写维护窗口执行，迁移完成后再进行 WAL checkpoint 与空间核验。