接口详情
GET /v1/user-configs
List per-user stream defaults
- operationId
listUserConfigs- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：streams.read
说明（契约原文）
type must be stream. Tenant principals see only their own rows; platform principals see all rows in the selected scope.
参数
listUserConfigs 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
X-Request-ID | header | string | 否 | Caller-stable request identity; invalid or absent values are replaced by middleware. |
|---|
type | query | string | 是 | — |
|---|
page | query | integer | 否 | — |
|---|
limit | query | integer | 否 | — |
|---|
search | query | string | 否 | — |
|---|
响应
listUserConfigs 响应| 状态码 | 说明 |
|---|
200 | Stable page ordered oldest first; display_id is the row ordinal. 字段：items: array<StreamUserConfig> total: integer(int64) page: integer limit: integer |
|---|
400 | Stable invalid request or validation error. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | The authenticated principal lacks the required permission or owner scope. |
|---|
500 | Internal operation failure without publication or activation claims. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/user-configs
Create a per-user stream default
- operationId
createUserConfig- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：streams.manage
说明（契约原文）
The scope is global, or a forwarding group that must exist in the same scope. New forwards resolve these defaults when the field is omitted.
参数
createUserConfig 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
X-Request-ID | header | string | 否 | Caller-stable request identity; invalid or absent values are replaced by middleware. |
|---|
Idempotency-Key | header | string | 是 | Reuse is accepted only for the exact same actor, operation, and normalized input. |
|---|
请求体
application/json · 必填：是
createUserConfig 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
target_scope_id | string(uuid) | 否 | Required for platform principals; tenant principals may omit it or use their current scope. |
|---|
owner_id | string(uuid) | 否 | Required for platform principals; tenant principals may omit it or use their current user. |
|---|
setting_name | string: proxy_protocol / listen_protocol / balance_way | 是 | — |
|---|
setting_value | string | 是 | — |
|---|
scope_name | string: global / group | 是 | — |
|---|
group_id | string(uuid) | 否 | Required exactly when scope_name is group, and must exist in the same scope. |
|---|
响应
createUserConfig 响应| 状态码 | 说明 |
|---|
201 | Default committed, or an exact idempotent replay returned. 字段：id: string(uuid) display_id: string scope_id: string(uuid) owner: StreamOwner | null setting_name: string: proxy_protocol / listen_protocol / balance_way setting_value: string scope_name: string: global / group group: StreamGroupReference | null created_at: string(date-time) |
|---|
400 | Stable invalid request or validation error. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | The authenticated principal lacks the required permission or owner scope. |
|---|
409 | Revision, idempotency, name, or listener-port conflict. |
|---|
415 | Exactly one Content-Type field parsing as application/json is required. |
|---|
500 | Internal operation failure without publication or activation claims. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/user-configs/effective
Resolve the stream defaults a new forward draft is prefilled with
- operationId
getEffectiveUserConfigs- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：streams.read
说明（契约原文）
type must be stream. The same resolution as creating a forward: the owner's global defaults, overridden by those of the given groups. Tenant principals resolve their own; platform principals must give target_scope_id and owner_id of a tenant member.
参数
getEffectiveUserConfigs 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
X-Request-ID | header | string | 否 | Caller-stable request identity; invalid or absent values are replaced by middleware. |
|---|
type | query | string | 是 | — |
|---|
target_scope_id | query | string(uuid) | 否 | — |
|---|
owner_id | query | string(uuid) | 否 | — |
|---|
group_id | query | array<string(uuid)> | 否 | — |
|---|
响应
getEffectiveUserConfigs 响应| 状态码 | 说明 |
|---|
200 | Effective defaults. 字段：protocol: string: tcp / udp / null | null: tcp / udp / null proxy_protocol_inbound: boolean | null balance_way: string: rr / ip_hash / null | null: rr / ip_hash / null |
|---|
400 | Stable invalid request or validation error. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | The authenticated principal lacks the required permission or owner scope. |
|---|
500 | Internal operation failure without publication or activation claims. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
DELETE /v1/user-configs/{id}
Delete a per-user stream default
- operationId
deleteUserConfig- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：streams.manage
参数
deleteUserConfig 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | Exact per-user stream default identity. |
|---|
X-Request-ID | header | string | 否 | Caller-stable request identity; invalid or absent values are replaced by middleware. |
|---|
Idempotency-Key | header | string | 是 | Reuse is accepted only for the exact same actor, operation, and normalized input. |
|---|
响应
deleteUserConfig 响应| 状态码 | 说明 |
|---|
204 | Default deleted. |
|---|
400 | Stable invalid request or validation error. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | The authenticated principal lacks the required permission or owner scope. |
|---|
404 | No visible stream matches the exact immutable stream identity. |
|---|
409 | Revision, idempotency, name, or listener-port conflict. |
|---|
500 | Internal operation failure without publication or activation claims. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表