Skip to content

API 参考

wxh1024 edited this page Oct 17, 2026 · 2 revisions

所有接口都在同一个 HTTP 服务上,无需额外前缀。响应体统一由 Gson 序列化,Content-Type: application/json; charset=utf-8(SSE 例外)。所有响应都带 Access-Control-Allow-Origin: *。

认证方式

两种任选:

  1. Cookie(浏览器默认):登录后服务端下发 webui_token=<uuid>; Path=/; HttpOnly; SameSite=Lax; Max-Age=86400;
  2. Bearer:Authorization: Bearer <token>。

除 public 路径外,/api/* 都需要认证;静态文件不需要。未认证时:

  • /api/* → 401 + {"error":"Authentication required"};
  • 其它路径 → 302 跳转 /login.html。

成功认证后,同一 TCP 连接上的后续请求会走 30 秒通道级缓存,不再重复校验 token(登出会通过 epoch 立即失效,见 认证与安全)。

端点总表

端点 方法 认证 作用
/api/auth/login POST 否 登录,下发 Cookie
/api/auth/logout POST 否 登出,清 Cookie 并吊销 token
/api/auth/status GET 否 查询当前登录状态
/api/dashboard GET 是 一次拿到全部仪表盘数据
/api/dashboard/stream GET (SSE) 是 每秒推送一帧仪表盘数据
/api/commands GET 是 列出可用命令
/api/commands POST 是 执行一条命令
/api/logs/stream GET (SSE) 是 回放最近 500 条日志 + 实时推送
/api/whitelist GET 是 白名单状态与列表
/api/whitelist POST 是 白名单增删改

通用错误:未知 /api/* 路径返回 404(纯文本 404 Not Found,不会回落到前端 index);/api/commands、/api/whitelist 收到不支持的方法返回 405;处理器内部异常返回 {"error":"Internal server error"}。


POST /api/auth/login

请求:

{ "username": "admin", "password": "3f9c1a7b2d8e4056" }

成功 200:

{ "success": true, "username": "admin" }

同时下发 Set-Cookie: webui_token=...。token 不会出现在响应体里,只能通过 Cookie 使用。

失败:

状态码 响应
400 {"success":false,"error":"Missing username or password"}
401 {"success":false,"error":"Invalid username or password"}(含被限流的情况)
500 {"success":false,"error":"Login failed"}

POST /api/auth/logout

{ "success": true }

同时下发过期 Cookie(Max-Age=0)并吊销服务端 token,该 token 关联的 SSE 连接会被立即关闭。

GET /api/auth/status

已登录 200:

{ "authenticated": true, "username": "admin" }

未登录 401:

{ "authenticated": false }

GET /api/dashboard

返回聚合后的仪表盘快照(离线时 player.health / player.food 是显式 null,不是缺字段):

{
  "connected": true,
  "inQueue": false,
  "queuePosition": -1,
  "queueOnlinePlayers": 0,
  "queuePos": "",
  "version": "1.21.4",
  "viaVersion": "via 1.21.4",
  "username": "MyBot",
  "proxyAddress": "3c3u.org:25565",
  "uptime": 3725000,
  "system": {
    "cpuLoad": 0.42,
    "memoryPercent": 18.75,
    "netBytesPerSecIn": 2048.5,
    "netBytesPerSecOut": 512.0
  },
  "latency": {
    "botLatency": 43,
    "players": [ { "name": "Steve", "ping": 51 } ]
  },
  "player": {
    "connected": true,
    "health": 20.0,
    "food": 20
  }
}

字段说明:

字段 说明
inQueue / queuePosition / queueOnlinePlayers / queuePos 队列状态,仅 3C 网络有意义;无数据时分别为 false / -1 / 0 / ""
uptime 毫秒,负数会被钳制为 0
system.cpuLoad 系统负载均值;不可用时 -1
system.netBytesPerSec* 仅 Linux 有值(读 /proc/net/dev),其它平台为 0
latency.botLatency 未连接时 -1
player.health float,离线 null

GET /api/dashboard/stream

响应头:Content-Type: text/event-stream、Cache-Control: no-cache、Connection: keep-alive。

每 1 秒一帧,内容与 /api/dashboard 完全一致:

data: {"connected":true,...}

没有客户端时后台任务直接跳过,不做无用序列化。token 在建立连接时校验一次,之后由登出/改密事件驱动断开。

GET /api/commands

返回 ZenithProxy 已注册的命令数组,字段按需出现:

[
  { "name": "connect", "description": "Connect to the server" },
  { "name": "whitelist", "description": "...", "aliases": ["wl"] }
]

POST /api/commands

请求:

{ "command": "connect" }

成功 200:

{ "success": true, "output": ["正在连接服务器..."] }

output 是把命令返回的 Embed(title、description、fields)和 multiline output 拍平后的字符串数组,顺序即展示顺序。

失败(仍是 200,靠 success 判断):

{ "success": false, "error": "Empty command" }

命令等价于在控制台输入,来源标记为 TERMINAL,权限与主程序命令一致。

GET /api/logs/stream

响应头同仪表盘流。连接建立后:

  1. 先回放缓冲区里最近最多 500 条日志(每帧一条 data:);
  2. 之后实时推送新日志。

帧格式(LogEntry):

data: {"level":"INFO","logger":"Proxy","message":"已上线 / Now online","timestamp":1744800000000,"id":42}

标题包会额外推一个不同类型:

data: {"type":"title","text":"欢迎来到服务器"}

日志超过 500 条时从最旧的开始丢弃;多个客户端共享同一份缓冲区,互不影响。

GET /api/whitelist

{
  "enabled": true,
  "kickmsg": "You are not whitelisted",
  "autoAddClient": true,
  "whitelist": [
    { "username": "Steve", "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5" }
  ]
}

POST /api/whitelist

四种 action:

{ "action": "toggle", "enabled": false }
{ "action": "add", "username": "Steve" }
{ "action": "remove", "username": "Steve" }
{ "action": "updateConfig", "kickmsg": "no whitelist?", "autoAddClient": false }

响应示例:

{ "success": true, "username": "Steve", "uuid": "069a79f4-..." }
{ "success": true, "enabled": false }
{ "success": true }

常见错误:

响应 触发条件
{"success":false,"error":"Empty request body"} 请求体为空
{"success":false,"error":"Missing action field"} 没有 action
{"success":false,"error":"Unknown action: xxx"} 未知 action
{"success":false,"error":"无法解析用户名 / Could not resolve username"} add 时用户名无法解析 UUID
{"success":false,"error":"Whitelist operation failed"} 内部异常

updateConfig 只更新请求里出现的字段,未出现的不动。


curl 速查

# 登录并把 Cookie 存到 jar
curl -c cookies.txt -H 'Content-Type: application/json' \
     -d '{"username":"admin","password":"你的密码"}' \
     http://localhost:8080/api/auth/login

# 带 Cookie 调接口
curl -b cookies.txt http://localhost:8080/api/dashboard | jq

# 执行命令
curl -b cookies.txt -H 'Content-Type: application/json' \
     -d '{"command":"status"}' \
     http://localhost:8080/api/commands

# 跟日志流(Ctrl+C 退出)
curl -N -b cookies.txt http://localhost:8080/api/logs/stream

# 用 Bearer:token 只能从浏览器 Cookie 里取,或自己改造登录响应
curl -H 'Authorization: Bearer <token>' http://localhost:8080/api/dashboard

curl -N 关闭缓冲,否则 SSE 会被本地缓冲住看不到实时输出。

Clone this wiki locally