Skip to content

Preview HTTP API

Jump to bottom
Cursor Agent edited this page Sep 18, 2026 · 2 revisions

Preview HTTP API（v2.6.0-preview-DevOnly）

分支 preview/v2.6.0-DevOnly / 标签 v2.6.0-preview-DevOnly。
稳定 main（2.5.x）见 HTTP-API（control_token + 旧路径）。

鉴权（双轨）

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

请求头（二选一）：

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

已废弃（控制/语音）： control_token、X-Control-Token、?key=、?token= → 401。

HTTP 含义
401 Key 缺失/错误/锁定
403 Key 有效但 ACL 拒绝（含旧路径、未授权端点、远程执行 sldataapi）
404 control_enabled: false、传输模式互斥、未知路径
405 非 POST
413 body > 64KB

响应体仍为 {success, message, data}。

Key 生命周期

sldataapi apikey create <id> <duty|admin> [note]   # 明文仅此时输出
sldataapi apikey list
sldataapi apikey revoke <id>
  • create / revoke：仅服务器本地可执行；经 /control/console/command 或控制 WS 403。
  • 确认：LocalAdmin 整屏面板（Y/N，默认取消，api_key_confirm_timeout_seconds 超时=拒绝）。
  • 落盘：仅 SHA-256 指纹（sha256:…），丢失明文只能 revoke 后重建。
  • 审计 control_log 的 actor 为 Key 的 id。

模板与 ACL

  • duty：玩家/地图/回合只读、日志与审计列表、ws:subscribe_events；默认无 moderation、admin、console、plugins、files、voice、cassie 等。
  • admin：按 endpoint_catalog 展开；条目为 true 的授予，false 不自动授予（即使 all_control_true）：
    • /control/console/、/control/plugins、/control/files/ 等为 false
    • 需对单把 Key 在 keys[].endpoints_override 显式放开
  • 匹配规则：最长前缀；键以 / 结尾表示前缀；值可为 true/false 或 {read, write}。
  • 非 HTTP 能力键：voice:/ws、voice:/status、ws:subscribe_events。

apikey.config 结构见 Configuration#apikeyconfig预览-26。

只读数据（不变）

curl -s "http://<host>:8081/get_sl_data?token=YOUR_VERIFY_TOKEN"

字段与刷新机制同 HTTP-API#只读数据接口。

控制端点（POST + JSON）

control_transport: ws 时 HTTP /control/* → 404 + transport_mismatch（与 2.5 相同）。

鉴权示例：

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 原 /control/player/* 部分
Admin /control/admin/teleport · state 原 player/teleport · player/state
Broadcast /control/broadcast · staffchat 501
Round /control/round · round/warhead · round/wave 原 warhead · wave
Map /control/map/facility · layout · export · seed 原 map 动作拆到 facility + 只读子路径
Other /control/cassie · /control/dummies dummies → 501
扩展 /control/console/command · plugins · plugins/slplayer · files/* · logs · reports · audit/list 原 command · slplayer · ban_*

请求体字段与 2.5 对应端点相同，仅 path 变更。完整 curl 见 HTTP-API，将路径与鉴权头替换即可。

示例（控制台）：

curl -s -X POST "http://<host>:8081/control/console/command" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command":"help"}'

示例（踢人）：

curl -s -X POST "http://<host>:8081/control/moderation/kick" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":"PlayerName","reason":"违规"}'

2.5 → 2.6 路径对照

2.5 2.6
/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 在鉴权通过后多被 ACL 判为 403。

语音口（8082）

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

路径 ACL
GET /ws（升级 WS） voice:/ws
GET /status voice:/status

帧格式见 Voice-Forwarding。

迁移清单

  1. 监控/机器人只读：继续 verify_token + /get_sl_data
  2. 控制客户端：改用 API Key 请求头；删除 X-Control-Token
  3. 按上表改 path
  4. 为不同职责创建多把 Key（duty vs admin + override）
  5. 丢失 Key：本地 revoke + create，无法从服务器导出明文

Clone this wiki locally