chore(ci): 升级migration验证，新增4项检查 (#451) #857

Merged

xiaoxia merged 2 commits from chore/ci-migration-validation-upgrade into develop 2026-07-25 09:43:26 +08:00

Conversation 2 Commits 2 Files Changed 2

+309 -33

xiaoxia commented 2026-07-25 00:06:36 +08:00

Owner

Copy Link

Copy Source

背景 (#451)

当前migration validate只跑 alembic upgrade head，只能发现升级失败，无法检测：

• migration文件命名不规范
• 回滚脚本写坏了（downgrade通不过）
• model改了但忘了生成migration

改动

新增：scripts/ci/check_migration_naming.py

migration文件命名规范检查，3项规则：

1. 文件名必须是 NNN_description.py 格式（3位数字前缀+下划线+小写描述）
2. 编号必须连续，不能跳号
3. revision变量的数字前缀必须与文件名一致

升级：scripts/ci/validate_migration.sh

从1项检查升级为5项：

1. ✅ 命名规范检查 — 静态检查，秒级返回，快速失败
2. ✅ 编号链完整性 — 静态检查（复用已有check_migration_chain.py）
3. ✅ upgrade head — 原有逻辑，真实PG执行
4. ✅ downgrade -1 回滚验证 — 验证最新migration的回滚脚本，然后再upgrade回去（双向验证）
5. ⚠️ alembic check — 检测未生成migration的model变更（当前为警告模式，不阻断CI，稳定后可升级为阻断）

优化点

• 静态检查前置：命名和链检查不需要数据库，先跑快速失败，节省资源
• 数据库清理用 trap EXIT 兜底，无论成功失败都清理
• downgrade验证只跑-1（最新一个migration），平衡检查深度和耗时

影响范围

• 只改CI脚本，不动业务代码
• 已验证：当前51个migration文件全部通过命名检查
• CI的Validate - Migration job名不变，不影响分支保护门禁

关联: #451

## 背景 (#451) 当前migration validate只跑 `alembic upgrade head`，只能发现升级失败，无法检测： - migration文件命名不规范 - 回滚脚本写坏了（downgrade通不过） - model改了但忘了生成migration ## 改动 ### 新增：`scripts/ci/check_migration_naming.py` migration文件命名规范检查，3项规则： 1. 文件名必须是 `NNN_description.py` 格式（3位数字前缀+下划线+小写描述） 2. 编号必须连续，不能跳号 3. revision变量的数字前缀必须与文件名一致 ### 升级：`scripts/ci/validate_migration.sh` 从1项检查升级为5项： 1. ✅ **命名规范检查** — 静态检查，秒级返回，快速失败 2. ✅ **编号链完整性** — 静态检查（复用已有check_migration_chain.py） 3. ✅ **upgrade head** — 原有逻辑，真实PG执行 4. ✅ **downgrade -1 回滚验证** — 验证最新migration的回滚脚本，然后再upgrade回去（双向验证） 5. ⚠️ **alembic check** — 检测未生成migration的model变更（当前为警告模式，不阻断CI，稳定后可升级为阻断） ### 优化点 - 静态检查前置：命名和链检查不需要数据库，先跑快速失败，节省资源 - 数据库清理用 trap EXIT 兜底，无论成功失败都清理 - downgrade验证只跑-1（最新一个migration），平衡检查深度和耗时 ## 影响范围 - 只改CI脚本，不动业务代码 - 已验证：当前51个migration文件全部通过命名检查 - CI的Validate - Migration job名不变，不影响分支保护门禁 关联: #451

xiaoxia added 1 commit 2026-07-25 00:06:36 +08:00

chore(ci): 升级migration验证，新增4项检查 (#451) ... 1aa47be16a

- 新增migration文件命名规范检查（check_migration_naming.py）
- 新增downgrade -1回滚验证（双向一致性验证）
- 新增alembic check检测未生成migration的model变更（警告模式）
- 整合链完整性检查到validate_migration.sh
- 静态检查前置，快速失败节省资源

auto-approve-bot commented 2026-07-25 00:17:34 +08:00

Collaborator

Copy Link

Copy Source

代码审查结果 - PR #857

⚠️ 问题（2个需要修改）

1. scripts/ci/validate_migration.sh 第237行：trap cleanup_db EXIT 设置位置过晚，导致资源泄漏风险。

   • 问题描述：在临时PG容器模式下（else分支），PG_CONTAINER 在第197行启动，随后进行 wait_tcp_ready 检查。如果网络检查超时或失败，脚本会因为 set -eu 退出，此时第237行的 trap 尚未执行，导致已创建的 Docker 容器无法被清理，造成 CI 环境资源泄漏。
   • 修改建议：将 trap cleanup_db EXIT 移至资源创建之后、网络检查之前；或者定义一个通用的清理函数，在脚本开头就设置 trap，并在函数内部判断资源是否存在。

2. scripts/ci/check_migration_naming.py 第52行：依赖错误消息字符串内容进行逻辑判断，导致输出误导。

   • 问题描述：代码使用 any("命名格式不规范" in e ... for e in errors) 来判断是否打印“格式正确”的提示。如果 errors 列表中包含其他类型的错误（如“目录不存在”），该条件为假，程序仍会打印“全部 X 个文件名格式正确”，掩盖了实际的错误状态。
   • 修改建议：引入独立的布尔标志（如 has_format_error）来记录格式检查是否通过，而非扫描错误消息字符串。

💡 建议（2个可选）

1. scripts/ci/validate_migration.sh 第265行：alembic check 的异常处理过于宽泛。

   • 具体内容：当 alembic check 命令执行出错（如配置错误、ImportError）时，脚本仅将其作为“非阻断”警告处理。这可能会掩盖 CI 环境配置错误或代码逻辑错误。建议将“执行出错”的情况视为严重错误并退出 CI，或者至少将其与“检测到Model变更”的情况区分处理。

2. scripts/ci/validate_migration.sh 第249行：提示信息与实际情况可能不符。

   • 具体内容：当 TOTAL_REVS 为 0 时，提示信息仍为“只有1个migration”。虽然逻辑上跳过了回滚是正确的，但提示信息不准确。建议修改为“Migration数量少于2个，跳过...”。

---

✅ 格式检查通过 | ❌ 逻辑审查需修改 | ⚠️ 建议关注性能

---

_{🤖 由 AI 代码审查机器人自动生成 | 2026-07-24 16:17:34 | 模型:}

## 代码审查结果 - PR #857 ### ⚠️ 问题（2个需要修改） 1. **scripts/ci/validate_migration.sh 第237行**：`trap cleanup_db EXIT` 设置位置过晚，导致资源泄漏风险。 - **问题描述**：在临时PG容器模式下（`else`分支），`PG_CONTAINER` 在第197行启动，随后进行 `wait_tcp_ready` 检查。如果网络检查超时或失败，脚本会因为 `set -eu` 退出，此时第237行的 `trap` 尚未执行，导致已创建的 Docker 容器无法被清理，造成 CI 环境资源泄漏。 - **修改建议**：将 `trap cleanup_db EXIT` 移至资源创建之后、网络检查之前；或者定义一个通用的清理函数，在脚本开头就设置 trap，并在函数内部判断资源是否存在。 2. **scripts/ci/check_migration_naming.py 第52行**：依赖错误消息字符串内容进行逻辑判断，导致输出误导。 - **问题描述**：代码使用 `any("命名格式不规范" in e ... for e in errors)` 来判断是否打印“格式正确”的提示。如果 `errors` 列表中包含其他类型的错误（如“目录不存在”），该条件为假，程序仍会打印“全部 X 个文件名格式正确”，掩盖了实际的错误状态。 - **修改建议**：引入独立的布尔标志（如 `has_format_error`）来记录格式检查是否通过，而非扫描错误消息字符串。 ### 💡 建议（2个可选） 1. **scripts/ci/validate_migration.sh 第265行**：`alembic check` 的异常处理过于宽泛。 - **具体内容**：当 `alembic check` 命令执行出错（如配置错误、ImportError）时，脚本仅将其作为“非阻断”警告处理。这可能会掩盖 CI 环境配置错误或代码逻辑错误。建议将“执行出错”的情况视为严重错误并退出 CI，或者至少将其与“检测到Model变更”的情况区分处理。 2. **scripts/ci/validate_migration.sh 第249行**：提示信息与实际情况可能不符。 - **具体内容**：当 `TOTAL_REVS` 为 0 时，提示信息仍为“只有1个migration”。虽然逻辑上跳过了回滚是正确的，但提示信息不准确。建议修改为“Migration数量少于2个，跳过...”。 --- ✅ 格式检查通过 | ❌ 逻辑审查需修改 | ⚠️ 建议关注性能 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-07-24 16:17:34 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

xiaoxia added 1 commit 2026-07-25 00:41:25 +08:00

style: black格式化check_migration_naming.py 35e7670376

xiaoxia merged commit 1e16e81344 into develop 2026-07-25 09:43:26 +08:00

gitea-actions bot commented 2026-07-25 09:43:40 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

PR #857 已关闭或合并，对应的预览环境已被清理。

如有需要，可以重新打开 PR 来重新生成预览环境。

🗑️ **预览环境已清理** PR #857 已关闭或合并，对应的预览环境已被清理。 > 如有需要，可以重新打开 PR 来重新生成预览环境。

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot xiaoxia

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#857