HTTP 服务路由管理

v3.0.0+

tcb routes 命令自 v3.0.0 起提供。

tcb routes 用于管理 HTTP 网关的路由规则。路由规则定义了如何将 HTTP 请求（按域名+路径）转发到云函数、云托管、静态托管等上游服务。

路由与域名的关系

使用 tcb routes（命令式）时，路由必须绑定在已有的自定义域名下。如果还没有绑定自定义域名，请先使用 tcb domains add 添加，详见自定义域名管理。

区别：声明式部署（tcb deploy + cloudbaserc.json 的 gateway.routes）会自动绑定自定义域名（幂等），无需先执行 tcb domains add。详见声明式部署网关说明与配置文件-网关。

查看路由列表

查看当前环境下的所有路由配置：

tcb routes list -e <envId>

支持分页和过滤：

# 分页查询
tcb routes list -e <envId> --limit 50 --offset 0

# 按域名过滤
tcb routes list -e <envId> --filter "Domain=api.example.com"

# 按上游服务类型过滤
tcb routes list -e <envId> --filter "UpstreamResourceType=CBR"

# 多条件组合（且关系，&连接；多值用逗号分隔，或关系）
tcb routes list -e <envId> --filter "UpstreamResourceType=SCF&Domain=api.example.com,api2.example.com"

--filter 可过滤字段：

字段	说明	可选值
`Domain`	域名	任意域名字符串，多值逗号分隔（或关系）
`Path`	路由路径	任意路径字符串
`UpstreamResourceType`	上游服务类型	`SCF`、`CBR`、`STATIC_STORE`、`WEB_SCF`、`LH`

创建路由

为指定域名创建一个或多个路由规则，通过 --data 参数传入 JSON 配置：

tcb routes add -e <envId> --data '<JSON>'

JSON 数据格式：

{
  "domain": "必填，域名",
  "routes": [
    {
      "path": "必填，路径（必须以 / 开头，不支持通配符）",
      "upstreamResourceType": "必填，上游类型",
      "upstreamResourceName": "必填，上游服务名",
      "enable": true,
      "enableAuth": false,
      "enableSafeDomain": true,
      "enablePathTransmission": false,
      "pathRewrite": { "prefix": "/newpath" },
      "qpsPolicy": {
        "qpsTotal": 500,
        "qpsPerClient": {
          "limitBy": "ClientIP",
          "limitValue": 20
        }
      }
    }
  ]
}

路由配置字段说明：

字段	类型	必填	说明
`domain`	string	是	目标域名，必须已通过 `tcb domains add` 绑定
`routes[].path`	string	是	路由路径，必须以 `/` 开头，*不支持通配符 `/`**。每段仅允许字母/数字/`.`/`_`/`-`，每段 ≤ 50 字符；不可使用系统保留前缀 `/__auth`、`/.well-known`
`routes[].upstreamResourceType`	string	是	上游服务类型：`SCF`（云函数）、`CBR`（云托管）、`STATIC_STORE`（静态托管）、`WEB_SCF`（Web 云函数）、`LH`（轻量应用服务器）
`routes[].upstreamResourceName`	string	是	上游服务名称
`routes[].enable`	boolean	否	是否启用路由，默认 `true`
`routes[].enableSafeDomain`	boolean	否	是否开启安全域名校验，默认 `true`

enableAuth / enablePathTransmission / pathRewrite / qpsPolicy 四个字段的权威定义见配置文件-网关。命令式 tcb routes 与声明式 cloudbaserc.json 的语义差异：

pathRewrite：命令式仅支持 prefix；声明式额外支持 staticStorePrefix（hosting 路由未配置时自动生成）
qpsPolicy：qpsTotal 命令式最大 500、声明式 100–100000；qpsPerClient.limitValue 声明式 0–30
enableAuth / enablePathTransmission：两种方式语义一致

使用示例：

# 将 /api 转发到云托管服务
tcb routes add -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/api","upstreamResourceType":"CBR","upstreamResourceName":"my-service"}]}'

# 将 /func 转发到云函数，并开启身份认证
tcb routes add -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/func","upstreamResourceType":"SCF","upstreamResourceName":"my-function","enableAuth":true}]}'

# 静态网站根路径
tcb routes add -e <envId> --data '{"domain":"www.example.com","routes":[{"path":"/","upstreamResourceType":"STATIC_STORE","upstreamResourceName":"website"}]}'

# 带 QPS 限流的路由
tcb routes add -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/v1","upstreamResourceType":"CBR","upstreamResourceName":"backend","qpsPolicy":{"qpsTotal":1000,"qpsPerClient":{"limitBy":"ClientIP","limitValue":50}}}]}'

# 一次创建多条路由
tcb routes add -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/v1","upstreamResourceType":"SCF","upstreamResourceName":"func-v1"},{"path":"/v2","upstreamResourceType":"CBR","upstreamResourceName":"service-v2"}]}'

路径不支持通配符

path 不支持通配符（如 /api/*、/* 会被拒绝）。如需匹配一级路径下所有子路径，可配置多条精确路径路由（如 /api、/api/v1、/api/v2）。静态托管（STATIC_STORE）只支持一级路径（如 / 或 /static），多级路径会被拒绝。

注意

同一域名下不能有重复路径：重复路径会被拒绝（报 INVALID_PARAM）；如需调整已有路由，用 tcb routes edit 更新
域名必须已通过 tcb domains add 绑定后才能创建路由（命令式 tcb routes；声明式 tcb deploy 会自动绑定，见顶部说明）

修改路由

增量更新已有路由配置。通过「域名 + 路径」定位路由，只更新传入的字段：

tcb routes edit -e <envId> --data '<JSON>'

JSON 数据格式（与创建相同，路径为必填定位键，其余字段按需传入）：

# 更换路由的上游服务
tcb routes edit -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/api","upstreamResourceName":"new-service"}]}'

# 禁用路由
tcb routes edit -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/api","enable":false}]}'

# 开启身份认证和路径透传
tcb routes edit -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/api","enableAuth":true,"enablePathTransmission":true}]}'

# 更新 QPS 限流配置
tcb routes edit -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/v1","qpsPolicy":{"qpsTotal":200,"qpsPerClient":{"limitBy":"ClientIP","limitValue":20}}}]}'

提示

修改是增量更新，只有传入的字段会被更新，未传入的字段保持不变。

删除路由

删除指定域名下的路由规则：

# 删除单条路由
tcb routes delete api.example.com -e <envId> -p /api

# 同时删除多条路由（逗号分隔）
tcb routes delete api.example.com -e <envId> -p "/api/v1,/api/v2"

命令参数：

参数	说明	必填
`<domain>`	目标域名	是
`-p, --path <paths>`	要删除的路由路径，多个路径用逗号分隔	是

典型使用流程

# 1. 先绑定自定义域名（详见 domains 文档）
tcb domains add api.example.com --certid <certId> -e <envId>

# 2. 创建路由规则
tcb routes add -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/api","upstreamResourceType":"CBR","upstreamResourceName":"my-service"}]}'

# 3. 查看路由配置
tcb routes list -e <envId> --filter "Domain=api.example.com"

# 4. 更新路由（如需调整）
tcb routes edit -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/api","enableAuth":true}]}'

# 5. 删除路由（如需清理）
tcb routes delete api.example.com -e <envId> -p /api

命令速查

命令	说明
`tcb routes list`	查看路由列表，支持过滤和分页
`tcb routes add --data <json>`	创建路由规则
`tcb routes edit --data <json>`	增量更新路由配置
`tcb routes delete <domain> -p <paths>`	删除路由

查看路由列表​

创建路由​

修改路由​

删除路由​

典型使用流程​

命令速查​