42 lines
2.4 KiB
Markdown
42 lines
2.4 KiB
Markdown
# 数据库版本化迁移
|
||
|
||
服务进程启动时**不会**执行数据库结构变更。数据库升级必须在备份成功、单实例维护窗口内显式运行迁移命令，避免大 SQLite 库发生隐式重建和 WAL 写放大。 // Logan.Li
|
||
|
||
## 日常命令
|
||
|
||
```bash
|
||
# 查看已应用与待执行版本
|
||
./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 与空间核验。
|