nocobase-env-bootstrap

目标

帮助用户从零开始顺利完成 NocoBase 的设置并运行，包括环境检查、安装、本地 CLI 环境初始化、应用环境管理、单实例升级，以及高频问题排查。

范围

• 尽可能自动检测主机环境和必需依赖。
• 使用 Docker、create-nocobase-app 或 Git 方法安装并初始化 NocoBase。
• 在一个环境中（本地计算机或单台服务器）启动 NocoBase。
• 安装成功后，自动初始化本地 nocobase-ctl 环境（local），供下游以 CLI 为主的技能使用。
• 通过技能本地封装脚本提供可复用的应用环境管理操作（add、use、current、list），供下游技能使用。
• 通过明确的预检查和后检查关卡，安全地执行单实例升级。
• 诊断并修复高频安装和运行问题。

非目标

• 不处理跨环境发布工作流。
• 不编排迁移管理器，也不在环境间提升数据。
• 未经用户明确确认，不执行不可逆的破坏性更改（删除数据库、删除数据卷）。
• 不隐瞒未知错误；始终显示确切命令和捕获到的故障信号。
• 不假设存在内置的外部数据库 Compose 模板；需要使用外部数据库时，必须要求用户明确提供数据库连接信息。

输入约定

输入	必填	默认值	验证规则	澄清问题
mode	否	quick	必须是 quick/standard/rescue 之一	"您希望使用快速模式、标准模式还是救援模式？"
task	是	根据用户文本推断	必须是 preflight/install/upgrade/diagnose/app-manage 之一	"您希望运行预检、安装、升级、诊断还是应用管理？"
install_method	安装时可选，升级时可选	安装：docker；升级：auto	必须是 auto/docker/create-nocobase-app/git 之一	"应使用哪种安装方法？"
release_channel	安装或升级时必填	latest	必须是 latest/beta/alpha 之一	"应使用哪个发布渠道（在 Docker 安装中需要 AI 构建能力时，建议使用 alpha）？"
target_version	升级时可选	无	非空版本或镜像标签	"要升级到哪个目标版本？"
backup_confirmed	升级时必填	false	升级前必须为 true	"您是否已完成并确认数据库备份？"
upgrade_confirmed	非试运行升级时必填	false	非试运行升级前必须为 true	"请确认已解析的升级方法、版本和重启计划。"
restart_mode	升级时可选	manual	必须是 manual/dev/start/pm2 之一	"升级后应如何重启应用？"
clean_retry	Git 升级时可选	false	布尔值（true/false）	"如果 Git 升级失败，是否启用清理后重试？"
allow_dirty	Git 升级时可选	false	布尔值（true/false）	"是否允许在 Git 工作区有未提交更改时升级？"
target_dir	安装/升级时必填	当前目录	可写路径	"应在哪里创建或操作项目？"
db_mode	安装时必填	Docker：bundled；create/git：existing	必须是 bundled/existing 之一	"使用内置数据库还是连接现有数据库？"
db_dialect	安装时必填	postgres	必须是 postgres/mysql/mariadb 之一	"使用 PostgreSQL、MySQL 还是 MariaDB？"
db_host	当 db_mode=existing 时必填	无	非空主机名	"应使用哪个数据库主机？"
db_port	当 db_mode=existing 时必填	根据数据库类型而定（5432/3306）	数字端口	"应使用哪个数据库端口？"
db_database	当 db_mode=existing 时必填	无	非空数据库名称	"应使用哪个数据库？"
db_database_mode	当 db_mode=existing 时必填	existing	必须是 existing/create 之一	"使用现有数据库，还是先创建数据库？"
db_user	当 db_mode=existing 时必填	无	非空用户名	"应使用哪个数据库用户？"
db_password	当 db_mode=existing 时必填	无	非空密码	"请提供数据库密码。"
db_underscored	否	false	布尔值（true/false）	"对于本地数据库，是否启用 DB_UNDERSCORED？"
port	否	13000	整数，范围为 1..65535	"应使用哪个应用端口？"
network_profile	否	online	必须是 online/restricted/offline 之一	"此主机能否直接访问外部互联网？"
cli_env_name	否	local	非空标识符	"应创建哪个本地 nocobase-ctl 环境名称？"
cli_auth_mode	否	oauth	必须是 oauth/token 之一	"为 CLI 环境初始化使用 OAuth 模式（默认）还是令牌模式？"
cli_token_env	否	NOCOBASE_API_TOKEN	有效的环境变量名称	"使用令牌模式时，哪个环境变量存储 API 令牌？"
app_env_action	仅当 task=app-manage 时必填	current	必须是 add/use/current/list 之一	"应执行哪种应用环境操作：添加、使用、查看当前环境还是列出环境？"
app_env_name	有条件必填	无	当 app_env_action=add/use 时必填	"应使用哪个环境名称？"
app_base_url	有条件必填	无	当 app_env_action=add 时必填；有效的 HTTP/HTTPS URL	"添加环境时应使用哪个应用 URL？"
app_scope	否	project	必须是 project/global 之一	"此环境操作应使用项目级还是全局范围？"
app_token	有条件必填	无	当 app_env_action=add 使用令牌模式添加远程 URL 时必填	"请提供用于以令牌模式添加远程环境的 API 令牌。"
用户说“由你决定”时的默认行为：

• mode=quick
• task=install
• install_method=docker
• release_channel=latest（Docker 安装仍会在用户未指定通道时询问通道）
• db_mode=bundled
• db_dialect=postgres
• db_database_mode=existing
• db_underscored=false
• port=13000
• network_profile=online
• cli_env_name=local
• cli_auth_mode=oauth
• cli_token_env=NOCOBASE_API_TOKEN

强制澄清门槛

• 最多澄清轮数：2
• 每轮最多提问数：3
• 在所选 task 的所有必需输入都已确定之前，不得执行可变更操作（install/upgrade）。
• Docker 发布渠道的安装澄清门槛为强制要求：
• 当 task=install 且 install_method=docker，如果用户未明确指定 release_channel，则在安装前提出一个简短问题：
• “Docker 默认使用 latest，但当前 AI 构建能力在 alpha 中更完善。现在安装 alpha 吗？”
• 可接受的值：alpha / latest / beta。
• 如果用户明确表示偏好稳定版或生产环境版本，则选择 latest。
• 记录渠道决策来源为 user_explicit、clarified 或 default_fallback。
• 升级门槛为强制要求：
• 执行升级命令前，backup_confirmed 必须为 true。
• 对于升级，install_method 默认为 auto；用户未指定时，根据标记或项目文件确定方法。
• 执行非 dry-run 升级命令前，upgrade_confirmed 必须为 true。
• 如果 target_version 低于当前版本，则停止（不支持降级）。
• 对于 install_method=git，如果工作区不干净，则阻止操作，除非 allow_dirty=true。
• 对于 task=app-manage：
• 如果 app_env_action=add，则必须提供 app_env_name 和 app_base_url。
• 安装时必须遵循数据库策略：
• docker 默认使用 db_mode=bundled。
• 如果用户在 Docker 流程中提供数据库连接信息，则切换为 db_mode=existing。
• create-nocobase-app 和 git 始终要求使用 db_mode=existing，且 PostgreSQL/MySQL/MariaDB 已就绪。
• 对于 db_mode=existing，必须确定 db_database_mode：
• existing：直接连接并验证现有数据库。
• create：先创建数据库，再连接并验证，以避免反复出现初始连接失败。
• 如果数据库主机是本地地址（localhost、127.0.0.1、::1、host.docker.internal），则询问用户对 db_underscored 的偏好；用户未指定时默认为 false。
• 如果 existing 模式下数据库缺失或无法访问，则停止并提供官方安装链接：
• PostgreSQL：https://www.postgresql.org/download/
• MySQL 安装文档：https://dev.mysql.com/doc/en/installing.html
• MySQL 下载：https://dev.mysql.com/downloads/mysql
• MariaDB 下载：https://mariadb.org/download/
• 应用环境身份验证模式规则为强制要求：
• 添加模式默认为 oauth（除非用户提供了 token 参数，但未明确指定身份验证模式）。
• oauth 模式需要依赖包 @nocobase/plugin-api-doc + @nocobase/plugin-idp-oauth，并需交互式执行 env auth。
• token 模式本地 URL（严格）：主机为 localhost、127.0.0.1、::1、*.localhost 或 host.docker.internal 时，必须使用 token，但由 env-manage 自动获取（绝不使用占位 token）。
• token 模式远程 URL：必须由用户手动提供 token（app_token 或 token 环境变量）。
• 对于安装流程，始终将 CLI 环境引导（node ./scripts/env-manage.mjs add ...）作为最后阶段执行。
• 执行 env update 前，确保 CLI 依赖插件已根据身份验证模式启用：
• oauth：@nocobase/plugin-api-doc + @nocobase/plugin-idp-oauth
• token：@nocobase/plugin-api-doc + @nocobase/plugin-api-keys
• 如果使用 token 模式，且 CLI 引导期间缺少 cli_token_env，则先尝试自动生成 token；仅在自动流程失败时才向用户询问。
• 如果缺少必需输入或信息含糊，则停止并提出一个简短的澄清问题。
• 如果任何必需路径无效或不可写，则停止并请求用户提供有效且可写的路径，然后再继续。

工作流

1. 解析请求并规范化意图。

• 如果意图不明确，只提出一个简短问题以确定 task。
• 第一轮最多提出五个问题。
• 对于 Docker 安装，按以下优先级确定 release_channel：
• 用户明确指定 > Docker 渠道澄清答复 > 默认回退值 latest。

2. 安装／升级前运行预检。

• 安装／升级时，仅运行核心检查：
• Windows：执行 powershell -File scripts/preflight.ps1 -InstallMethod <install_method> -DbMode <db_mode> -DbDialect <db_dialect> -DbHost <db_host> -DbPort <db_port> -DbDatabase <db_database> -DbDatabaseMode <db_database_mode> -DbUser <db_user> -DbPassword <db_password>。
• Linux/macOS：在环境中设置 DB_HOST/DB_PORT/DB_DATABASE/DB_USER/DB_PASSWORD，执行 bash scripts/preflight.sh <port> <install_method> <db_mode> <db_dialect> <db_database_mode>。
• 将检查结果归类为 fail、warn 和 pass。
• 将依赖项、运行时、路径或网络问题视为需要立即处理的阻塞问题。

3. 按模式执行。

• quick：优先使用 Docker，尽量减少提问。
• quick + Docker 安装：如果用户未提供通道，则必须询问 Docker 通道，并推荐 alpha。
• standard：由用户选择安装方式和数据库方言。
• rescue：收集诊断信息（Windows 上运行 powershell -File scripts/collect-diagnostics.ps1，Linux/macOS 上运行 bash scripts/collect-diagnostics.sh），将发现的问题对应到故障排查条目，然后先应用最小且安全的修复。
• 安装执行策略：
• 仅使用本地脚本和模板。
• Docker 路径使用 assets/docker-templates/。
• create-app/git 路径使用 assets/install-templates/。
• 执行期间不要搜索网页中的安装命令片段。

4. 执行特定任务的操作手册。

• 安装：遵循安装操作手册。
• 执行安装命令时，使用本地脚本：
• Windows：powershell -File scripts/install.ps1 --method <install_method> --target-dir <target_dir> --release-channel <release_channel> --db-mode <db_mode> --db-dialect <db_dialect> --db-host <db_host> --db-port <db_port> --db-database <db_database> --db-database-mode <db_database_mode> --db-user <db_user> --db-password <db_password> --db-underscored <db_underscored> --project-name <project_name>
• Linux/macOS：bash scripts/install.sh --method <install_method> --target-dir <target_dir> --release-channel <release_channel> --db-mode <db_mode> --db-dialect <db_dialect> --db-host <db_host> --db-port <db_port> --db-database <db_database> --db-database-mode <db_database_mode> --db-user <db_user> --db-password <db_password> --db-underscored <db_underscored> --project-name <project_name>
• 升级：遵循升级操作手册，并执行本地脚本：
• Windows：powershell -File scripts/upgrade.ps1 --method <install_method|auto> --target-dir <target_dir> --backup-confirmed true --confirm-upgrade true --target-version <target_version> --restart-mode <restart_mode> --clean-retry <clean_retry> --allow-dirty <allow_dirty>
• Linux/macOS：bash scripts/upgrade.sh --method <install_method|auto> --target-dir <target_dir> --backup-confirmed true --confirm-upgrade true --target-version <target_version> --restart-mode <restart_mode> --clean-retry <clean_retry> --allow-dirty <allow_dirty>
• 诊断：遵循故障排查知识库。
• 管理应用环境（task=app-manage）：遵循应用环境管理。

5. 运行安装后检查门禁并引导 CLI 环境。

• 验证服务可用性、登录路径、基本插件／运行时健康状况和错误日志。
• 对于安装，应用启动并具备登录条件即表示核心安装流程完成。
• 在刷新 CLI 运行时之前，确保 CLI 依赖插件包已启用：
• oauth（默认）：@nocobase/plugin-api-doc + @nocobase/plugin-idp-oauth
• token：@nocobase/plugin-api-doc + @nocobase/plugin-api-keys
• 首选启用方式：
• oauth：Use $nocobase-plugin-manage enable @nocobase/plugin-api-doc @nocobase/plugin-idp-oauth
• token：Use $nocobase-plugin-manage enable @nocobase/plugin-api-doc @nocobase/plugin-api-keys
• 如果插件状态发生变化，请在运行 node ./scripts/run-ctl.mjs -- env update ... 之前重启应用。
• 安装／升级的最后阶段始终运行 CLI 引导：
• Windows：powershell -File scripts/cli-postcheck.ps1 -Port <port> -EnvName <cli_env_name> -AuthMode <cli_auth_mode> -TokenEnv <cli_token_env> -Scope project -BaseDir <target_dir>
• Linux/macOS：AUTH_MODE=<cli_auth_mode> bash scripts/cli-postcheck.sh <port> <cli_env_name> <cli_token_env> project <target_dir>
• CLI 引导目标命令：
• node ./scripts/env-manage.mjs add --name <cli_env_name> --url http://localhost:<port>/api --auth-mode <cli_auth_mode> --scope project --base-dir <target_dir>
• 成功添加环境后，运行时刷新以确保后续命令就绪：
• node ./scripts/run-ctl.mjs -- env update -e <cli_env_name> -s project
• 立即回读（node ./scripts/env-manage.mjs current --scope project --base-dir <target_dir>），并提供预期值与实际值。

6. 报告输出。

• 包含已执行的命令列表。
• 提供命令输出中的成功／失败证据。
• 对于安装流程，提供 release_channel_source 证据（user_explicit/clarified/default_fallback）。
• 对每项写入操作（例如 .env、compose 文件或运行时配置），立即执行写入后回读验证，并报告预期值与实际值。
• 包含 CLI 引导证据：
• cli_env_name
• base_url
• scope
• auth_mode
• env_update_status
• 对于 task=app-manage，包含应用环境操作证据：
• app_env_action
• current_env_name
• current_base_url
• is_local
• auth_mode（用于 add）
• token_mode（用于 add）
• 对于安装成功的情况，包含首次登录凭据：
• 如果未明确自定义 root 凭据，请显示默认值 [email protected] / admin123，并提醒用户更换密码。
• 如果已自定义，请显示已配置的登录账号和密码来源。
• 包含一项明确的后续操作。

参考资料加载表

参考资料	使用时机	备注
assets/docker-templates.md	Docker 安装	本地模板选择器和发布渠道映射
assets/install-templates.md	create-app/git 安装	本地命令／环境模板映射和渠道默认值
references/preflight-checklist.md	安装／升级之前	依赖、路径、网络和端口检查
references/install-runbook.md	安装和首次启动	Docker/create-app/git 执行指南
references/app-env-manage.md	task=app-manage	add/use/current/list 约定及 oauth/token 身份验证模式策略
references/upgrade-runbook.md	单实例升级	升级前检查、执行、升级后检查和回滚指南
references/troubleshooting.md	诊断和恢复	高频问题决策表

安全关卡

高影响操作：

• 修改运行中服务的版本
• 更改运行时环境变量
• 重启类似生产环境的服务
• 替换或移除 compose 服务

安全规则：

• 执行任何升级操作前都必须获得明确确认。
• 升级前必须确认已完成备份。
• 执行非演练升级脚本前，必须提供 --confirm-upgrade true。
• 绝不自动运行破坏性删除命令。
• 如果命令失败，必须停止操作，并在执行下一步前展示准确的失败输出。

确认模板：

• “确认执行：在 {{target}} 上使用 {{install_method}} 执行 {{task}}。影响：运行时可能重启，服务可能短暂不可用。回复 confirm 以继续。”

验证清单

• 预检已完成，且不存在未解决的阻塞性故障。
• 对于已有项目文件，如果 APP_KEY 较弱，预检会失败；只有在全新安装目标上且本地安装脚本生成之前，预检才会暂缓检查缺失的 APP_KEY。
• Docker 安装未明确指定渠道时，会要求澄清并推荐 alpha。
• 尊重用户明确选择的渠道，不再重复询问。
• 现有数据库模式下，如果缺少必需的数据库字段或无法访问端点，预检会失败。
• 如果 PostgreSQL/MySQL/MariaDB 不可用，create-nocobase-app/git 的预检会失败。
• 安装方式和发布渠道均已明确确认或设置默认值。
• 安装命令已记录且可重现。
• 根据应用启动和登录就绪状态判定安装核心部分是否成功。
• 安装/升级的最后阶段会运行 CLI，并通过技能本地环境辅助工具（node ./scripts/env-manage.mjs add ...）成功创建或更新本地环境。
• task=app-manage 通过 node ./scripts/env-manage.mjs ... 支持 add/use/current/list。
• 添加应用环境时会正确执行身份验证模式规则（默认使用带元数据/身份验证流程的 oauth；令牌模式遵循本地与远程令牌策略）。
• 只有 env update 连通性验证成功，才能将添加应用环境视为成功。
• 引导环境的 CLI 运行时刷新（node ./scripts/run-ctl.mjs -- env update ...）成功。
• 如果运行时刷新因 swagger:get 404 或禁用 API 文档而失败，技能会执行插件激活流程并重试。
• OAuth 流程会在验证 OAuth 元数据/身份验证前，确认 @nocobase/plugin-idp-oauth 已启用。
• 获取令牌流程会在生成/提供令牌前，确认 @nocobase/plugin-api-keys 已启用。
• 回读结果确认预期的环境名称/基础 URL/范围以及当前环境选择。
• 升级流程包含备份确认。
• 升级流程在计划回读后包含脚本级确认门槛（--confirm-upgrade true）。
• 后置检查会验证应用是否可访问以及登录页面是否可用。
• 故障排查输出包含根因假设和具体修复步骤。
• 结果摘要包含已完成、待处理和下一步操作事项。
• 每项写入操作都附有即时回读证据。

最小测试场景

1. 在可使用 Docker 的干净主机上快速安装，然后自动运行 CLI 本地环境引导。
2. Docker 和 Node 均缺失时运行预检。
3. 缺少或使用占位符形式的 APP_KEY 时，预检失败；设置随机密钥后，预检通过。
4. 存在严重问题时，安装预检会阻止继续操作。
5. 缺少 idp-oauth 时，CLI 引导的默认 oauth 路径失败；依赖自动启用并修复登录问题后，操作成功。
6. 缺少令牌时，CLI 引导的令牌模式失败；自动生成令牌或修复手动令牌后，操作成功。
7. 自动检测升级方式、确认备份、确认升级计划，并成功完成升级后检查。
8. 诊断 Environment mismatch 并提供可执行的步骤。
9. 诊断由端口冲突导致的启动失败，并提供修复命令。
10. 诊断由文件权限被拒绝（EACCES）导致的启动失败，并提供具体的权限／访问修复步骤。
11. 离线模式下使用本地 compose 模板成功完成 Docker 安装，无需查询外部文档。
12. 用户提供数据库输入时，Docker 安装会自动切换到 db_mode=existing。
13. 数据库不可用时，create/git 预检失败，并返回 PostgreSQL/MySQL/MariaDB 官方安装链接。
14. 数据库端点和身份验证探测成功时，create/git 预检通过。
15. oauth 模式下的 task=app-manage 会验证元数据／身份验证流程、运行 env update，并且仅在完整连通性检查成功后返回当前环境信息。
16. 令牌模式下，远程 URL 缺少令牌时，task=app-manage 会失败并给出明确的令牌必需错误。
17. Docker 安装未指定 channel 时会请求澄清，并在用户选择后记录 release_channel_source=clarified。
18. Docker 安装指定 channel 时会保留用户选择，并记录 release_channel_source=user_explicit。

输出约定

最终响应必须包含：

• 所选模式和任务
• 使用的输入（method、channel、directory、port）
• release_channel_source（user_explicit/clarified/default_fallback）
• 预检摘要（fail/warn/pass）
• 已执行的操作
• 验证结果
• CLI 引导结果（cli_env_name、base_url、scope、env_update_status）
• 未解决的风险
• 建议的下一步操作

对于 install 任务，recommended next action 必须包括：

• 登录 URL
• 首次登录的账号和密码
• 更换密码提醒

参考资料

• 使用指南：面向用户的指南，介绍安装、CLI 引导、应用环境管理、升级和诊断工作流。

• Docker 模板：本地优先的 compose 模板选择器及发布渠道映射。

• 安装模板：用于 create-app/git 的本地命令模板及渠道映射覆盖项。

• 预检清单：执行任何可变更操作前使用。

• 安装运行手册：用于安装和启动流程。

• 应用环境管理：用于应用环境的添加、使用、查看当前环境、列出操作及 oauth/token 策略。

• 升级运行手册：用于安全地升级单实例。

• 故障排除知识库：用于排查高频故障。

• NocoBase Docker 安装：首要的 Docker 安装参考。[已验证：2026-04-08]

• NocoBase Docker 升级：Docker 升级限制和步骤。[已验证：2026-04-08]

• NocoBase create-nocobase-app 安装：create-app 引导路径。[已验证：2026-04-08]

• NocoBase Git 安装：源代码安装路径。[已验证：2026-04-08]

• NocoBase 环境变量：运行时环境配置参考。[已验证：2026-04-08]

• Docker 安装文档：缺少依赖时的 Docker 安装指南。[已验证：2026-04-08]

• Node.js 下载：Node.js 安装参考。[已验证：2026-04-08]

• Git 安装：Git 安装参考。[已验证：2026-04-08]

• Yarn Classic 安装：Yarn 1.x 安装参考。[已验证：2026-04-08]

• PostgreSQL 下载：PostgreSQL 安装指南和软件包。[已验证：2026-04-15]

• MySQL 安装文档：MySQL 官方安装文档。[已验证：2026-04-15]

• MySQL 下载：MySQL 官方下载页面。[已验证：2026-04-15]

• MariaDB 下载：MariaDB 官方下载页面。[已验证：2026-04-16]