HTTP 服务路由管理

v3.0.0+

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

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

路由与域名的关系

路由必须绑定在已有的自定义域名下。如果还没有绑定自定义域名，请先使用 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	是	路由路径，支持通配符 /*，如 /api/*
routes[].upstreamResourceType	string	是	上游服务类型：SCF（云函数）、CBR（云托管）、STATIC_STORE（静态托管）、WEB_SCF（Web 云函数）、LH（轻量应用服务器）
routes[].upstreamResourceName	string	是	上游服务名称
routes[].enable	boolean	否	是否启用路由，默认 true
routes[].enableAuth	boolean	否	是否开启身份认证，默认 false
routes[].enableSafeDomain	boolean	否	是否开启安全域名校验，默认 true
routes[].enablePathTransmission	boolean	否	是否开启路径透传，默认 false
routes[].pathRewrite	object	否	路径重写配置，{ "prefix": "/newpath" }
routes[].qpsPolicy.qpsTotal	number	否	资源总 QPS 限制，最大 500
routes[].qpsPolicy.qpsPerClient	object	否	单客户端限频：{ "limitBy": "ClientIP" \| "UserID", "limitValue": N }

使用示例：

# 将 /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"}]}'

注意

• 同一域名下不能有重复路径
• 域名必须已通过 tcb domains add 绑定后才能创建路由

修改路由

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

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>	删除路由