nocobase-publish-manage

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Goal

目标

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:
    • backup_restore
      : source backup artifact download + target upload restore.
    • migration
      : source rule create/generate/download + target check/up.
  • 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:
    • publish
      /
      rollback
      apply confirmation (
      --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:*
      )
  • 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_restore
    ->
    Use existing backup package
  • migration
    ->
    Create new release package
Migration template presets (independent rules are always disabled):
  • schema_only_all
    -> user-defined=
    schema-only
    , system=
    schema-only
  • user_overwrite_only
    -> user-defined=
    overwrite
    , system=
    schema-only
  • system_overwrite_only
    -> user-defined=
    schema-only
    , system=
    overwrite-first
  • full_overwrite
    -> user-defined=
    overwrite
    , system=
    overwrite-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
    /
    .ps1
    ) for release flow.
  • 不修改NocoBase服务端源代码。
  • 不假设所有插件版本的备份/迁移操作名称固定。
  • 不静默执行破坏性操作。
  • 不将部分失败伪装为成功。
  • 不依赖Shell脚本(
    .sh
    /
    .ps1
    )实现发布流程。

Input Contract

输入约定

InputRequiredDefaultValidationClarification Question
action
yesnoneone of
precheck/publish/verify/rollback
"Run precheck, publish, verify, or rollback?"
method
yesnoneone of
backup_restore/migration
"Use backup_restore or migration?"
publish_method_confirm
conditionalemptyrequired when
action=publish
and
apply=true
; must equal
method
"Please confirm release method with --publish-method-confirm <same-as-method>."
channel
no
auto
one of
auto/local_cli/remote_api/remote_ssh_cli
"Should I force a channel?"
migration_template
conditionalnonerequired when migration publish executes; one of
schema_only_all/user_overwrite_only/system_overwrite_only/full_overwrite
"For migration, choose one preset: schema_only_all, user_overwrite_only, system_overwrite_only, or full_overwrite."
source_env
no
local
(when source url missing)
valid env name when provided"Which source env should be used?"
target_env
no
test
(when target url missing)
valid env name when provided"Which target env should be used?"
source_url
noemptyvalid HTTP(S) URL"Do you want to force a source URL?"
target_url
noemptyvalid HTTP(S) URL"Do you want to force a target URL?"
source_token_env
noemptyenv var name"Which env var stores source token?"
target_token_env
no
NOCOBASE_API_TOKEN
env var name for remote API"Which env var stores target token?"
backup_auto
no
true
boolean"Should auto-backup be enabled?"
backup_artifact
conditionalnonerequired for
rollback
; also required for
publish + backup_restore + apply=true
"Which backup artifact should be used?"
apply
no
false
boolean"Should I execute now or only generate a plan?"
confirm
publish/rollback apply: yesnonemust be
confirm
"Please type confirm to continue high-risk execution."
base_dir
nocurrent directoryexisting path"Which base directory should commands run in?"
scope
no
project
one of
project/global
"Use project scope or global scope?"
prefer
no
auto
one of
auto/global/local
"Prefer global ctl or local ctl?"
ssh_host
remote_ssh_cli: yesemptynon-empty host"What SSH host should be used?"
ssh_path
remote_ssh_cli: yesemptynon-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 (
    add/use/current/list
    ) must be handled by
    $nocobase-env-bootstrap task=app-manage ...
    , not by this skill.
  • 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.
输入项是否必填默认值校验规则确认问题
action
必须为
precheck/publish/verify/rollback
之一
"要执行预检查、发布、验证还是回滚?"
method
必须为
backup_restore/migration
之一
"使用backup_restore还是migration方式?"
publish_method_confirm
条件必填
action=publish
apply=true
时必填;必须等于
method
"请通过--publish-method-confirm <与method一致的值>确认发布方式。"
channel
auto
必须为
auto/local_cli/remote_api/remote_ssh_cli
之一
"是否要强制指定发布渠道?"
migration_template
条件必填执行migration发布时必填;必须为
schema_only_all/user_overwrite_only/system_overwrite_only/full_overwrite
之一
"对于migration方式,请选择一个预设:schema_only_all、user_overwrite_only、system_overwrite_only或full_overwrite。"
source_env
local
(当源URL缺失时)
提供时需为有效环境名称"应使用哪个源环境?"
target_env
test
(当目标URL缺失时)
提供时需为有效环境名称"应使用哪个目标环境?"
source_url
有效HTTP(S) URL"是否要强制指定源URL?"
target_url
有效HTTP(S) URL"是否要强制指定目标URL?"
source_token_env
环境变量名称"哪个环境变量存储源环境令牌?"
target_token_env
NOCOBASE_API_TOKEN
远程API的环境变量名称"哪个环境变量存储目标环境令牌?"
backup_auto
true
布尔值"是否启用自动备份?"
backup_artifact
条件必填
rollback
时必填;
publish + backup_restore + apply=true
时也必填
"应使用哪个备份制品?"
apply
false
布尔值"是立即执行还是仅生成计划?"
confirm
publish/rollback执行时:是必须为
confirm
"请输入confirm以继续高风险操作。"
base_dir
当前目录存在的路径命令应在哪个基础目录下运行?"
scope
project
必须为
project/global
之一
"使用项目范围还是全局范围?"
prefer
auto
必须为
auto/global/local
之一
"优先使用全局ctl还是本地ctl?"
ssh_host
remote_ssh_cli时:是非空主机地址"应使用哪个SSH主机?"
ssh_path
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 (
    publish
    /
    rollback
    with apply):
    • method
      and
      channel
      are resolved
    • source and target context are resolved (
      source_url/source_env
      ,
      target_url/target_env
      or ssh target)
    • auth is ready for
      remote_api
    • migration_template
      is explicitly set when
      method=migration
      • when missing, runtime must return
        action_required.type=choose_migration_template
        with 4 presets
    • publish_method_confirm
      equals
      method
      when
      action=publish
    • backup_artifact
      is selected when
      action=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
    action_required
    choice gate, stop and wait for user response.
Deterministic keyword routing:
  • Follow references/intent-routing.md exactly.
  • Conflict (
    restore
    +
    migration
    in one request) must stop execution and ask user to choose one intent.
  • 最大确认轮次:
    2
  • 每轮最多问题数:
    3
  • 执行变更前(
    publish
    /
    rollback
    且apply=true):
    • method
      channel
      已确定
    • 源和目标上下文已确定(
      source_url/source_env
      target_url/target_env
      或SSH目标)
    • remote_api
      的认证已就绪
    • method=migration
      时,
      migration_template
      已明确设置
      • 若缺失,运行时必须返回
        action_required.type=choose_migration_template
        并提供4个预设选项
    • action=publish
      时,
      publish_method_confirm
      等于
      method
    • action=publish + method=backup_restore
      时,已选择
      backup_artifact
    • 已提供二次确认(
      confirm
  • 若未通过这些检查,停止操作并返回阻塞项及
    action_required
反推断策略:
  • 不从通用发布请求中推断发布方式/模板/制品。
  • 对于模糊输入如"publish local to 19000",仅执行预检查并询问用户选择。
  • 若运行时返回任何
    action_required
    选择关卡,停止操作并等待用户响应。
确定性关键词路由:
  • 严格遵循references/intent-routing.md
  • 若出现冲突(同一请求中同时包含
    restore
    migration
    ),必须停止执行并要求用户选择一个意图。

Workflow

工作流

  1. Normalize and validate input.
  2. Read environment inventory via CLI wrapper:
    node ./scripts/run-ctl.mjs -- env list -s <scope>
    .
  3. If CLI env inventory fails, hand off to
    $nocobase-env-bootstrap task=app-manage ...
    for repair.
  4. Check source/target env existence and run CLI update checks for both envs.
  5. If env is missing or CLI check fails, hand off to
    $nocobase-env-bootstrap task=app-manage ...
    .
  6. Resolve source/target URLs and release channel (
    auto
    allowed).
  7. Run
    pm list
    for target env:
    • 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
  8. Run method-specific gates:
    • publish + apply=true
      : enforce
      --publish-method-confirm <same-as--method>
    • publish + method=backup_restore + apply=true
      : query latest 5 source backup artifacts and enforce
      --backup-artifact
    • publish + method=migration + apply=true
      : enforce migration preset selection (
      --migration-template
      )
    • migration template safety checks (
      schema_only_all
      /
      user_overwrite_only
      /
      system_overwrite_only
      /
      full_overwrite
      )
  9. Build command plan (with explicit
    exec_context
    ):
    • backup_restore
      publish:
      • source:
        backup_download
      • target:
        backup_create
        (if
        backup_auto=true
        )
      • target:
        backup_upload
    • migration
      publish:
      • source:
        migration_rules_create
      • source:
        migration_generate
        (
        ruleIdRef=latest_migration_rule
        )
      • source:
        migration_files_download
      • target:
        backup_create
        (if
        backup_auto=true
        )
      • target:
        migration_files_check
      • target:
        migration_up
  10. Execute plan only when
    apply=true
    ; otherwise return dry-run plan.
  11. Verify result and output
    verification
    :
    • passed
    • failed
    • pending_verification
      (when plan-only)
  12. Return structured output with next-step instructions.
  1. 标准化并验证输入。
  2. 通过CLI包装器读取环境清单:
    node ./scripts/run-ctl.mjs -- env list -s <scope>
  3. 若CLI环境清单读取失败,交由
    $nocobase-env-bootstrap task=app-manage ...
    修复。
  4. 检查源/目标环境存在性,并对两个环境运行CLI更新检查。
  5. 若环境缺失或CLI检查失败,交由
    $nocobase-env-bootstrap task=app-manage ...
    处理。
  6. 解析源/目标URL及发布渠道(允许
    auto
    )。
  7. 对目标环境运行
    pm list
    • 通过
      plugin-migration-manager
      检测商业功能
    • 检测必备发布插件(
      migration_manager
      backup_manager
    • 若插件未激活/缺失,交由
      $nocobase-plugin-manage enable ...
      处理
    • 若缺失商业功能,返回购买链接及重启指引
  8. 执行特定方式的关卡检查:
    • publish + apply=true
      :强制要求
      --publish-method-confirm <与method一致的值>
    • publish + method=backup_restore + apply=true
      :查询源环境最新5个备份制品并强制要求
      --backup-artifact
    • publish + method=migration + apply=true
      :强制选择迁移预设(
      --migration-template
    • 迁移模板安全检查(
      schema_only_all
      /
      user_overwrite_only
      /
      system_overwrite_only
      /
      full_overwrite
  9. 构建命令计划(包含明确的
    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
  10. 仅当
    apply=true
    时执行计划;否则返回试运行计划。
  11. 验证结果并输出
    verification
    状态:
    • passed
      (通过)
    • failed
      (失败)
    • pending_verification
      (仅计划时)
  12. 返回结构化输出及下一步操作指引。

Reference Loading Map

参考加载映射

ReferenceUse WhenNotes
references/v1-runtime-contract.mdimplementing action/channel/method matrixcanonical behavior contract
references/intent-routing.mdmapping user keywords to intent/method flowdeterministic anti-inference routing
references/test-playbook.mdverifying skill behaviorprompt-ready acceptance set
publish-resource-adapter.mjsany release mutation/readbackunified resource templates for backup/migration operations
run-ctl.mjsany ctl command executionlocal/global nocobase-ctl resolver
publish-manage.mjspublish orchestrationprecheck/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:
  • publish
    in apply mode
  • rollback
    in apply mode
  • migration
    with overwrite templates (
    user_overwrite_only
    ,
    system_overwrite_only
    ,
    full_overwrite
    )
Mandatory hard gates before publish apply:
  • --confirm confirm
  • --publish-method-confirm <same-as--method>
  • --backup-artifact <name>
    for
    backup_restore
Secondary confirmation template:
  • "Confirm execution:
    {{action}}
    with method
    {{method}}
    on target
    {{target}}
    . Impact: target data may be overwritten or restored. Reply
    confirm
    to continue."
Rollback guidance:
  • Trigger rollback when
    publish
    fails after partial write.
  • Rollback steps:
    • identify latest valid backup artifact
    • execute rollback with explicit confirmation
    • run
      verify
      action and compare key health signals
高风险操作:
  • 执行模式下的
    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
    ,
    blockers
    , and
    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
    verification
    state matches execution reality.
  • 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

最小测试场景

  1. Precheck with migration/schema_only_all and complete source+target context.
  2. Publish plan-only (
    apply=false
    ) for
    backup_restore
    .
  3. Publish apply without
    --confirm confirm
    is blocked.
  4. Publish apply without
    --publish-method-confirm
    is blocked.
  5. Publish apply with
    backup_restore
    but without
    --backup-artifact
    is blocked and returns latest 5 source candidates.
  6. Rollback without backup artifact is blocked.
  7. Remote API channel without token env is blocked.
  8. Remote SSH channel without host/path is blocked.
  9. Migration overwrite returns high-risk warning.
  1. 使用migration/schema_only_all及完整源+目标上下文执行预检查。
  2. backup_restore
    生成发布计划(
    apply=false
    )。
  3. 未提供
    --confirm confirm
    的publish执行被阻塞。
  4. 未提供
    --publish-method-confirm
    的publish执行被阻塞。
  5. 使用
    backup_restore
    但未提供
    --backup-artifact
    的publish执行被阻塞,并返回源环境最新5个候选制品。
  6. 未指定备份制品的rollback被阻塞。
  7. 未提供令牌环境变量的Remote API渠道被阻塞。
  8. 未提供主机/路径的Remote SSH渠道被阻塞。
  9. 使用覆盖模板的migration返回高风险警告。

Output Contract

输出约定

Final response must include:
  • request
    (action/method/publish_method_confirm/channel/migration_template/apply)
  • channel
  • target_resolution
  • pre_state
  • checks
    ,
    blockers
    ,
    warnings
  • plugin_checks
  • backup_candidates
  • action_required
  • backup_artifact
  • commands_or_actions
  • execution
  • verification
  • assumptions
  • fallback_hints
  • next_steps
最终响应必须包含:
  • request
    (action/method/publish_method_confirm/channel/migration_template/apply)
  • channel
  • target_resolution
  • pre_state
  • checks
    blockers
    warnings
  • plugin_checks
  • backup_candidates
  • action_required
  • backup_artifact
  • commands_or_actions
  • execution
  • verification
  • assumptions
  • fallback_hints
  • next_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:模板枚举、风险检查及命令映射。