nocobase-publish-manage
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseGoal
目标
Provide a deterministic release workflow for NocoBase applications with explicit risk gates, Node-only execution scripts, and machine-parseable verification output.
为NocoBase应用提供具有明确风险关卡、仅Node执行脚本和机器可解析验证输出的确定性发布工作流。
Scope
适用范围
- Handle release channel routing: ,
local_cli,remote_api.remote_ssh_cli - Handle release method routing:
- : source backup artifact download + target upload restore.
backup_restore - : source rule create/generate/download + target check/up.
migration
- Enforce pre-release checks:
- source/target environment presence and CLI readiness
- target commercial capability via
plugin-migration-manager - required plugin readiness (,
migration_manager)backup_manager
- Enforce release safety:
- /
publishapply confirmation (rollback)--confirm confirm - method confirmation hard gate ()
--publish-method-confirm - backup artifact selection hard gate for
backup_restore - auto-backup by default before target mutation
- Provide resource-level adapters for release-critical plugin interfaces:
- backups (+
backups:*)backupSettings:* - migration manager (,
migrationRules:*,migrationFiles:*)migrationLogs:*
- backups (
- Keep release execution Node-only and hand off app environment lifecycle to .
nocobase-env-bootstrap
User-facing publish method copy (internal key -> display text):
- ->
backup_restoreUse existing backup package - ->
migrationCreate new release package
Migration template presets (independent rules are always disabled):
- -> user-defined=
schema_only_all, system=schema-onlyschema-only - -> user-defined=
user_overwrite_only, system=overwriteschema-only - -> user-defined=
system_overwrite_only, system=schema-onlyoverwrite-first - -> user-defined=
full_overwrite, system=overwriteoverwrite-first
- 处理发布渠道路由:、
local_cli、remote_api。remote_ssh_cli - 处理发布方式路由:
- :源环境备份制品下载 + 目标环境上传恢复。
backup_restore - :源环境规则创建/生成/下载 + 目标环境检查/更新。
migration
- 执行发布前预检查:
- 源/目标环境存在性及CLI就绪状态
- 通过检测目标环境商业功能
plugin-migration-manager - 必备插件就绪状态检测(、
migration_manager)backup_manager
- 保障发布安全性:
- /
publish执行确认(rollback)--confirm confirm - 发布方式强制确认关卡()
--publish-method-confirm - 方式下的备份制品选择强制关卡
backup_restore - 目标环境变更前默认自动备份
- 为发布关键插件接口提供资源级适配器:
- 备份(+
backups:*)backupSettings:* - 迁移管理器(、
migrationRules:*、migrationFiles:*)migrationLogs:*
- 备份(
- 发布执行仅保留Node环境,应用环境生命周期交由处理。
nocobase-env-bootstrap
面向用户的发布方式显示文本(内部标识→展示文本):
- → 使用现有备份包
backup_restore - → 创建新发布包
migration
迁移模板预设(独立规则始终禁用):
- → 用户自定义=仅架构,系统=仅架构
schema_only_all - → 用户自定义=覆盖,系统=仅架构
user_overwrite_only - → 用户自定义=仅架构,系统=优先覆盖
system_overwrite_only - → 用户自定义=覆盖,系统=优先覆盖
full_overwrite
Non-Goals
不包含内容
- Do not modify NocoBase server source code.
- Do not assume fixed backup/migration action names across every plugin version.
- Do not execute destructive actions silently.
- Do not hide partial failures as success.
- Do not rely on shell scripts (/
.sh) for release flow..ps1
- 不修改NocoBase服务端源代码。
- 不假设所有插件版本的备份/迁移操作名称固定。
- 不静默执行破坏性操作。
- 不将部分失败伪装为成功。
- 不依赖Shell脚本(/
.sh)实现发布流程。.ps1
Input Contract
输入约定
| Input | Required | Default | Validation | Clarification Question |
|---|---|---|---|---|
| yes | none | one of | "Run precheck, publish, verify, or rollback?" |
| yes | none | one of | "Use backup_restore or migration?" |
| conditional | empty | required when | "Please confirm release method with --publish-method-confirm <same-as-method>." |
| no | | one of | "Should I force a channel?" |
| conditional | none | required when migration publish executes; one of | "For migration, choose one preset: schema_only_all, user_overwrite_only, system_overwrite_only, or full_overwrite." |
| no | | valid env name when provided | "Which source env should be used?" |
| no | | valid env name when provided | "Which target env should be used?" |
| no | empty | valid HTTP(S) URL | "Do you want to force a source URL?" |
| no | empty | valid HTTP(S) URL | "Do you want to force a target URL?" |
| no | empty | env var name | "Which env var stores source token?" |
| no | | env var name for remote API | "Which env var stores target token?" |
| no | | boolean | "Should auto-backup be enabled?" |
| conditional | none | required for | "Which backup artifact should be used?" |
| no | | boolean | "Should I execute now or only generate a plan?" |
| publish/rollback apply: yes | none | must be | "Please type confirm to continue high-risk execution." |
| no | current directory | existing path | "Which base directory should commands run in?" |
| no | | one of | "Use project scope or global scope?" |
| no | | one of | "Prefer global ctl or local ctl?" |
| remote_ssh_cli: yes | empty | non-empty host | "What SSH host should be used?" |
| remote_ssh_cli: yes | empty | non-empty path | "What app path on SSH host should be used?" |
Rules:
- Default command entrypoint: .
node ./scripts/publish-manage.mjs ... - Local CLI wrapper: .
node ./scripts/run-ctl.mjs ... - App environment lifecycle () must be handled by
add/use/current/list, not by this skill.$nocobase-env-bootstrap task=app-manage ... - Migration template policy source is code-only: .
scripts/migration-template-rules.mjs - If required inputs are missing, stop mutation and return blocker list.
- If user says "you decide", use defaults in this table.
| 输入项 | 是否必填 | 默认值 | 校验规则 | 确认问题 |
|---|---|---|---|---|
| 是 | 无 | 必须为 | "要执行预检查、发布、验证还是回滚?" |
| 是 | 无 | 必须为 | "使用backup_restore还是migration方式?" |
| 条件必填 | 空 | 当 | "请通过--publish-method-confirm <与method一致的值>确认发布方式。" |
| 否 | | 必须为 | "是否要强制指定发布渠道?" |
| 条件必填 | 无 | 执行migration发布时必填;必须为 | "对于migration方式,请选择一个预设:schema_only_all、user_overwrite_only、system_overwrite_only或full_overwrite。" |
| 否 | | 提供时需为有效环境名称 | "应使用哪个源环境?" |
| 否 | | 提供时需为有效环境名称 | "应使用哪个目标环境?" |
| 否 | 空 | 有效HTTP(S) URL | "是否要强制指定源URL?" |
| 否 | 空 | 有效HTTP(S) URL | "是否要强制指定目标URL?" |
| 否 | 空 | 环境变量名称 | "哪个环境变量存储源环境令牌?" |
| 否 | | 远程API的环境变量名称 | "哪个环境变量存储目标环境令牌?" |
| 否 | | 布尔值 | "是否启用自动备份?" |
| 条件必填 | 无 | | "应使用哪个备份制品?" |
| 否 | | 布尔值 | "是立即执行还是仅生成计划?" |
| publish/rollback执行时:是 | 无 | 必须为 | "请输入confirm以继续高风险操作。" |
| 否 | 当前目录 | 存在的路径 | 命令应在哪个基础目录下运行?" |
| 否 | | 必须为 | "使用项目范围还是全局范围?" |
| 否 | | 必须为 | "优先使用全局ctl还是本地ctl?" |
| remote_ssh_cli时:是 | 空 | 非空主机地址 | "应使用哪个SSH主机?" |
| remote_ssh_cli时:是 | 空 | 非空路径 | "SSH主机上的应用路径是什么?" |
规则:
- 默认命令入口:。
node ./scripts/publish-manage.mjs ... - 本地CLI包装器:。
node ./scripts/run-ctl.mjs ... - 应用环境生命周期()必须由
add/use/current/list处理,而非本技能。$nocobase-env-bootstrap task=app-manage ... - 迁移模板策略仅通过代码定义:。
scripts/migration-template-rules.mjs - 若必填输入项缺失,停止变更并返回阻塞项列表。
- 若用户说"你决定",使用本表中的默认值。
Mandatory Clarification Gate
强制确认关卡
- Max clarification rounds: .
2 - Max questions per round: .
3 - Before mutation (/
publishwith apply):rollback- and
methodare resolvedchannel - source and target context are resolved (,
source_url/source_envor ssh target)target_url/target_env - auth is ready for
remote_api - is explicitly set when
migration_templatemethod=migration- when missing, runtime must return with 4 presets
action_required.type=choose_migration_template
- when missing, runtime must return
- equals
publish_method_confirmwhenmethodaction=publish - is selected when
backup_artifactaction=publish + method=backup_restore - secondary confirmation is provided ()
confirm
- If these checks are not met, stop and return blocker items plus .
action_required
Anti-inference policy:
- Do not infer publish method/template/artifact from generic publish requests.
- For ambiguous input such as "publish local to 19000", run precheck only and ask user to choose.
- If runtime returns any choice gate, stop and wait for user response.
action_required
Deterministic keyword routing:
- Follow references/intent-routing.md exactly.
- Conflict (+
restorein one request) must stop execution and ask user to choose one intent.migration
- 最大确认轮次:。
2 - 每轮最多问题数:。
3 - 执行变更前(/
publish且apply=true):rollback- 和
method已确定channel - 源和目标上下文已确定(、
source_url/source_env或SSH目标)target_url/target_env - 的认证已就绪
remote_api - 当时,
method=migration已明确设置migration_template- 若缺失,运行时必须返回并提供4个预设选项
action_required.type=choose_migration_template
- 若缺失,运行时必须返回
- 当时,
action=publish等于publish_method_confirmmethod - 当时,已选择
action=publish + method=backup_restorebackup_artifact - 已提供二次确认()
confirm
- 若未通过这些检查,停止操作并返回阻塞项及。
action_required
反推断策略:
- 不从通用发布请求中推断发布方式/模板/制品。
- 对于模糊输入如"publish local to 19000",仅执行预检查并询问用户选择。
- 若运行时返回任何选择关卡,停止操作并等待用户响应。
action_required
确定性关键词路由:
- 严格遵循references/intent-routing.md。
- 若出现冲突(同一请求中同时包含和
restore),必须停止执行并要求用户选择一个意图。migration
Workflow
工作流
- Normalize and validate input.
- Read environment inventory via CLI wrapper: .
node ./scripts/run-ctl.mjs -- env list -s <scope> - If CLI env inventory fails, hand off to for repair.
$nocobase-env-bootstrap task=app-manage ... - Check source/target env existence and run CLI update checks for both envs.
- If env is missing or CLI check fails, hand off to .
$nocobase-env-bootstrap task=app-manage ... - Resolve source/target URLs and release channel (allowed).
auto - Run for target env:
pm list- detect commercial capability via
plugin-migration-manager - detect required release plugins (,
migration_manager)backup_manager - if plugin inactive/missing, hand off to
$nocobase-plugin-manage enable ... - if commercial capability missing, return purchase URL and restart guidance
- detect commercial capability via
- Run method-specific gates:
- : enforce
publish + apply=true--publish-method-confirm <same-as--method> - : query latest 5 source backup artifacts and enforce
publish + method=backup_restore + apply=true--backup-artifact - : enforce migration preset selection (
publish + method=migration + apply=true)--migration-template - migration template safety checks (/
schema_only_all/user_overwrite_only/system_overwrite_only)full_overwrite
- Build command plan (with explicit ):
exec_context- publish:
backup_restore- source:
backup_download - target: (if
backup_create)backup_auto=true - target:
backup_upload
- source:
- publish:
migration- source:
migration_rules_create - source: (
migration_generate)ruleIdRef=latest_migration_rule - source:
migration_files_download - target: (if
backup_create)backup_auto=true - target:
migration_files_check - target:
migration_up
- source:
- Execute plan only when ; otherwise return dry-run plan.
apply=true - Verify result and output :
verificationpassedfailed- (when plan-only)
pending_verification
- Return structured output with next-step instructions.
- 标准化并验证输入。
- 通过CLI包装器读取环境清单:。
node ./scripts/run-ctl.mjs -- env list -s <scope> - 若CLI环境清单读取失败,交由修复。
$nocobase-env-bootstrap task=app-manage ... - 检查源/目标环境存在性,并对两个环境运行CLI更新检查。
- 若环境缺失或CLI检查失败,交由处理。
$nocobase-env-bootstrap task=app-manage ... - 解析源/目标URL及发布渠道(允许)。
auto - 对目标环境运行:
pm list- 通过检测商业功能
plugin-migration-manager - 检测必备发布插件(、
migration_manager)backup_manager - 若插件未激活/缺失,交由处理
$nocobase-plugin-manage enable ... - 若缺失商业功能,返回购买链接及重启指引
- 通过
- 执行特定方式的关卡检查:
- :强制要求
publish + apply=true--publish-method-confirm <与method一致的值> - :查询源环境最新5个备份制品并强制要求
publish + method=backup_restore + apply=true--backup-artifact - :强制选择迁移预设(
publish + method=migration + apply=true)--migration-template - 迁移模板安全检查(/
schema_only_all/user_overwrite_only/system_overwrite_only)full_overwrite
- 构建命令计划(包含明确的):
exec_context- 发布:
backup_restore- 源环境:
backup_download - 目标环境:(若
backup_create)backup_auto=true - 目标环境:
backup_upload
- 源环境:
- 发布:
migration- 源环境:
migration_rules_create - 源环境:(
migration_generate)ruleIdRef=latest_migration_rule - 源环境:
migration_files_download - 目标环境:(若
backup_create)backup_auto=true - 目标环境:
migration_files_check - 目标环境:
migration_up
- 源环境:
- 仅当时执行计划;否则返回试运行计划。
apply=true - 验证结果并输出状态:
verification- (通过)
passed - (失败)
failed - (仅计划时)
pending_verification
- 返回结构化输出及下一步操作指引。
Reference Loading Map
参考加载映射
| Reference | Use When | Notes |
|---|---|---|
| references/v1-runtime-contract.md | implementing action/channel/method matrix | canonical behavior contract |
| references/intent-routing.md | mapping user keywords to intent/method flow | deterministic anti-inference routing |
| references/test-playbook.md | verifying skill behavior | prompt-ready acceptance set |
| publish-resource-adapter.mjs | any release mutation/readback | unified resource templates for backup/migration operations |
| run-ctl.mjs | any ctl command execution | local/global nocobase-ctl resolver |
| publish-manage.mjs | publish orchestration | precheck/publish/verify/rollback entrypoint |
| 参考文档 | 使用场景 | 说明 |
|---|---|---|
| references/v1-runtime-contract.md | 实现action/channel/method矩阵 | 标准行为约定 |
| references/intent-routing.md | 将用户关键词映射到意图/方式流程 | 确定性反推断路由 |
| references/test-playbook.md | 验证技能行为 | 可直接用于测试的验收用例集 |
| publish-resource-adapter.mjs | 任何发布变更/回读操作 | 备份/迁移操作的统一资源模板 |
| run-ctl.mjs | 任何ctl命令执行 | 本地/全局nocobase-ctl解析器 |
| publish-manage.mjs | 发布编排 | 预检查/发布/验证/回滚入口 |
Safety Gate
安全关卡
High-risk actions:
- in apply mode
publish - in apply mode
rollback - with overwrite templates (
migration,user_overwrite_only,system_overwrite_only)full_overwrite
Mandatory hard gates before publish apply:
--confirm confirm--publish-method-confirm <same-as--method>- for
--backup-artifact <name>backup_restore
Secondary confirmation template:
- "Confirm execution: with method
{{action}}on target{{method}}. Impact: target data may be overwritten or restored. Reply{{target}}to continue."confirm
Rollback guidance:
- Trigger rollback when fails after partial write.
publish - Rollback steps:
- identify latest valid backup artifact
- execute rollback with explicit confirmation
- run action and compare key health signals
verify
高风险操作:
- 执行模式下的
publish - 执行模式下的
rollback - 使用覆盖模板的(
migration、user_overwrite_only、system_overwrite_only)full_overwrite
发布执行前的强制关卡:
--confirm confirm--publish-method-confirm <与method一致的值>- 方式下的
backup_restore--backup-artifact <名称>
二次确认模板:
- "确认执行:,方式为
{{action}},目标环境为{{method}}。影响:目标环境数据可能被覆盖或恢复。回复{{target}}继续。"confirm
回滚指引:
- 当执行失败且已部分写入数据时触发回滚。
publish - 回滚步骤:
- 识别最新的有效备份制品
- 执行回滚并要求明确确认
- 运行操作并对比关键健康指标
verify
Change Window
变更窗口
- Prefer a maintenance window for publish/rollback apply mode.
- Avoid long-running data writes during business peak periods.
- 优先在维护窗口执行publish/rollback的执行模式。
- 避免在业务高峰期执行长时间的数据写入操作。
Approval Chain
审批流程
- Require business owner approval before first production rollout.
- Require technical owner approval before .
migration full_overwrite
- 首次生产环境发布前需业务负责人审批。
- 执行前需技术负责人审批。
migration full_overwrite
Rollback Drill
回滚演练
- Dry-run rollback plan before production release.
- Keep at least one known-good backup artifact ID per target.
- 生产发布前试运行回滚计划。
- 每个目标环境至少保留一个已知可用的备份制品ID。
Post-Change Audit
变更后审计
- Record release request, executed steps, and verification output.
- Keep blocker/warning history for future release hardening.
- 记录发布请求、执行步骤及验证输出。
- 保留阻塞/警告历史以优化未来发布流程。
Verification Checklist
验证 checklist
- Input contract is complete for selected action.
- Channel resolution is explicit in output.
- Precheck reports ,
checks, andblockers.warnings - Publish/rollback apply mode enforces .
confirm - Publish apply enforces method hard gate ().
publish_method_confirm - Backup restore publish enforces artifact selection gate.
- Auto-backup behavior is explicit ().
backup_auto - Commands/actions are listed for reproducibility.
- Execution results include per-step status and (
exec_context/source).target - Final state matches execution reality.
verification - Fallback hints are provided when failed.
- Next-step guidance is actionable.
- 所选操作的输入约定已完整。
- 渠道解析结果在输出中明确。
- 预检查报告包含、
checks和blockers。warnings - publish/rollback执行模式强制要求。
confirm - publish执行模式强制要求方式确认关卡()。
publish_method_confirm - backup_restore发布强制要求制品选择关卡。
- 自动备份行为明确()。
backup_auto - 列出命令/操作以确保可复现。
- 执行结果包含每步状态及(
exec_context/source)。target - 最终状态与执行实际情况匹配。
verification - 失败时提供回退提示。
- 下一步指引具备可操作性。
Minimal Test Scenarios
最小测试场景
- Precheck with migration/schema_only_all and complete source+target context.
- Publish plan-only () for
apply=false.backup_restore - Publish apply without is blocked.
--confirm confirm - Publish apply without is blocked.
--publish-method-confirm - Publish apply with but without
backup_restoreis blocked and returns latest 5 source candidates.--backup-artifact - Rollback without backup artifact is blocked.
- Remote API channel without token env is blocked.
- Remote SSH channel without host/path is blocked.
- Migration overwrite returns high-risk warning.
- 使用migration/schema_only_all及完整源+目标上下文执行预检查。
- 为生成发布计划(
backup_restore)。apply=false - 未提供的publish执行被阻塞。
--confirm confirm - 未提供的publish执行被阻塞。
--publish-method-confirm - 使用但未提供
backup_restore的publish执行被阻塞,并返回源环境最新5个候选制品。--backup-artifact - 未指定备份制品的rollback被阻塞。
- 未提供令牌环境变量的Remote API渠道被阻塞。
- 未提供主机/路径的Remote SSH渠道被阻塞。
- 使用覆盖模板的migration返回高风险警告。
Output Contract
输出约定
Final response must include:
- (action/method/publish_method_confirm/channel/migration_template/apply)
request channeltarget_resolutionpre_state- ,
checks,blockerswarnings plugin_checksbackup_candidatesaction_requiredbackup_artifactcommands_or_actionsexecutionverificationassumptionsfallback_hintsnext_steps
最终响应必须包含:
- (action/method/publish_method_confirm/channel/migration_template/apply)
request channeltarget_resolutionpre_state- 、
checks、blockerswarnings plugin_checksbackup_candidatesaction_requiredbackup_artifactcommands_or_actionsexecutionverificationassumptionsfallback_hintsnext_steps
References
参考资料
- NocoBase Documentation: official product and plugin behavior reference. [verified: 2026-04-15]
- NocoBase Commercial: official commercial purchase and activation guidance. [verified: 2026-04-15]
- Runtime Contract: action/channel/method behavior map.
- Test Playbook: acceptance prompts and expected assertions.
- run-ctl Resolver: skill-local ctl runtime resolver.
- Release Resource Adapter: resource operation templates and adapter helpers.
- nocobase-env-bootstrap: authoritative app environment lifecycle skill ().
task=app-manage - Release Runtime: skill-local release orchestration entrypoint.
- Migration Template Rules: template enum, risk checks, and command mapping.
- NocoBase Documentation:官方产品及插件行为参考。[验证时间:2026-04-15]
- NocoBase Commercial:官方商业版购买及激活指引。[验证时间:2026-04-15]
- Runtime Contract:action/channel/method行为映射。
- Test Playbook:验收提示及预期断言。
- run-ctl Resolver:技能本地ctl运行时解析器。
- Release Resource Adapter:资源操作模板及适配器工具。
- nocobase-env-bootstrap:权威应用环境生命周期技能()。
task=app-manage - Release Runtime:技能本地发布编排入口。
- Migration Template Rules:模板枚举、风险检查及命令映射。