Skip to content

Preview HTTP API

Jump to bottom
DNTOF edited this page Sep 5, 2026 · 1 revision

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

仅适用于 preview 线：分支 preview/v2.6.0-DevOnly / 预发布包 v2.6.0-preview-DevOnly。
生产向稳定版仍以 HTTP-API + Security-Model（control_token）为准。
正式 2.6.0 计划 11 月合入 main 后再改主文档。

本页描述 preview 的双轨鉴权与按原版 RA 面板重对齐后的控制路径。

鉴权（双轨）

通道 鉴权 配置
GET /get_sl_data 保持 2.5：verify_token（?token=） config.yml
/control/*、控制 WS、语音口 API Key 独立文件 apikey.config

控制面请求头（二选一）：

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

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

API Key 生命周期

  • 游戏内 / LocalAdmin：sldataapi apikey create <id> <duty|admin> [note...]
    明文只显示一次；落盘仅为指纹（SHA-256）。
  • sldataapi apikey list：只显示 id / 模板 / 时间 / note
  • sldataapi apikey revoke <id>：吊销；丢失只能重建
  • 默认模板：
    • duty：只读信息（含地图 layout/export/seed 等只读）；不含 teleport / moderation / console / voice（默认可改 override）
    • admin：控制面 catalog 全开
  • 单 Key 可用 endpoints_override 按 path / 前缀细调（最长前缀优先；可 {read,write}）

审计写操作里 actor = Key 的 id（不是明文）。

冒烟脚本（DevKit）：scripts/Test-ControlEndpoints.ps1（只打自有服务器）。

只读数据口（不变）

GET /get_sl_data?token=<verify_token>

与稳定版相同。AstrBot 等只读客户端不必为 preview 改鉴权。

curl -s "http://<服务器IP>:8081/get_sl_data?token=YOUR_VERIFY_TOKEN"

控制接口（preview 路径）

全部：仅 POST，JSON body，响应 {success,message,data}。
control_transport: ws 时 HTTP /control/* 仍返回 404 + transport_mismatch（与稳定版相同互斥）。

鉴权示例：

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

PLAYER

路径 说明
/control/player/data Request Data / 档案类查询
/control/player/role 强制角色
/control/player/effects 状态效果（原 /control/player/effect）
/control/player/inventory 501 占位

SERVER · Moderation

路径 说明
/control/moderation/kick 踢出（原 /control/player/kick）
/control/moderation/ban 封禁
/control/moderation/mute 禁言
/control/moderation/msg 私聊 hint
/control/moderation/ban_list 封禁列表
/control/moderation/ban/add 添加封禁
/control/moderation/ban/revoke 解除封禁

SERVER · Administration

路径 说明
/control/admin/teleport 传送（原 /control/player/teleport；不属于 Map）
/control/admin/state 状态查询/设置（原 /control/player/state）

SERVER · Broadcasting / Staff Chat

路径 说明
/control/broadcast 501 占位
/control/staffchat 501 占位

GAME · Round / Dummies / Map / CASSIE

路径 说明
/control/round 回合
/control/round/warhead 核弹（原 /control/warhead）
/control/round/wave 波次（原 /control/wave）
/control/dummies 501 占位
/control/map/facility 门/梯/灯（原 /control/map 的控制动作）
/control/map/layout 布局只读
/control/map/export 导出只读
/control/map/seed 种子
/control/cassie CASSIE

扩展（非 RA 页）

路径 说明
/control/console/command 控制台命令（原 /control/command）
/control/plugins 插件管理
/control/plugins/slplayer SLPlayer（原 /control/slplayer）
`/control/files/list read
/control/logs 日志
/control/reports 举报
/control/audit/list 控制审计列表

语音口仍为独立端口（默认 8082）；鉴权改为 API Key，ACL 键名 voice:/ws、voice:/status。WS 事件订阅 ACL：ws:subscribe_events。

旧路径对照（无兼容别名）

旧（2.5） 新（preview 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 /control/map/facility（控制）+ layout/seed/export
/control/warhead / wave /control/round/warhead / wave
/control/ban_* /control/moderation/ban_*
/control/slplayer /control/plugins/slplayer

未登记在 catalog 中的旧 path：鉴权通过后常先被 ACL 拦成 403（不是稳定版语义下的业务 404）。

第三方迁移清单

  1. 只读监控：继续 verify_token + /get_sl_data
  2. 控制台 / 机器人：换 Bearer Key；删掉 X-Control-Token
  3. 按上表改 path
  4. duty Key 不能踢人/传送/跑控制台——是设计如此
  5. 丢失 Key 只能 revoke + create

更细的联调说明见对应 Pre-release 说明与 DevKit；契约讨论以本 wiki 页 + preview 分支代码为准。

Clone this wiki locally