# 迁移工作流程

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [composer.json](file://composer.json)
- [composer.lock](file://composer.lock)
- [.example.env](file://.example.env)
- [AGENTS.MD](file://AGENTS.MD)
- [public/api.php](file://public/api.php)
- [public/index.php](file://public/index.php)
- [public/router.php](file://public/router.php)
- [public/plugins/swagger/swagger/OpenApiSpec.php](file://public/plugins/swagger/swagger/OpenApiSpec.php)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向 ThinkCMF 的数据库迁移工作流程，覆盖从需求分析、设计与规划、开发与测试、到生产部署与回滚的完整生命周期。内容包含版本规划、依赖管理、回滚策略、团队协作（分支、评审、冲突）、生产部署（预演、执行、验证）以及自动化与监控建议。ThinkCMF 在 6.0.5 版本起引入数据库迁移能力，并通过 xia/migration 包集成 Phinx，结合 Composer 的 post-autoload-dump 钩子实现安装后自动迁移。

## 项目结构
- ThinkCMF 采用多应用架构与插件机制，公共入口位于 public 目录，API 入口为 public/api.php，主站入口为 public/index.php，路由由 public/router.php 统一处理。
- 迁移框架由 xia/migration 提供，其内部使用 Phinx，遵循 ThinkPHP 命令体系，通过 php think migrate:* 系列命令进行迁移管理。
- Composer 配置中定义了自动执行脚本，安装/更新后会自动执行服务发现、资源发布与数据库迁移，确保部署一致性。

```mermaid
graph TB
A["public/index.php<br/>主站入口"] --> B["public/router.php<br/>路由分发"]
C["public/api.php<br/>API入口"] --> B
D["composer.json<br/>自动脚本与依赖"] --> E["xia/migration<br/>Phinx封装"]
F["AGENTS.MD<br/>迁移命令与规范"] --> E
G[".example.env<br/>数据库配置示例"] --> E
```

图表来源
- [public/index.php](file://public/index.php)
- [public/api.php](file://public/api.php)
- [public/router.php](file://public/router.php)
- [composer.json](file://composer.json)
- [AGENTS.MD](file://AGENTS.MD)
- [.example.env](file://.example.env)

章节来源
- [README.md:17-49](file://README.md#L17-L49)
- [composer.json:67-72](file://composer.json#L67-L72)
- [AGENTS.MD:576-598](file://AGENTS.MD#L576-L598)

## 核心组件
- 迁移命令体系
  - 创建迁移：php think migrate:create <MigrationName>
  - 执行迁移：php think migrate:run
  - 回滚迁移：php think migrate:rollback
- 自动化执行
  - Composer 安装/更新后自动执行：service:discover → vendor:publish → migrate:run
- 迁移文件管理
  - 迁移文件由 xia/migration 包管理，遵循 Phinx 规范；迁移文件位置由该包负责组织。
- 配置与环境
  - 使用 .env 或环境变量配置数据库连接等参数；示例配置位于 .example.env。

章节来源
- [AGENTS.MD:578-596](file://AGENTS.MD#L578-L596)
- [composer.json:67-72](file://composer.json#L67-L72)
- [.example.env:1](file://.example.env#L1)

## 架构总览
下图展示迁移在 ThinkCMF 中的端到端流程：从 Composer 安装触发，到命令行迁移执行，再到数据库变更落地。

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant Composer as "Composer"
participant Think as "Think 命令行"
participant Migration as "xia/migration/Phinx"
participant DB as "数据库"
Dev->>Composer : 执行 composer install/update
Composer-->>Dev : 触发 post-autoload-dump 脚本
Composer->>Think : 调用 php think service : discover
Composer->>Think : 调用 php think vendor : publish
Composer->>Think : 调用 php think migrate : run
Think->>Migration : 解析迁移任务
Migration->>DB : 执行迁移 SQL
DB-->>Migration : 返回执行结果
Migration-->>Think : 输出迁移状态
Think-->>Dev : 显示迁移日志
```

图表来源
- [composer.json:67-72](file://composer.json#L67-L72)
- [AGENTS.MD:578-596](file://AGENTS.MD#L578-L596)

## 详细组件分析

### 迁移设计原则与规划方法
- 版本规划
  - 以语义化版本号为基准，配合迁移编号或时间戳前缀，确保迁移顺序可预测。
  - 将破坏性变更拆分为独立迁移，避免单次迁移过大导致失败风险上升。
- 依赖管理
  - 迁移之间尽量避免隐式依赖；若存在先后关系，应通过迁移文件名或注释明确约束。
  - 依赖外部表或数据时，先检查目标对象是否存在，再进行变更。
- 回滚策略
  - 每个迁移应具备可逆性；对于不可逆操作（如删除列），需谨慎评估并准备替代方案。
  - 使用 php think migrate:rollback 进行回滚，建议在测试环境充分验证后再在生产执行。
- 命名规范
  - 迁移名称应清晰表达变更意图，例如 AddUsersTable、ModifyPostsStatusColumn 等。
- 变更范围
  - 优先进行非阻塞变更（如新增字段、索引），避免在高峰期执行大范围结构变更。

章节来源
- [AGENTS.MD:578-596](file://AGENTS.MD#L578-L596)

### 团队协作中的迁移管理
- 分支管理
  - 迁移相关改动纳入功能分支，合并前确保迁移已通过本地与 CI 测试。
- 代码审查
  - 审查重点：迁移是否满足幂等性、是否包含破坏性操作、是否具备回滚路径。
- 冲突解决
  - 当多个分支同时修改同一张表结构时，优先采用顺序化迁移或重构为原子性变更。
  - 若出现迁移冲突，建议通过回滚到共同祖先，重新设计迁移序列。

章节来源
- [AGENTS.MD:578-596](file://AGENTS.MD#L578-L596)

### 生产环境迁移部署流程
- 预演
  - 在预生产环境执行 php think migrate:run，核对日志与数据库结构变化。
  - 对比迁移前后快照，确认无意外变更。
- 执行
  - 选择维护窗口，执行 php think migrate:run；若失败，立即执行 php think migrate:rollback 并修复。
- 验证
  - 核验关键业务接口与数据完整性；结合 Swagger 文档验证 API 正常。
  - 关注 .env 中数据库配置，确保连接参数正确。

```mermaid
flowchart TD
Start(["开始"]) --> Precheck["预演：在预生产执行迁移"]
Precheck --> Pass{"预演通过？"}
Pass --> |否| Fix["修复迁移并回归测试"]
Fix --> Precheck
Pass --> |是| Deploy["生产窗口执行迁移"]
Deploy --> Rollback{"执行成功？"}
Rollback --> |否| ManualRollback["手动回滚并修复"]
ManualRollback --> End(["结束"])
Rollback --> |是| Verify["验证业务与接口"]
Verify --> End
```

图表来源
- [AGENTS.MD:578-596](file://AGENTS.MD#L578-L596)
- [public/plugins/swagger/swagger/OpenApiSpec.php:1-72](file://public/plugins/swagger/swagger/OpenApiSpec.php#L1-L72)

章节来源
- [AGENTS.MD:578-596](file://AGENTS.MD#L578-L596)
- [public/plugins/swagger/swagger/OpenApiSpec.php:1-72](file://public/plugins/swagger/swagger/OpenApiSpec.php#L1-L72)

### 迁移项目的管理工具与自动化方案
- CI/CD 集成
  - 在流水线中加入 Composer 安装步骤，利用 post-autoload-dump 自动执行迁移，保证部署一致性。
  - 建议在“部署前置检查”阶段执行 php think migrate:run --dry-run（如可用）或等效校验。
- 监控与告警
  - 监控迁移执行日志与数据库变更；失败时触发告警。
  - 结合 API 文档与接口测试，确保迁移后业务可用性。

章节来源
- [composer.json:67-72](file://composer.json#L67-L72)
- [AGENTS.MD:578-596](file://AGENTS.MD#L578-L596)

## 依赖分析
- 运行时依赖
  - PHP 版本要求 ≥ 8.1；数据库驱动与连接参数通过 .env 或环境变量注入。
- 迁移依赖
  - xia/migration 包提供 ThinkPHP 命令行迁移能力，内部基于 Phinx；版本信息可在 composer.lock 中查看。
- 自动化链路
  - composer.json 的 scripts.post-autoload-dump 定义了安装/更新后的自动化步骤，确保迁移在部署后自动执行。

```mermaid
graph TB
CMF["ThinkCMF 核心"] --> XIA["xia/migration 包"]
XIA --> PHINX["Phinx 引擎"]
CMF --> COMPOSER["Composer 脚本"]
COMPOSER --> MIGRATE["migrate:run"]
MIGRATE --> DB["数据库"]
```

图表来源
- [composer.json:67-72](file://composer.json#L67-L72)
- [composer.lock:1122-1151](file://composer.lock#L1122-L1151)

章节来源
- [composer.json:30-42](file://composer.json#L30-L42)
- [composer.lock:1122-1151](file://composer.lock#L1122-L1151)

## 性能考虑
- 迁移执行期间对数据库的影响
  - 大型表结构变更可能造成锁表或性能抖动，建议在低峰期执行。
- 幂等性与可逆性
  - 迁移应尽量幂等，避免重复执行产生副作用；破坏性操作必须有回滚路径。
- 日志与可观测性
  - 通过命令行输出与数据库变更记录，建立可追溯的审计链。

## 故障排查指南
- 迁移失败
  - 使用 php think migrate:rollback 回滚至上一个稳定版本，定位失败原因（语法、权限、依赖）。
- 环境差异
  - 对比 .example.env 与当前 .env，确保数据库连接参数一致。
- 命令不可用
  - 确认已安装 xia/migration 包且 Think 命令行可用；参考 AGENTS.MD 中的命令清单。

章节来源
- [AGENTS.MD:578-596](file://AGENTS.MD#L578-L596)
- [.example.env:1](file://.example.env#L1)

## 结论
ThinkCMF 的迁移工作流程以 xia/migration 为核心，结合 Composer 自动化与命令行工具，形成从开发到生产的闭环。通过严格的版本规划、依赖管理与回滚策略，以及完善的团队协作与自动化方案，可显著降低数据库变更风险，提升交付质量与效率。

## 附录
- 快速参考
  - 创建迁移：php think migrate:create <MigrationName>
  - 执行迁移：php think migrate:run
  - 回滚迁移：php think migrate:rollback
  - 自动化脚本：composer install/update 后自动执行 migrate:run
  - 数据库配置：参考 .example.env 与当前 .env

章节来源
- [AGENTS.MD:578-596](file://AGENTS.MD#L578-L596)
- [composer.json:67-72](file://composer.json#L67-L72)
- [.example.env:1](file://.example.env#L1)