版本 2.4.7.20261116085428 · 最新

四层转发 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列出四层转发

鉴权: 用户(部分参数仅管理员)

查询参数

字段类型说明
pageinteger 页码,从 1 开始。
默认 1
page_sizeinteger 每页条数。
默认 20
sortstring 排序字段,逗号分隔,前缀 `-` 表示降序,如 `-created_at,id`。
tenant_idinteger 仅管理员可用:按租户过滤(格式错 422)。租户凭据调用时忽略,只返回本租户数据。
portinteger 只列监听该端口的转发。
group_idinteger 只列该分组里的转发。
upidinteger 只列该用户套餐下的转发。
enabledboolean 按启停过滤。
idinteger 按转发 id 精确过滤。
originstring 按源站 IP 子串过滤。
protocolstring 只列有该协议监听的转发。
可选值 ["tcp","udp"]
stop_codeinteger 按停用码过滤;0 = 正常。
tenant_idsstring 仅管理员可用:只看这些租户,逗号分隔的正整数,去重后至多 200 个(超了或格式错 422);只选 1 个也可用。只做过滤、不切换请求作用域,与 tenant_id 及其他条件取交集;租户凭据带了非空值回 403。
idsstring 只列这些 id:逗号分隔的正整数,去重后至多 200 个(同 page_size 上限,超了或格式错 422);空串等同不传。与其他条件取交集;看不到的 id 不返回也不报错。分页照旧,一次取回要把 page_size 设成不少于 id 个数。
upidsstring 按用户套餐(多个)过滤:逗号分隔的正整数,去重后至多 200 个(超了或格式错 422);只选 1 个也可用;与其他条件取交集。
namestring 按名称子串过滤(不分大小写)。
group_idsstring 多个分组 id 逗号分隔(正整数,去重后至多 200 个,超了或格式错 422),转发在其中任一分组里即命中;可与 group_id 同用(两者都要满足)。
package_idinteger 按基础套餐过滤。
region_idinteger 按区域过滤:接入名的主线路分组属于该区域;没有自己接入名的按所属已售套餐的共用接入名算。
node_group_idinteger 按线路分组过滤:接入名的主线路分组或备用线路分组是它。
cname_domain_idinteger 按接入根域过滤。
package_idsstring 按基础套餐(多个)过滤,语义同 package_id:逗号分隔的正整数,去重后至多 200 个(超了或格式错 422);只选 1 个也可用;与其他条件取交集。
region_idsstring 按区域(多个)过滤,语义同 region_id:逗号分隔的正整数,去重后至多 200 个(超了或格式错 422);只选 1 个也可用;与其他条件取交集。
node_group_idsstring 按线路分组(多个)过滤,语义同 node_group_id:逗号分隔的正整数,去重后至多 200 个(超了或格式错 422);只选 1 个也可用;与其他条件取交集。
cname_domain_idsstring 按接入根域(多个)过滤,语义同 cname_domain_id:逗号分隔的正整数,去重后至多 200 个(超了或格式错 422);只选 1 个也可用;与其他条件取交集。
cname_hostnamestring 按接入名主机记录精确过滤。
sync_statestring 按配置同步状态过滤:behind = 配置落后(还有在线节点没装上它最近一次修改后的配置版本);
可选值 ["behind","synced"]
POST/api/v2/streams创建四层转发

鉴权: 用户(部分参数仅管理员)

查询参数

字段类型说明
tenant_idinteger 管理员代建时的属主租户(必填);租户调用时忽略,属主恒为本人。

请求体 application/json

字段类型说明
aclStreamAcl 四层访问控制:逐条按来源 IP/网段匹配,首条命中定结果,都不中按 default_action;deny 直接断开连接。
balanceStreamBalance 负载方式:rr 轮询、ip_hash 按来源 IP 哈希、least_conn 最少连接、random 随机。
可选值 ["rr","ip_hash","least_conn","random"]
cnameCnameBinding 接入名(CNAME):用户把域名 CNAME 到 fqdn,解析由平台按节点组生成;没有接入名时为 null。
conn_limitinteger 单 IP 并发连接上限,0 = 不限。
enabledboolean 是否启用
expected_updated_atstring 乐观锁(修改时用):调用方读到的该资源 updated_at。与库里当前值不等则回 409 stale_version、不保存;不带则不检查;创建时忽略。
group_idsinteger[] 所属转发分组 id 列表。
listen必填StreamListen[] 监听列表:每项为端口与协议。
namestring 名称
origin_port必填integer 回源端口。
origins必填StreamOrigin[] 源站列表:每项为源站 IP、权重与备用/下线标记。
proxy_protocolboolean 是否向源站发送 PROXY protocol 头。
stop_codeinteger 0 = 正常;非 0 = 新连接直接断开(管理员/计费设置;用户套餐到期时快照里为 512)。
udp_responsesinteger UDP 应答数:1~100 = 每个 UDP 会话收到源站这么多个包就结束(不再等 UDP 空闲超时),0 = 不设。只适合一问一答(DNS、探测);一问多答的游戏/语音别设,会被提前断开。
upidinteger 用户套餐 id(建/改时不填:名下恰一份套餐就自动挂上,已到期的也算、挂上后照常核到期(新建报 422 package_expired);一份没有 422 no_package,多份须指定 422 required;快照里空时取 tenant_id)。
POST/api/v2/streams/batch批量操作四层转发

鉴权: 用户(部分参数仅管理员)

查询参数

字段类型说明
tenant_idinteger 管理员代建时的属主租户(必填);租户调用时忽略,属主恒为本人。

请求体 application/json

字段类型说明
action必填string 操作类型:set_enabled 启停、delete 删除、set_groups 换分组、update 批量修改、create 批量新建、 set_lines 改接入名的主/备线路分组(仅管理员)、set_cname_domain 改接入名的根域(仅管理员,主机记录不变)。
可选值 ["set_enabled","delete","set_groups","update","create","set_lines","set_cname_domain"]
backup_group_idinteger set_lines 用:备用线路分组;0 = 清空,不给 = 不动。
cname_domain_idinteger set_cname_domain 用:新的接入根域。
enabledboolean 是否启用
group_idsinteger[] 所属转发分组 id 列表。
idsinteger[] 要操作的转发 id 列表,一次最多 100 条(create 以外的操作必填)。
itemsStreamWrite[] create 用:要新建的转发(最多 100 条),每条同 POST /streams 的请求体。
node_group_idinteger set_lines 用:主线路分组(必填)。
patchStreamPatch 批量 update 用:给了的字段改到每一条上,规则同单条修改。
region_idinteger set_lines 用:区域;给了就校验主/备线路分组都属于它(不给不校验)。
GET/api/v2/streams/{id}获取四层转发

鉴权: 用户(部分参数仅管理员)

PUT/api/v2/streams/{id}修改四层转发

鉴权: 用户(部分参数仅管理员)

请求体 application/json

字段类型说明
aclStreamAcl 四层访问控制:逐条按来源 IP/网段匹配,首条命中定结果,都不中按 default_action;deny 直接断开连接。
balanceStreamBalance 负载方式:rr 轮询、ip_hash 按来源 IP 哈希、least_conn 最少连接、random 随机。
可选值 ["rr","ip_hash","least_conn","random"]
cnameCnameBinding 接入名(CNAME):用户把域名 CNAME 到 fqdn,解析由平台按节点组生成;没有接入名时为 null。
conn_limitinteger 单 IP 并发连接上限,0 = 不限。
enabledboolean 是否启用
expected_updated_atstring 乐观锁(修改时用):调用方读到的该资源 updated_at。与库里当前值不等则回 409 stale_version、不保存;不带则不检查;创建时忽略。
group_idsinteger[] 所属转发分组 id 列表。
listen必填StreamListen[] 监听列表:每项为端口与协议。
namestring 名称
origin_port必填integer 回源端口。
origins必填StreamOrigin[] 源站列表:每项为源站 IP、权重与备用/下线标记。
proxy_protocolboolean 是否向源站发送 PROXY protocol 头。
stop_codeinteger 0 = 正常;非 0 = 新连接直接断开(管理员/计费设置;用户套餐到期时快照里为 512)。
udp_responsesinteger UDP 应答数:1~100 = 每个 UDP 会话收到源站这么多个包就结束(不再等 UDP 空闲超时),0 = 不设。只适合一问一答(DNS、探测);一问多答的游戏/语音别设,会被提前断开。
upidinteger 用户套餐 id(建/改时不填:名下恰一份套餐就自动挂上,已到期的也算、挂上后照常核到期(新建报 422 package_expired);一份没有 422 no_package,多份须指定 422 required;快照里空时取 tenant_id)。
DELETE/api/v2/streams/{id}删除四层转发

鉴权: 用户(部分参数仅管理员)

四层转发对象

字段类型说明
aclStreamAcl 四层访问控制:逐条按来源 IP/网段匹配,首条命中定结果,都不中按 default_action;deny 直接断开连接。
action必填string 操作类型:set_enabled 启停、delete 删除、set_groups 换分组、update 批量修改、create 批量新建、 set_lines 改接入名的主/备线路分组(仅管理员)、set_cname_domain 改接入名的根域(仅管理员,主机记录不变)。
可选值 ["set_enabled","delete","set_groups","update","create","set_lines","set_cname_domain"]
affectedinteger 受影响的条数
backup_group_idinteger set_lines 用:备用线路分组;0 = 清空,不给 = 不动。
balanceStreamBalance 负载方式:rr 轮询、ip_hash 按来源 IP 哈希、least_conn 最少连接、random 随机。
可选值 ["rr","ip_hash","least_conn","random"]
cnameCnameBinding 接入名(CNAME):用户把域名 CNAME 到 fqdn,解析由平台按节点组生成;没有接入名时为 null。
cname_domain_idinteger set_cname_domain 用:新的接入根域。
conn_limitinteger 单 IP 并发连接上限,0 = 不限。
created_atstring 创建时间
只读
enabledboolean 是否启用
expected_updated_atstring 乐观锁(修改时用):调用方读到的该资源 updated_at。与库里当前值不等则回 409 stale_version、不保存;不带则不检查;创建时忽略。
group_idsinteger[] 所属转发分组 id 列表。
idinteger 记录 ID
只读
idsinteger[] 要操作的转发 id 列表,一次最多 100 条(create 以外的操作必填)。
itemsStreamWrite[] create 用:要新建的转发(最多 100 条),每条同 POST /streams 的请求体。
listenStreamListen[] 监听列表:每项为端口与协议。
namestring 名称
node_group_idinteger set_lines 用:主线路分组(必填)。
node_issuesNodeIssue[] 在线节点上这条转发没完全生效的口或原因(列表与详情里给);都正常时不给这个字段。
只读
origin_portinteger 回源端口。
originsStreamOrigin[] 源站列表:每项为源站 IP、权重与备用/下线标记。
patchStreamPatch 批量 update 用:给了的字段改到每一条上,规则同单条修改。
proxy_protocolboolean 是否向源站发送 PROXY protocol 头。
region_idinteger set_lines 用:区域;给了就校验主/备线路分组都属于它(不给不校验)。
stop_codeinteger 0 = 正常;非 0 = 新连接直接断开(管理员/计费设置;用户套餐到期时快照里为 512)。
tenant_idinteger 所属租户(用户)ID
只读
udp_responsesinteger UDP 应答数:1~100 = 每个 UDP 会话收到源站这么多个包就结束(不再等 UDP 空闲超时),0 = 不设。只适合一问一答(DNS、探测);一问多答的游戏/语音别设,会被提前断开。
updated_atstring 更新时间
只读
upidinteger 用户套餐 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"
}
开始使用

123

123