system-migration-development

# FastGPT 系统升级脚本开发规范 ## 目标与边界 系统升级任务属于 App 部署生命周期能力。框架负责顺序、状态、lease、并发互斥、重试入口和最终状态；脚本只负责可重复执行的业务迁移、进度、checkpoint，以及与阻塞类型匹配的错误报告方式。 开始前先查看当前实现，不能凭本 Skill 猜测已经变化的 Context 或目录结构： - `projects/app/src/migration/registry.ts` - `projects/app/src/migration/runner.ts` - `packages/global/migration/constants.ts` - `packages/global/migration/schema.ts` - `projects/app/src/migration/tasks/README.md` - 注册表中最近一个任务及其测试 如果这些路径正在迁移，以仓库中 `systemMigrations` 和 `SystemMigrationContext` 的实际定义为准。迁移执行框架和任务实现收敛到 `projects/app/src/migration`；需要被 App 前后端共同使用的状态枚举、Zod Schema 和 API 类型放在 `packages/global/migration`。 ## 编写前必须确认 先明确以下契约；存在会改变数据安全或启动行为的缺失信息时，向用户确认后再编码： 1. 永久稳定的任务 ID，格式为 `YYYYMMDD_short_semantic_name`，以及首次发布版本（对应版本目录去除点号，例如版本 `4.17.0` 对应目录 `4170`，`4.17.1` 对应 `4171`）。 2. 源数据、目标数据、权威数据源和迁移完成条件。 3. 该任务为什么必须排在当前注册表末尾，以及它依赖哪些前置任务。 4. 是否阻塞启动，以及失败后应停止还是继续后续任务；只有相互独立的非阻塞任务才能使用继续策略。 5. 恢复策略是“分批断点续跑”还是“幂等全量重跑”。该策略发布后不能切换。 6. 重复执行的幂等依据：唯一键、确定性覆盖、`$setOnInsert`、compare-and-set 或事务性全量重建。 7. 数据规模、预期耗时、批次大小和内存上界。 8. 坏数据是立即终止，还是跳过、汇总后由管理员修复再重试。 9. 滚动升级期间，旧版本节点是否仍能安全读写迁移中的结构。 10. 成功校验、失败回滚方式，以及需要展示给管理员的进度和错误定位数据。 不要用“目标表存在”“目标表非空”或当前数据形态替代任务状态。是否需要执行只能由静态注册表和迁移状态决定。 ## 基本要求 - 注册表只允许在数组尾部追加。已发布任务的 ID、顺序、`blockStartup`、`onFailure` 和函数语义不得修改、删除或复用；修复已发布迁移时追加新任务。 - 完整任务及其可能重放的最小单元必须幂等。Lease 只保证同一时刻的执行权，不提供 exactly-once。 - 默认追加或回填，不删除旧字段、旧集合、回滚依据或用户数据。破坏性清理应放到后续兼容窗口结束后的独立任务。 - 自动迁移必须兼容滚动升级；要求全站停机或会立即破坏旧版本的变更不能直接进入该注册表。 - 禁止不可重放的外部副作用，例如无幂等键的消息、扣费或第三方写入。 - 所有业务写入必须有确定性，不能根据不稳定排序、offset 分页或随机值决定结果。 - 修改目标前验证源数据；返回前校验完成条件。不能仅因函数没有抛错就假设迁移完成。 - 日志、进度、最终结果、checkpoint 和错误数据不得包含凭证、完整业务正文、超大对象或完整错误栈。 - 迁移专属实现不得放入业务 DDD 模块。业务模块可以被迁移单向依赖，但不能反向依赖迁移目录。 ## 状态与 Context ### 状态所有权 | 状态 | 谁负责写入 | 触发条件 | | --- | --- | --- | | `pending` | 框架 | 首次初始化，或管理员将非阻塞失败任务恢复为待执行 | | `running` | Runner | 原子获得 lease，并生成新的 `runId` | | `failed` | Runner / `context.fail` | 脚本明确报告失败，或普通异常被 Runner 捕获 | | `succeeded` | Runner | 脚本正常返回且当前 `runId` 仍持有有效 lease | 脚本禁止直接操作迁移状态表和错误数据表，也不得主动设置 `pending`、`running`、`failed` 或 `succeeded`。所有运行状态写入必须经过 Context，让框架统一执行 runId fencing 和输入校验。 ### 脚本可使用的状态能力 - `context.reportProgress(...)`：按注册表声明的阶段 `key` 更新该阶段快照。进入阶段时上报 `running`，完成后上报 `succeeded`；分批任务按合理频率更新 `current/total`，不要每条数据写一次。脚本不得主动上报 `failed`。 - `context.getCheckpoint(schema)`：读取并用任务自有 Zod Schema 校验断点。仅分批任务使用。 - `context.getFailedRecords()`：仅供非阻塞任务读取上次失败留下的坏数据。若任务曾跳过坏数据并把 checkpoint 推进到其后，重试时必须先处理这些记录；阻塞任务调用会被 Context 拒绝。 - `context.reportFailedRecords(records)`：仅供非阻塞任务按批替换“当前完整未解决错误快照”。业务批次提交后应先上报错误快照，再推进 checkpoint；替换语义保证批次重放不会重复追加同一错误。阻塞任务调用会被 Context 拒绝。 - `context.saveCheckpoint(value)`：只在一个幂等批次的业务事务完整提交、错误快照成功持久化并校验后保存。禁止先保存 checkpoint 再写业务数据或上报该批错误。 - `context.assertActive()`：确认当前 `runId` 仍持有 lease。每个业务写入批次前必须调用；全量任务至少在关键事务前及事务后的后续阶段前调用。 - `context.fail(...)`：保存可预期的结构化错误及最终错误快照，并终止本次执行。主要供需要在管理页面排障和重试的非阻塞任务使用；不要在调用后继续业务逻辑。阻塞任务通过该方法携带 `failedRecords` 会被拒绝。 - `context.logger`：记录诊断信息，框架会附加 migrationId、runId 和 runnerId。日志不能替代进度或结构化失败。 - `context.signal`：长计算或可取消 I/O 应响应中止信号。 正常返回表示脚本认为业务迁移和完成校验均已成功，由 Runner 标记 `succeeded` 并清理该任务的错误明细。任务可以返回有限标量的业务参数对象；Runner 校验后把参数与 `succeeded` 原子写入，列表接口再从静态注册表取得 `resultKey` 组装展示结果。`nameKey`、`descriptionKey`、`resultKey` 和阶段 `labelKey` 必须在注册表中使用 `i18nT(...)` 声明，禁止把 i18n key 写入 Mongo。不要自行调用完成状态更新，也不要用最后一条 progress 代替最终结果。 普通 `throw` 也会进入 `failed`，Runner 会把错误归属到当前 `running` 阶段，并保留任务之前通过 `reportFailedRecords` 上报的最新快照。只有 `context.fail` 显式携带 `failedRecords`（包括空数组）时才替换或清空旧快照。非阻塞任务的已知数据问题应维护完整未解决错误快照：处理中按批调用 `context.reportFailedRecords`，扫描结束仍有异常时再调用 `context.fail` 写入相同最终快照。错误对象只保存原始 `message`，不得携带 i18n key 或模板参数；每条错误数据必须包含已声明的 `stageKey`，只保存必要 ID 和原因，不复制原文档。框架按阶段记录异常数量，管理员从对应阶段按需打开详情。阻塞任务失败时管理页面本身不可用，应通过 `context.logger` 输出必要诊断后抛出异常；Context 会拒绝其读写错误明细，Runner 只把多节点协调所需的最小 `lastError` 写入状态表。 ## 选择恢复策略 任务一旦获得新 runId，无论入口是管理员重置还是过期 lease 接管，都使用同一恢复策略：保留 checkpoint、progress 和最近错误；非阻塞任务还会保留供修复使用的错误明细。但触发条件不同：`running` 的 lease 过期可自动接管，阻塞 `failed` 在 owner 重启、lease 过期后可接管，非阻塞 `failed` 必须由管理员重置为 `pending`。脚本如何恢复由发布时选定的策略决定。 ### 分批断点续跑 适用于数据量较大、执行时间不可控、无法在一个短事务内完成，或需要跳过坏数据继续扫描的任务。 每次执行必须覆盖三种输入状态： 1. 无 checkpoint、无错误数据：从稳定排序的起点开始。 2. 有 checkpoint、无错误数据：从最后完整提交的批次之后继续。 3. 有 checkpoint、有错误数据：先重新处理已跳过的错误记录，再从 checkpoint 继续扫描新数据。 推荐循环： ```text 读取并校验 checkpoint 读取 failedRecords，建立完整未解决错误快照并优先重试 while 还有数据: assertActive 按稳定游标读取下一批 在业务事务中执行幂等写入 校验该批结果并提交事务 如果错误快照变化，reportFailedRecords(完整未解决错误快照) saveCheckpoint reportProgress 执行全局完成校验 如果仍有错误，fail(包含相同最终错误快照) reportProgress(completed) return ``` 关键约束： - 使用 `_id` 或其他不可变、唯一且有索引的游标；不要使用 offset。 - 进程可能在业务提交后、checkpoint 保存前退出，因此整个批次必须可重复执行。 - checkpoint 只记录恢复所需的最小游标，不保存业务正文或不断增长的数组。 - `reportFailedRecords` 接收的是完整快照而不是新增项；不得逐条 append，也不得只上报当前批次，否则会覆盖之前仍未解决的错误。 - 错误快照必须先于对应 checkpoint 持久化。若进程在两者之间退出，接管节点会从旧 checkpoint 重放该批，并能读取已经保存的错误；禁止反向调用造成坏数据被 checkpoint 永久跳过。 - 错误快照已上报后又发生未预期异常时，Runner 会保留该快照；任务不得为了上报新异常而传入不完整的错误数组。 - 扫描结束仍有失败项时调用 `context.fail({ failedRecords })`，其中 `failedRecords` 与最近一次上报的完整快照一致。 - 重试后再次失败会替换旧错误明细；完整成功后由框架删除。 ### 幂等全量重跑 仅适用于数据量确定较小、资源消耗有上界、结果由权威源确定，且整次写入可以保持原子或安全幂等的任务。 推荐流程： ```text reportProgress(started) 读取完整权威源 在修改目标前完成全部转换、去重和校验 assertActive 原子写入或确定性覆盖完整结果 assertActive 刷新缓存并执行完成校验 reportProgress(completed) return ``` 关键约束： - 不保存没有恢复意义的伪 checkpoint。每次管理员重试或 lease 接管都重新执行完整流程。 - 如果需要清空目标，目标必须完全由权威源派生，不包含用户增量；权威源必须保留。 - 清空和完整重建必须在同一事务中，失败时不能暴露空表或半成品。 - 源数据必须在清空目标前完成校验；重复执行和源数据修复后再执行都应产生确定结果。 - 如果全量操作无法在 lease 内稳定完成，改用分批策略，而不是单纯调大 lease。 ## 阻塞与非阻塞 `blockStartup` 只决定节点 readiness，`onFailure` 只决定失败后是否暂停后续队列；所有任务仍严格按注册表顺序单线程执行。 - 选择阻塞任务：目标 Schema、配置或数据是新版本处理流量的必要前提。任一阻塞任务未成功，节点不能 ready。 - 选择非阻塞任务：新旧数据均可被业务兼容读取，迁移可在节点 ready 后后台完成。 - 阻塞任务的阶段进度仍通过 `reportProgress` 保存最新快照并同步输出阶段日志；具体错误诊断写终端日志，不写 `failedRecords`。状态表中的最小 `lastError` 仅用于跨节点观察失败事实，不承担错误日志存储职责。 - 阻塞任务明确失败后，owner 持续持有 lease 并等待；修复后需要重启 owner，lease 过期后由一个节点接管。 - 非阻塞任务明确失败后不自动重试；管理员查看错误、修复数据后点击重试，任务重新竞争 lease。 - `onFailure: 'continue'` 只允许相互独立的非阻塞任务使用：当前任务保持 `failed` 且等待管理员重试，Runner 可以跳过它继续后续任务；`stop` 则暂停后续队列。 - 位于后续阻塞任务之前且使用 `onFailure: 'stop'` 的非阻塞任务仍是启动前置条件；`continue` 任务失败后允许后续阻塞任务推进，因此必须确认二者没有成功依赖。 ## 文件位置 迁移执行框架、静态注册表、Mongo Schema、服务端执行逻辑和任务集中在 App；前后端公共契约位于 global： ```text packages/global/migration/ ├── constants.ts └── schema.ts projects/app/src/migration/ ├── constants.ts ├── registry.ts ├── runner.ts ├── entity.ts ├── service.ts ├── mongoSchema.ts ├── utils.ts └── tasks/ ├── README.md └── <version>/ └── <migration-id>/ ├── index.ts ├── service.ts └── utils.ts ``` - `index.ts` 只负责任务编排、Context 调用和进度阶段。 - 迁移任务必须按 `tasks/<version>/<migration-id>/` 目录规范定义，严禁在 `tasks/` 根目录下平铺存放迁移脚本。其中 `<version>` 对应发布版本（无点号，如 `4.17.0` 对应 `4170`，`4.17.1` 对应 `4171`），`<migration-id>` 为具体迁移任务 ID。 - 同一版本内多个迁移任务共享的辅助逻辑、类型或转换工具，应收敛在该版本的公共子目录内（例如 `tasks/<version>/<shared_helper_dir>/`），严禁在 `tasks/` 根目录下平铺。 - `packages/global/migration` 只保存前后端共享的状态枚举、有限输入 Schema 和 API 类型，不放任务实现、Mongo Model 或 Runner。 - 注册项必须按执行顺序声明完整的 `progressSteps: [{ key, labelKey }]`；`key` 是永久稳定的机器标识，`labelKey` 放在 client-only `system_migration` i18n namespace，不写入 Mongo。 - 该任务专属的数据访问、转换和工具函数全部放在同名目录，不要散落到 `packages/global` 或 `packages/service`。 - 真正被正常运行期业务复用的能力保留在业务模块；迁移通过单向依赖调用它。 - Next.js API 路由和页面受框架目录约束，可以保留在 `pages/api`、`pages/config`，但必须是调用 migration service 的薄入口，不承载迁移逻辑。 - i18n 文案按项目现有机制放入所有语言文件；任务注册项使用 `i18nT(...)` 保存稳定的 name、description、result 和 progress label key。 - i18n key 只属于静态注册表和 API 展示 DTO，禁止写入状态表或错误明细表。成功结果只持久化有限标量参数，错误只持久化原始 `message`。 - 测试放在 `projects/app/test/migration/` 下并严格镜像源码子路径（即 `projects/app/test/migration/tasks/<version>/<migration-id>/`）。 ## 测试与验证 新增任务至少验证与其恢复策略相关的真实不变量，不写只匹配文案的测试。 通用场景： - 首次执行成功，完成条件真实成立。 - 重复执行不会产生重复、覆盖错误数据或改变不应变化的结果。 - 源数据无效时不会留下部分目标数据，并能给出可定位错误。 - 业务写入或完成校验失败时不会被标记成功。 - 进度阶段、失败记录和日志不包含敏感或无界数据。 - 每个阶段均按 `running -> succeeded` 上报；任务返回前所有声明阶段都已成功，阶段异常和错误数据使用正确的 `stageKey`。 - 最终结果只在任务成功后存在；Mongo 只含参数，列表接口从注册表补入 key 后能渲染出预期业务结果。 - 任务注册在数组尾部，ID 唯一，`blockStartup` 和 `onFailure` 符合数据依赖。 分批任务额外验证： - 从 checkpoint 恢复，不重扫已完成范围。 - 业务提交后、checkpoint 前退出时，重复批次仍然正确。 - checkpoint 与错误记录同时存在时，错误记录会被重新处理。 - 错误快照会在每批后替换持久化，且崩溃发生在错误上报与 checkpoint 之间时不会丢失或重复追加坏数据。 - 错误快照之后发生普通异常时，已保存的坏数据不会被空数组覆盖。 - 中途丢失 lease 后不再开始新的业务批次或保存状态。 - 阻塞任务调用 `getFailedRecords`、`reportFailedRecords` 或通过 `fail` 携带 `failedRecords` 时会被 Context 拒绝。 全量任务额外验证： - 目标已有旧数据时仍能完整覆盖为权威结果。 - 写入失败会回滚清空和部分写入。 - 修改权威源后再次运行会产生对应的新结果。 - 空源数据的行为经过明确设计和测试，不能默认为安全。 只运行覆盖改动范围的局部测试、App typecheck、相关 ESLint 和 `git diff --check`。用户最终验收前不主动运行全量测试。若修改 API 路由或入参，继续遵守 `api-development` Skill；若新增单元测试，继续遵守 `test-case` Skill。 ## 交付前检查 - [ ] 已确认恢复策略，并在任务函数注释中说明选择原因。 - [ ] 已证明任务整体及重放单元幂等。 - [ ] 只在注册表末尾追加，未修改已发布任务语义。 - [ ] 脚本未直接操作迁移状态表或错误数据表。 - [ ] 必需进度、lease 检查、完成校验和与阻塞类型匹配的失败出口均已实现。 - [ ] 需要展示最终产出时已由任务返回有限的 i18n 结果，并由 Runner 随成功终态提交。 - [ ] checkpoint 保存时机正确，或全量任务明确不使用 checkpoint。 - [ ] 分批任务在 checkpoint 前及时替换完整错误快照，没有只在任务末尾一次性保存坏数据。 - [ ] 阻塞任务只写终端诊断和最小 `lastError`，没有调用错误明细能力。 - [ ] 启动阻塞、失败调度策略、滚动升级兼容性和破坏性操作均已审查。 - [ ] 任务代码与测试严格按 tasks/<version>/<migration-id>/ 规范组织并镜像测试目录，不平铺在 tasks 根目录下，不污染业务模块。 - [ ] 局部测试、类型检查、lint 和差异检查通过。