跳到主要内容

声明式部署编排

版本提示

声明式部署编排（app.deployOrchestrator）自 v5.1.0 起提供，对应 CLI tcb deploy（≥ v3.8.0）。

DeployOrchestrator 提供一键编排部署能力：读取一份 cloudbaserc.json（v2.1）配置，按依赖顺序（database → functions → app → hosting → gateway）部署全部资源，支持 dry-run 计划预览、函数覆盖确认、本地 state 快照实现真增量跳过。

通过 app.deployOrchestrator 访问（与 CLI tcb deploy 同一套实现，能力下沉）。

无交互设计

manager-node 不内置任何交互 UI。函数覆盖确认完全外部化：传 yes: true 直接放行，或注入 confirmUpdate 回调按返回值决定。

deployPlan​

1. 接口描述​

接口功能：计算部署计划（dry-run），不执行任何实际部署

接口声明：app.deployOrchestrator.deployPlan(options): Promise<IDeployPlanItem[]>

2. 输入参数​

字段必填类型说明
config是Record<string, any>解析后的 cloudbaserc 配置（含 envOverrides 已合并）
envId是String环境 ID
only否ResourceType[]只部署指定类型
skip否ResourceType[]跳过指定类型
refresh否Boolean忽略本地 state skip 判定，强制云端对比（漂移检测）
cwd否String项目根目录，默认 process.cwd()

ResourceType：database / functions / app / hosting / gateway

3. 返回结果​

IDeployPlanItem[]：

字段类型说明
typeResourceType资源类型
nameString资源名称
statusStringcreate（新建）/ update（覆盖更新）/ skip（未变更）/ conflict（database 冲突，中断）/ deploy（直传覆盖）
actionString动作说明（用户可读）
changesArray变更字段明细（from → to）
fileDiffObjecthosting 文件级 diff（added/modified/deleted + totalChanged）

4. 示例代码​

import CloudBase from "@cloudbase/manager-node";

const app = CloudBase.init({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId",
});

const plan = await app.deployOrchestrator.deployPlan({
  config: { envId: "xxx", functions: [{ name: "fn-a" }] },
  envId: "xxx",
  cwd: process.cwd(),
});

for (const item of plan) {
  console.log(`[${item.type}] ${item.name}: ${item.action}`);
}

deploy​

1. 接口描述​

接口功能：执行部署（含覆盖确认）

接口声明：app.deployOrchestrator.deploy(options): Promise<IDeployResult>

2. 输入参数​

字段必填类型说明
config是Record<string, any>解析后的 cloudbaserc 配置
envId是String环境 ID
dryRun否Booleantrue 时只出计划不部署
yes否Boolean已存在函数（update）直接放行（AI Agent / CI）
confirmUpdate否(item) => Promise<boolean>每个 update 项回调，返回 true 执行 / false 跳过
only / skip否ResourceType[]类型过滤
refresh否Boolean强制云端对比（漂移检测）
cwd否String项目根目录
log否Object日志回调（info/success/warn/error）

3. 返回结果​

IDeployResult：

字段类型说明
planIDeployPlanItem[]完整部署计划
resultsArray每项：{ type, name, ok, url?, error?, reason? }

results 判定：

  • ok: true → 成功，url 为访问地址（如有）
  • ok: false + error → 部署失败原因
  • ok: false + reason: 'no-confirm' → 无确认机制，保守跳过（不擅自覆盖线上）
  • ok: false + reason: 'skipped-by-user' → 用户取消覆盖

4. 示例代码​

import CloudBase from "@cloudbase/manager-node";

const app = CloudBase.init({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId",
});

// AI Agent / CI：直接放行所有覆盖
const result = await app.deployOrchestrator.deploy({
  config: { envId: "xxx", functions: [{ name: "fn-a" }] },
  envId: "xxx",
  yes: true,
  cwd: process.cwd(),
});

if (result.results.every((r) => r.ok)) {
  console.log("部署完成");
} else {
  for (const r of result.results.filter((r) => !r.ok)) {
    console.error(`[${r.type}] ${r.name} 失败: ${r.error || r.reason}`);
  }
}

说明​

幂等与真增量​

  • 函数：云端存在性判断（ListFunctions）→ create / update；不做本地 hash
  • hosting：本地 .cloudbase/state.json 指纹快照，一致则 skip
  • app：本地 state 配置快照，一致则 skip
  • refresh: true 强制忽略本地快照重新对比云端

HTTP 云函数镜像部署​

functions 中的 HTTP 函数可通过顶层 buildStrategy 选择镜像部署方式：

  • image：使用 imageConfig.imageUri 指定的已有镜像。
  • local：在本地通过 Docker 构建并推送镜像。
  • cloud：上传构建上下文，由 CloudApp 云端构建并推送镜像。

镜像配置字段位于 imageConfig，构建配置位于 imageConfig.build。imageConfig.imageType 支持 personal 和 enterprise：个人版构建必须显式提供 imageConfig.build.registryCredential.username/password；企业版可通过 registryId 指定 TCR 实例，未填写时由部署流程自动发现。namespace 和 repository 未填写时由部署器按环境 ID 和函数名补齐。

部署流程会将镜像函数运行时设为 CustomImage，默认使用 9000 端口、Dockerfile 和 linux/amd64 构建平台；已显式配置的值优先保留。local 构建还会执行 Docker CLI、Daemon 和 Buildx 的部署前检查，并支持通过 imageConfig.localFallback: "cloud" 标记云端构建回退。

database 冲突中断​

database 迁移存在 conflict 时，部署中断（后续资源可能依赖新 Schema）。计划中表现为 status: 'conflict'。

版本对应​

manager-nodeCLI说明
≥ v5.1.0≥ v3.8.0声明式部署编排可用

参考​