代理资源

自建与已购代理的列表、详情、创建、批量创建、按桌面端行格式导入、在客户端本机检测出口（单个或批量），以及修改和删除。购买代理见 代理商店。数组型查询参数按 state=1&state=0 的形式重复传递。

在本页搜索

显示 10 / 10 个接口

GET/proxy/list

代理列表

分页查询当前登录团队的代理资源，并附带绑定该代理的窗口。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
page	number	可选	页码，默认 1
size	number	可选	每页数量，默认 20，服务端上限 1000
keyword	string	可选	关键词，模糊匹配 host、username、activeIp 或 remark
source	string	可选	来源过滤：CUSTOM、BUY
state	number[]	可选	状态过滤，需重复传参构造数组，如 state=1&state=0；state[]= 形式无效

注意事项

• 已删除的代理始终被排除；响应包含明文代理密码。

响应字段

字段	类型	说明
data.count	number	匹配到的总条数
data.size	number	每页数量，回显请求值
data.page	number	当前页码，回显请求值
data.total	number	总页数
data.data	object[]	当前页记录
data.data[].id	number	代理主键 ID
data.data[].userId	number	代理归属用户 ID
data.data[].teamId	number	代理归属团队 ID
data.data[].ipVersion	string	IP 版本：IPv4、IPv6
data.data[].protocol	string	协议：SOCKS5、HTTP、HTTPS
data.data[].host	string	代理主机，IP 或域名
data.data[].port	number	代理端口
data.data[].username	string	代理认证用户名
data.data[].password	string	代理认证密码（明文）
data.data[].provider	string	出口 IP 检测服务方
data.data[].activeTime	string	最近一次检测时间
data.data[].activeIp	string	最近一次检测到的出口 IP
data.data[].state	number	状态：0 待检测、1 可用、-1 不可用、-2 已过期
data.data[].remark	string	备注
data.data[].expireTime	string	到期时间，自定义代理通常为 null
data.data[].createdAt	string	创建时间
data.data[].updatedAt	string	更新时间
data.data[].country	string	出口国家，未检测为 null
data.data[].region	string	出口省/州
data.data[].countryCode	string	出口国家码
data.data[].city	string	出口城市
data.data[].timezone	string	出口时区标识，如 Asia/Shanghai
data.data[].source	string	来源：CUSTOM 自定义、BUY 平台购买
data.data[].sourceId	number	来源 ID，自定义代理为 null
data.data[].userEmail	string	归属用户邮箱，由服务端回填
data.data[].bindScreen	object[]	绑定该代理的窗口，无绑定时为 null

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "count": 10,
    "size": 20,
    "page": 1,
    "total": 1,
    "data": [
      {
        "id": 6001,
        "userId": 1001,
        "teamId": 2001,
        "ipVersion": "IPv4",
        "protocol": "SOCKS5",
        "host": "198.51.100.24",
        "port": 1080,
        "username": "proxy-user",
        "password": "proxy-password",
        "provider": "http://ip-api.com/json",
        "activeTime": "2026-06-01 12:30:00",
        "activeIp": "198.51.100.24",
        "state": 1,
        "remark": null,
        "expireTime": "2026-07-15 10:00:00",
        "createdAt": "2026-06-01 12:30:00",
        "updatedAt": "2026-06-01 12:30:00",
        "country": "United States",
        "region": "California",
        "countryCode": "US",
        "city": "Los Angeles",
        "timezone": "America/Los_Angeles",
        "source": "BUY",
        "sourceId": 7001,
        "userEmail": "[email protected]",
        "bindScreen": null
      }
    ]
  }
}

GET/proxy/list_merged

合并代理列表

与 /proxy/list 转发同一个后端分页命令，参数与响应完全一致，仅保留路径别名。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
page	number	可选	页码，默认 1
size	number	可选	每页数量，默认 20，服务端上限 1000
keyword	string	可选	关键词，模糊匹配 host、username、activeIp 或 remark
source	string	可选	来源过滤：CUSTOM、BUY
state	number[]	可选	状态过滤，需重复传参构造数组

注意事项

• 客户端不做任何额外合并，结果与 /proxy/list 相同。

响应字段

字段	类型	说明
data.count	number	匹配到的总条数
data.size	number	每页数量，回显请求值
data.page	number	当前页码，回显请求值
data.total	number	总页数
data.data	object[]	当前页记录
data.data[].id	number	代理主键 ID
data.data[].userId	number	代理归属用户 ID
data.data[].teamId	number	代理归属团队 ID
data.data[].ipVersion	string	IP 版本：IPv4、IPv6
data.data[].protocol	string	协议：SOCKS5、HTTP、HTTPS
data.data[].host	string	代理主机，IP 或域名
data.data[].port	number	代理端口
data.data[].username	string	代理认证用户名
data.data[].password	string	代理认证密码（明文）
data.data[].provider	string	出口 IP 检测服务方
data.data[].activeTime	string	最近一次检测时间
data.data[].activeIp	string	最近一次检测到的出口 IP
data.data[].state	number	状态：0 待检测、1 可用、-1 不可用、-2 已过期
data.data[].remark	string	备注
data.data[].expireTime	string	到期时间，自定义代理通常为 null
data.data[].createdAt	string	创建时间
data.data[].updatedAt	string	更新时间
data.data[].country	string	出口国家，未检测为 null
data.data[].region	string	出口省/州
data.data[].countryCode	string	出口国家码
data.data[].city	string	出口城市
data.data[].timezone	string	出口时区标识，如 Asia/Shanghai
data.data[].source	string	来源：CUSTOM 自定义、BUY 平台购买
data.data[].sourceId	number	来源 ID，自定义代理为 null
data.data[].userEmail	string	归属用户邮箱，由服务端回填
data.data[].bindScreen	object[]	绑定该代理的窗口，无绑定时为 null

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "count": 10,
    "size": 20,
    "page": 1,
    "total": 1,
    "data": [
      {
        "id": 6001,
        "userId": 1001,
        "teamId": 2001,
        "ipVersion": "IPv4",
        "protocol": "SOCKS5",
        "host": "198.51.100.24",
        "port": 1080,
        "username": "proxy-user",
        "password": "proxy-password",
        "provider": "http://ip-api.com/json",
        "activeTime": "2026-06-01 12:30:00",
        "activeIp": "198.51.100.24",
        "state": 1,
        "remark": null,
        "expireTime": "2026-07-15 10:00:00",
        "createdAt": "2026-06-01 12:30:00",
        "updatedAt": "2026-06-01 12:30:00",
        "country": "United States",
        "region": "California",
        "countryCode": "US",
        "city": "Los Angeles",
        "timezone": "America/Los_Angeles",
        "source": "BUY",
        "sourceId": 7001,
        "userEmail": "[email protected]",
        "bindScreen": null
      }
    ]
  }
}

GET/proxy/bought_list

已购代理列表

与 /proxy/list 转发同一个后端分页命令，需自行传 source=BUY 才只返回平台购买的代理。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
page	number	可选	页码，默认 1
size	number	可选	每页数量，默认 20，服务端上限 1000
source	string	可选	不传则返回全部来源；传 BUY 只返回平台购买的代理
keyword	string	可选	关键词，模糊匹配 host、username、activeIp 或 remark
state	number[]	可选	状态过滤，需重复传参构造数组

注意事项

• 路径本身不隐含 source=BUY 过滤。

响应字段

字段	类型	说明
data.count	number	匹配到的总条数
data.size	number	每页数量，回显请求值
data.page	number	当前页码，回显请求值
data.total	number	总页数
data.data	object[]	当前页记录
data.data[].id	number	代理主键 ID
data.data[].userId	number	代理归属用户 ID
data.data[].teamId	number	代理归属团队 ID
data.data[].ipVersion	string	IP 版本：IPv4、IPv6
data.data[].protocol	string	协议：SOCKS5、HTTP、HTTPS
data.data[].host	string	代理主机，IP 或域名
data.data[].port	number	代理端口
data.data[].username	string	代理认证用户名
data.data[].password	string	代理认证密码（明文）
data.data[].provider	string	出口 IP 检测服务方
data.data[].activeTime	string	最近一次检测时间
data.data[].activeIp	string	最近一次检测到的出口 IP
data.data[].state	number	状态：0 待检测、1 可用、-1 不可用、-2 已过期
data.data[].remark	string	备注
data.data[].expireTime	string	到期时间，自定义代理通常为 null
data.data[].createdAt	string	创建时间
data.data[].updatedAt	string	更新时间
data.data[].country	string	出口国家，未检测为 null
data.data[].region	string	出口省/州
data.data[].countryCode	string	出口国家码
data.data[].city	string	出口城市
data.data[].timezone	string	出口时区标识，如 Asia/Shanghai
data.data[].source	string	来源：CUSTOM 自定义、BUY 平台购买
data.data[].sourceId	number	来源 ID，自定义代理为 null
data.data[].userEmail	string	归属用户邮箱，由服务端回填
data.data[].bindScreen	object[]	绑定该代理的窗口，无绑定时为 null

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "count": 5,
    "size": 20,
    "page": 1,
    "total": 1,
    "data": [
      {
        "id": 6001,
        "userId": 1001,
        "teamId": 2001,
        "ipVersion": "IPv4",
        "protocol": "SOCKS5",
        "host": "198.51.100.24",
        "port": 1080,
        "username": "proxy-user",
        "password": "proxy-password",
        "provider": "http://ip-api.com/json",
        "activeTime": "2026-06-01 12:30:00",
        "activeIp": "198.51.100.24",
        "state": 1,
        "remark": null,
        "expireTime": "2026-07-15 10:00:00",
        "createdAt": "2026-06-01 12:30:00",
        "updatedAt": "2026-06-01 12:30:00",
        "country": "United States",
        "region": "California",
        "countryCode": "US",
        "city": "Los Angeles",
        "timezone": "America/Los_Angeles",
        "source": "BUY",
        "sourceId": 7001,
        "userEmail": "[email protected]",
        "bindScreen": null
      }
    ]
  }
}

GET/proxy/detail

代理详情

与 /proxy/list 转发同一个后端分页命令，用 keyword 定位单条代理后取 data.data[0]。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
keyword	string	可选	定位条件，模糊匹配 host、username、activeIp 或 remark
page	number	可选	页码，默认 1
size	number	可选	每页数量，默认 20，服务端上限 1000
source	string	可选	来源过滤：CUSTOM、BUY
state	number[]	可选	状态过滤，需重复传参构造数组

注意事项

• 后端命令不支持按 id 查询单条，响应仍是分页结构。

响应字段

字段	类型	说明
data.count	number	匹配到的总条数
data.size	number	每页数量，回显请求值
data.page	number	当前页码，回显请求值
data.total	number	总页数
data.data	object[]	当前页记录
data.data[].id	number	代理主键 ID
data.data[].userId	number	代理归属用户 ID
data.data[].teamId	number	代理归属团队 ID
data.data[].ipVersion	string	IP 版本：IPv4、IPv6
data.data[].protocol	string	协议：SOCKS5、HTTP、HTTPS
data.data[].host	string	代理主机，IP 或域名
data.data[].port	number	代理端口
data.data[].username	string	代理认证用户名
data.data[].password	string	代理认证密码（明文）
data.data[].provider	string	出口 IP 检测服务方
data.data[].activeTime	string	最近一次检测时间
data.data[].activeIp	string	最近一次检测到的出口 IP
data.data[].state	number	状态：0 待检测、1 可用、-1 不可用、-2 已过期
data.data[].remark	string	备注
data.data[].expireTime	string	到期时间，自定义代理通常为 null
data.data[].createdAt	string	创建时间
data.data[].updatedAt	string	更新时间
data.data[].country	string	出口国家，未检测为 null
data.data[].region	string	出口省/州
data.data[].countryCode	string	出口国家码
data.data[].city	string	出口城市
data.data[].timezone	string	出口时区标识，如 Asia/Shanghai
data.data[].source	string	来源：CUSTOM 自定义、BUY 平台购买
data.data[].sourceId	number	来源 ID，自定义代理为 null
data.data[].userEmail	string	归属用户邮箱，由服务端回填
data.data[].bindScreen	object[]	绑定该代理的窗口，无绑定时为 null

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "count": 1,
    "size": 1,
    "page": 1,
    "total": 1,
    "data": [
      {
        "id": 6001,
        "userId": 1001,
        "teamId": 2001,
        "ipVersion": "IPv4",
        "protocol": "SOCKS5",
        "host": "198.51.100.24",
        "port": 1080,
        "username": "proxy-user",
        "password": "proxy-password",
        "provider": "http://ip-api.com/json",
        "activeTime": "2026-06-01 12:30:00",
        "activeIp": "198.51.100.24",
        "state": 1,
        "remark": null,
        "expireTime": "2026-07-15 10:00:00",
        "createdAt": "2026-06-01 12:30:00",
        "updatedAt": "2026-06-01 12:30:00",
        "country": "United States",
        "region": "California",
        "countryCode": "US",
        "city": "Los Angeles",
        "timezone": "America/Los_Angeles",
        "source": "BUY",
        "sourceId": 7001,
        "userEmail": "[email protected]",
        "bindScreen": null
      }
    ]
  }
}

POST/proxy/create

创建代理

创建一个或一组代理；不传 items 时把整个请求体当作单个代理项。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
items	object[]	可选	代理集合；不传时整个请求体作为单个代理项
ipVersion	string	可选	IP 版本：IPv4、IPv6
protocol	string	必填	协议：SOCKS5、HTTP、HTTPS
host	string	必填	代理主机，IP 或域名
port	number	必填	代理端口
username	string	可选	代理认证用户名
password	string	可选	代理认证密码
remark	string	可选	备注

注意事项

• teamId 与 userId 由服务端按当前登录账号写入，传入值无效。
• 单条创建时命中唯一键重复会返回业务失败；批量创建时重复项被跳过。

响应字段

字段	类型	说明
data	object[]	保存后的代理项
data[].id	number	代理 ID，新建时为新生成的主键
data[].userId	number	归属用户 ID，由服务端写入
data[].teamId	number	归属团队 ID，由服务端写入
data[].ipVersion	string	IP 版本
data[].protocol	string	协议
data[].host	string	代理主机
data[].port	number	代理端口
data[].username	string	代理认证用户名
data[].password	string	代理认证密码，按请求原样回显
data[].state	number	状态，未检测为 0

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "id": 6002,
      "userId": 1001,
      "teamId": 2001,
      "ipVersion": "IPv4",
      "protocol": "SOCKS5",
      "host": "198.51.100.24",
      "port": 1080,
      "username": "proxy-user",
      "password": "proxy-password",
      "state": 0
    }
  ]
}

POST/proxy/batch_create

批量创建代理

批量保存代理，items 里的每一项都是一条独立代理。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
items	object[]	必填	代理集合，每项字段同 /proxy/create
items[].protocol	string	必填	协议：SOCKS5、HTTP、HTTPS
items[].host	string	必填	代理主机
items[].port	number	必填	代理端口
items[].username	string	可选	代理认证用户名
items[].password	string	可选	代理认证密码

注意事项

• 与 /proxy/create 的区别只是不会把请求体本身当作单项；集合为空时直接返回成功。
• 兼容旧调用：items 也可写成 proxies 或 proxyList。

响应字段

字段	类型	说明
data	object[]	保存后的代理项集合
data[].id	number	代理 ID
data[].teamId	number	归属团队 ID，由服务端写入
data[].protocol	string	协议
data[].host	string	代理主机
data[].port	number	代理端口
data[].state	number	状态，未检测为 0

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "id": 6003,
      "teamId": 2001,
      "protocol": "SOCKS5",
      "host": "198.51.100.24",
      "port": 1080,
      "state": 0
    },
    {
      "id": 6004,
      "teamId": 2001,
      "protocol": "HTTP",
      "host": "198.51.100.25",
      "port": 8080,
      "state": 0
    }
  ]
}

POST/proxy/import

导入代理

按桌面端「批量导入」相同的行格式解析并保存自定义代理。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
text	string	可选	多行代理文本，与 lines 二选一。格式：protocol://user:pass@host:port {remark}、protocol://host:port:user:pass {remark}、user:pass@host:port、host:port:user:pass。协议仅 HTTP、HTTPS、SOCKS5；省略时默认 SOCKS5。IPv6 主机使用 [address]:port
lines	string[]	可选	与 text 等价的行数组，与 text 二选一

注意事项

• text 与 lines 至少传一个，且去掉空白后不能为空，否则返回参数错误。
• 没有任何可导入行时返回业务失败，并在 data.invalid 中给出逐行原因。
• 响应可能回显 username/password；不要把该响应转发给不受信任的调用方。

响应字段

字段	类型	说明
data.items	object[]	保存成功的代理项，字段同 /proxy/create
data.imported	number	本次写入条数
data.duplicateCount	number	因重复被跳过的行数
data.invalid	object[]	无法识别的行
data.invalid[].error	string	该行失败原因

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "items": [
      {
        "id": 6005,
        "protocol": "SOCKS5",
        "host": "1.2.3.4",
        "port": "1080",
        "remark": "JP"
      }
    ],
    "imported": 1,
    "duplicateCount": 0,
    "invalid": []
  }
}

POST/proxy/detect

检测代理

在客户端本机检测代理的出口 IP 与归属地，与代理中心「检测」相同；支持单个已保存代理、临时地址和批量检测。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
proxyIds	string[] | number[]	可选	批量检测的已保存代理 ID，单次最多 50 个，自动去重；传此字段即走批量模式
proxyId	string | number	可选	单个已保存代理 ID；未传 host 与 port 时必填
host	string	可选	临时检测的代理主机，与 port 一起传入时不读取已保存代理
port	string | number	可选	临时检测的代理端口
protocol	string	可选	临时检测的协议：SOCKS5、HTTP、HTTPS
username	string	可选	临时检测的代理认证用户名
password	string	可选	临时检测的代理认证密码

注意事项

• 检测只在客户端本机执行（临时启动与代理中心相同的 sing-box 中继），不经过服务端检测接口。
• 按已保存代理检测时会像代理中心一样写回结果：成功写入出口信息并把 state 置为 1，失败把 state 置为 -1。临时地址检测不写入任何记录。
• 单个检测失败时返回 code 1，msg 为中文失败原因，data 中带 id、status、code；原始探测报错可能含代理凭据，不会回传。
• 批量检测每 5 个一组并发；请求带 X-Nex-Request-Deadline（毫秒时间戳）时按该期限安排批次，未传按 30 秒估算，期限不足以跑完下一组时剩余代理放入 unchecked。
• proxyIds 为空返回 proxyIds is required，超过 50 个返回 at most 50 proxyIds per request；proxyId 与 host/port 都缺省时返回 proxyId or host and port are required。
• 兼容旧调用：proxyIds 也可写成 ids，proxyId 也可写成 id。

响应字段

字段	类型	说明
data.id	string | number	单个检测：代理 ID，临时地址未传 proxyId 时缺省
data.protocol	string	单个检测：代理协议
data.host	string	单个检测：代理主机
data.port	string | number	单个检测：代理端口
data.status	string	单个检测：成功时固定为 success
data.activeIp	string	检测到的出口 IP，ip、query 与其取值相同
data.country	string	出口国家
data.countryCode	string	出口国家码
data.region	string	出口省/州
data.city	string	出口城市
data.timezone	string	出口时区标识
data.ms	number	检测耗时，毫秒
data.saved	boolean	检测结果是否已写回代理记录；临时地址检测不返回
data.saveMessage	string	写回失败时的原因
data.total	number	批量检测：去重后的请求 ID 数
data.success	number	批量检测：检测成功数
data.failed	number	批量检测：检测失败数
data.notFound	string[]	批量检测：当前团队下找不到的代理 ID
data.unchecked	string[]	批量检测：因请求期限不足本次未检测的代理 ID，可下次再测
data.rows	object[]	批量检测：逐个代理结果，成功行字段同单个检测
data.rows[].status	string	成功为 success，失败为探测状态，如 fail
data.rows[].code	string	失败行的错误码，如 DETECTION_FAILED
data.rows[].message	string	失败行的中文原因

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": 6001,
    "protocol": "SOCKS5",
    "host": "198.51.100.24",
    "port": 1080,
    "status": "success",
    "activeIp": "198.51.100.24",
    "ip": "198.51.100.24",
    "query": "198.51.100.24",
    "country": "United States",
    "countryCode": "US",
    "region": "California",
    "city": "Los Angeles",
    "timezone": "America/Los_Angeles",
    "ms": 820,
    "saved": true
  }
}

POST/proxy/modify

修改代理

把请求体作为单个代理项转发到保存命令，按 id 更新。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
id	number	必填	代理 ID；缺省或 <1 会被当作新建
protocol	string	可选	协议：SOCKS5、HTTP、HTTPS
host	string	可选	代理主机
port	number	可选	代理端口
username	string	可选	代理认证用户名
password	string	可选	代理认证密码
remark	string	可选	备注
state	number	可选	传 1 时服务端同时刷新 activeTime

注意事项

• 代理不属于当前登录团队时该项被静默跳过，响应仍为成功。
• 兼容旧调用：id 也可写成 proxyId。

响应字段

字段	类型	说明
data	object[]	保存后的代理项
data[].id	number	代理 ID
data[].teamId	number	归属团队 ID
data[].host	string	代理主机
data[].port	number	代理端口
data[].remark	string	备注

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "id": 6001,
      "teamId": 2001,
      "host": "198.51.100.24",
      "port": 1080,
      "remark": "已更新"
    }
  ]
}

POST/proxy/delete

删除代理

软删除代理（state 置为 2），并解除窗口对该代理的绑定。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
items	number[]	必填	代理 ID 数组

注意事项

• 非正整数会被丢弃；ID 集合为空或代理不属于当前登录团队时后端直接返回成功且不删除任何数据。
• 兼容旧调用：items 也可写成 proxyIds、proxyId 或 ids，单值同样接受。

响应字段

字段	类型	说明
data	null	无返回数据，成功以 code=0 表示

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": null
}