BlankTrail Proxy
登录 立即开始

API 参考

BlankTrail Proxy 提供了一个本地 HTTP API，让你能够开放端口、配置身份，并自动化控制面板所能完成的一切操作。本页介绍基础 URL、身份验证和约定规范。

基础 URL

所有端点都位于与控制面板相同的主机和端口下的 /api/v1 前缀之下：

http://127.0.0.1:8891/api/v1

API 与控制面板共用同一个源，因此来自你自己的脚本和工具的调用可以开箱即用。

身份验证

该 API 采用默认拒绝策略：几乎每个端点都需要身份验证。有两种身份验证方式：

  • API 密钥 —— 通过 X-API-Key 请求头发送。最适合脚本和自动化。
  • 会话 Cookie —— 通过登录获取；供浏览器控制面板使用。

你可以在控制面板的“设置”对话框中查找和轮换你的 API 密钥。在每个请求上都要发送它：

curl -H "X-API-Key: YOUR_API_KEY" http://127.0.0.1:8891/api/v1/status
重要API 密钥可完全控制你的端口。请对其保密，并限制对控制面板端口的网络访问（绑定到 localhost，或在服务器上使用 SSH 隧道）。

约定规范

  • 请求和响应均为 JSON。对于带有请求体的请求，请发送 Content-Type: application/json。
  • 配置始终在 JSON 请求体中发送，绝不通过查询字符串发送。
  • 该 API 在 /api/v1 下进行版本管理。破坏性变更将迁移到新的版本前缀。

状态码

状态码含义
200 OK成功。
202 Accepted已接受并正在处理（例如，已触发一次更新）。
400 Bad Request输入无效、缺少字段或值有误。
401 Unauthorized需要身份验证，但身份验证信息缺失或无效。
404 Not Found资源不存在（例如，该端口未开放）。
409 Conflict存在冲突 —— 例如端口已开放，或某个网关正在使用中。
429 Too Many Requests已达速率限制；请放慢速度并重试。
500 Internal Server Error发生意外错误。

按主题查阅参考

  • 端口与流量 —— 开放、关闭、列出和配置端口；测试上游代理。
  • 配置文件与路由 —— 身份、预设、域名规则和网关。
  • 端口池 —— 从代理列表开放和管理端口池。
  • 许可证与访问 —— 许可证状态、身份验证以及 CA 证书。