跳到主要内容

声明式部署（tcb deploy）

版本要求

tcb deploy 声明式编排自 v3.8.0 起提供，需要 cloudbaserc.json v2.1 配置格式。

tcb deploy 读取项目根目录的 cloudbaserc.json（v2.1），按依赖顺序一键编排部署云函数、云应用、静态托管、网关路由和数据库迁移，无需逐个调用单资源命令。

第一次使用 CloudBase CLI？

请先阅读 快速开始：安装 CLI、登录账号、生成 cloudbaserc.json 后，再回到本页使用 tcb deploy。

与单资源命令的区别​

维度tcb deploytcb fn deploy / tcb hosting deploy 等
配置源一份 cloudbaserc.json 声明全部资源每个命令各自传参
编排database → functions → app → hosting → gateway 自动排序单资源
依赖处理函数依赖新 Schema（database 先行）、网关依赖函数/hosting不感知
幂等云端存在性判断 + 本地 state 快照，未变更自动跳过每次全量执行
覆盖确认已存在函数覆盖更新前确认（--yes 放行）--force

完整工作流​

声明式部署从零到一的标准流程：初始化配置 → 部署前校验 → 预览变更 → 实际部署。

步骤命令作用完成标志
1 初始化配置tcb config init智能检测项目资源（云函数目录 / 前端框架 / 静态托管目录），交互式生成 cloudbaserc.json（v2.1）项目根目录生成合法配置
2 部署前校验tcb validate校验 Schema 版本 / envId / 资源目录 / 引用一致性退出码 0，输出资源概览
3 预览变更tcb deploy --dry-run输出资源级变更计划：字段级差异（from → to）、hosting 文件 diff，不实际部署变更计划符合预期
4 实际部署tcb deploy按 database → functions → app → hosting → gateway 顺序编排部署部署成功，生成 state 快照

配置示例​

最小 cloudbaserc.json（v2.1）：

{
  "envId": "your-env-id",
  "version": "2.1",
  "functions": [
    { "name": "pay-common", "type": "Event", "handler": "index.main" }
  ],
  "hosting": [
    { "name": "web", "root": "web", "framework": "vite", "outputDir": "dist", "deployPath": "/web" }
  ],
  "gateway": {
    "routes": [
      { "path": "/api", "target": "function:pay-common" },
      { "path": "/web", "target": "hosting:web" }
    ]
  }
}

对应的项目目录结构：

project/
├── cloudbaserc.json
├── functions/
│   └── pay-common/
│       └── index.js
└── web/
    └── dist/        # 构建产物（或让 tcb deploy 本地构建）
目录约定

完整目录结构约定见下方 项目目录结构约定。数据库迁移默认放在 cloudbase/migrations/。

部署流程​

覆盖确认​

  • 云端已存在的函数（update 场景）会先确认是否覆盖
  • --yes 直接放行；交互模式逐项确认
  • 未提供确认机制时保守跳过（不擅自覆盖线上）

真增量部署​

  • 首次部署成功后，本地生成 .cloudbase/state.json 指纹快照
  • 二次部署：hosting 产物文件指纹一致、app 配置一致 → 自动 skip（不重复上传/构建）
  • --refresh 强制重新对比云端（漂移检测）

命令选项​

--dry-run​

只输出变更计划（terraform plan 心智），不实际部署：

tcb deploy --dry-run

输出字段级变更（from → to）、hosting 文件级 diff、database 迁移计划。

--only / --skip​

只部署指定类型 / 跳过指定类型：

tcb deploy --only=functions          # 只部署云函数
tcb deploy --only=hosting,gateway    # 只部署静态托管和网关
tcb deploy --skip=gateway            # 跳过网关

可选类型：database / functions / app / hosting / gateway。

--mode / --env-id​

按环境覆盖配置：

tcb deploy --mode=production       # 应用 envOverrides.production + .env.production
tcb deploy --env-id=xxx            # 指定环境（优先级最高）

--refresh​

忽略本地 state 快照的 skip 判定，强制重新对比云端并部署（漂移检测）：

tcb deploy --refresh

--yes​

函数覆盖更新直接放行（CI / AI Agent 场景）：

tcb deploy --yes

并发度（--concurrency）​

默认 1（严格串行），与历史行为一致。设置后，同类型的多个资源实例会并行部署；跨资源类型仍按依赖顺序（database → functions → app → hosting → gateway）串行，不会破坏依赖关系。

tcb deploy --concurrency 3          # 多个函数/多个托管站点之间并行，最大同时 3 个
  • 仅作用于「同类型连续实例」之间（例如多个 hosting 站点、多个函数）；函数与托管之间、托管与网关之间始终串行。
  • 并发数上限为 20，防止对后端 API 造成过大压力。

失败中断策略（--continue-on-error）​

默认 fail-fast：任一资源部署失败即中断后续资源，进程以非零退出码结束（便于 CI/CD 感知）。若希望「先跑完所有、最后统一看失败数」，可加 --continue-on-error：

tcb deploy --continue-on-error      # 某个资源失败也继续部署其余

例外：database 失败始终强制中断（无论是否 --continue-on-error），因为后续资源可能依赖新建的数据库 Schema。

资源配置概览​

各资源的完整配置字段见对应文档：

资源配置字段关键说明详细文档
数据库迁移database仅 postgresql；迁移文件 14位时间戳_名称.sql，默认目录 cloudbase/migrations/；冲突时中断部署PostgreSQL 管理
云函数functionsEvent / HTTP 双类型；zip 代码包或镜像部署（buildStrategy）；HTTP 函数支持 public 匿名访问与 gatewayPath 网关路由云函数配置 · 部署云函数
云应用app构建路径由 framework 决定：static 直传 / 其余云端构建应用部署
静态托管hosting数组多站点；本地构建（install + build）后直传静态网站托管
网关路由gateway.routestarget：function:<name> / hosting:<name>；pathRewrite 自动生成配置文件-网关
环境覆盖envOverrides按 --mode 合并覆盖配置文件说明
函数 target 类型

网关路由 target: function:<name> 支持两种函数类型：

  • HTTP 型（type: "HTTP"）→ 创建为 WEB_SCF 路由
  • Event 型（普通函数）→ 创建为 SCF 路由（已验证可正常访问，网关会把 HTTP 请求包装为事件转发给函数）

CLI 会自动查询函数详情判断类型，两种类型均可作为网关 target。

数据库迁移（database）​

声明式部署支持 database 资源，按 database.migrations 目录下的 SQL 文件顺序应用 PostgreSQL 迁移：

维度说明
支持类型仅 type: postgresql（type: nosql 仅透传、不编排）
迁移文件命名 14位时间戳_小写名称.sql（如 20260101120000_init.sql），默认目录 cloudbase/migrations/
计划（--dry-run）聚合为单条变更项：pending → create
冲突处理目标库已存在同名迁移 → 中断部署
失败策略database 失败始终强制中断（即便 --continue-on-error），后续资源可能依赖新建 Schema
数据库迁移失败即中断整体部署

database 排在编排最前（database → functions → app → hosting → gateway），一旦失败后续资源不再执行。请先用 tcb deploy --dry-run 确认迁移计划无误。

项目目录结构约定​

推荐目录形态（以 vibe-app 为例）：

vibe-app/
├── cloudbaserc.json          # 声明式配置（核心契约，含 envId/version 2.1）
├── .env                      # 密钥（不入 Git；--mode <mode> 时读 .env.<mode>）
├── .env.example              # 密钥模板（入 Git）
├── cloudbase/migrations/               # 数据库迁移（SQL，默认目录）
│   ├── 20260101120000_init.sql
│   └── 20260102150000_add_users.sql
├── functions/                # 云函数代码（functionRoot 默认 ./functions）
│   ├── task-runner/          # Event 函数：exports.main(event, context)
│   └── api-server/           # HTTP 函数：需 scf_bootstrap 启动脚本
├── web/                      # 前端代码（hosting[].root 指向）
└── Dockerfile                # HTTP 函数镜像部署用（可选，放函数目录内）

各路径决定规则：

资源配置字段默认/解析规则
数据库迁移目录database.migrationscloudbase/migrations/（相对项目根）
函数根目录functionRootfunctions/
函数代码目录dir / functionRoot+name显式 dir → {cwd}/{dir}（独立于 functionRoot）；否则 {cwd}/{functionRoot}/{name}
前端站点hosting[].root相对 cloudbaserc 的项目目录

常见问题​

1. gateway.routes 校验失败（should NOT have additional properties）​

Schema v2.1 不允许额外字段。例如 cdnType 不是合法路由字段，应移除；CDN 接入方式用 accessType（DIRECT / CDN / CUSTOM / EO）控制：

{ "path": "/web", "target": "hosting:web", "accessType": "DIRECT" }

2. HTTP 函数依赖安装规则​

函数类型运行时依赖安装方式
Event任意云端在线安装（默认）
HTTPNode.js云端在线安装（默认）
HTTP非 Node.js（Python/Php/Java/Go）必须本地安装后随代码包上传

HTTP 非 Node.js 函数需确保本机已安装依赖（如 Python pip install 到函数目录）。

3. 已存在函数是否覆盖？​

云端已存在（update）的函数默认需要确认；--yes 放行。声明式部署语义对齐 tcb fn deploy --force。

4. 网关路由在已绑定域名上，域名级字段不生效​

certId / protocol / accessType 是域名级字段（同一域名所有路由共享）。在已存在的域名上创建路由时，这些字段不会覆盖域名原值（如域名已绑定 HTTP_AND_HTTPS，配置 protocol: "HTTPS" 不生效），这是平台的安全行为——避免影响同域名下其它业务路由。它们只在首次创建域名时生效。

5. 网关路由幂等语义​

tcb deploy 的网关路由是幂等收敛（create / update / skip）：

  • 路由不存在 → 创建（create）
  • 路由已存在且显式声明的字段一致 → 跳过（skip）
  • 路由已存在但显式声明的字段不一致 → 更新（update，调 modifyHttpServiceRoute）

只比较显式声明的字段（enableAuth / enablePathTransmission 显式配置才比较、qpsPolicy / pathRewrite 本地有值才比较），未声明的字段不会覆盖云端配置。重复路径不会被当作错误（与命令式 tcb routes add 的 INVALID_PARAM 不同）。字段权威定义见 配置文件-网关。

参考​