cdnca

开放接口

/v1/streams

7 个接口 · 7 个接口支持 API Key

← 全部分组 · 第一次调用？先看教程：认证、权限、请求与响应、常见失败

方法路径摘要认证
GET/v1/streamsList layer-four forwarding rulesAPI Key 可调登录会话
POST/v1/streamsCreate a forwarding rule and immutable publication intentAPI Key 可调登录会话
POST/v1/streams/batch批量添加 forwarding rules, one per lineAPI Key 可调登录会话
POST/v1/streams/batch-action更多操作 on selected forwarding rules (platform)API Key 可调登录会话
GET/v1/streams/{id}Get one layer-four forwarding ruleAPI Key 可调登录会话
PATCH/v1/streams/{id}Replace a rule and create an immutable publication intentAPI Key 可调登录会话
DELETE/v1/streams/{id}Soft-delete a rule and create a deletion publication intentAPI Key 可调登录会话

契约文件：api/control-l4-forward.openapi.yaml

接口详情

GET /v1/streams

List layer-four forwarding rules

operationId
listStreams
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.read

说明（契约原文）

Tenant principals see only rules owned by their current user and tenant. Platform principals can list tenant rules after streams.read authorization. All supplied filters are combined with AND and apply to both items and total. Unknown or repeated query parameters are rejected. protocol, enabled, listen_port, upstream, display_id, owner_display_id, publication_state, group_id, package_product_id, cname_domain, cname_hostname, region_id, node_group_id, sync_state and admin_status reject empty values.

参数

listStreams 参数
名称位置类型必填说明
X-Request-IDheaderstring否Caller-stable request identity; invalid or absent values are replaced by middleware.
pagequeryinteger否—
limitqueryinteger否—
searchquerystring否—
protocolquerystring: tcp / udp否Exact lowercase tcp or udp matching any primary or additional listener. When listen_port is supplied, both must match the same listener. Whitespace and other spellings are rejected.
enabledqueryboolean否Exact lowercase true or false; whitespace, numbers and other spellings are rejected.
listen_portqueryinteger否Exact listening port, written as a canonical positive decimal integer.
upstreamquerystring否Case-insensitive literal substring of the upstream IP address or hostname. Surrounding whitespace is trimmed; SQL wildcard characters remain literal. Control characters and invalid UTF-8 are rejected.
display_idquerystring否Exact display ID as a canonical positive decimal string, at most 9223372036854775807. Display IDs are tenant-scoped.
owner_display_idquerystring否Exact stable user display number, written as a canonical positive decimal string at most 9223372036854775807. This is not a user UUID. Tenant principals remain restricted to their own scope and user; a different owner number returns an empty page.
forwardquerystring否Case-insensitive substring of the forward name or remark (the name form of display_id).
ownerquerystring否Platform only. Case-insensitive substring of the owner's username or display name (the name form of owner_display_id); tenant principals get 403.
publication_statequerystring: unknown / pending / leased / retrying / reconciling / succeeded / failed / superseded否Exact publish_intent.state of the latest intent and its latest automatic publication observation. retry_wait is exposed as retrying; missing or unrecognized observations are unknown. This is not a business eligibility status or an independently inferred edge synchronization result.
group_idquerystring(uuid)否Exact active stream group membership in the stream scope. This is a stream group, not a node line group.
package_product_idquerystring(uuid)否Exact package product referenced by the stream subscription in the same tenant scope, not a subscription ID.
cname_domainquerystring否Case-insensitive literal substring of the effective CNAME domain (the stream's own, else its package's).
cname_hostnamequerystring否Case-insensitive literal substring of the package CNAME hostname (按套餐 streams).
region_idquerystring(uuid)否区域. Exact line.region_id (the stream's own region, else its package's). Platform principals only; tenant principals get 403.
node_group_idquerystring(uuid)否线路分组. Exact line.node_group_id (the stream's own line group, else its package's primary group). Platform principals only; tenant principals get 403.
sync_statequerystring: done / pending / failed否同步状态. Exact sync_state, derived from the latest intent's automatic publication and its node deployment receipts.
admin_statusquerystring: normal / locked / traffic_exceeded / package_expired否状态. Exact admin_status.

响应

listStreams 响应
状态码说明
200Stable page ordered newest first.

字段：items: array<Stream> total: integer(int64) page: integer limit: integer

400Stable invalid request or validation error.
401Authentication is missing or invalid.
403The authenticated principal lacks the required permission or owner scope.
500Internal operation failure without publication or activation claims.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/streams

Create a forwarding rule and immutable publication intent

operationId
createStream
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.manage

说明（契约原文）

Tenant principals are fixed to their current scope and user. Platform principals must provide target_scope_id and owner_id. The committed publication intent does not claim delivery or edge activation.

参数

createStream 参数
名称位置类型必填说明
X-Request-IDheaderstring否Caller-stable request identity; invalid or absent values are replaced by middleware.
Idempotency-Keyheaderstring是Reuse is accepted only for the exact same actor, operation, and normalized input.

请求体

application/json · 必填：是

createStream 请求体
名称类型必填说明
package_subscription_idstring(uuid)否The stream's package subscription (所属套餐). A stream belongs to no website; its line, CNAME, usage and stream_ports quota are the package's unless it sets its own line / CNAME.
namestring否—
remarkstring否—
protocolstring: tcp / udp否—
listen_addressstring否The current runtime binds wildcard IPv4 and IPv6 listeners.
listen_portinteger否—
listen_port_endinteger否端口范围. When non-zero the primary listener is listen_port..listen_port_end (greater than listen_port, at most 1000 ports), each port a socket of its own that counts against the package's stream_ports. A range may not cover the node ports 80/443/18080/18443, overlap a website port or another stream's socket of the same protocol, nor be TLS passthrough; such saves are refused with stream_port_conflict whose details say where. v2 streams only. Requires TCP/UDP capability API version 9 on every target node; otherwise publication is refused with node_capability_unavailable naming the nodes.
upstream_follow_portboolean否跟随端口回源. Connect to the origin on the port the client connected to (for a range, the matching port). upstream_port is then stored as listen_port and may be omitted. v2 streams only. Requires TCP/UDP capability API version 9.
additional_listenersarray<StreamAdditionalListener>否Extra listeners sharing this stream's endpoint, DNS and Geo policies. IDs are required client-generated UUIDs, globally distinct from every stream and other listener ID; IDs are returned in canonical order. Omitted on create means none; omitted on update preserves existing extras; an explicit empty array removes them. Any UDP listener requires both PROXY flags false. Active protocol and port pairs are reserved globally, including disabled streams, until removal or stream deletion.
upstream_addressany | any | any否—
upstream_hoststring否Canonical lowercase IDNA host in stored responses.
upstream_portinteger否—
dns_policyStreamDNSPolicyZero | StreamDNSPolicy否—
geo_policyStreamGeoPolicy否—
connect_timeout_msinteger否—
response_timeout_msinteger否—
max_connections_per_clientinteger否—
proxy_protocol_inboundboolean否Must be true exactly when enabled geo source resolution uses trusted_proxy_cidrs.
proxy_protocol_v1boolean否Outbound Proxy Protocol v1; TCP only.
tls_passthroughboolean否Forward TLS unterminated and pick this stream by SNI, so several streams, websites and at most one plain TCP stream can share the TCP port. TCP only, including every additional listener. Non-TLS connections go to the plain TCP stream on the port; TLS connections whose SNI matches nothing are closed.
server_namesarray<string>否SNI of a TLS passthrough stream, 1-32 names, empty otherwise. Exact names win over wildcards. Each (port, name) is reserved globally while the stream is live; "*.a.com" and "x.a.com" are distinct names. Stored responses are lower-case and sorted.
max_new_connections_per_client_per_secondinteger否单 IP 新建连接速率. New connections (UDP sessions) one client IP may open to this stream per second, shared by all its listeners; 0 is unlimited. The client is the PROXY protocol address when the peer is a trusted proxy. Requires TCP/UDP capability API version 6 on every target node; otherwise publication is refused with node_capability_unavailable naming the nodes.
new_connection_burstinteger否Connections allowed at once beyond the per-second rate (bucket capacity is rate + burst). Must be 0 when the rate is 0.
new_connection_ban_secondsinteger否0 refuses only connections over the rate; otherwise a client over the rate is refused new connections to this stream for this many seconds (node-local). Must be 0 when the rate is 0.
toaboolean否回源携带客户端 IP via TOA. The node writes the IPv4 client address and port into TCP option 254 (length 8) on the handshake ACK towards the origin; the origin needs a TOA module. IPv6 clients are forwarded without the option. TCP only (all listeners); excludes proxy_protocol_v1 and proxy_protocol_inbound. Requires capability L4_TOA v1 on every target node (Linux 5.10+ with the node's eBPF probe passing); otherwise publication is refused with node_capability_unavailable naming the nodes.
session_log_enabledboolean否会话日志. Write a per-session access log (client IP — the PROXY protocol address when the peer is a trusted proxy — upstream, bytes, duration and end reason, refused sessions included) and register live TCP sessions for the real-time connection list. v2 streams only. Requires TCP/UDP capability API version 7 on every target node; otherwise publication is refused with node_capability_unavailable naming the nodes.
guard_rulesarray<StreamGuardRule>否防护规则. Evaluated in order on each new connection (UDP session) at the node; the first rule whose conditions all hold decides. Omitted or empty is none; responses always carry the array. v2 streams only. Requires TCP/UDP capability API version 10 on every target node; a rule with a geo condition also requires IP_INTEL v2 and a verified IP intelligence library on every target node. Otherwise publication is refused with node_capability_unavailable naming the nodes.
originsarray<StreamOrigin>否源站列表. Several origins on upstream_port, each with a weight (1..100, share of new connections) and down (下线, gets none); at least one up. Several origins are IP addresses; a single origin may be a domain name (then dns_policy applies). When sent, upstream_address/upstream_host are taken from the first origin; omitted keeps the single upstream_address/upstream_host. Responses always carry the list (one entry, weight 1, for a single origin). Not with upstream_follow_port when several. Several origins, or balance_way ip_hash, require TCP/UDP capability API version 11 on every target node.
listen_ipv6boolean否IPv6开启. The node also listens on [::] for the stream's own sockets. Requires TCP/UDP capability API version 11.
aclStreamACL否访问控制 IP rules. Rules are evaluated in order, the first matching rule decides; otherwise default_action (默认允许 allow / 默认拒绝 deny). The node enforces them as the stream's leading guard rules (client_ip allow / drop), ahead of guard_rules, so they need TCP/UDP capability API version 10 and count against the platform ACL rule limit together with guard_rules. Omitted on a write keeps default allow without rules.
enabledboolean否—
balance_waystring: rr / ip_hash否Origin connection balancing strategy; this is independent of the selected node line group.
groupsarray<StreamGroupReference>否—
target_scope_idstring(uuid)否Required for platform principals; tenant principals may omit it or use their current scope.
owner_idstring(uuid)否Required for platform principals; tenant principals may omit it or use their current user.
group_idsarray<string(uuid)>否Groups in the same scope; omitted or empty means ungrouped.

响应

createStream 响应
状态码说明
201Rule and publication intent committed atomically, or an exact idempotent replay returned.

字段：package_subscription_id?: string(uuid) name?: string remark?: string protocol?: string: tcp / udp listen_address?: string listen_port?: integer listen_port_end?: integer upstream_follow_port?: boolean additional_listeners?: array<StreamAdditionalListener> upstream_address?: any | any | any upstream_host?: string upstream_port?: integer dns_policy?: StreamDNSPolicyZero | StreamDNSPolicy geo_policy: StreamGeoPolicy connect_timeout_ms?: integer response_timeout_ms?: integer max_connections_per_client?: integer proxy_protocol_inbound?: boolean proxy_protocol_v1?: boolean tls_passthrough?: boolean server_names?: array<string> max_new_connections_per_client_per_second?: integer new_connection_burst?: integer new_connection_ban_seconds?: integer toa?: boolean session_log_enabled?: boolean guard_rules?: array<StreamGuardRule> origins?: array<StreamOrigin> listen_ipv6?: boolean acl?: StreamACL enabled?: boolean balance_way?: string: rr / ip_hash groups?: array<StreamGroupReference> id: string(uuid) display_id: string scope_id: string(uuid) package_name?: string | null package_expires_at?: string(date-time) | null(date-time) cname?: string | null cname_domain?: string | null cname_hostname?: string | null cname_state?: string: pending / failed / done / null | null: pending / failed / done / null cname_failure_code?: string | null eligibility_state: string: eligible / ineligible admin_status: string: normal / locked / traffic_exceeded / package_expired overrides: StreamOverrides line: StreamLine sync_state: string: done / pending / failed owner: StreamOwner | null revision: integer(int64) publish_intent: StreamPublishIntent created_at: string(date-time) updated_at: string(date-time)

400Stable invalid request or validation error.
401Authentication is missing or invalid.
403The authenticated principal lacks the required permission or owner scope.
409Revision, idempotency, name, or listener-port conflict.
415Exactly one Content-Type field parsing as application/json is required.
500Internal operation failure without publication or activation claims.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/streams/batch

批量添加 forwarding rules, one per line

operationId
batchCreateStreams
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.manage

说明（契约原文）

Each line is "监听端口|IP|回源端口", e.g. "88 99/udp|1.2.3.4|8080": the first port (default tcp, "/udp" or "/tcp" suffix) is the primary listener, the others additional listeners; the origin is an IP address or a domain name. template holds the fields every line shares (package, remark, timeouts, DNS policy for domain origins, …); its listen and origin fields are ignored. Lines are validated and written in order. With ignore_errors (忽略错误) a failed line is skipped and the others are committed (200). Without it the batch is atomic: one failed line and nothing is written (422, the failed line says why, the rest are skipped). The idempotency key covers the whole batch.

参数

batchCreateStreams 参数
名称位置类型必填说明
X-Request-IDheaderstring否Caller-stable request identity; invalid or absent values are replaced by middleware.
Idempotency-Keyheaderstring是Reuse is accepted only for the exact same actor, operation, and normalized input.

请求体

application/json · 必填：是

batchCreateStreams 请求体
名称类型必填说明
target_scope_idstring(uuid)否Required for platform principals.
owner_idstring(uuid)否Required for platform principals.
group_idsarray<string(uuid)>否—
templateStreamFields是—
linesarray<string>是—
ignore_errorsboolean否—

响应

batchCreateStreams 响应
状态码说明
200Committed; failed lines (only with ignore_errors) are listed with their error.

字段：items: array<object> created: integer failed: integer committed: boolean

400Stable invalid request or validation error.
401Authentication is missing or invalid.
403The authenticated principal lacks the required permission or owner scope.
409Revision, idempotency, name, or listener-port conflict.
415Exactly one Content-Type field parsing as application/json is required.
422Without ignore_errors a line failed; nothing was written (committed false).
500Internal operation failure without publication or activation claims.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/streams/batch-action

更多操作 on selected forwarding rules (platform)

operationId
batchStreamAction
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.manage

说明（契约原文）

Platform principals only. set_status (设置状态) sets admin_status; a status other than normal takes the stream off the nodes until it is normal again. cname_domain (修改CNAME域名), cname_mode (修改CNAME生成模式) and line_group (修改线路分组: region_id, node_group_id, backup_node_group_id) set the stream's own overrides; "" / an omitted id clears one, so the stream follows its package. A stream's line group (its own, else its package's) adds its nodes to the scope's publication targets. Each item carries its own expected_revision and is applied alone: a missing or stale item fails with its code (stream_not_found, version_conflict, and for cname_regenerate stream_cname_not_overridden / stream_cname_not_failed) and the others are applied.

参数

batchStreamAction 参数
名称位置类型必填说明
X-Request-IDheaderstring否Caller-stable request identity; invalid or absent values are replaced by middleware.
Idempotency-Keyheaderstring是Reuse is accepted only for the exact same actor, operation, and normalized input.

请求体

application/json · 必填：是

batchStreamAction 请求体
名称类型必填说明
actionstring: set_status / cname_domain / cname_mode / line_group / cname_regenerate是—
admin_statusstring: normal / locked / traffic_exceeded / package_expired否状态 (设置状态). Only normal streams are served.
cname_domainstring否A CNAME domain of 节点管理 > DNS配置, or "" to follow the package.
cname_modestring: / site / package否按转发生成 (site) / 按套餐生成 (package), or "" to follow the package.
region_idstring(uuid)否A platform region; omitted to follow the package.
node_group_idstring(uuid)否A live platform general line group; omitted to follow the package.
backup_node_group_idstring(uuid)否A live platform general line group other than node_group_id.
itemsarray<object>是—

响应

batchStreamAction 响应
状态码说明
200Per-item results in request order.

字段：items: array<object>

400Stable invalid request or validation error.
401Authentication is missing or invalid.
403The authenticated principal lacks the required permission or owner scope.
409Revision, idempotency, name, or listener-port conflict.
415Exactly one Content-Type field parsing as application/json is required.
500Internal operation failure without publication or activation claims.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/streams/{id}

Get one layer-four forwarding rule

operationId
getStream
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.read

说明（契约原文）

Returns the current rule and its latest exact publication intent projection.

参数

getStream 参数
名称位置类型必填说明
idpathstring(uuid)是Exact immutable stream identity.
X-Request-IDheaderstring否Caller-stable request identity; invalid or absent values are replaced by middleware.

响应

getStream 响应
状态码说明
200Current rule and latest exact publication intent.

字段：package_subscription_id?: string(uuid) name?: string remark?: string protocol?: string: tcp / udp listen_address?: string listen_port?: integer listen_port_end?: integer upstream_follow_port?: boolean additional_listeners?: array<StreamAdditionalListener> upstream_address?: any | any | any upstream_host?: string upstream_port?: integer dns_policy?: StreamDNSPolicyZero | StreamDNSPolicy geo_policy: StreamGeoPolicy connect_timeout_ms?: integer response_timeout_ms?: integer max_connections_per_client?: integer proxy_protocol_inbound?: boolean proxy_protocol_v1?: boolean tls_passthrough?: boolean server_names?: array<string> max_new_connections_per_client_per_second?: integer new_connection_burst?: integer new_connection_ban_seconds?: integer toa?: boolean session_log_enabled?: boolean guard_rules?: array<StreamGuardRule> origins?: array<StreamOrigin> listen_ipv6?: boolean acl?: StreamACL enabled?: boolean balance_way?: string: rr / ip_hash groups?: array<StreamGroupReference> id: string(uuid) display_id: string scope_id: string(uuid) package_name?: string | null package_expires_at?: string(date-time) | null(date-time) cname?: string | null cname_domain?: string | null cname_hostname?: string | null cname_state?: string: pending / failed / done / null | null: pending / failed / done / null cname_failure_code?: string | null eligibility_state: string: eligible / ineligible admin_status: string: normal / locked / traffic_exceeded / package_expired overrides: StreamOverrides line: StreamLine sync_state: string: done / pending / failed owner: StreamOwner | null revision: integer(int64) publish_intent: StreamPublishIntent created_at: string(date-time) updated_at: string(date-time)

400Stable invalid request or validation error.
401Authentication is missing or invalid.
403The authenticated principal lacks the required permission or owner scope.
404No visible stream matches the exact immutable stream identity.
500Internal operation failure without publication or activation claims.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

PATCH /v1/streams/{id}

Replace a rule and create an immutable publication intent

operationId
updateStream
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.manage

说明（契约原文）

If-Match and expected_revision must contain the same quoted positive revision. Ownership is retained; no owner or scope field is accepted.

参数

updateStream 参数
名称位置类型必填说明
idpathstring(uuid)是Exact immutable stream identity.
X-Request-IDheaderstring否Caller-stable request identity; invalid or absent values are replaced by middleware.
Idempotency-Keyheaderstring是Reuse is accepted only for the exact same actor, operation, and normalized input.
If-Matchheaderstring是Quoted positive current resource revision.

请求体

application/json · 必填：是

updateStream 请求体
名称类型必填说明
package_subscription_idstring(uuid)否The stream's package subscription (所属套餐). A stream belongs to no website; its line, CNAME, usage and stream_ports quota are the package's unless it sets its own line / CNAME.
namestring否—
remarkstring否—
protocolstring: tcp / udp否—
listen_addressstring否The current runtime binds wildcard IPv4 and IPv6 listeners.
listen_portinteger否—
listen_port_endinteger否端口范围. When non-zero the primary listener is listen_port..listen_port_end (greater than listen_port, at most 1000 ports), each port a socket of its own that counts against the package's stream_ports. A range may not cover the node ports 80/443/18080/18443, overlap a website port or another stream's socket of the same protocol, nor be TLS passthrough; such saves are refused with stream_port_conflict whose details say where. v2 streams only. Requires TCP/UDP capability API version 9 on every target node; otherwise publication is refused with node_capability_unavailable naming the nodes.
upstream_follow_portboolean否跟随端口回源. Connect to the origin on the port the client connected to (for a range, the matching port). upstream_port is then stored as listen_port and may be omitted. v2 streams only. Requires TCP/UDP capability API version 9.
additional_listenersarray<StreamAdditionalListener>否Extra listeners sharing this stream's endpoint, DNS and Geo policies. IDs are required client-generated UUIDs, globally distinct from every stream and other listener ID; IDs are returned in canonical order. Omitted on create means none; omitted on update preserves existing extras; an explicit empty array removes them. Any UDP listener requires both PROXY flags false. Active protocol and port pairs are reserved globally, including disabled streams, until removal or stream deletion.
upstream_addressany | any | any否—
upstream_hoststring否Canonical lowercase IDNA host in stored responses.
upstream_portinteger否—
dns_policyStreamDNSPolicyZero | StreamDNSPolicy否—
geo_policyStreamGeoPolicy否—
connect_timeout_msinteger否—
response_timeout_msinteger否—
max_connections_per_clientinteger否—
proxy_protocol_inboundboolean否Must be true exactly when enabled geo source resolution uses trusted_proxy_cidrs.
proxy_protocol_v1boolean否Outbound Proxy Protocol v1; TCP only.
tls_passthroughboolean否Forward TLS unterminated and pick this stream by SNI, so several streams, websites and at most one plain TCP stream can share the TCP port. TCP only, including every additional listener. Non-TLS connections go to the plain TCP stream on the port; TLS connections whose SNI matches nothing are closed.
server_namesarray<string>否SNI of a TLS passthrough stream, 1-32 names, empty otherwise. Exact names win over wildcards. Each (port, name) is reserved globally while the stream is live; "*.a.com" and "x.a.com" are distinct names. Stored responses are lower-case and sorted.
max_new_connections_per_client_per_secondinteger否单 IP 新建连接速率. New connections (UDP sessions) one client IP may open to this stream per second, shared by all its listeners; 0 is unlimited. The client is the PROXY protocol address when the peer is a trusted proxy. Requires TCP/UDP capability API version 6 on every target node; otherwise publication is refused with node_capability_unavailable naming the nodes.
new_connection_burstinteger否Connections allowed at once beyond the per-second rate (bucket capacity is rate + burst). Must be 0 when the rate is 0.
new_connection_ban_secondsinteger否0 refuses only connections over the rate; otherwise a client over the rate is refused new connections to this stream for this many seconds (node-local). Must be 0 when the rate is 0.
toaboolean否回源携带客户端 IP via TOA. The node writes the IPv4 client address and port into TCP option 254 (length 8) on the handshake ACK towards the origin; the origin needs a TOA module. IPv6 clients are forwarded without the option. TCP only (all listeners); excludes proxy_protocol_v1 and proxy_protocol_inbound. Requires capability L4_TOA v1 on every target node (Linux 5.10+ with the node's eBPF probe passing); otherwise publication is refused with node_capability_unavailable naming the nodes.
session_log_enabledboolean否会话日志. Write a per-session access log (client IP — the PROXY protocol address when the peer is a trusted proxy — upstream, bytes, duration and end reason, refused sessions included) and register live TCP sessions for the real-time connection list. v2 streams only. Requires TCP/UDP capability API version 7 on every target node; otherwise publication is refused with node_capability_unavailable naming the nodes.
guard_rulesarray<StreamGuardRule>否防护规则. Evaluated in order on each new connection (UDP session) at the node; the first rule whose conditions all hold decides. Omitted or empty is none; responses always carry the array. v2 streams only. Requires TCP/UDP capability API version 10 on every target node; a rule with a geo condition also requires IP_INTEL v2 and a verified IP intelligence library on every target node. Otherwise publication is refused with node_capability_unavailable naming the nodes.
originsarray<StreamOrigin>否源站列表. Several origins on upstream_port, each with a weight (1..100, share of new connections) and down (下线, gets none); at least one up. Several origins are IP addresses; a single origin may be a domain name (then dns_policy applies). When sent, upstream_address/upstream_host are taken from the first origin; omitted keeps the single upstream_address/upstream_host. Responses always carry the list (one entry, weight 1, for a single origin). Not with upstream_follow_port when several. Several origins, or balance_way ip_hash, require TCP/UDP capability API version 11 on every target node.
listen_ipv6boolean否IPv6开启. The node also listens on [::] for the stream's own sockets. Requires TCP/UDP capability API version 11.
aclStreamACL否访问控制 IP rules. Rules are evaluated in order, the first matching rule decides; otherwise default_action (默认允许 allow / 默认拒绝 deny). The node enforces them as the stream's leading guard rules (client_ip allow / drop), ahead of guard_rules, so they need TCP/UDP capability API version 10 and count against the platform ACL rule limit together with guard_rules. Omitted on a write keeps default allow without rules.
enabledboolean否—
balance_waystring: rr / ip_hash否Origin connection balancing strategy; this is independent of the selected node line group.
groupsarray<StreamGroupReference>否—
expected_revisioninteger(int64)是Must exactly equal the quoted If-Match revision.
group_idsarray<string(uuid)>否Omitted keeps current membership; an empty array clears it.

响应

updateStream 响应
状态码说明
200Rule and publication intent committed atomically, or an exact idempotent replay returned.

字段：package_subscription_id?: string(uuid) name?: string remark?: string protocol?: string: tcp / udp listen_address?: string listen_port?: integer listen_port_end?: integer upstream_follow_port?: boolean additional_listeners?: array<StreamAdditionalListener> upstream_address?: any | any | any upstream_host?: string upstream_port?: integer dns_policy?: StreamDNSPolicyZero | StreamDNSPolicy geo_policy: StreamGeoPolicy connect_timeout_ms?: integer response_timeout_ms?: integer max_connections_per_client?: integer proxy_protocol_inbound?: boolean proxy_protocol_v1?: boolean tls_passthrough?: boolean server_names?: array<string> max_new_connections_per_client_per_second?: integer new_connection_burst?: integer new_connection_ban_seconds?: integer toa?: boolean session_log_enabled?: boolean guard_rules?: array<StreamGuardRule> origins?: array<StreamOrigin> listen_ipv6?: boolean acl?: StreamACL enabled?: boolean balance_way?: string: rr / ip_hash groups?: array<StreamGroupReference> id: string(uuid) display_id: string scope_id: string(uuid) package_name?: string | null package_expires_at?: string(date-time) | null(date-time) cname?: string | null cname_domain?: string | null cname_hostname?: string | null cname_state?: string: pending / failed / done / null | null: pending / failed / done / null cname_failure_code?: string | null eligibility_state: string: eligible / ineligible admin_status: string: normal / locked / traffic_exceeded / package_expired overrides: StreamOverrides line: StreamLine sync_state: string: done / pending / failed owner: StreamOwner | null revision: integer(int64) publish_intent: StreamPublishIntent created_at: string(date-time) updated_at: string(date-time)

400Stable invalid request or validation error.
401Authentication is missing or invalid.
403The authenticated principal lacks the required permission or owner scope.
404No visible stream matches the exact immutable stream identity.
409Revision, idempotency, name, or listener-port conflict.
415Exactly one Content-Type field parsing as application/json is required.
500Internal operation failure without publication or activation claims.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

DELETE /v1/streams/{id}

Soft-delete a rule and create a deletion publication intent

operationId
deleteStream
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

全部需要：streams.manage

参数

deleteStream 参数
名称位置类型必填说明
idpathstring(uuid)是Exact immutable stream identity.
X-Request-IDheaderstring否Caller-stable request identity; invalid or absent values are replaced by middleware.
Idempotency-Keyheaderstring是Reuse is accepted only for the exact same actor, operation, and normalized input.
If-Matchheaderstring是Quoted positive current resource revision.

响应

deleteStream 响应
状态码说明
204Rule deleted and immutable deletion intent committed.
400Stable invalid request or validation error.
401Authentication is missing or invalid.
403The authenticated principal lacks the required permission or owner scope.
404No visible stream matches the exact immutable stream identity.
409Revision, idempotency, name, or listener-port conflict.
500Internal operation failure without publication or activation claims.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表