NocoBase CLInb backup restore命令实战详解参数机制、确认流程与源码级实现原理【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase本文围绕 NocoBase CLI 的nb backup restore命令展开完整覆盖其参数语义、跨 env 确认机制、路径校验、非交互AI agent场景约束以及“上传 → 恢复 → 健康检查”的底层执行链路。读完本文你可以安全地把*.nbdata备份文件恢复到任意目标 env理解命令成功返回即代表应用已恢复到可访问状态这一承诺背后的实现并能在脚本、CI 或 agent 会话中正确组装--yes/--force参数。命令概述nb backup restore把本地备份文件恢复到目标 CLI env。通常使用的是*.nbdata备份文件。由于恢复操作会覆盖目标应用的数据CLI 默认会再做一次确认在缺少交互能力的终端或 AI agent 会话中则要求显式传入--force否则命令直接拒绝执行。从 index 文档 可以确认nb backup restore与nb backup create共同构成nb backup命令组而恢复流程依赖目标 env 暴露的nb api backup restore-upload运行时命令——这是理解整个命令行为的关键前提。用法nb backup restore --file path [flags]参数参数类型默认值说明--env,-estring当前 env要恢复到的 CLI env 名称省略时使用当前 env--yes,-ybooleanfalse当显式--env指向的 env 与当前 env 不一致时跳过交互确认--file,-fstring必填本地备份文件路径--forcebooleanfalse确认覆盖应用数据在非交互终端和 AI agent 会话中必需显式传入以上默认值与必填约束可直接在命令实现中确认--file声明为required: true--yes与--force均default: false见 restore.ts。示例nb backup restore --file ./backups/base.nbdata --force nb backup restore --env e2e --file ./backups/base.nbdata --yes --force完整执行流程从输入到应用就绪结合 restore.ts 的run()实现命令的完整执行链路如下跨 env 守卫仅当你在 argv 中显式传入--env/-e时才检查目标 env 是否与当前 env 一致不一致则触发确认逻辑备份文件校验检查--file指向的路径是否存在、是否为普通文件解析目标 env将--env或当前 env解析为已配置的 env 记录恢复确认根据--force与终端交互性决定跳过、交互确认或直接失败备份运行时命令检查确认目标 env 的 runtime 暴露了backup restore-upload命令缺失时自动刷新一次 runtime 缓存执行恢复上传内部转调nb api backup restore-upload --file path --force [--env name --yes]等待健康检查轮询目标应用的__health_check端点直到应用重新就绪后命令才返回成功。下面逐节展开每个环节的机制细节。跨 env 守卫--env与--yes的配合只有在你显式传入--env时CLI 才会检查它是否与当前 env 一致。这一点由 env-guard.ts 中的hasExplicitEnvSelection判断实现——它会扫描原始 argv 中是否出现--env、-e、--env...等 token而不是只看解析后的 flags 值。ensureCrossEnvConfirmed的行为见 env-guard.ts未显式指定 env或指定值与当前 env 相同 → 直接通过传了--yes→ 跳过交互提示交互终端 → 弹出确认提示默认答案为false非交互终端 → 直接报错拒绝提示需要先nb env use name切换或显式追加--yes后重试。因此在非交互终端或 AI agent 场景下跨 env 恢复的可靠写法是显式带上--yes或者先执行nb env use name再重试。恢复命令随后通过 backup.ts 的buildBackupEnvArgv把 env 参数透传给底层nb api子命令只有显式选择 env 时才会附加--env name且只要--yes或存在显式 env 选择就会一并附加--yes。备份文件校验--file的路径规则执行前CLI 会先检查--file指向的路径是否存在并确认它是一个普通文件。该逻辑实现在 backup.ts 的resolveBackupRestoreFilePath相对路径会先基于当前工作目录解析为绝对路径path.resolve(process.cwd(), file)所以--file ./backups/base.nbdata指向的是相对 cwd 的位置路径不存在 → 直接抛出Backup file not found: resolved path路径指向目录 → 抛出Backup restore input must be a file: resolved path。两种情况命令都会在真正发起任何上传/恢复动作之前失败不会产生半截状态。确认机制--force在交互与非交互环境下的差异恢复会覆盖目标应用数据因此存在一道独立的确认关口实现在 restore.ts 的confirmBackupRestore传入--force直接视为已确认流程继续未传--force交互终端弹出确认框提示语为Restore backup file into env? This will overwrite application data.默认答案为false拒绝则命令直接返回、不执行任何恢复动作未传--force非交互终端 / AI agent 会话直接抛出错误并拒绝执行错误信息本身给出一条可直接复制的重跑提示nb backup restore needs confirmation. Re-run with --force to restore file into env in non-interactive mode.如果同时还是跨 env 操作显式--env指向不同于当前 env 的名字则通常需要同时传入--yes和--force——前者用于跨过 env 守卫后者用于跨过数据覆盖确认两者作用于不同环节。以上行为均有对应的自动化测试覆盖见 backup-commands.test.ts 中“交互确认、拒绝确认、非交互必须--force”三个用例。备份运行时命令检查为什么有时需要先刷新 runtimenb backup restore依赖目标 env 暴露nb api backup restore-upload命令。在执行前backup.ts 的ensureBackupRuntimeCommands会先读取该 env 已缓存的 runtime 命令清单清单中已包含backup restore-upload→ 直接通过否则自动触发一次 runtime 刷新updateEnvRuntime重新拉取命令清单刷新后仍缺失 → 报错并列出缺失的命令提示“Enable or upgrade the backup/restore capability for that env, then try again”即需要先处理目标应用本身的备份能力。四个备份相关命令的 ID 定义见 backup.tsbackup create、backup status、backup download、backup restore-upload其中restore-upload是本命令唯一依赖项。底层调用与成功判定restore-upload__health_check确认全部通过后CLI 通过 backup.ts 的runBackupCliCommand以子进程方式转调本 CLI 的 API 命令nb api backup restore-upload --file resolved path --force [--env name --yes]子进程环境变量中会设置NB_SKIP_STARTUP_UPDATE1跳过启动更新并清空_NOCO_CLI_TSX_CHILD以兼容 tsx 源模式下的再次执行。上传恢复成功后命令并不会立刻返回而是进入健康检查等待。这一点正是文档中“命令成功返回时应用通常已经恢复到可访问状态”的实现依据。app-health.ts 给出了关键常量与判定逻辑行为取值说明检查 URLapiBaseUrl/__health_check期望 HTTP 2xx 且响应体为ok轮询间隔2000 msAPP_HEALTH_CHECK_INTERVAL_MS总超时600 000 ms10 分钟APP_HEALTH_CHECK_TIMEOUT_MS单次请求超时5000 msAPP_HEALTH_CHECK_REQUEST_TIMEOUT_MS进度日志间隔10000 ms等待期间定期打印已耗时其中apiBaseUrl的解析规则见 backup.ts 的resolveBackupWaitApiBaseUrl优先使用 env 上保存的baseUrl去除尾部斜杠若没有baseUrl而 env 记录了appPort则回退为http://127.0.0.1:appPort/api。如果两者都拿不到CLI 会跳过健康检查并提示“该 env 没有保存本地 API 地址”。若 10 分钟内健康检查仍未通过waitForAppReady抛出AppHealthCheckError附带最后一次的检查状态如HTTP 503: ...或No response within 5s并提示可用docker logs container排查。常见失败场景与处理现象原因处理No env is configured. Run nb init --ui first.工作区还没有配置任何 env先执行nb init --ui初始化并配置 envEnv X is not configured. Run nb init --ui --env X first.显式指定的--env X未配置先nb init --ui --env X创建/连接该 env或改用已有 envCurrent env X is not configured.当前 env 记录缺失用nb env use name切换到已有 env或nb init --ui --env XBackup file not found: path/Backup restore input must be a file: path--file指向不存在的路径或目录检查备份文件路径与当前工作目录跨 env 确认在非交互终端被拒绝显式--env指向与当前 env 不同且缺少--yes追加--yes或先nb env use name重试非交互模式缺--force被拒绝缺少覆盖确认按错误提示中的语句重跑追加--force缺少nb api backup restore-upload能力目标 env 未开启/同步 backup/restore 能力按提示先处理目标应用使其暴露备份 API 命令等待就绪超时10 分钟恢复后应用未恢复可访问查看错误中的最后检查状态用docker logs container查看应用日志非交互 / AI agent 场景的最佳实践综合上述机制在脚本或 agent 会话中恢复备份的推荐写法是# 恢复到当前 env非交互 nb backup restore --file ./backups/base.nbdata --force # 恢复到显式指定的 env非交互跨 env nb backup restore --env e2e --file ./backups/base.nbdata --yes --force要点非交互环境下--force是硬性要求缺失会直接失败且错误信息中自带可复制的重跑命令跨 env 时必须同时携带--yes否则会在 env 守卫环节被拒绝命令成功返回意味着restore-upload已完成且__health_check已通过可以认为应用已恢复到可访问状态测试文件 backup-commands.test.ts 中的“uploads the file and waits for the app to become ready”用例精确验证了这条链路子命令参数为[api, backup, restore-upload, --file, file, --force, --env, e2e, --yes]随后调用waitForAppReady({ envName: e2e, apiBaseUrl: http://127.0.0.1:13000/api })成功时输出Backup restored for e2e from file。源码与文档位置索引命令实现packages/core/cli/src/commands/backup/restore.tsenv 解析、路径校验、子命令转调packages/core/cli/src/lib/backup.ts跨 env 确认守卫packages/core/cli/src/lib/env-guard.ts健康检查等待packages/core/cli/src/lib/app-health.ts自动化测试packages/core/cli/src/tests/backup-commands.test.ts命令组索引文档docs/docs/cn/api/cli/backup/index.md相关命令nb backup create在目标 env 创建远端备份并下载到本地产出可供本命令恢复的*.nbdata文件nb app restart重启目标应用在恢复后应用状态异常时可作为补充操作【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考