nocobase-env-manage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Goal

目标

Use

nb

CLI only to complete NocoBase bootstrap and lifecycle actions.

仅使用

nb

CLI完成NocoBase的初始化及生命周期操作。

Hard Rules

硬性规则

Only run direct
```
nb
```
commands.
Never run local scripts (
```
*.mjs
```
,
```
*.ps1
```
,
```
*.sh
```
).
Never use template-driven install flows.
For
```
task=install
```
, only execute
```
nb init --ui
```
.
Do not add extra precheck gates before executing user-requested
```
nb
```
commands.
Prefer executing user-requested runtime commands first; use
```
nb --help
```
when user asks for diagnostics/help output or command discovery is needed.
Surface CLI outputs and hints directly to users.

仅直接运行
```
nb
```
命令。
绝不运行本地脚本（
```
*.mjs
```
、
```
*.ps1
```
、
```
*.sh
```
）。
绝不使用模板驱动的安装流程。
当
```
task=install
```
时，仅执行
```
nb init --ui
```
。
在执行用户请求的
```
nb
```
命令前，不要添加额外的预检查环节。
优先执行用户请求的运行时命令；当用户需要诊断/帮助输出或需要发现命令时，使用
```
nb --help
```
。
直接向用户展示CLI输出内容和提示信息。

Supported Tasks

支持的任务

```
install
```
```
app-manage
```
```
upgrade
```
```
stop
```
```
start
```

```
install
```
（安装）
```
app-manage
```
（应用管理）
```
upgrade
```
（升级）
```
stop
```
（停止）
```
start
```
（启动）

Input Contract

输入约定

Input	Required	Default	Notes
`task`	yes	inferred	one of `install/app-manage/upgrade/start/stop`
`app_env_action`	for `task=app-manage`	`list`	one of `add/use/current/list/remove` ; `current` is derived from list output
`app_env_name`	conditional	none	required for `add/use/remove`
`app_base_url`	conditional	none	required for `add` ; accepts URL with or without `/api` (auto-normalized)
`app_scope`	no	`project`	one of `project/global`
`cli_auth_mode`	for env add	`oauth`	one of `oauth/token`
`app_token`	conditional	none	required when `cli_auth_mode=token`
`runtime_env_name`	optional for `upgrade/start/stop`	current env	explicit runtime env name

输入项	是否必填	默认值	说明
`task`	是	自动推断	可选值： `install/app-manage/upgrade/start/stop`
`app_env_action`	仅 `task=app-manage` 时需填	`list`	可选值： `add/use/current/list/remove` ； `current` 由列表输出推导得出
`app_env_name`	条件必填	无	`add/use/remove` 操作时必填
`app_base_url`	条件必填	无	`add` 操作时必填；接受带或不带 `/api` 的URL（会自动标准化）
`app_scope`	否	`project`	可选值： `project/global`
`cli_auth_mode`	仅添加环境时需填	`oauth`	可选值： `oauth/token`
`app_token`	条件必填	无	当 `cli_auth_mode=token` 时必填
`runtime_env_name`	`upgrade/start/stop` 操作可选	当前环境	明确指定的运行时环境名称

Execution Policy

执行策略

Execute the target
```
nb
```
command directly.
Install routing is fixed:
- ```
task=install
```
  ->
```
nb init --ui
```
  only
Do not run separate preflight checks unless the user explicitly asks for diagnostics.
If command fails, return key CLI output lines and suggested next commands from CLI output.
For environment query intents (
```
list/current
```
), use fast path:
- first command:
```
nb env list -s project
```
- only run
```
nb env list -s global
```
  when user explicitly asks global/all scopes, or when project scope is empty and user asks for available envs.
For environment query intents, keep command set minimal and compatible:
- ```
nb env --help
```
  /
```
nb env list --help
```
  are available when command discovery is needed.
- ```
nb env current
```
  and
```
nb env list --json
```
  may be unavailable in some CLI builds.
For
```
env add
```
, normalize API base URL before execution:
- if URL already ends with
```
/api
```
  , keep as-is
- otherwise append
```
/api
```

直接执行目标
```
nb
```
命令。
安装路由固定：
- ```
task=install
```
  -> 仅执行
```
nb init --ui
```
除非用户明确要求诊断，否则不要运行单独的预检检查。
如果命令执行失败，返回关键的CLI输出行以及CLI输出中建议的后续命令。
对于环境查询意图（
```
list/current
```
），使用快速路径：
- 第一个命令：
```
nb env list -s project
```
- 仅当用户明确要求全局/所有范围，或项目范围为空且用户询问可用环境时，才运行
```
nb env list -s global
```
  。
对于环境查询意图，保持命令集最小且兼容：
- 当需要发现命令时，可使用
```
nb env --help
```
  /
```
nb env list --help
```
  。
- 在某些CLI版本中，
```
nb env current
```
  和
```
nb env list --json
```
  可能不可用。
执行
```
env add
```
操作时，先标准化API基础URL：
- 如果URL已以
```
/api
```
  结尾，则保持不变
- 否则追加
```
/api
```

Env Resolution Rule

环境解析规则

For

upgrade/start/stop

If
```
runtime_env_name
```
is provided, pass
```
-e <env>
```
.
If no env is provided, run command without
```
-e
```
and follow CLI response.
If CLI reports no env configured, surface that message and ask user whether to create a new app or add an env.

对于

upgrade/start/stop

操作：

如果提供了
```
runtime_env_name
```
，则传递参数
```
-e <env>
```
。
如果未提供环境，则不带
```
-e
```
参数运行命令并遵循CLI的响应。
如果CLI报告未配置环境，则展示该消息并询问用户是创建新应用还是添加环境。

Command Map

命令映射

install

install（安装）

bash

nb init --ui
nb env list -s project

bash

nb init --ui
nb env list -s project

app-manage

app-manage（应用管理）

list/current

list/current（列表/当前环境）

bash

nb env list -s <project|global>

For

current

, derive from the row marked with leading

nb env list

output. Do not call

nb env current

When CLI returns:

```
No envs configured.
```

Run 'nb env add <name> --base-url <url>' to add one.

surface this message directly and ask whether to create a new app (

nb init --ui

) or add env.

bash

nb env list -s <project|global>

对于

current

，从

nb env list

输出中带有前置

的行推导得出。不要调用

nb env current

。

当CLI返回以下内容时：

```
No envs configured.
```
（未配置任何环境。）
```
Run 'nb env add <name> --base-url <url>' to add one.
```
（运行'nb env add <name> --base-url <url>'添加一个环境。）

直接展示该消息并询问用户是创建新应用（

nb init --ui

）还是添加环境。

add (oauth)

add (oauth)（添加（OAuth认证））

bash

nb env add <name> --scope <project|global> --api-base-url <url> --auth-type oauth

<url>

uses normalized value (auto-append

/api

when missing).

bash

nb env add <name> --scope <project|global> --api-base-url <url> --auth-type oauth

<url>

使用标准化后的值（当缺少

/api

时自动追加）。

add (token)

add (token)（添加（令牌认证））

bash

nb env add <name> --scope <project|global> --api-base-url <url> --auth-type token --access-token <token>

<url>

uses normalized value (auto-append

/api

when missing).

bash

nb env add <name> --scope <project|global> --api-base-url <url> --auth-type token --access-token <token>

<url>

使用标准化后的值（当缺少

/api

时自动追加）。

use

use（切换环境）

bash

nb env use <name> -s <project|global>

bash

nb env use <name> -s <project|global>

remove

remove（移除环境）

bash

nb env remove <name> -s <project|global>

Write actions (

add/use/remove

) must always be followed by:

bash

nb env list -s <project|global>

bash

nb env remove <name> -s <project|global>

写入操作（

add/use/remove

）执行后必须始终运行：

bash

nb env list -s <project|global>

upgrade

upgrade（升级）

bash

nb upgrade [-e <env>]

Optional:

bash

nb upgrade [ -e <env> ] --skip-code-update

bash

nb upgrade [-e <env>]

可选命令：

bash

nb upgrade [ -e <env> ] --skip-code-update

stop

stop（停止）

bash

nb stop [-e <env>]

bash

nb stop [-e <env>]

start

start（启动）

bash

nb start [-e <env>]

Optional:

bash

nb start -e <env> --quickstart
nb start -e <env> --port <port>
nb start -e <env> --daemon

bash

nb start [-e <env>]

可选命令：

bash

nb start -e <env> --quickstart
nb start -e <env> --port <port>
nb start -e <env> --daemon

Safety

安全注意事项

Never run
```
upgrade
```
on ambiguous env.
Ask explicit confirmation before
```
upgrade
```
when user intent is not explicit.

Confirmation template:

Confirm execution: nb upgrade -e <env>. Reply confirm to continue.

绝不在环境不明确的情况下执行
```
upgrade
```
。
当用户意图不明确时，执行
```
upgrade
```
前需明确确认。

确认模板：

确认执行：nb upgrade -e <env>。回复confirm以继续。

Output Contract

输出约定

Final response must include:

selected task
executed commands
relevant CLI outputs (including error/hint lines when failed)
normalized API base URL (for
```
env add
```
)
next action

最终响应必须包含：

选定的任务
执行的命令
相关的CLI输出（包括执行失败时的错误/提示行）
标准化后的API基础URL（针对
```
env add
```
操作）
下一步操作

References

参考资料

Usage Guide
Install Runbook
Upgrade Runbook
Preflight Checklist
Troubleshooting

使用指南
安装手册
升级手册
预检清单
故障排查