创建子应用项目
使用已取得下载权限的兼容模板:
pnpm create @nocobase/app@beta customer-app --template sub-app --template-tag beta
cd customer-app
pnpm nocobase config init
pnpm nocobase config checksub-app 是独立业务项目,预装项目部署 CLI,并注册 Platform SSO。主应用不会替你生成业务代码。应用开发方法见开发应用。
本地开发与登录
按快速开始配置独立数据库、访问地址和初始管理员,启动时显式传入开发端口,并核对终端打印的地址。本地管理员与部署后的实例管理员分别初始化;开发数据不会随构建归档部署。
APP_SERVER_HOST=0.0.0.0 APP_SERVER_PORT=13240 pnpm dev未配置平台凭据时,子应用使用本地登录。不要把某个已部署实例的 SSO 密钥复制进源码或本地示例配置来代替集成。

初始化部署配置
在子应用根目录运行:
pnpm nocobase deploy init --server https://apps.example.com/main --instance dev --id customer-dev --node local
pnpm nocobase deploy validate命令生成 deploy.yml。主应用地址包含其 base path;同一个文件中的实例使用同一主应用。validate 在本地检查部署配置及引用的配置文件,不连接主应用。
授权项目部署 CLI
pnpm nocobase deploy auth
pnpm nocobase deploy auth status
pnpm nocobase deploy doctor在浏览器中使用有部署权限的平台账号确认授权。CLI 会按主应用保存会话;auth logout 移除当前主应用的本机会话。部署权限不等于子应用业务权限。
doctor 检查 Node.js、配置、主应用连接、授权、运行节点和已有归档。尚未构建的项目应先解决连接和授权问题,再构建并重新检查。

配置目标节点与应用实例
一个项目可以在 deploy.yml 中配置多个实例。以下是 SQLite 示例:
version: 1
server: https://apps.example.com/main
build:
platform: auto
instances:
dev:
id: customer-dev
name: Customer Dev
node: local
database:
dialect: sqlite
access:
platformSso: true
admin: generated
sampleData: false
variables: {}dev 是本地配置键;id 是主应用中的稳定实例标识,不能使用主应用占用的 main。node 可以写具体节点标识或 auto,后者使用与界面一致的节点推荐规则,仍须检查计划中的选择。
使用外部数据库时,填写该实例的独立数据库连接,将密码写为 passwordEnv: CUSTOMER_DB_PASSWORD,由运行 CLI 的进程提供对应环境变量。配置文件用 config: ./deploy/dev.config.yml 引用;秘密值用 ${env:NAME},变量用 { env: NAME },不要写明文。
DB_*、INITIAL_ADMIN_*、PLATFORM_* 及主应用写入的访问地址不能作为普通变量随意覆盖。完整字段以 pnpm nocobase deploy schema 为准。
构建并发布版本
pnpm nocobase deploy artifact upload --build --yes
pnpm nocobase deploy artifact listCLI 构建、检查、上传并发布归档。应用包名取自项目 package.json 的 name,版本取自构建内容;首次上传自动创建应用包。发布前更新版本号,不可用同一版本覆盖旧内容。
--build 强制重新构建;省略它时可能使用已有归档,因此源码更新后不要依赖旧文件。artifact upload --dev --build --yes 发布带时间标识的开发版本,普通版本列表默认不显示它。
构建平台自动匹配目标节点;跨平台构建失败时,依据诊断选择兼容的构建机器或目标,不能靠修改归档元数据绕过检查。
预览部署计划与执行部署
pnpm nocobase deploy instance plan dev --action create
pnpm nocobase deploy instance create dev --plan <planId> --yes --wait以第一条命令返回的 planId 替换占位符。计划只读,显示目标版本、节点、配置变化和阻塞项;执行前确认这些内容。计划绑定请求内容和实例版本状态,目标或输入变化后需要重新生成。
部署结束后执行 instance status dev,并在真实访问地址验证登录和业务功能。等待审批、请求结果未知或进程仍在启动都不等于部署成功。

更新版本与同步配置
发布新版本后,先预览升级:
pnpm nocobase deploy instance plan dev --version 0.0.2确认数据库、文件和配置已备份后,再执行:
pnpm nocobase deploy instance upgrade dev --version 0.0.2 --plan <planId> --backup-acknowledged --yes --wait将示例版本替换为实际发布版本。备份确认只是记录你的确认,不会创建备份;升级可能执行迁移,降级版本不能撤销已经执行的数据变更。
修改实例配置文件或 variables 后,用 instance plan dev --action config 预览,再以 instance config dev --plan <planId> --backup-acknowledged --yes --wait 应用。配置变更会重启实例。
CLI 比较上次应用的配置、本地配置和主应用现状。仅在主应用修改的值会保留;两边修改同一项时以 CONFIG_DRIFT_CONFLICT 停止。执行 instance config dev --from-current 取回当前配置作为基线,合并需要的本地修改后重新预览。该命令会写入本地配置文件,先保存自己的改动。
使用 Agent 与 CI 部署
Agent 可以读取项目内安装的 nocobase-deploy-cli Skill,用 pnpm nocobase deploy commands --json 查询当前命令。授权分成两步:
pnpm nocobase deploy auth --start --json
# 由用户打开返回地址并批准授权后,再继续
pnpm nocobase deploy auth --resume --jsonCI 使用秘密存储注入 NB_DEPLOY_API_KEY 和 NB_DEPLOY_SERVER,后者必须与 deploy.yml 的主应用一致。API key 需要相应部署权限,不将其提交到仓库。自动化命令使用 --json,检查 ok、error.code 和退出码。
| 退出码 | 处理 |
|---|---|
0 | 命令完成,仍需按任务验证运行或业务结果 |
4 | 等待审批,交由有权限的人处理 |
5 | 计划存在阻塞项,尚未提交 |
6 | 结果未知,查询状态和原操作回执 |
7 | 计划已变化,重新预览 |
结果未知时先执行 instance status dev --wait --json。保留 storage/deployment/ 下的操作回执,使用原参数重试以查询原操作,不删除锁或改参数来重复提交。备份确认、降级和删除数据需要人的明确决定,Agent 不应自行添加相应确认参数。