代理资源

自建与已购代理的列表、详情、创建、批量创建、按桌面端行格式导入、连通性检测，以及修改和删除。数组型查询参数按 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[]= 形式无效

注意事项

• 已删除代理（state=2）始终被排除；响应包含明文代理密码。

响应字段

字段	类型	说明
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 已过期、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 已过期、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 已过期、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 已过期、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

检测代理

服务端尚未提供该能力，调用固定返回 code -1000，接入方暂时不要依赖本接口。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
透传业务参数	object	可选	原样转发给后端检测命令

注意事项

• 实测返回 {"code":-1000,"msg":"接口不存在或未注册"}。
• 代理可用性可改看 /proxy/list 条目的 state 与 activeTime 字段。

响应字段

字段	类型	说明
code	number	当前固定为 -1000
msg	string	当前固定为 "接口不存在或未注册"
data	null	固定为 null

响应示例

{
  "code": -1000,
  "msg": "接口不存在或未注册",
  "data": null
}

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
}