HTTP API

HTTP / 控制 API（2.6.0 PEAK）

现行正式接口文档。源码在 main，安装包见 v2.6.0_PEAK。

历史 2.5.x（control_token + 旧扁平路径）见 Old-HTTP-API。

---

鉴权（双轨）

通道	凭据	配置
GET /get_sl_data、GET /plugins/adapted 等数据口	verify_token	config.yml
/control/*、控制 WS、语音 :8082	API Key	apikey.config（与 config.yml 同目录）

数据口（verify_token）

推荐请求头：

Authorization: Bearer <verify_token>
X-SLDataAPI-Token: <verify_token>
X-SLDataAPI-Verify-Token: <verify_token>

?token= 仍兼容但已弃用（会入访问日志），后续版本将移除。

出厂 / 弱 verify_token（空、默认 your_secret_token、或不满足强度：长度 ≥8 且同时含大写/小写/数字/特殊符号）→ fail-closed：数据口拒绝；若控制面也未启用则不绑定 HTTP 端口。详见 Security-Model。

控制 / 语音（API Key）

Authorization: Bearer <api_key>
X-SLDataAPI-Key: <api_key>

不再接受： control_token、X-Control-Token、控制面 ?key= / ?token= → 401。
config.yml 里若仍写 control_token，启动仅警告后忽略，不作为鉴权。

HTTP	含义
401	Key 缺失 / 错误 / 锁定
403	Key 有效但被拒绝（ACL、远程执行 sldataapi、无权限路径等）
404	control_enabled: false、传输模式互斥、未知路径
405	非 POST
413	body > 64KB
501	已知占位（inventory / dummies）

响应体统一：{ "success", "message", "data" }。

Key 生命周期

sldataapi apikey create <id> <duty|admin> [note]
sldataapi apikey list
sldataapi apikey revoke <id>

• 仅服务器本地控制台可执行；经 /control/console/command 或控制 WS 一律拒绝。
• 落盘只存 SHA-256 指纹；明文写入一次性文件（约 5 分钟自动删），命令输出只回路径。
• 审计 control_log 的 actor 为 Key 的 id。
• 模板 duty / admin 影响默认 ACL（duty 默认不可全量读审计 body）。详见 Configuration。

---

只读数据

curl -s "http://<host>:8081/get_sl_data" \
  -H "Authorization: Bearer YOUR_VERIFY_TOKEN"

# 兼容（已弃用）
curl -s "http://<host>:8081/get_sl_data?token=YOUR_VERIFY_TOKEN"

适配插件发现：GET /plugins/adapted（同数据口鉴权）。快照字段说明可参考 Old-HTTP-API 中「只读数据」一节（字段大体连续；2.6 另含 adapted_plugins 等扩展）。

---

控制端点（POST + JSON）

control_transport: ws 时 HTTP /control/* → 404 + transport_mismatch。

curl -s -X POST "http://<host>:8081/control/map/layout" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

路径一览

分组	路径	备注
Player	/control/player/data · role · effects · inventory	inventory → 501
Moderation	/control/moderation/kick · ban · mute · msg · ban_list · ban/add · ban/revoke
Admin	/control/admin/teleport · state
Broadcast	/control/broadcast · /control/staffchat	已实现；admin 默认开，duty 默认关
Round	/control/round · round/warhead · round/wave
Map	/control/map/facility · layout · export · seed
Other	/control/cassie · /control/dummies	dummies → 501
扩展	/control/console/command · plugins · plugins/slplayer · files/* · logs · reports · audit/list

全服广播

curl -s -X POST "http://<host>:8081/control/broadcast" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"服务器维护通知","duration_seconds":10,"clear_previous":true}'

字段	说明
message	必填，≤500
duration_seconds	可选，默认 5，上限 60
clear_previous	可选 bool

管理聊天（RA AdminChat）

curl -s -X POST "http://<host>:8081/control/staffchat" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"值班备注","is_silent":false}'

字段	说明
message	必填，≤500
is_silent	可选 bool

---

自 2.5 升级：路径对照

2.5	2.6.0 PEAK
/control/command	/control/console/command
/control/player/kick 等	/control/moderation/...
/control/player/teleport	/control/admin/teleport
/control/player/effect	/control/player/effects
/control/player/state	/control/admin/state
/control/map（混用）	map/facility（写）+ layout / export / seed（读）
/control/warhead / wave	/control/round/warhead / wave
/control/ban_*	/control/moderation/ban_*
/control/slplayer	/control/plugins/slplayer

无兼容别名；旧 path → 404 或 403。

---

语音口（8082）

鉴权同控制面（Bearer / X-SLDataAPI-Key）。不要在 URL 带 key。

路径	说明
GET /ws（升级 WS）	语音流
GET /status	说话状态

帧格式见 Voice-Forwarding。可选 WebDAV 定稿 zip（仅 https://）见 Configuration。

---

迁移清单

1. 设置强 verify_token；数据口改用请求头，少用 ?token=
2. 控制 / 语音 / 控制 WS：改用 API Key 头；删除 X-Control-Token / control_token
3. 按上表改 path；broadcast / staffchat 已可用
4. 按需要创建多把 Key（duty / admin）
5. 丢失 Key：本地 revoke + create（无法找回明文）