版本 2.4.8 · 最新
四层转发 streams
TCP/UDP 端口转发规则。每条规则含监听端口与协议、源站列表、负载方式;(协议, 端口) 全平台唯一。
点击任一接口,右侧显示对应的调用示例。
四层转发鉴权: 用户(部分参数仅管理员)6 个接口
鉴权
请求头带 X-API-Key(在「API 密钥」页开通,密钥只在开通时显示一次);也可用登录得到的 Authorization: Bearer 令牌。
X-API-Key
鉴权失败回 401;无权回 403(code 为 insufficient_scope 等)。
约定
分页参数 page(从 1 起)、page_size;排序 sort=字段 或 -字段。
时间一律 RFC 3339(UTC);金额单位为分。
写操作成功回 200/201/204;重复提交按资源唯一键回 409。
GET
/api/v2/streams列出四层转发
鉴权: 用户(部分参数仅管理员)
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
page | integer | 页码,从 1 开始。 |
page_size | integer | 每页条数。 |
sort | string | 排序字段,逗号分隔,前缀 `-` 表示降序,如 `-created_at,id`。 |
tenant_id | integer | 仅管理员可用:按租户过滤(格式错 422)。租户凭据调用时忽略,只返回本租户数据。 |
port | integer | 只列监听该端口的转发。 |
group_id | integer | 只列该分组里的转发。 |
upid | integer | 只列该用户套餐下的转发。 |
enabled | boolean | 按启停过滤。 |
id | integer | 按转发 id 精确过滤。 |
origin | string | 按源站 IP 子串过滤。 |
protocol | string | 只列有该协议监听的转发。 |
stop_code | integer | 按停用码过滤;0 = 正常。 |
tenant_ids | string | 仅管理员可用:只看这些租户,逗号分隔的正整数,去重后至多 200 个(超了或格式错 422);只选 1 个也可用。只做过滤、不切换请求作用域,与 tenant_id 及其他条件取交集;租户凭据带了非空值回 403。 |
ids | string | 只列这些 id:逗号分隔的正整数,去重后至多 200 个(同 page_size 上限,超了或格式错 422);空串等同不传。与其他条件取交集;看不到的 id 不返回也不报错。分页照旧,一次取回要把 page_size 设成不少于 id 个数。 |
upids | string | 按用户套餐(多个)过滤:逗号分隔的正整数,去重后至多 200 个(超了或格式错 422);只选 1 个也可用;与其他条件取交集。 |
name | string | 按名称子串过滤(不分大小写)。 |
group_ids | string | 多个分组 id 逗号分隔(正整数,去重后至多 200 个,超了或格式错 422),转发在其中任一分组里即命中;可与 group_id 同用(两者都要满足)。 |
package_id | integer | 按基础套餐过滤。 |
region_id | integer | 按区域过滤:接入名的主线路分组属于该区域;没有自己接入名的按所属已售套餐的共用接入名算。 |
node_group_id | integer | 按线路分组过滤:接入名的主线路分组或备用线路分组是它。 |
cname_domain_id | integer | 按接入根域过滤。 |
package_ids | string | 按基础套餐(多个)过滤,语义同 package_id:逗号分隔的正整数,去重后至多 200 个(超了或格式错 422);只选 1 个也可用;与其他条件取交集。 |
region_ids | string | 按区域(多个)过滤,语义同 region_id:逗号分隔的正整数,去重后至多 200 个(超了或格式错 422);只选 1 个也可用;与其他条件取交集。 |
node_group_ids | string | 按线路分组(多个)过滤,语义同 node_group_id:逗号分隔的正整数,去重后至多 200 个(超了或格式错 422);只选 1 个也可用;与其他条件取交集。 |
cname_domain_ids | string | 按接入根域(多个)过滤,语义同 cname_domain_id:逗号分隔的正整数,去重后至多 200 个(超了或格式错 422);只选 1 个也可用;与其他条件取交集。 |
cname_hostname | string | 按接入名主机记录精确过滤。 |
sync_state | string | 按配置同步状态过滤:behind = 配置落后(还有在线节点没装上它最近一次修改后的配置版本); |
POST
/api/v2/streams创建四层转发
鉴权: 用户(部分参数仅管理员)
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
tenant_id | integer | 管理员代建时的属主租户(必填);租户调用时忽略,属主恒为本人。 |
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
acl | StreamAcl | 四层访问控制:逐条按来源 IP/网段匹配,首条命中定结果,都不中按 default_action;deny 直接断开连接。 |
balance | StreamBalance | 负载方式:rr 轮询、ip_hash 按来源 IP 哈希、least_conn 最少连接、random 随机。 |
cname | CnameBinding | 接入名(CNAME):用户把域名 CNAME 到 fqdn,解析由平台按节点组生成;没有接入名时为 null。 |
conn_limit | integer | 单 IP 并发连接上限,0 = 不限。 |
enabled | boolean | 是否启用 |
expected_updated_at | string | 乐观锁(修改时用):调用方读到的该资源 updated_at。与库里当前值不等则回 409 stale_version、不保存;不带则不检查;创建时忽略。 |
group_ids | integer[] | 所属转发分组 id 列表。 |
listen必填 | StreamListen[] | 监听列表:每项为端口与协议。 |
name | string | 名称 |
origin_port必填 | integer | 回源端口。 |
origins必填 | StreamOrigin[] | 源站列表:每项为源站 IP、权重与备用/下线标记。 |
proxy_protocol | boolean | 是否向源站发送 PROXY protocol 头。 |
stop_code | integer | 0 = 正常;非 0 = 新连接直接断开(管理员/计费设置;用户套餐到期时快照里为 512)。 |
udp_responses | integer | UDP 应答数:1~100 = 每个 UDP 会话收到源站这么多个包就结束(不再等 UDP 空闲超时),0 = 不设。只适合一问一答(DNS、探测);一问多答的游戏/语音别设,会被提前断开。 |
upid | integer | 用户套餐 id(建/改时不填:名下恰一份套餐就自动挂上,已到期的也算、挂上后照常核到期(新建报 422 package_expired);一份没有 422 no_package,多份须指定 422 required;快照里空时取 tenant_id)。 |
POST
/api/v2/streams/batch批量操作四层转发
鉴权: 用户(部分参数仅管理员)
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
tenant_id | integer | 管理员代建时的属主租户(必填);租户调用时忽略,属主恒为本人。 |
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
action必填 | string | 操作类型:set_enabled 启停、delete 删除、set_groups 换分组、update 批量修改、create 批量新建、 set_lines 改接入名的主/备线路分组(仅管理员)、set_cname_domain 改接入名的根域(仅管理员,主机记录不变)。 |
backup_group_id | integer | set_lines 用:备用线路分组;0 = 清空,不给 = 不动。 |
cname_domain_id | integer | set_cname_domain 用:新的接入根域。 |
enabled | boolean | 是否启用 |
group_ids | integer[] | 所属转发分组 id 列表。 |
ids | integer[] | 要操作的转发 id 列表,一次最多 100 条(create 以外的操作必填)。 |
items | StreamWrite[] | create 用:要新建的转发(最多 100 条),每条同 POST /streams 的请求体。 |
node_group_id | integer | set_lines 用:主线路分组(必填)。 |
patch | StreamPatch | 批量 update 用:给了的字段改到每一条上,规则同单条修改。 |
region_id | integer | set_lines 用:区域;给了就校验主/备线路分组都属于它(不给不校验)。 |
GET
/api/v2/streams/{id}获取四层转发
鉴权: 用户(部分参数仅管理员)
PUT
/api/v2/streams/{id}修改四层转发
鉴权: 用户(部分参数仅管理员)
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
acl | StreamAcl | 四层访问控制:逐条按来源 IP/网段匹配,首条命中定结果,都不中按 default_action;deny 直接断开连接。 |
balance | StreamBalance | 负载方式:rr 轮询、ip_hash 按来源 IP 哈希、least_conn 最少连接、random 随机。 |
cname | CnameBinding | 接入名(CNAME):用户把域名 CNAME 到 fqdn,解析由平台按节点组生成;没有接入名时为 null。 |
conn_limit | integer | 单 IP 并发连接上限,0 = 不限。 |
enabled | boolean | 是否启用 |
expected_updated_at | string | 乐观锁(修改时用):调用方读到的该资源 updated_at。与库里当前值不等则回 409 stale_version、不保存;不带则不检查;创建时忽略。 |
group_ids | integer[] | 所属转发分组 id 列表。 |
listen必填 | StreamListen[] | 监听列表:每项为端口与协议。 |
name | string | 名称 |
origin_port必填 | integer | 回源端口。 |
origins必填 | StreamOrigin[] | 源站列表:每项为源站 IP、权重与备用/下线标记。 |
proxy_protocol | boolean | 是否向源站发送 PROXY protocol 头。 |
stop_code | integer | 0 = 正常;非 0 = 新连接直接断开(管理员/计费设置;用户套餐到期时快照里为 512)。 |
udp_responses | integer | UDP 应答数:1~100 = 每个 UDP 会话收到源站这么多个包就结束(不再等 UDP 空闲超时),0 = 不设。只适合一问一答(DNS、探测);一问多答的游戏/语音别设,会被提前断开。 |
upid | integer | 用户套餐 id(建/改时不填:名下恰一份套餐就自动挂上,已到期的也算、挂上后照常核到期(新建报 422 package_expired);一份没有 422 no_package,多份须指定 422 required;快照里空时取 tenant_id)。 |
DELETE
/api/v2/streams/{id}删除四层转发
鉴权: 用户(部分参数仅管理员)
四层转发对象
| 字段 | 类型 | 说明 |
|---|---|---|
acl | StreamAcl | 四层访问控制:逐条按来源 IP/网段匹配,首条命中定结果,都不中按 default_action;deny 直接断开连接。 |
action必填 | string | 操作类型:set_enabled 启停、delete 删除、set_groups 换分组、update 批量修改、create 批量新建、 set_lines 改接入名的主/备线路分组(仅管理员)、set_cname_domain 改接入名的根域(仅管理员,主机记录不变)。 |
affected | integer | 受影响的条数 |
backup_group_id | integer | set_lines 用:备用线路分组;0 = 清空,不给 = 不动。 |
balance | StreamBalance | 负载方式:rr 轮询、ip_hash 按来源 IP 哈希、least_conn 最少连接、random 随机。 |
cname | CnameBinding | 接入名(CNAME):用户把域名 CNAME 到 fqdn,解析由平台按节点组生成;没有接入名时为 null。 |
cname_domain_id | integer | set_cname_domain 用:新的接入根域。 |
conn_limit | integer | 单 IP 并发连接上限,0 = 不限。 |
created_at | string | 创建时间 |
enabled | boolean | 是否启用 |
expected_updated_at | string | 乐观锁(修改时用):调用方读到的该资源 updated_at。与库里当前值不等则回 409 stale_version、不保存;不带则不检查;创建时忽略。 |
group_ids | integer[] | 所属转发分组 id 列表。 |
id | integer | 记录 ID |
ids | integer[] | 要操作的转发 id 列表,一次最多 100 条(create 以外的操作必填)。 |
items | StreamWrite[] | create 用:要新建的转发(最多 100 条),每条同 POST /streams 的请求体。 |
listen | StreamListen[] | 监听列表:每项为端口与协议。 |
name | string | 名称 |
node_group_id | integer | set_lines 用:主线路分组(必填)。 |
node_issues | NodeIssue[] | 在线节点上这条转发没完全生效的口或原因(列表与详情里给);都正常时不给这个字段。 |
origin_port | integer | 回源端口。 |
origins | StreamOrigin[] | 源站列表:每项为源站 IP、权重与备用/下线标记。 |
patch | StreamPatch | 批量 update 用:给了的字段改到每一条上,规则同单条修改。 |
proxy_protocol | boolean | 是否向源站发送 PROXY protocol 头。 |
region_id | integer | set_lines 用:区域;给了就校验主/备线路分组都属于它(不给不校验)。 |
stop_code | integer | 0 = 正常;非 0 = 新连接直接断开(管理员/计费设置;用户套餐到期时快照里为 512)。 |
tenant_id | integer | 所属租户(用户)ID |
udp_responses | integer | UDP 应答数:1~100 = 每个 UDP 会话收到源站这么多个包就结束(不再等 UDP 空闲超时),0 = 不设。只适合一问一答(DNS、探测);一问多答的游戏/语音别设,会被提前断开。 |
updated_at | string | 更新时间 |
upid | integer | 用户套餐 id(建/改时不填:名下恰一份套餐就自动挂上,已到期的也算、挂上后照常核到期(新建报 422 package_expired);一份没有 422 no_package,多份须指定 422 required;快照里空时取 tenant_id)。 |
返回与错误
成功直接回资源 JSON(HTTP 2xx);失败回 application/problem+json(code、detail,校验失败带 errors);列表为 items + total。
成功
{
"id": 1,
"name": "example"
}列表
{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}失败
{
"code": "validation_failed",
"detail": "请求参数不合法",
"errors": [
{
"code": "required",
"field": "/name",
"message": "name 必填"
}
],
"request_id": "0123456789abcdef",
"status": 422,
"title": "Unprocessable Entity",
"type": "about:blank"
}