Configuration File - Gateway

The gateway field in cloudbaserc.json is used for declarative gateway deployment via tcb deploy. It defines how HTTP requests are forwarded to upstream services (cloud functions, static hosting, etc.) by "domain + path".

Property	Value
Type	Object
Description	CloudBase gateway routing configuration for declarative deployment via tcb deploy

Sub-fields

Field	Type	Required	Description
routes	Array<Object>	Yes	Gateway route list

routes[] Fields

Field	Type	Required	Default	Description
path	String	Yes	—	URL path, e.g. /api. Must start with /; wildcard * is not supported; each segment only allows letters/digits/./_/-, each segment ≤ 50 characters; system-reserved prefixes /__auth and /.well-known cannot be used
target	String	Yes	—	Target resource: function:<name> (cloud function) or hosting:<name> (static hosting). Cloud functions auto-distinguish type: HTTP type → WEB_SCF route, Event type → SCF route (both supported); hosting only supports one-level paths (e.g. / or /web), multi-level paths error out
domain	String	No	Environment default domain	Bound custom domain. When not bound, tcb deploy auto-binds (idempotent), no need to run tcb domains add first
certId	String	No	—	SSL certificate ID. Explicit config takes priority; when not configured and the domain is unbound, auto-matches an issued certificate by domain (only Status=1, unexpired); if no match, deployment fails
accessType	String	No	DIRECT	Domain access type: DIRECT / CDN (CloudBase CDN, being deprecated) / CUSTOM (requires customCname) / EO (EdgeOne)
customCname	String	No	—	Required CNAME record when accessType=CUSTOM
protocol	String	No	HTTP_AND_HTTPS	Domain protocol: HTTP / HTTPS / HTTP_AND_HTTPS / HTTP_TO_HTTPS (redirect HTTP to HTTPS) / HTTPS_TO_HTTP
enable	Boolean	No	true	Domain enable status (applies to domain binding, uses the first route's config in the domain group; the route itself is always enabled)
pathRewrite	Object	No	—	Path rewrite: { "prefix": "/newpath" } or { "staticStorePrefix": "/xxx" }. Only one of prefix and staticStorePrefix can be set; hosting routes auto-generate prefix=the hosting deploy path when not configured
enablePathTransmission	Boolean	No	false	Path transmission: true=pass full path to upstream, false=only pass matched path. ⚠️ Enabling on hosting routes without explicit pathRewrite will conflict with the auto-generated rewrite and fail
enableAuth	Boolean	No	false	Whether to enable authentication
qpsPolicy	Object	No	—	QPS rate limiting: { "qpsTotal": 100-100000, "qpsPerClient": { "limitBy": "ClientIP" | "UserID", "limitValue": 0-30 } }. Both limitBy and limitValue in qpsPerClient are required

Example

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

Detailed Notes

• accessType access modes:
  • DIRECT: Direct access, DNS resolves to gateway IP, lowest latency
  • CDN: CloudBase CDN acceleration (being deprecated, migrate to EO)
  • CUSTOM: Custom CNAME access, requires customCname
  • EO: EdgeOne edge acceleration
• customCname: CNAME record value required when accessType=CUSTOM; add the CNAME record in your DNS provider first
• protocol types:
  • HTTP: HTTP only
  • HTTPS: HTTPS only (requires certId)
  • HTTP_AND_HTTPS: Both HTTP and HTTPS (default)
  • HTTP_TO_HTTPS: HTTP auto 301-redirects to HTTPS (recommended for production)
  • HTTPS_TO_HTTP: HTTPS auto 301-redirects to HTTP
• certId: SSL certificate ID. Domain-level field — only takes effect when the domain is first created; does not override existing values on already-bound domains. Required when protocol=HTTPS
• enable: Domain-level switch (not route-level); shared by all routes under the same domain, using the first route's configuration
• enablePathTransmission: Path transmission. ⚠️ Enabling on hosting routes without explicit pathRewrite will conflict with the auto-generated rewrite and fail
• enableAuth: When enabled, requests must carry auth credentials (SDK login token via Authorization header)
• qpsPolicy rate limiting:
  • qpsTotal: Global QPS cap (100-100000)
  • qpsPerClient: Per-client QPS cap (0-30), by ClientIP (IP) or UserID (user)

Related Commands

• HTTP Service Route Management: tcb routes
• Custom Domains: tcb domains
• Security Domains: tcb cors