nocobase-env-bootstrap

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Goal

目标

Help users set up NocoBase smoothly from zero to running by handling environment checks, installation, local CLI environment bootstrap, application environment management, single-instance upgrade, and high-frequency troubleshooting.

帮助用户顺利完成NocoBase从0到运行的搭建，涵盖环境检查、安装、本地CLI环境初始化、应用环境管理、单实例升级以及高频问题排查。

Scope

适用范围

Detect host environment and required dependencies automatically when possible.
Install and initialize NocoBase with Docker, create-nocobase-app, or Git method.
Start NocoBase in one environment (local machine or single server).
After successful install, automatically bootstrap local
```
nocobase-ctl
```
environment (
```
local
```
) for downstream CLI-first skills.
Provide reusable app environment management actions (
```
add
```
,
```
use
```
,
```
current
```
,
```
list
```
) through skill-local wrapper script for downstream skills.
Run safe single-instance upgrades with explicit pre-check and post-check gates.
Diagnose and fix high-frequency setup and runtime failures.

尽可能自动检测主机环境及所需依赖。
通过Docker、create-nocobase-app或Git方式安装并初始化NocoBase。
在单一环境（本地机器或单服务器）中启动NocoBase。
安装成功后，自动初始化本地
```
nocobase-ctl
```
环境（
```
local
```
），为后续CLI优先的操作提供支持。
通过技能本地包装脚本提供可复用的应用环境管理操作（
```
add
```
、
```
use
```
、
```
current
```
、
```
list
```
），供后续操作使用。
执行安全的单实例升级，包含明确的前置检查和后置检查环节。
诊断并修复搭建和运行过程中的高频故障。

Non-Goals

不适用范围

Do not handle cross-environment release workflows.
Do not orchestrate migration manager or data promotion between environments.
Do not make irreversible destructive changes (drop database, delete data volumes) without explicit user confirmation.
Do not hide unknown errors; always show the exact command and captured failure signal.
Do not assume built-in external-database compose templates exist; require explicit user-provided DB connection inputs when external DB is needed.

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

Input Contract

输入约定

Input	Required	Default	Validation	Clarification Question
`mode`	no	`quick`	one of `quick/standard/rescue`	"Do you want quick mode, standard mode, or rescue mode?"
`task`	yes	inferred from user text	one of `preflight/install/upgrade/diagnose/app-manage`	"Should I run preflight, install, upgrade, diagnose, or app-manage?"
`install_method`	install optional, upgrade optional	install: `docker` ; upgrade: `auto`	one of `auto/docker/create-nocobase-app/git`	"Which installation method should be used?"
`release_channel`	install or upgrade	`latest`	one of `latest/beta/alpha`	"Which release channel should be used ( `alpha` is recommended when AI build capabilities are needed in docker install)?"
`target_version`	upgrade optional	none	non-empty version or image tag	"Which target version should be upgraded to?"
`backup_confirmed`	upgrade required	`false`	must be `true` before upgrade	"Have you completed and confirmed database backup?"
`upgrade_confirmed`	upgrade required for non-dry-run	`false`	must be `true` before non-dry-run upgrade	"Please confirm the resolved upgrade method/version/restart plan."
`restart_mode`	upgrade optional	`manual`	one of `manual/dev/start/pm2`	"How should app be restarted after upgrade?"
`clean_retry`	upgrade git optional	`false`	boolean ( `true/false` )	"If git upgrade fails, should clean-retry be enabled?"
`allow_dirty`	upgrade git optional	`false`	boolean ( `true/false` )	"Allow upgrade on dirty git worktree?"
`target_dir`	install/upgrade	current directory	writable path	"Where should the project be created or operated?"
`db_mode`	install	`bundled` for docker; `existing` for create/git	one of `bundled/existing`	"Use bundled database or connect existing database?"
`db_dialect`	install	`postgres`	one of `postgres/mysql/mariadb`	"Use PostgreSQL, MySQL, or MariaDB?"
`db_host`	when `db_mode=existing`	none	non-empty host	"Which DB host should be used?"
`db_port`	when `db_mode=existing`	by dialect ( `5432` / `3306` )	numeric port	"Which DB port should be used?"
`db_database`	when `db_mode=existing`	none	non-empty database name	"Which DB database should be used?"
`db_database_mode`	when `db_mode=existing`	`existing`	one of `existing/create`	"Use existing database or create database first?"
`db_user`	when `db_mode=existing`	none	non-empty user	"Which DB user should be used?"
`db_password`	when `db_mode=existing`	none	non-empty password	"Please provide DB password."
`db_underscored`	no	`false`	boolean ( `true/false` )	"For local DB, should DB_UNDERSCORED be enabled?"
`port`	no	`13000`	integer 1..65535	"Which app port should be used?"
`network_profile`	no	`online`	one of `online/restricted/offline`	"Can this host access external internet directly?"
`cli_env_name`	no	`local`	non-empty slug	"Which local nocobase-ctl env name should be created?"
`cli_auth_mode`	no	`oauth`	one of `oauth/token`	"Use OAuth mode (default) or token mode for CLI env bootstrap?"
`cli_token_env`	no	`NOCOBASE_API_TOKEN`	valid env variable name	"Which env var stores API token when token mode is used?"
`app_env_action`	only when `task=app-manage`	`current`	one of `add/use/current/list`	"Which app environment action should run: add, use, current, or list?"
`app_env_name`	conditional	none	required for `app_env_action=add/use`	"Which environment name should be used?"
`app_base_url`	conditional	none	required for `app_env_action=add` ; valid HTTP/HTTPS URL	"Which application URL should be used for env add?"
`app_scope`	no	`project`	one of `project/global`	"Should this env action use project or global scope?"
`app_token`	conditional	none	required when `app_env_action=add` uses token mode with remote URL	"Please provide API token for token-mode remote environment add."

Default behavior when user says "you decide":

```
mode=quick
```
```
task=install
```
```
install_method=docker
```
```
release_channel=latest
```
(docker install still runs channel clarification when user did not specify channel)
```
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
```

输入项	是否必填	默认值	验证规则	确认问题
`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模式（默认）还是Token模式？"
`cli_token_env`	否	`NOCOBASE_API_TOKEN`	有效的环境变量名称	"使用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` 使用Token模式连接远程URL时必填	"请提供Token模式添加远程环境所需的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
```

Mandatory Clarification Gate

强制确认环节

Max clarification rounds:
```
2
```
Max questions per round:
```
3
```
Never run mutable actions (
```
install/upgrade
```
) until all required inputs for the selected
```
task
```
are resolved.
Docker release-channel clarification gate is mandatory for install:
when
```
task=install
```
and
```
install_method=docker
```
, if user did not explicitly specify
```
release_channel
```
, ask one short question before install:
"Docker default is
```
latest
```
, but current AI build capabilities are more complete in
```
alpha
```
. Install
```
alpha
```
now?"
accepted values:
```
alpha
```
/
```
latest
```
/
```
beta
```
.
if user explicitly indicates stability or production preference, select
```
latest
```
.
record channel decision source as
```
user_explicit
```
,
```
clarified
```
, or
```
default_fallback
```
.
Upgrade gate is mandatory:
```
backup_confirmed
```
must be
```
true
```
before running upgrade commands.
For upgrade,
```
install_method
```
defaults to
```
auto
```
; resolve method from marker/project files when user does not specify.
```
upgrade_confirmed
```
must be
```
true
```
before non-dry-run upgrade commands.
If
```
target_version
```
is lower than current version, stop (downgrade is not supported).
For
```
install_method=git
```
, block dirty worktree unless
```
allow_dirty=true
```
.
For
```
task=app-manage
```
:

app_env_action=add

, require

app_env_name

and

app_base_url

DB policy is mandatory for install:
```
docker
```
default is
```
db_mode=bundled
```
.
If user provides DB connection inputs on docker path, switch to
```
db_mode=existing
```
.
```
create-nocobase-app
```
and
```
git
```
always require
```
db_mode=existing
```
plus PostgreSQL/MySQL/MariaDB readiness.
for
```
db_mode=existing
```
, require
```
db_database_mode
```
decision:
```
existing
```
: connect and verify existing database directly.
```
create
```
: create database first, then connect/verify to avoid repeated initial connection failures.
If DB host is local (
```
localhost
```
,
```
127.0.0.1
```
,
```
::1
```
,
```
host.docker.internal
```
), ask for
```
db_underscored
```
preference; default to
```
false
```
when user does not specify.
If DB is missing or unreachable for existing mode, stop and provide official install links:
PostgreSQL:
```
https://www.postgresql.org/download/
```

MySQL install docs:

https://dev.mysql.com/doc/en/installing.html

MySQL downloads:
```
https://dev.mysql.com/downloads/mysql
```
MariaDB downloads:
```
https://mariadb.org/download/
```
App env auth-mode rule is mandatory:
default add mode is
```
oauth
```
(unless token args are provided without explicit auth-mode).

oauth mode requires dependency bundle

@nocobase/plugin-api-doc

@nocobase/plugin-idp-oauth

and interactive

env auth

token mode local URL (strict): host in
```
localhost
```
,
```
127.0.0.1
```
,
```
::1
```
,
```
*.localhost
```
, or
```
host.docker.internal
```
-> token is mandatory but auto-acquired by
```
env-manage
```
(never use placeholder token).
token mode remote URL: token must be manually provided by user (
```
app_token
```
or token env).
For install flows, always run CLI environment bootstrap (
```
node ./scripts/env-manage.mjs add ...
```
) as final stage.
Before running
```
env update
```
, ensure CLI dependency plugins are active by auth mode:

oauth:

@nocobase/plugin-api-doc

@nocobase/plugin-idp-oauth

token:

@nocobase/plugin-api-doc

@nocobase/plugin-api-keys

If token mode is used and
```
cli_token_env
```
is missing during CLI bootstrap, attempt automatic token generation first; ask user manually only when automatic path fails.
If required inputs are missing or ambiguous, stop and ask one short clarification question.
If any required path is invalid or not writable, stop and request a valid writable path before continuing.

最大确认轮次：
```
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
```
（默认 fallback）。
升级必须经过确认：
执行升级命令前，
```
backup_confirmed
```
必须为
```
true
```
。
升级时，
```
install_method
```
默认值为
```
auto
```
；若用户未指定，从标记/项目文件中推断方式。
执行非试运行升级命令前，
```
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
```
。
若现有模式下数据库缺失或无法访问，停止操作并提供官方安装链接：
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；仅当自动生成失败时，再询问用户手动提供。
若必填输入项缺失或不明确，停止操作并询问一个简短的确认问题。
若任何必填路径无效或不可写入，停止操作并要求用户提供有效的可写入路径后再继续。

Workflow

工作流程

Parse request and normalize intent.

If intent is unclear, ask only one short question to select
```
task
```
.
Keep first round to at most five questions.
For docker install, resolve
```
release_channel
```
with this priority:
user explicit input > docker channel clarification answer > default fallback
```
latest
```
.

Run preflight gate before install/upgrade.

For install/upgrade, run core checks only:

Windows: execute

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: execute

bash scripts/preflight.sh <port> <install_method> <db_mode> <db_dialect> <db_database_mode>

with

DB_HOST/DB_PORT/DB_DATABASE/DB_USER/DB_PASSWORD

in environment.

Classify findings into
```
fail
```
,
```
warn
```
, and
```
pass
```
.
Treat dependency/runtime/path/network blockers as immediate blockers.

Execute by mode.

```
quick
```
: Docker-first path with minimal questions.
```
quick
```
+ docker install: if user did not provide channel, ask the mandatory docker channel clarification and recommend
```
alpha
```
.
```
standard
```
: user chooses method and database dialect.
```
rescue
```
: collect diagnostics (
```
powershell -File scripts/collect-diagnostics.ps1
```
on Windows,
```
bash scripts/collect-diagnostics.sh
```
on Linux/macOS), map findings to troubleshooting entries, then apply the smallest safe fix first.
Install execution policy:
Use local scripts and templates only.
Docker path uses
```
assets/docker-templates/
```
.
create-app/git path uses
```
assets/install-templates/
```
.
Do not search web pages for install command snippets during execution.

Execute task-specific runbook.

For install: follow Install Runbook.
For install command execution, use local script:

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>

For upgrade: follow Upgrade Runbook and execute local script:

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>

For diagnose: follow Troubleshooting KB.
For app environment management (
```
task=app-manage
```
): follow App Environment Manage.

Run post-check gate and bootstrap CLI environment.

Verify service availability, login path, basic plugin/runtime health, and error logs.
For install, app startup and login readiness complete core install flow.
Ensure CLI dependency plugin bundle is active before CLI runtime refresh:

oauth (default):

@nocobase/plugin-api-doc

@nocobase/plugin-idp-oauth

token:

@nocobase/plugin-api-doc

@nocobase/plugin-api-keys

Preferred activation path:

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

If plugin state changed, restart app before

node ./scripts/run-ctl.mjs -- env update ...

Always run CLI bootstrap as final stage for install/upgrade:

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 bootstrap target command:

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>

After env add succeeds, run runtime refresh for downstream command readiness:

node ./scripts/run-ctl.mjs -- env update -e <cli_env_name> -s project

Perform immediate readback (

node ./scripts/env-manage.mjs current --scope project --base-dir <target_dir>

) and include expected vs actual values.

Report output.

Include command list executed.
Include evidence of success/failure from command output.

Include

release_channel_source

evidence (

user_explicit

clarified

default_fallback

) for install flows.

For every write action (for example
```
.env
```
, compose file, or runtime config), perform immediate read-after-write verification and report expected vs actual values.
Include CLI bootstrap evidence:
```
cli_env_name
```
```
base_url
```
```
scope
```
```
auth_mode
```
```
env_update_status
```
For
```
task=app-manage
```
, include app env operation evidence:
```
app_env_action
```
```
current_env_name
```
```
current_base_url
```
```
is_local
```
```
auth_mode
```
(for add)
```
token_mode
```
(for add)
For
```
install
```
success paths, include first-login credentials:
if root credentials were not explicitly customized, show default
```
admin@nocobase.com
```
/
```
admin123
```
and remind user to rotate password.
if customized, show configured login account and password source.
Include one clear next action.

解析请求并标准化意图。

若意图不明确，仅询问一个简短问题以确定
```
task
```
。
第一轮提问最多不超过5个。
Docker安装时，按以下优先级确定
```
release_channel
```
：
用户明确输入 > Docker渠道确认回复 > 默认 fallback
```
latest
```
。

安装/升级前执行预检查环节。

对于安装/升级，仅执行核心检查：

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: 执行

bash scripts/preflight.sh <port> <install_method> <db_mode> <db_dialect> <db_database_mode>

，并将

DB_HOST/DB_PORT/DB_DATABASE/DB_USER/DB_PASSWORD

设置为环境变量。

将检查结果分为
```
fail
```
（失败）、
```
warn
```
（警告）和
```
pass
```
（通过）。
将依赖/运行时/路径/网络问题视为即时阻塞项。

根据模式执行操作。

```
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/
```
下的模板。
执行过程中不得从网页搜索安装命令片段。

执行任务特定的运行手册。

安装：遵循安装运行手册。
安装命令执行使用本地脚本：

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
```
）：遵循应用环境管理手册。

执行后置检查环节并初始化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>

）并包含预期值与实际值。

输出报告。

包含已执行的命令列表。
包含命令输出中的成功/失败证据。

安装流程需包含

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
```
（添加操作时）
```
token_mode
```
（添加操作时）
安装成功时，包含首次登录凭据：
若未明确自定义管理员凭据，显示默认
```
admin@nocobase.com
```
/
```
admin123
```
并提醒用户修改密码。
若已自定义，显示配置的登录账号和密码来源。
包含一个明确的下一步操作建议。

Reference Loading Map

参考文档映射表

Reference	Use When	Notes
assets/docker-templates.md	docker install	local template selector and release-channel mapping
assets/install-templates.md	create-app/git install	local command/env template mapping and channel defaults
references/preflight-checklist.md	before install/upgrade	dependency, path, network, and port checks
references/install-runbook.md	install and first startup	docker/create-app/git execution guide
references/app-env-manage.md	`task=app-manage`	add/use/current/list contract with oauth/token auth-mode policy
references/upgrade-runbook.md	single-instance upgrade	pre-check, execution, post-check, rollback guidance
references/troubleshooting.md	diagnose and recovery	high-frequency issue decision table

参考文档	使用场景	说明
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	诊断和恢复	高频问题决策表

Safety Gate

安全保障环节

High-impact actions:

modifying running service version
changing runtime environment variables
restarting production-like services
replacing or removing compose services

Safety rules:

Require explicit confirmation before any upgrade action.
Require backup confirmation before upgrade.
Require
```
--confirm-upgrade true
```
before non-dry-run upgrade script execution.
Never run destructive delete commands automatically.
If commands fail, stop and surface exact failure output before next action.

Confirmation template:

"Confirm execution:
```
{{task}}
```
on
```
{{target}}
```
with method
```
{{install_method}}
```
. Impact: runtime may restart and service may be briefly unavailable. Reply
```
confirm
```
to continue."

高影响操作：

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

安全规则：

任何升级操作前需获得用户明确确认。
升级前需确认已完成备份。
执行非试运行升级脚本前需添加
```
--confirm-upgrade true
```
参数。
不得自动执行破坏性删除命令。
若命令失败，停止操作并显示确切的失败输出后再进行下一步。

确认模板：

"确认执行：
```
{{task}}
```
，目标环境：
```
{{target}}
```
，方式：
```
{{install_method}}
```
。影响：运行时可能重启，服务可能短暂不可用。回复
```
confirm
```
以继续。"

Verification Checklist

验证清单

Preflight completed and contains zero unresolved blocking failures.
Preflight fails when
```
APP_KEY
```
is weak for existing project files, and defers missing
```
APP_KEY
```
only for fresh install targets before local install script generation.
Docker install without explicit channel triggers clarification and recommends
```
alpha
```
.
Explicit user channel choice is respected without re-asking.
Existing DB mode fails when required DB fields are missing or endpoint is unreachable.
```
create-nocobase-app
```
/
```
git
```
fail preflight when PostgreSQL/MySQL/MariaDB is unavailable.
Method and release channel are explicitly confirmed or defaulted.
Install commands are recorded and reproducible.
Install core success is determined by app startup and login readiness.
CLI final stage runs for install/upgrade and successfully creates/updates local env via skill-local env helper (
```
node ./scripts/env-manage.mjs add ...
```
).

task=app-manage

supports

add/use/current/list

through

node ./scripts/env-manage.mjs ...

App env add enforces auth-mode rules correctly (
```
oauth
```
default with metadata/auth flow; token mode keeps local-vs-remote token policy).
App env add is not considered success unless
```
env update
```
connectivity verification succeeds.
CLI runtime refresh (
```
node ./scripts/run-ctl.mjs -- env update ...
```
) succeeds for the bootstrap env.
If runtime refresh fails with
```
swagger:get
```
404 or API documentation disabled, skill applies plugin activation sequence and retries.
OAuth path confirms
```
@nocobase/plugin-idp-oauth
```
is active before OAuth metadata/auth verification.
Token acquisition path confirms
```
@nocobase/plugin-api-keys
```
is active before generating/providing token.
Readback confirms expected env name/base URL/scope and current env selection.
Upgrade path includes backup confirmation.
Upgrade path includes script-level confirmation gate (
```
--confirm-upgrade true
```
) after plan readback.
Post-check verifies app reachability and login page.
Troubleshooting output includes root-cause hypothesis and concrete fix steps.
Result summary contains completed, pending, and next action items.
Every write action includes immediate readback evidence.

预检查已完成且无未解决的阻塞性失败。
现有项目文件中
```
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模式及元数据/认证流程；Token模式遵循本地/远程Token策略）。
仅当
```
env update
```
连接验证成功时，应用环境添加才视为成功。
初始化环境的CLI运行时刷新（
```
node ./scripts/run-ctl.mjs -- env update ...
```
）成功。
若运行时刷新因
```
swagger:get
```
404或API文档禁用失败，技能会执行插件激活流程并重试。
OAuth方式在验证OAuth元数据/认证前，确认
```
@nocobase/plugin-idp-oauth
```
已激活。
Token获取方式在生成/提供Token前，确认
```
@nocobase/plugin-api-keys
```
已激活。
回读检查确认预期的环境名称/基础URL/范围以及当前选中的环境。
升级流程包含备份确认。
升级流程在方案回读后包含脚本级确认环节（
```
--confirm-upgrade true
```
）。
后置检查验证应用可访问性和登录页面。
故障排查输出包含根因假设和具体修复步骤。
结果摘要包含已完成、待处理和下一步操作项。
每个写入操作都包含即时的回读证据。

Minimal Test Scenarios

基础测试场景

Quick install on a clean host with Docker available, then CLI local env bootstrap runs automatically.
Preflight with missing Docker and missing Node.
Preflight fails on missing or placeholder-like
```
APP_KEY
```
, and passes after random key is set.
Install preflight blocks on critical issues.
CLI bootstrap default oauth path fails when
```
idp-oauth
```
is missing, then succeeds after dependency auto-enable/login fix.
CLI bootstrap token mode fails when token is missing, then succeeds after auto-generate/manual token fix.
Upgrade with method auto-detected, backup confirmed, upgrade plan confirmed, and successful post-check.
Diagnose
```
Environment mismatch
```
and produce actionable steps.
Diagnose startup failure caused by port conflict and provide fix command.
Diagnose startup failure caused by file permission denied (
```
EACCES
```
) and provide concrete permission/access fix steps.
Docker install in offline mode succeeds using local compose template without external docs lookup.
Docker install with user-provided DB inputs auto-switches to
```
db_mode=existing
```
.
create/git preflight fails when DB is unavailable and returns official PostgreSQL/MySQL/MariaDB install links.
create/git preflight passes when DB endpoint and auth probe succeed.
```
task=app-manage
```
with oauth mode validates metadata/auth flow, runs
```
env update
```
, and returns current env info only on full connectivity success.
```
task=app-manage
```
with token mode remote URL + missing token fails with clear token-required error.
Docker install without explicit channel asks clarification and records
```
release_channel_source=clarified
```
when user chooses.
Docker install with explicit channel keeps user choice and records
```
release_channel_source=user_explicit
```
.

干净主机上快速安装Docker版NocoBase，自动执行CLI本地环境初始化。
缺失Docker和Node.js的预检查。
```
APP_KEY
```
缺失或为占位符时预检查失败，设置随机密钥后通过。
安装预检查因关键问题阻塞。
CLI初始化默认OAuth方式因
```
idp-oauth
```
缺失失败，自动启用依赖并修复登录后成功。
CLI初始化Token方式因Token缺失失败，自动生成/手动提供Token后成功。
自动检测升级方式、确认备份、确认升级方案并通过后置检查的升级流程。
诊断
```
Environment mismatch
```
问题并提供可操作步骤。
诊断端口冲突导致的启动失败并提供修复命令。
诊断文件权限拒绝（
```
EACCES
```
）导致的启动失败并提供具体权限修复步骤。
离线模式下Docker安装使用本地compose模板成功，无需访问外部文档。
用户提供数据库信息的Docker安装自动切换为
```
db_mode=existing
```
。
数据库不可用时，create/git方式预检查失败并返回官方PostgreSQL/MySQL/MariaDB安装链接。
数据库端点和认证探测成功时，create/git方式预检查通过。
```
task=app-manage
```
使用OAuth模式验证元数据/认证流程，执行
```
env update
```
，仅在完全连接成功时返回当前环境信息。
```
task=app-manage
```
使用Token模式连接远程URL且缺失Token时，返回明确的Token必填错误。
未明确指定渠道的Docker安装询问确认问题，用户选择后记录
```
release_channel_source=clarified
```
。
用户明确指定渠道的Docker安装保留用户选择并记录
```
release_channel_source=user_explicit
```
。

Output Contract

输出约定

Final response must include:

selected mode and task
inputs used (method, channel, directory, port)

release_channel_source

(

user_explicit

clarified

default_fallback

)

preflight summary (
```
fail/warn/pass
```
)
actions executed
verification result

CLI bootstrap result (

cli_env_name

base_url

scope

env_update_status

)

unresolved risks
recommended next action

For

install

tasks,

recommended next action

must include:

login URL
first-login account and password
password rotation reminder

最终回复必须包含：

所选模式和任务
使用的输入参数（方式、渠道、目录、端口）

release_channel_source

（

user_explicit

clarified

default_fallback

）

预检查摘要（
```
fail/warn/pass
```
）
已执行的操作
验证结果

CLI初始化结果（

cli_env_name

、

base_url

、

scope

、

env_update_status

）

未解决的风险
推荐的下一步操作

对于

install

任务，

推荐的下一步操作

必须包含：

登录URL
首次登录账号和密码
修改密码提醒

References

参考资料

Usage Guide: human-readable guide for install, CLI bootstrap, app environment management, upgrade, and diagnose workflows.
Docker Templates: local-first compose template selector and release-channel mapping.
Install Templates: local command templates for create-app/git plus channel mapping overrides.
Preflight Checklist: use before any mutable action.
Install Runbook: use for install and startup flows.
App Environment Manage: use for app env add/use/current/list operations and oauth/token policy.
Upgrade Runbook: use for safe single-instance upgrades.
Troubleshooting KB: use for high-frequency failures.
NocoBase Docker Installation: primary Docker install reference. [verified: 2026-04-08]
NocoBase Docker Upgrading: Docker upgrade constraints and sequence. [verified: 2026-04-08]
NocoBase create-nocobase-app Installation: create-app bootstrap path. [verified: 2026-04-08]
NocoBase Git Installation: source-code install path. [verified: 2026-04-08]
NocoBase Environment Variables: runtime env configuration references. [verified: 2026-04-08]
Docker Install Docs: Docker setup guidance for missing dependency. [verified: 2026-04-08]
Node.js Downloads: Node.js installation reference. [verified: 2026-04-08]
Git Install: Git installation reference. [verified: 2026-04-08]
Yarn Classic Install: Yarn 1.x installation reference. [verified: 2026-04-08]
PostgreSQL Download: PostgreSQL installation guide and packages. [verified: 2026-04-15]
MySQL Install Docs: MySQL official installation documentation. [verified: 2026-04-15]
MySQL Downloads: MySQL official download page. [verified: 2026-04-15]
MariaDB Downloads: MariaDB official download page. [verified: 2026-04-16]

使用指南：安装、CLI初始化、应用环境管理、升级和诊断流程的易读指南。
Docker模板：本地优先的compose模板选择器和发布渠道映射。
安装模板：create-app/git方式的本地命令模板及渠道映射覆盖规则。
预检查清单：任何可变操作前需使用。
安装运行手册：安装和启动流程使用。
应用环境管理手册：应用环境add/use/current/list操作及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]