# 迁移执行与管理

<cite>
**本文引用的文件**
- [composer.lock](file://composer.lock)
- [AGENTS.MD](file://AGENTS.MD)
- [AbstractMigration.php](file://vendor/xia/migration/phinx/src/Phinx/Migration/AbstractMigration.php)
- [Manager.php](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php)
- [Migrate.php](file://vendor/xia/migration/phinx/src/Phinx/Console/Command/Migrate.php)
- [Create.php](file://vendor/xia/migration/phinx/src/Phinx/Console/Command/Create.php)
- [Rollback.php](file://vendor/xia/migration/phinx/src/Phinx/Console/Command/Rollback.php)
- [Config.php](file://vendor/xia/migration/phinx/src/Phinx/Config/Config.php)
- [Environment.php](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager/Environment.php)
- [20230320162718_migration_cmf_role_type.php](file://vendor/thinkcmf/cmf/src/data/migrations/20230320162718_migration_cmf_role_type.php)
- [IndexController.php](file://vendor/thinkcmf/cmf-install/src/install/controller/IndexController.php)
</cite>

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

## 简介
本文件面向 ThinkCMF 的数据库迁移执行与管理工作，围绕迁移命令的使用、执行过程的监控与验证、迁移管理工具的使用、安全措施以及故障排除进行系统化说明。ThinkCMF 使用 xia/migration 包集成 Phinx，提供创建、执行与回滚迁移的能力，并在安装流程中自动运行迁移以初始化数据库。

## 项目结构
- 迁移命令由 Phinx 控制台命令提供，包含创建、执行与回滚三大类命令。
- 迁移文件遵循 Phinx 命名规范，位于各应用的迁移路径中。
- ThinkCMF 在安装控制器中调用迁移命令，确保首次安装时数据库结构正确初始化。
- 迁移配置通过 Config 类加载，支持多种配置格式与环境变量注入。

```mermaid
graph TB
subgraph "ThinkCMF 应用"
CLI["命令行接口<br/>phinx migrate/rollback/create"]
Cfg["配置加载<br/>Config.php"]
Env["环境适配器<br/>Environment.php"]
Mgr["迁移管理器<br/>Manager.php"]
Mig["迁移文件<br/>命名规范 *.php"]
end
CLI --> Cfg
CLI --> Mgr
Mgr --> Env
Env --> Mig
```

图表来源
- [Migrate.php:1-141](file://vendor/xia/migration/phinx/src/Phinx/Console/Command/Migrate.php#L1-L141)
- [Rollback.php:1-170](file://vendor/xia/migration/phinx/src/Phinx/Console/Command/Rollback.php#L1-L170)
- [Create.php:1-315](file://vendor/xia/migration/phinx/src/Phinx/Console/Command/Create.php#L1-L315)
- [Config.php:266-307](file://vendor/xia/migration/phinx/src/Phinx/Config/Config.php#L266-L307)
- [Environment.php:66-124](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager/Environment.php#L66-L124)
- [Manager.php:695-791](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php#L695-L791)

章节来源
- [AGENTS.MD:576-599](file://AGENTS.MD#L576-L599)
- [composer.lock:1121-1151](file://composer.lock#L1121-L1151)

## 核心组件
- 迁移抽象类：定义迁移生命周期、适配器交互与表对象封装。
- 迁移管理器：负责扫描迁移文件、排序、执行与回滚、状态打印与断点管理。
- 控制台命令：提供 create、migrate、rollback 三类命令及其选项。
- 环境适配器：封装数据库连接、事务、日志记录与断点设置。
- 配置系统：解析配置文件、环境变量注入、迁移路径与版本顺序等。

章节来源
- [AbstractMigration.php:27-331](file://vendor/xia/migration/phinx/src/Phinx/Migration/AbstractMigration.php#L27-L331)
- [Manager.php:25-1087](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php#L25-L1087)
- [Migrate.php:17-141](file://vendor/xia/migration/phinx/src/Phinx/Console/Command/Migrate.php#L17-L141)
- [Create.php:22-315](file://vendor/xia/migration/phinx/src/Phinx/Console/Command/Create.php#L22-L315)
- [Rollback.php:16-170](file://vendor/xia/migration/phinx/src/Phinx/Console/Command/Rollback.php#L16-L170)
- [Environment.php:19-399](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager/Environment.php#L19-L399)
- [Config.php:24-541](file://vendor/xia/migration/phinx/src/Phinx/Config/Config.php#L24-L541)

## 架构总览
下图展示从命令到迁移执行的关键调用链路，包括迁移文件扫描、版本排序、事务包裹与日志记录。

```mermaid
sequenceDiagram
participant U as "运维/开发者"
participant CLI as "命令行<br/>Migrate.php"
participant CFG as "配置<br/>Config.php"
participant MGR as "管理器<br/>Manager.php"
participant ENV as "环境适配器<br/>Environment.php"
participant ADP as "适配器/事务<br/>Environment.php"
participant DB as "数据库"
U->>CLI : 执行 migrate 命令
CLI->>CFG : 读取默认环境与配置
CLI->>MGR : 调用 migrate(environment, version)
MGR->>MGR : 扫描迁移文件并按版本排序
MGR->>ENV : 获取环境实例与适配器
ENV->>ADP : 初始化适配器(含事务包装)
MGR->>ENV : executeMigration(migration, direction)
ENV->>ADP : beginTransaction()
ENV->>DB : 执行迁移SQL
ENV->>ADP : commitTransaction()
ENV->>DB : 记录迁移日志(phinxlog)
ENV-->>MGR : 返回执行结果
MGR-->>CLI : 输出执行耗时与状态
CLI-->>U : 显示执行完成
```

图表来源
- [Migrate.php:60-139](file://vendor/xia/migration/phinx/src/Phinx/Console/Command/Migrate.php#L60-L139)
- [Manager.php:311-395](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php#L311-L395)
- [Environment.php:74-124](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager/Environment.php#L74-L124)
- [Config.php:195-236](file://vendor/xia/migration/phinx/src/Phinx/Config/Config.php#L195-L236)

## 详细组件分析

### 迁移命令使用
- 创建迁移
  - 命令：phinx create 或 php think migrate:create
  - 行为：根据配置选择迁移目录，生成符合命名规范的迁移文件，支持自定义模板或模板类。
- 执行迁移
  - 命令：phinx migrate 或 php think migrate:run
  - 行为：按版本顺序执行未执行的迁移；支持目标版本、日期回退、假执行(dry-run/fake)。
- 回滚迁移
  - 命令：phinx rollback 或 php think migrate:rollback
  - 行为：按执行顺序回滚最后执行的迁移或指定版本；支持断点(force)强制回滚。

章节来源
- [Create.php:139-313](file://vendor/xia/migration/phinx/src/Phinx/Console/Command/Create.php#L139-L313)
- [Migrate.php:60-139](file://vendor/xia/migration/phinx/src/Phinx/Console/Command/Migrate.php#L60-L139)
- [Rollback.php:68-130](file://vendor/xia/migration/phinx/src/Phinx/Console/Command/Rollback.php#L68-L130)
- [AGENTS.MD:578-593](file://AGENTS.MD#L578-L593)

### 迁移执行流程与事务管理
- 版本顺序：支持按创建时间或执行时间排序，影响回滚顺序。
- 事务包裹：迁移执行前开启事务，执行后提交；若执行失败则回滚，保证原子性。
- 断点机制：可对特定版本设置断点，阻止继续回滚；支持切换、设置、清除与批量清除。
- 日志记录：迁移完成后记录开始/结束时间与方向，便于审计与状态查询。

```mermaid
flowchart TD
Start(["开始执行"]) --> Scan["扫描迁移文件<br/>按版本排序"]
Scan --> Decide{"是否指定目标版本/日期"}
Decide --> |是| Target["定位目标版本"]
Decide --> |否| Latest["定位最新版本"]
Target --> TxBegin["开启事务"]
Latest --> TxBegin
TxBegin --> Exec["执行迁移SQL"]
Exec --> Commit{"执行成功?"}
Commit --> |是| Log["记录日志(phinxlog)"]
Commit --> |否| Rollback["回滚事务"]
Log --> End(["结束"])
Rollback --> End
```

图表来源
- [Manager.php:311-395](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php#L311-L395)
- [Environment.php:88-123](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager/Environment.php#L88-L123)
- [Manager.php:975-1036](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php#L975-L1036)

章节来源
- [Manager.php:25-254](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php#L25-L254)
- [Environment.php:66-124](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager/Environment.php#L66-L124)
- [Config.php:379-398](file://vendor/xia/migration/phinx/src/Phinx/Config/Config.php#L379-L398)

### 迁移文件示例与模式
- 示例迁移：在 ThinkCMF 核心中存在示例迁移文件，展示 change 方法与表字段变更的常用模式。
- 命名规范：迁移文件名遵循 Phinx 规范，管理器会据此提取版本号并排序。

章节来源
- [20230320162718_migration_cmf_role_type.php:28-39](file://vendor/thinkcmf/cmf/src/data/migrations/20230320162718_migration_cmf_role_type.php#L28-L39)

### 安装流程中的迁移执行
- 安装控制器在安装过程中调用迁移命令，确保系统与各应用的迁移被执行，完成数据库初始化。

章节来源
- [IndexController.php:328-345](file://vendor/thinkcmf/cmf-install/src/install/controller/IndexController.php#L328-L345)

## 依赖关系分析
- Composer 依赖：xia/migration 提供 think\migration\Service 服务注册，内部使用 Phinx 核心组件。
- 配置依赖：Config 统一解析配置，支持 YAML/JSON/PHP 三种格式，支持环境变量令牌替换。
- 迁移依赖：Manager 负责迁移文件发现与加载，依赖 Config 的迁移路径与命名空间配置。

```mermaid
graph LR
CMF["ThinkCMF 应用"] --> XIA["xia/migration 包"]
XIA --> PHINX["Phinx 核心<br/>Console/Config/Manager"]
PHINX --> CMD["命令<br/>Migrate/Rollback/Create"]
PHINX --> CFG["配置<br/>Config.php"]
PHINX --> MGR["管理器<br/>Manager.php"]
PHINX --> ENV["环境<br/>Environment.php"]
```

图表来源
- [composer.lock:1121-1151](file://composer.lock#L1121-L1151)
- [Config.php:65-136](file://vendor/xia/migration/phinx/src/Phinx/Config/Config.php#L65-L136)
- [Manager.php:695-791](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php#L695-L791)

章节来源
- [composer.lock:1121-1151](file://composer.lock#L1121-L1151)
- [Config.php:266-307](file://vendor/xia/migration/phinx/src/Phinx/Config/Config.php#L266-L307)

## 性能考量
- 迁移执行时间：命令输出包含总耗时，便于评估迁移性能。
- 事务粒度：每个迁移在独立事务内执行，避免跨迁移的长事务锁竞争。
- 批量回滚：按执行顺序回滚，减少不必要的 SQL 生成与执行。
- 断点控制：通过断点避免误操作导致的大范围回滚，提升安全性。

章节来源
- [Migrate.php:135-139](file://vendor/xia/migration/phinx/src/Phinx/Console/Command/Migrate.php#L135-L139)
- [Rollback.php:122-129](file://vendor/xia/migration/phinx/src/Phinx/Console/Command/Rollback.php#L122-L129)
- [Manager.php:438-539](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php#L438-L539)

## 故障排除指南
- 环境不存在
  - 现象：提示环境不存在。
  - 排查：确认配置文件中是否存在该环境，或通过环境变量 PHINX_ENVIRONMENT 指定。
- 数据库名称缺失
  - 现象：无法确定数据库名。
  - 排查：在配置中为环境设置 name。
- 无效版本号
  - 现象：目标版本不存在。
  - 排查：使用迁移状态查看可用版本，或检查版本号格式。
- 断点拦截
  - 现象：回滚被断点阻止。
  - 排查：使用强制选项忽略断点，或先清除断点后再回滚。
- 迁移文件冲突
  - 现象：同版本或同名迁移冲突。
  - 排查：修改迁移文件名或版本号，确保唯一性。
- 日期格式错误
  - 现象：日期回滚格式不合法。
  - 排查：使用 YYYY[MM[DD[HH[II[SS]]]]] 格式。

章节来源
- [Migrate.php:76-97](file://vendor/xia/migration/phinx/src/Phinx/Console/Command/Migrate.php#L76-L97)
- [Rollback.php:87-104](file://vendor/xia/migration/phinx/src/Phinx/Console/Command/Rollback.php#L87-L104)
- [Manager.php:322-333](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php#L322-L333)
- [Manager.php:527-530](file://vendor/xia/migration/phinx/src/Phinx/Migration/Manager.php#L527-L530)
- [Create.php:168-194](file://vendor/xia/migration/phinx/src/Phinx/Console/Command/Create.php#L168-L194)
- [Rollback.php:141-167](file://vendor/xia/migration/phinx/src/Phinx/Console/Command/Rollback.php#L141-L167)

## 结论
ThinkCMF 的迁移体系基于 xia/migration 与 Phinx，提供了完整的迁移生命周期管理：从创建、执行、回滚到断点与日志记录。通过配置驱动与命令行工具，结合事务与断点机制，既保证了执行的安全性，也提升了可观测性与可维护性。建议在生产环境中配合备份策略与灰度发布，确保迁移过程的可控与可恢复。

## 附录

### 迁移命令速查
- 创建迁移
  - 命令：phinx create 或 php think migrate:create
  - 关键选项：模板、模板类、迁移路径
- 执行迁移
  - 命令：phinx migrate 或 php think migrate:run
  - 关键选项：环境、目标版本、日期、假执行
- 回滚迁移
  - 命令：phinx rollback 或 php think migrate:rollback
  - 关键选项：环境、目标版本、日期、强制、假执行

章节来源
- [Create.php:29-60](file://vendor/xia/migration/phinx/src/Phinx/Console/Command/Create.php#L29-L60)
- [Migrate.php:29-51](file://vendor/xia/migration/phinx/src/Phinx/Console/Command/Migrate.php#L29-L51)
- [Rollback.php:28-58](file://vendor/xia/migration/phinx/src/Phinx/Console/Command/Rollback.php#L28-L58)
- [AGENTS.MD:578-593](file://AGENTS.MD#L578-L593)