API 参考

当前的日志级别。

curl -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/log_level

{
  "level": "info"
}

在排查期间提高详细度：debug 会写入明显更多内容，并持续到下次重启。

{ "level": "debug" }

curl -X PUT -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"level":"debug"}' \
  http://127.0.0.1:8891/api/v1/log_level

{
  "level": "debug"
}

• 其他取值一律返回 400 “level must be one of: debug, info, warn, error”。

已安装的版本以及是否有新版本：没有更新时 available 为空；state 显示更新器当前的状态。

curl -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/update/status

{
  "current": "1.3.2",
  "available": "",
  "state": "idle",
  "last_error": "",
  "download_url": ""
}

• 在未包含自更新的构建中返回 404 “self-update not available”。

安装 /update/status 所报告的更新。应用会自行重启。

curl -X POST -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/update

{
  "status": "started"
}

• 🔴 响应为 202 Accepted 而不是 200：更新已被接受并在后台执行，并非在响应返回时已经完成。请通过轮询 /update/status 等待其结束。
• 若没有可安装的更新，返回 409 “no update available”；在未包含自更新的构建中返回 404 “self-update not available”。

简单路由规则：一组域名以及它们共用的出口代理。列表为空表示该规则关闭。带名称的详细规则位于 /domain_rules。

curl -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/domain_routing

{
  "domains": ["example.com", "*.example.net"],
  "proxy": "socks5://203.0.113.10:1080"
}

整体设置简单规则：域名与代理。域名列表为空即关闭该规则。

{ "domains": ["example.com"], "proxy": "socks5://203.0.113.10:1080" }

curl -X PUT -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"domains":["example.com"],"proxy":"socks5://203.0.113.10:1080"}' \
  http://127.0.0.1:8891/api/v1/domain_routing

{
  "domains": ["example.com"],
  "proxy": "socks5://203.0.113.10:1080"
}

• 若域名或代理地址格式有误，返回 400 并附说明。

适用于没有自身设置的端口的全局空闲超时。0 表示不关闭。

{ "seconds": 1800 }

curl -X PUT -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"seconds":1800}' \
  http://127.0.0.1:8891/api/v1/idle_timeout

{
  "idle_timeout_seconds": 1800
}

• 取负值时返回 400 “seconds must be >= 0”。设置了自身覆盖值的端口（PUT /api/v1/port/{port}/idle）不会采用该值。

报告发送是否已启用，以及上次运行是否非正常退出——若是，控制面板会主动提示发送报告。

curl -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/bug-report/status

{
  "enabled": true,
  "unclean_previous_exit": false
}

• enabled=false 表示在没有有效许可的情况下无法发送。

生成报告并展示，但不发送任何内容。

curl -X POST -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/bug-report/preview

{
  "report": { "version": 1, "ports": [ … ], "log": [ … ] },
  "notes_included": false
}

• 若报告收集功能未接入，返回 404 “bug report not available”；500 “failed to build report”。

把报告连同您的描述一起发送给支持团队。

{ "description": "更换出口后端口不再返回 200" }

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"description":"port stopped returning 200 after an egress change"}' \
  http://127.0.0.1:8891/api/v1/bug-report/send

{
  "status": "sent",
  "bug_report_id": "br-7f3a1c9d"
}

• 未填写描述时返回 400 “description required”；403 “activate your license to send a bug report”；404 “bug report not available”；发送过于频繁时返回 429；若支持服务器不可达，返回 502。
• 请求体上限为 64 KiB。

拒绝所提示的报告：在本次运行剩余时间内不再显示非正常退出提示。

curl -X POST -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/bug-report/dismiss

{
  "status": "dismissed"
}

• 该标记仅存于内存：若下次运行确实再次非正常退出，它会被重新置位。

进程自身的快照：goroutine、系统线程、句柄、内存与运行时间。若应用变得沉重，这是首先应附上的内容。

curl -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/debug

{
  "goroutines": 142,
  "threads": 21,
  "handles": 380,
  "open_ports": 2,
  "uptime": "3h14m22s",
  "memory": {
    "alloc_mb": 96,
    "total_alloc_mb": 8140,
    "sys_mb": 310,
    "heap_objects": 410000,
    "heap_inuse_mb": 120,
    "heap_released_mb": 64,
    "gc_cycles": 1830,
    "stack_inuse_mb": 6
  }
}

• handles 字段始终存在，但只在 Windows 上有意义：该数值由系统自身统计；在其他平台上它恒为 0。

报告当前是否在资源包特征库之上叠加了调试特征层，以及其中有多少条目。

curl -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/debug/signatures

{
  "debug_active": true,
  "debug_vendors": 3
}

• 若已设置开关但该构建未接入解题器钩子，返回 503 “solver debug hooks not wired”。这不是 404：路由本身存在，区分这两种状态很重要。

把所提交的特征集合作为独立层叠加到资源包特征库之上——无需重建资源包、签名或发布。

{ "Version": 7, "Vendors": [ { "…": "…" } ], "NavHints": [ ] }

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  --data-binary @signatures.json \
  http://127.0.0.1:8891/api/v1/debug/signatures

{
  "installed": 3,
  "dropped": 1
}

• 请求体是与资源包相同格式的特征库。installed 表示被接受的厂商数量，dropped 表示所提交条件中被丢弃的数量。
• 该层可经受任意次数的资源包更新，只有显式 DELETE 才会移除。安装动作会以警告写入日志——被遗忘的层不应无声无息地留存。
• 503 “solver debug hooks not wired”；400 “invalid JSON body”。

移除调试特征层，让解题器回到资源包特征库。

curl -X DELETE -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/debug/signatures

{
  "cleared": true
}

• 若未接入钩子，返回 503 “solver debug hooks not wired”。

让解题器经由指定端口访问给定地址，并返回它在那里看到的内容——无论特征是否匹配。

{ "url": "https://example.com/", "solve": true }

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -H "Accept-Language: ru-RU,ru;q=0.9" \
  -d '{"url":"https://example.com/","solve":true}' \
  http://127.0.0.1:8891/api/v1/port/20134/solve_probe

• 🔴 当 solve=true 时，此处刻意不设人为超时：强制求解确实需要数十秒，某些验证甚至长达一分半。请求并没有卡死。
• 该请求的 Accept-Language 头会被原样传入任务：启动语言会影响结果，若不传入，求解就会带着出口节点的语言而非所请求的语言。
• 503 “solver debug hooks not wired”；400 “url is required”；若访问本身失败，返回 502 并附带错误文本。