nocobase-publish-manage

目标

使用当前 API CLI 命令集编排 NocoBase 备份恢复和迁移工作流。

该技能会将用户意图转换为以 API 为先的发布上下文，在各步骤间传递生成的名称和本地路径，并要求在恢复或迁移执行会更改目标数据之前获得明确确认。

范围

• 通过 nb api backup 列出、创建、查看状态、下载、移除和恢复备份，以及上传备份并查看恢复状态。
• 通过 nb api migration 列出、获取、创建、下载、移除、检查和执行迁移文件。
• 通过 nb api migration rules 列出、获取和创建全局迁移规则。
• 通过 nb api migration logs 列出、获取和下载迁移日志以进行诊断。
• 同环境和跨环境工作流。默认测试工作流使用 source_env=dev 和 target_env=dev。
• 根据命令输出进行规划、干运行说明、只读验证和故障诊断。

非目标

• 此技能专注于范围中列出的 API CLI 命令集。
• 软件包和规则的选择必须明确指定。
• 恢复、执行和移除操作必须通过执行确认关卡。
• 故障恢复会保留当前上下文，并在创建新软件包或规则前等待用户指示。

输入约定

输入	必填	默认值	验证	澄清
action	是	推断	plan、run 或 validate	“应该规划、运行还是验证工作流？”
method	运行时必填	推断	backup 或 migration	“使用备份恢复还是迁移发布？”
source_env	有条件必填	测试时为 dev	非空环境名称	“哪个环境提供或生成文件？”
target_env	运行时必填	测试时为 dev	非空环境名称	“文件应在哪个环境接收并执行？”
backup_name	可选	未设置	来自 backup list/create 的备份文件名	“要恢复或下载哪个服务器备份？”
migration_name	可选	未设置	来自 migration list/create 的迁移文件名	“要下载哪个服务器迁移软件包？”
local_file	可选	未设置	可读取的本地 .nbdata 路径	“要上传或执行哪个本地软件包文件？”
cli_home	可选	CLI 全局主目录	可写的 CLI 主目录	“应将下载的发布文件存储在哪个 CLI 主目录中？”
rule_id	仅创建迁移时	未设置	非空 ID	“要使用哪个迁移规则 ID？”
migration_user_rule	仅创建迁移规则时	schema-only	schema-only 或 overwrite	“如何处理用户定义的表？”
migration_system_rule	仅创建迁移规则时	overwrite-first	overwrite-first 或 schema-only	“如何处理系统表？”
title	仅创建迁移时	publish-<source>-to-<target>	非空文本	“要使用哪个迁移标题？”
execute_options	可选	CLI 安全默认值	已知的 nb api backup restore* 或 nb api migration execute 标志	“是否有 --skip-backup 或 --skip-revert-on-error 等高风险标志？”
confirm_publish_input	创建、下载、创建规则或检查前	未设置	明确批准	“请确认所选输入，然后我再创建、下载或检查软件包。”
confirm_execute	恢复、执行或移除前	未设置	必须为 confirm	“输入 confirm，以在目标环境执行。”

强制澄清关卡

• 最多澄清 2 轮。
• 每轮最多提出 3 个简短问题。
• 变更步骤要求已明确 method、source_env 和 target_env。
• 创建迁移包要求选择或新建 rule_id。
• 列出现有包的流程要求用户选择一个具体文件。
• 创建包、下载包、创建迁移规则和检查迁移均要求确认发布输入。
• 恢复备份、上传并恢复备份、删除备份、执行迁移和删除迁移均要求确认执行。
• 如果用户说“由你决定”，请选择只读规划路径。

工作流

1. 将意图路由到 backup 或 migration。
2. 构建包含 method、sourceEnv、targetEnv、cliHome、releaseDir、backupName、migrationName、localFile、downloadPath、ruleId、title 和 step 的上下文。
3. 对所需的命令组运行只读能力探测。将 404、Not Found、未知资源、未激活的插件或许可证能力错误视为 unsupported_publish_env。
4. 对于备份恢复：
   • 本地文件：确认文件，然后使用 nb api backup restore-upload --file <localFile> -e <targetEnv> --force 恢复。
   • 目标环境上的服务端备份：确认备份名称，然后使用 nb api backup restore --name <backupName> -e <targetEnv> --force 恢复。
   • 从源环境迁移到目标环境：在 sourceEnv 上创建或选择备份，将其下载到 <cliHome>/release/<sourceEnv>/<backupName>，然后在 targetEnv 上使用 --force 恢复该路径。
5. 对于迁移：
   • 本地文件：确认文件，在 targetEnv 上检查，然后在 targetEnv 上执行。
   • 服务端迁移包：将其从 sourceEnv 下载到 <cliHome>/release/<sourceEnv>/<migrationName>，在 targetEnv 上检查，然后执行。
   • 创建迁移包：列出或创建全局规则，在 sourceEnv 上创建迁移，轮询 migration get，直到生成的包报告 status=ok，将其下载到 <cliHome>/release/<sourceEnv>/<migrationName>，在 targetEnv 上检查，然后执行。
6. 必要时，使用可用命令轮询或检查状态：backup status、backup restore-status --task <taskId>、migration get 和 migration logs。
7. 将恢复任务 ID 视为兼容字段：从 data.taskId 或 data.task 解析 taskId，然后将该值传递给 backup restore-status --task。
8. 报告最终状态、已执行或计划执行的命令、文件名、本地路径、失败步骤以及下一条验证命令。

有关精确的命令构造和解析规则，请参阅 运行时契约。

参考资料加载映射

参考资料	使用时机
意图路由	将用户表述映射到备份、迁移、文件复用和环境形态。
运行时契约	构建命令，并在步骤间传递名称、路径、规则和状态。
测试手册	验证受支持的 API 工作流和故障场景。

安全门禁

高影响操作：

• nb api backup restore
• nb api backup restore-upload
• nb api backup remove
• nb api migration execute
• nb api migration remove
• nb api migration rules create
• 任何会跳过目标备份或回滚行为的选项，例如 --skip-backup 或 --skip-revert-on-error

发布输入确认模板：

Confirm publish input: <method> from <source_env> to <target_env>. Package source: <existing server file | local file | create new>. Migration rule: <ruleId/name | create new with user-defined-rule/system-defined-rule | not applicable>. Reply `confirm input` to continue with package creation, download, or check.

执行确认模板：

Confirm execution: <backup restore | migration execute> on <target_env> using <backupName | migrationName | localFile>. This may change target data. Reply `confirm` to continue.

失败处理指南：

• 备份恢复失败：如果可从 data.taskId 或 data.task 获取恢复任务 ID，请检查 nb api backup restore-status --task <taskId> -e <targetEnv>。
• 创建迁移包：如果 migration get 报告 status=in_progress，请告知用户该迁移包仍在生成中，等待其完成，并且在 status=ok 前不要运行 migration download。
• 迁移检查失败：报告检查输出，并保留本地迁移包路径。
• 迁移执行失败：检查 nb api migration logs list -e <targetEnv> 以及相关的 logs get/download 输出。
• 失败后重新创建迁移包或规则需要用户明确指示。
• 在最终回复中保留上下文，以便用户可以从正确的文件或规则继续操作。

验证清单

• 发布操作使用 nb api backup 和 nb api migration 命令组。
• 默认测试上下文为 sourceEnv=dev 和 targetEnv=dev。
• 参与操作的环境在变更前通过只读命令探测。
• 能力探测失败时，报告 unsupported_publish_env。
• 迁移包列表和迁移规则列表应引导用户进行明确选择。
• 如果本地文件已存在，则跳过迁移包创建。
• 在同一目标环境内恢复时，现有服务器备份名称可以使用 backup restore --name。
• 跨环境备份恢复使用 backup download，然后使用 backup restore-upload --force。
• 备份恢复和 restore-upload 命令直接包含 --force。
• 下载的备份、迁移包和日志文件存储在 <cliHome>/release/<sourceEnv>/ 下。
• 迁移执行前，使用本地迁移包文件运行 migration check --file，然后再运行 migration execute --file。
• 缺少迁移文件时，先列出迁移规则，再询问或创建 rule_id。
• migration rules create 使用全局规则选项。
• 在可行时，使用 migration rules get 验证已创建或选定的迁移规则。
• 下载命令包含 --output。
• 恢复状态命令包含 --task <taskId>，且仅在返回 data.taskId 或 data.task 任务 ID 后运行。
• 恢复或执行操作需等待二次确认。
• 失败输出包含失败步骤和相关 CLI 行。

参考资料

• 意图路由
• 运行时契约
• 测试手册
• NocoBase 迁移管理器：迁移风险和发布相关操作的官方背景资料。[已验证：2026-04-30]