Repository navigation
API 参考
所有接口都在同一个 HTTP 服务上,无需额外前缀。响应体统一由 Gson 序列化,Content-Type: application/json; charset=utf-8(SSE 例外)。所有响应都带 Access-Control-Allow-Origin: *。
两种任选:
-
Cookie(浏览器默认):登录后服务端下发
webui_token=<uuid>; Path=/; HttpOnly; SameSite=Lax; Max-Age=86400; -
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"}。
请求:
{ "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"} |
{ "success": true }同时下发过期 Cookie(Max-Age=0)并吊销服务端 token,该 token 关联的 SSE 连接会被立即关闭。
已登录 200:
{ "authenticated": true, "username": "admin" }未登录 401:
{ "authenticated": false }返回聚合后的仪表盘快照(离线时 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
|
响应头:Content-Type: text/event-stream、Cache-Control: no-cache、Connection: keep-alive。
每 1 秒一帧,内容与 /api/dashboard 完全一致:
data: {"connected":true,...}
没有客户端时后台任务直接跳过,不做无用序列化。token 在建立连接时校验一次,之后由登出/改密事件驱动断开。
返回 ZenithProxy 已注册的命令数组,字段按需出现:
[
{ "name": "connect", "description": "Connect to the server" },
{ "name": "whitelist", "description": "...", "aliases": ["wl"] }
]请求:
{ "command": "connect" }成功 200:
{ "success": true, "output": ["正在连接服务器..."] }output 是把命令返回的 Embed(title、description、fields)和 multiline output 拍平后的字符串数组,顺序即展示顺序。
失败(仍是 200,靠 success 判断):
{ "success": false, "error": "Empty command" }命令等价于在控制台输入,来源标记为 TERMINAL,权限与主程序命令一致。
响应头同仪表盘流。连接建立后:
- 先回放缓冲区里最近最多 500 条日志(每帧一条
data:); - 之后实时推送新日志。
帧格式(LogEntry):
data: {"level":"INFO","logger":"Proxy","message":"已上线 / Now online","timestamp":1744800000000,"id":42}
标题包会额外推一个不同类型:
data: {"type":"title","text":"欢迎来到服务器"}
日志超过 500 条时从最旧的开始丢弃;多个客户端共享同一份缓冲区,互不影响。
{
"enabled": true,
"kickmsg": "You are not whitelisted",
"autoAddClient": true,
"whitelist": [
{ "username": "Steve", "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5" }
]
}四种 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 只更新请求里出现的字段,未出现的不动。
# 登录并把 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 会被本地缓冲住看不到实时输出。
ZenithProxy Web UI · 以 AGPL-3.0-or-later 开源 · 源码 · 问题反馈