企业官网建设流程全解析

NocoBase CLI 详解：nb env update 命令如何安全更新环境配置与触发运行时同步

【免费下载链接】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

nb env update是 NocoBase CLI 中用于维护"已保存环境（env）"的核心命令：它可以修改环境的 API 地址、认证方式、源码来源、应用路径、端口与数据库参数，也可以不带任何参数按当前状态重新同步运行时。本文以 命令参考文档 为骨架，结合 CLI 源码实现 EnvUpdate 命令，完整梳理该命令的全部参数、校验规则、更新后的自动提示逻辑以及典型用法，帮助你把环境配置变更做到"改得准、知道该做什么后续动作"。

命令定位与用法

nb env update用来更新一个已保存 env 的配置。你可以用它调整 API 地址、认证方式、源码来源、本地应用路径、公开访问路径、端口、数据库参数等。更新完成后，CLI 会根据变更自动处理后续事宜；而如果你不带任何配置参数执行，CLI 也会按当前 env 状态做一次运行时重新同步。

nb env update [name] [flags]

从源码结构看，name是一个可选的位置参数（见 update.ts 的 args 定义），省略时命令会调用getCurrentEnvName解析当前 env 后再走运行时刷新流程；--verbose只是切换输出详细度，不参与配置变更。

完整参数参考

以下参数表完整继承自 官方命令参考，并结合源码中标签定义（Flags配置）补充了取值约束。

API 与认证参数

源码中的 flag 定义（Flags 配置）确认了--auth-type通过options: ['basic', 'token', 'oauth']做白名单约束，--access-token带短字符-t与别名--token，--api-base-url带短字符-u。

源码与下载参数

这些字段在源码中被归入SOURCE_SETTING_FIELDS集合（字段分组定义），其语义是：更新它们只会修改保存值，现有本地源码、依赖和镜像不会被自动替换——这一点会在更新完成后以提示信息的形式明确告知（见下文）。

应用参数

另外源码中还定义了三个文档未列出的隐藏参数（hidden: true），分别是--app-root-path、--storage-path和--env-file（见 隐藏 flag 定义），主要用于内部保存应用根路径、存储路径与 Docker--env-file路径，常规使用中不必关心。

数据库参数

--db-dialect在源码中同样受options: ['kingbase', 'mariadb', 'mysql', 'postgres']白名单约束。

配置清理参数

源码视角：命令到底做了什么

阅读 EnvUpdate 命令实现 可以看清nb env update的完整执行路径，这部分机制正是文档"说明"章节中各种行为的底层依据。

1. 无参数时：走运行时重新同步

run()方法先解析--unset（normalizeUnsetFields）与所有显式传入的配置字段（collectProvidedConfigFields），统计出是否存在配置变更（变更判定逻辑）。当hasConfigChanges为假时，命令直接调用refreshRuntime，内部通过updateEnvRuntime（来自 bootstrap 库）拉取该 env 运行时的最新版本并刷新，输出类似Updated env "<name>" to runtime "<version>"的提示。这就是"不带配置参数时按当前 env 状态重新同步"的实现。

2. 有参数时：先校验、再保存、按需刷新运行时

存在配置变更时，命令按以下顺序执行（run 方法主体）：

1. 互斥与约束校验：
   • 同一字段不能同时用--unset和显式赋值，否则报Cannot combine --unset <field> with an explicit update for the same field.；
   • --access-token/--token只能配合--auth-type token使用，报--access-token or --token can only be used with --auth-type token.；
   • --username只能在 env 使用 basic 认证（或显式传--auth-type basic）时使用；
   • 传入--api-base-url时会调用validateApiBaseUrl做合法性校验（API 地址校验）。
2. 构建新配置：以当前 env 已保存的config、apiBaseUrl、authType、authUsername为基底，仅覆盖本次显式传入的字段（buildCurrentConfigInput），再通过--unset删除指定字段（applyUnsetField会按规范名映射到存储字段，如username映射到authUsername）。
3. 保存：调用replaceEnvConfig写回存储。字段到存储键的映射由 env-command-config.ts 中的ENV_STRING_CONFIG_FLAG_MAP与ENV_BOOLEAN_CONFIG_FLAG_MAP统一维护，保证 flag 名与存储字段一一对应。
4. 运行时刷新：只有当本次变更包含api-base-url或access-token时（shouldRefreshRuntime），保存后才会自动执行运行时刷新；刷新失败时会输出警告块"已保存配置，但运行时刷新失败"，配置本身不会回滚。

3. 更新完成后的自动提示

对于只改保存值、不刷新运行时的场景，命令会调用printConfigUpdateHints输出针对性建议（提示逻辑），这些提示正是文档"说明"中各条注意事项的代码来源：

• 若变更字段命中APP_RESTART_WITH_DB_FIELDS（builtin-db、db-dialect、builtin-db-image、db-port、db-database、db-user、db-password、storage-path）且 env 使用内置数据库，则提示执行nb app restart --env <name> --with-db；
• 若变更字段命中APP_RESTART_FIELDS（app-path、app-port、app-key、timezone及各类db-*等），则提示执行nb app restart --env <name>；
• 若变更了源码类字段，则提示"保存的源码设置已更新，现有本地源码文件不会被自动替换"；
• 若认证方式切到basic/oauth、token 被清空，则提示执行nb env auth <name>重新认证。

这套"字段 → 集合 → 提示"的机制意味着：你不需要记住每个参数变更后的后续动作，命令会根据你实际改动的字段给出精确建议。相关行为在 env-update 测试用例 中有对应的断言覆盖。

使用说明与约束

以下条目完整继承自 文档"说明"章节，建议结合上一节的实现机制一起理解：

• 如果你只是想让 CLI 按当前 env 的最新状态重新同步，直接执行nb env update或nb env update <name>就够了，不需要额外参数。
• 更新完成后，CLI 会根据这次变更自动处理需要的后续同步。
• 其他参数只会更新已保存的 env 配置，不会自动重启应用，也不会自动替换本地源码或 Docker 镜像。
• 修改app-path、app-port、timezone、db-*这类配置后，CLI 通常会提示你后续执行nb app restart --env <name>；如果变更涉及 CLI 托管的内置数据库，则会提示使用nb app restart --env <name> --with-db。
• 修改app-port、app-public-path、cdn-base-url这类会影响反向代理渲染结果的配置后，如果你已经在用nb proxy nginx或nb proxy caddy，通常还要重新执行对应的generate。
• 更新source、download-version、docker-registry、git-url、npm-registry这类源码设置时，只会改保存值，现有本地源码、依赖和镜像不会自动替换。
• --access-token不能和--auth-type basic或--auth-type oauth一起使用。
• 同一个字段不能同时用--unset和显式赋值，比如不能同时写--unset git-url和--git-url ...。
• 如果你把认证方式切到basic或oauth，或者清空了 token，后续通常还要执行nb env auth <name>。

示例

以下示例完整来自 官方参考文档，覆盖了同步、认证、源码、应用与清理的典型场景：

# 让当前 env 按最新状态重新同步 nb env update # 让指定 env 按最新状态重新同步 nb env update prod # 更新 API 地址 nb env update prod --api-base-url http://localhost:13000/api # 更新 token，并把认证方式切到 token nb env update prod --access-token <token> # 切到 basic 认证，只保存用户名，稍后再执行 nb env auth nb env update prod --auth-type basic --username admin # 调整源码来源和版本，只更新已保存配置 nb env update local --source git --git-url git@github.com:nocobase/nocobase.git --download-version next # 调整应用端口和时区，稍后再重启应用 nb env update local --app-port 13080 --timezone Asia/Shanghai # 调整应用公开访问路径，改完后通常还要重新生成 proxy nb env update local --app-public-path /nocobase/ # 保存客户端静态资源的 CDN 基地址 nb env update local --cdn-base-url https://cdn.example.com/nocobase/ # 清空已保存的字段 nb env update local --unset git-url --unset username nb env update local --unset git-url,username

对照源码可以看出两个细节：--access-token <token>之所以会"顺便"把认证切到token，是因为tokenOverride触发后会强制nextInput.authType = 'token'；而--unset之所以只接受"规范名"（如git-url而非存储键gitUrl），是因为normalizeUnsetFields会先对照UNSETTABLE_FIELDS白名单做校验，非法字段名会直接报错并列出所有支持的字段。

相关命令

• nb api
• nb env auth
• nb env info
• nb env add
• nb app restart
• nb source download

【免费下载链接】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