docs: 记录开发服务器版本化迁移部署与回滚点

2026-08-13 23:46:37 +08:00
parent a1f1e7baaa
commit f1ba6b35dc
3 changed files with 31 additions and 4 deletions
@@ -1159,3 +1159,27 @@ UPDATE cameras SET gb_channel_id = '44010201001320000001' WHERE gb_device_id = '
 - `npm run build` 通过，无 TS 诊断错误
 - 前端已部署到 `http://100.83.103.1:5174/videos`（5174 端口正常监听）
 - 编辑摄像头不再崩溃，"认证密码"正确回显，"码流类型"字段已移除且不再出现残留值
+
+---
+
+## 2026-08-13 版本化数据库迁移部署（Task 2）
+
+### 变更内容
+
+- 后端采用 `golang-migrate/migrate/v4 v4.18.2`，启动时执行 `server-go/migrations/` 下 SQL 迁移并校验 `schema_migrations`；
+- `000001_baseline` 覆盖当前 26 张业务表、索引和唯一约束，并已调整为幂等建表/建索引；
+- `database.Init` 不再无条件 AutoMigrate；生产环境忽略 `ALLOW_DEV_AUTOMIGRATE`；
+- 开发服务器 `100.83.103.1` 已从 AutoMigrate 旧二进制切换为迁移版本二进制。
+
+### 验证结果
+
+- 开发服务器后端 `:3000` 与 Web `:5174` 均监听正常，`/api/v1/health` 返回 200；
+- `schema_migrations`：`1|f`；
+- 后端日志：`数据库连接成功，版本化迁移完成 schemaVersion=1`；
+- 新二进制 SHA256：`9acb5fbfdb854b90b821d456f0f05177cd34dd8f3161686e1c472170af5d1201`。
+
+### 回滚点
+
+- 数据库备份：`/home/pan/backups/silk-20260813-234221.dump`；
+- 旧二进制：`/home/pan/silk/server-go/server-go-linux.bak-20260813-234221`；
+- 回滚步骤：恢复旧二进制并重启，或先 `pg_restore` 恢复数据库备份；开发服务器无 git 仓库，不依赖 git tag。
@@ -10,7 +10,7 @@
 |---|---|---|---|---|
 | Wave 0 | 决策与基线 | Task 0 固化开放决策与整改基线 | 方案确定 | 无，决策记录已生成 |
 | Wave 0 | 决策与基线 | Task 1 恢复可复现的多端质量基线 | 部分可用 | CI 待 Task 0 平台落地 |
-| Wave 1 | P0 安全与正确性 | Task 2 版本化数据库迁移与 Schema 启动门禁 | 部分可用 | 本机无 PostgreSQL/Docker，真实空库/回滚演练待环境 |
+| Wave 1 | P0 安全与正确性 | Task 2 版本化数据库迁移与 Schema 启动门禁 | 部分可用 | 开发库升级已验证，真实 down 回滚演练待后续 |
 | Wave 1 | P0 安全与正确性 | Task 3 移除默认密钥与默认管理员密码 | 未开始 | 无 |
 | Wave 1 | P0 安全与正确性 | Task 4 收口视频访问与摄像头密钥输出 | 未开始 | 无 |
 | Wave 1 | P0 安全与正确性 | Task 5 修复 WebSocket 越权与 AI 流 SSRF | 未开始 | 无 |
@@ -818,7 +818,8 @@ MVP 沿用 IoTDB（现状）；TDengine 作为生产规模化候选（先基准
 - 开发服务器首轮启动暴露 `migrate.Close()` 会关闭底层数据库连接，已改为只关闭迁移 source，保留 `sql.DB` 供后续启动检查使用；
 - `database.Init` 改为先执行版本化迁移并校验 `schema_migrations`，生产环境忽略 `ALLOW_DEV_AUTOMIGRATE`；开发环境仅显式开启时允许 AutoMigrate；
 - `config.Config` 增加 `APP_ENV`、`ALLOW_DEV_AUTOMIGRATE`；README 与物理机部署指南补充迁移说明和环境变量；
- 新增 sqlmock 测试，覆盖版本匹配、版本不匹配、空版本、dirty 状态和嵌入式迁移文件解析。
+- 新增 sqlmock 测试，覆盖版本匹配、版本不匹配、空版本、dirty 状态和嵌入式迁移文件解析；
+- 已在开发服务器 `100.83.103.1` 部署迁移版本。

 ### 设计思路与决策依据

@@ -831,10 +832,12 @@ MVP 沿用 IoTDB（现状）；TDengine 作为生产规模化候选（先基准

 - `go test ./...`、`go vet ./...`、`go build ./...` 全部通过；
 - `internal/database` 迁移版本检查与嵌入式迁移解析单测通过；
- 本机无 Docker/PostgreSQL，未执行真实空库建库、旧库升级和 down 回滚演练；需在开发服务器或本地 PostgreSQL 环境完成，并严格按 AGENTS.md 先备份。
+- 开发服务器：`schema_migrations` 为 `1|f`，`/api/v1/health` 200，Web `5174` 200，后端日志显示 `版本化迁移完成 schemaVersion=1`；
+- 已执行旧库升级验证；真实空库建库和 down 回滚演练尚未执行。

 ### 回滚点

 - 本任务前基线提交为 `20bea00`；回滚可还原 Task 2 提交并恢复 go.mod/go.sum；
 - 若迁移已应用到数据库，必须先恢复迁移前数据库备份，不能只回滚代码而保留不兼容 schema；
- 本次未连接开发服务器、未执行生产部署。
+- 开发服务器回滚点：数据库备份 `/home/pan/backups/silk-20260813-234221.dump`，旧二进制 `/home/pan/silk/server-go/server-go-linux.bak-20260813-234221`；
+- 开发服务器无 git 仓库，回滚按旧二进制 + 数据库 dump 恢复，不再依赖服务器 git tag。