gateway

The gateway field of cloudbaserc.json drives declarative gateway deployment with tcb deploy, defining how HTTP requests are forwarded to functions and static hosting by "domain + path".

Property	Value
Type	Object
Description	Gateway route configuration for declarative deployment with tcb deploy

Fields

Field	Type	Required	Description
routes	Array<Object>	Yes	List of gateway routes

routes[]

Field	Type	Required	Default	Description
path	String	Yes	—	URL path, for example /api. Must start with /, no wildcards, each segment allows letters, digits, ., _, - and is at most 50 characters; reserved prefixes /__auth and /.well-known are rejected
target	String	Yes	—	function:<name> or hosting:<name>. Functions are typed automatically: HTTP → WEB_SCF route, Event → SCF route; hosting supports one path level only (/ or /web), nested paths fail
domain	String	No	Environment default domain	Custom domain. When unbound, tcb deploy binds it idempotently, no need to run tcb domains add first
certId	String	No	—	SSL certificate ID. An explicit value wins; otherwise an issued certificate is matched by domain (Status=1, not expired), and the deployment fails when none matches
accessType	String	No	DIRECT	DIRECT / CDN (being retired) / CUSTOM (needs customCname) / EO
customCname	String	No	—	CNAME record required when accessType=CUSTOM
protocol	String	No	HTTP_AND_HTTPS	HTTP / HTTPS / HTTP_AND_HTTPS / HTTP_TO_HTTPS / HTTPS_TO_HTTP
enable	Boolean	No	true	Domain enablement, applied to the domain binding and taken from the first route of the domain group; routes themselves stay enabled
pathRewrite	Object	No	—	{ "prefix": "/newpath" } or { "staticStorePrefix": "/xxx" }, only one of the two. Hosting routes without a value get prefix generated from the hosting deploy path
enablePathTransmission	Boolean	No	false	true passes the full path upstream, false passes only the matched part. Enabling it on a hosting route without an explicit pathRewrite conflicts with the generated rewrite and fails
enableAuth	Boolean	No	false	Whether to require authentication
qpsPolicy	Object	No	—	{ "qpsTotal": 100-100000, "qpsPerClient": { "limitBy": "ClientIP" | "UserID", "limitValue": 0-30 } }; both limitBy and limitValue are required

Example

{
  "gateway": {
    "routes": [
      { "path": "/api", "target": "function:api-server" },
      { "path": "/web", "target": "hosting:web", "accessType": "CDN" }
    ]
  }
}

Field notes

accessType

Value	Description
DIRECT	Direct access, DNS resolves to the gateway IP, lowest latency
CDN	CloudBase CDN acceleration, being retired, migrate to EO
CUSTOM	Custom CNAME access, requires customCname
EO	EdgeOne edge acceleration

protocol

Value	Description
HTTP	HTTP only
HTTPS	HTTPS only, requires certId
HTTP_AND_HTTPS	Both, the default
HTTP_TO_HTTPS	HTTP redirects to HTTPS with a 301, recommended in production
HTTPS_TO_HTTP	HTTPS redirects to HTTP with a 301

Other fields:

• customCname: the CNAME record required when accessType=CUSTOM; add the record at the DNS provider first
• certId: a domain-level field applied only when the domain is first created; an existing domain keeps its value. Required when protocol=HTTPS
• enable: a domain-level switch shared by every route of the domain, taken from the first route
• enablePathTransmission: enabling it on a hosting route without an explicit pathRewrite conflicts with the generated rewrite
• enableAuth: requests must then carry credentials; the token obtained after SDK login is passed in the Authorization header
• qpsPolicy: qpsTotal caps total QPS, qpsPerClient caps a single client by ClientIP or UserID

Related Commands

• List routes: tcb routes
• List domains: tcb domains
• List security domains: tcb cors
• Declarative deployment: how gateway.routes behaves during tcb deploy