SLDataAPI

把你的 SCP:SL 服务器变成一个可编程的平台

LabAPI 原生插件 · 数据查询 · 远程控制 · 实时事件流 · 语音转发与录音取证

快速开始 · 功能一览 · 配置 · 鉴权与安全 · 接口 · Wiki · Q&A

SLDataAPI 架构总览：SCP:SL 服务器（LabAPI）→ SLDataAPI 核心（数据快照、远程控制、事件流、语音转发、录音取证、审计日志）→ :8081 HTTP / WS、:8082 语音 WS，同端口可选自签 TLS → SLConsole、Foundation Console、AstrBot 与自定义集成

40+	19	48 kHz	1	180+
控制端点	实时事件类型	全频道语音转发	端口同时承载 HTTP / WS / TLS	自动化回归用例

✨ 为什么选择 SLDataAPI

📊 数据一手掌握一个请求拿到人数、回合、核弹、玩家 SteamID 与坐标、游戏版本、当前节日，机器人和面板直接用。	🎮 远程全面掌控玩家、物品栏、回合、地图、CASSIE、封禁、控制台、文件……40+ 端点覆盖日常运维，HTTP 或 WebSocket 任选。	⚡ 事件实时推送回合、进出、死亡、逃脱、核弹、重生波次、SCP 收容……19 种游戏事件经 WebSocket 实时推送。
🎙️ 语音转发与取证全频道 48 kHz PCM 实时转发；分轨 WAV + 时间轴 TSV 按局归档，可自动上传到 WebDAV。	🔐 安全默认开启 API Key 分级授权、仅存指纹；弱口令 fail-closed；同端口自签 TLS + 指纹固定；侵入性操作全程审计。	🧩 开放可扩展其它插件可注册为「适配插件」，通过 SLDataAPI 对外暴露状态与操作，无需自建 HTTP 服务。

📦 功能一览

模块	能力
数据查询	`GET /get_sl_data`：人数、回合、核弹、玩家（SteamID / 坐标）、`game_version` / `active_holiday`、DNT_OF 插件状态；`GET /plugins/adapted` 发现适配插件
控制面	`/control/*`：玩家 / 物品栏 / 管理 / 回合 / 地图（设施状态快照、灯光颜色、布局导出）/ CASSIE / 全服广播 / 管理聊天 / 控制台 / 插件 / 文件 / 日志 / 举报 / 假人；`/control/player/data` 含生命、护盾、体力、物品、弹药、当前效果与 TemporaryBypass 开门权限
事件流	控制 WS 订阅：回合开始 / 结束、进出、死亡、角色变化、逃脱、封禁 / 踢出、重生波次、核弹、去污、发电机、SCP 收容播报、举报等
节日玩法	万圣节糖果 / 棉花糖人 / 节日物品：跟随游戏当前节日自动启用，未开启时返回结构化 `409 holiday_inactive`，无需改代码
语音转发	独立端口 WebSocket，全频道 48 kHz PCM（SPY）
语音录音	分轨 WAV + 时间轴 TSV，按局保留；可选 WebDAV（仅 https）自动上传定稿 zip
举报	Esc 服务器设置面板 + `/control/reports`（默认关）
审计	侵入性控制操作写入 `control_log.json`（默认开）
自动更新	启动时 + 每 72 小时静默检查 GitHub Releases；仅安装经强名称验签的正式包

🚀 快速开始

1. 准备依赖

插件运行时需要两个程序集，放入所有端口共享的全局依赖目录：

%AppData%/SCP Secret Laboratory/LabAPI/dependencies/global/0Harmony.dll
%AppData%/SCP Secret Laboratory/LabAPI/dependencies/global/Newtonsoft.Json.dll

依赖	版本	获取	缺失现象
`0Harmony.dll`	2.3.x（建议与 LabAPI 自带一致）	Harmony Releases（选 net472）	插件加载失败 / 事件补丁不生效
`Newtonsoft.Json.dll`	13.0.x（程序集版本 13.0.0.0）	NuGet	插件加载失败 / 启动即崩

2. 安装插件

从 最新 Release 下载 SLDataAPI.dll（或自行构建，见 Building）
放入 %AppData%/SCP Secret Laboratory/LabAPI/plugins/global/
启动服务器，自动生成配置文件

3. 完成初始化

把 verify_token 改成强随机值，然后重启
需要控制面时，在本地控制台执行 sldataapi apikey create <id> admin（或 duty）
防火墙按需放行 http_port（启用语音时还有 voice_port）

4. 发出第一个请求

curl -H "Authorization: Bearer <verify_token>" http://<host>:8081/get_sl_data

Tip

升级前请备份 config.yml 与 apikey.config。从旧版 control_token 鉴权升级时，控制端需改用 API Key，路径改为 RA 对齐分组，对照表见 Wiki HTTP-API。

🔧 配置

路径：LabAPI/configs/<端口或 global>/SLDataAPI/config.yml（键名 snake_case）。

展开查看常用配置项

debug: false
language: "zh-CN"                   # zh-CN（默认）| en：接口文本语言；zh-CN 下既有输出逐字不变
verify_token: "your_secret_token"   # 必须改成强随机值；默认/弱口令会 fail-closed 关闭数据口
http_port: 8081
push_interval_seconds: 8
tls_mode: optional                  # off | optional | required：同端口自签 TLS

control_enabled: false              # 关则所有 /control/* → 404
control_transport: http             # http | ws（硬互斥）
# control_token 已废弃：写了也会被忽略并警告

auto_update_check: true             # 启动 + 默认 72h 静默复查 GitHub Releases
auto_update_install: true           # 仅稳定正式包；入站须正式强签名验签；未签名当前可引导升级
# auto_update_check_interval_hours: 72

voice_enabled: false
voice_port: 8082
voice_record_enabled: false

webdav_upload_enabled: false        # 定稿 zip 自动上传（默认关）
webdav_url: ""                      # 仅 https:// 目录 URL，或含 {filename} 的模板
webdav_username: ""
webdav_password: ""

report_enabled: false
control_log_enabled: true
# apikey_copy_to_clipboard: false   # Windows 创建 Key 后是否复制剪贴板（默认关）

完整字段、YAML 常见坑、token 写法见 Wiki Configuration。

多语言与稳定 code / Language & stable codes

language："zh-CN"（默认）或 "en"。非法值回退 zh-CN 并在启动日志告警。仅影响插件生成的 HTTP / WebSocket 文本；玩家昵称、控制台回显、封禁 / 踢出 / 解封原因等外部内容原样透传。
稳定 code 与语言无关（language 切换时值不变）。错误文本经 Localization.T/F 生成时，en 结果会在有界缓存中记录“英文结果 → 中文结果”映射；error.code 推断先还原成中文文本，再复用 zh-CN 的同一套规则，zh-CN 路径与既有结果完全一致：
- role_code：RoleTypeId 枚举成员名（如 Spectator / Tutorial / NtfCaptain）
- team_code：Team 枚举成员名（如 ClassD / ChaosInsurgency / FoundationForces / SCPs / Dead / OtherAlive）
- phase_code：waiting / in_progress / ended
- warhead_code：inactive / armed / detonating / detonated
- error.code（控制面错误对象的 code 字段）：snake_case，至少包含 timeout / symlink_forbidden / unauthorized / forbidden / not_found / invalid_argument
所有插件生成的 JSON 根对象新增 lang（"zh-CN" / "en"）。新字段只追加在既有字段之后。
English: set language: "en" to switch plugin-generated HTTP/WebSocket text to English. Stable codes and lang do not change with language; player nicknames, console output, and ban/kick/revoke reasons are passed through unchanged.

🔐 鉴权与安全

通道	凭据	存放位置
`GET /get_sl_data`、`GET /plugins/adapted`	`verify_token`（`Authorization: Bearer` / `X-SLDataAPI-Token`；`?token=` 兼容但已弃用）	`config.yml`
`/control/*`、控制 WS、语音口	API Key	`apikey.config`（同配置目录，仅存指纹）

控制面请求头（二选一）。X-Control-Token、控制面 URL 中的 ?token= / ?key= 均不再接受。

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

API Key 管理

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

仅限本地控制台（LocalAdmin）：RemoteAdmin 与远程控制通道一律拒绝（与 cert 一致）；sldataapi / slda 经 /control/console/command（HTTP 与 WS）同样拒绝。
一次性交付：create 成功后明文写入配置目录的 apikey_once_<id>.txt，命令只返回文件路径，不回显密钥；文件约 5 分钟后自动删除，请尽快存入密码管理器。
不可找回：丢失明文只能 revoke 后重新 create。
分级授权：duty 偏只读，默认不授予 /control/audit/list、广播、管理聊天；admin 按端点目录授权，控制台 / 插件 / 文件等需通过 endpoints_override 单独放开。
权限插件收窄 RemoteAdmin 时，仍建议同时拒绝 sldataapi / slda 的其它子命令。

同端口自签 TLS

`tls_mode`	行为
`optional`（默认）	主端口与语音端口同端口同时接受 TLS 与明文：首字节为 TLS 握手（`0x16`）走 TLS 1.2，否则按明文处理
`required`	明文 HTTP、明文控制 WS / 语音 WS 一律返回 `426`，`data.code = "tls_required"`
`off`	不生成 / 加载证书，行为与旧版一致

首次启动在配置目录生成 sld_tls.pfx 与随机口令文件 sld_tls.pwd（RSA-2048 / SHA-256 / 约 10 年，CN=SLDataAPI）。Windows 上文件权限暂未收紧，请自行限制配置目录访问。
启动日志打印 TLS: <mode>, SHA-256 <指纹>，客户端应固定（pin）该指纹，而不是信任 CA。
控制 WS 与语音 WS 的 hello 消息带有 tls（本连接是否加密）与 cert_fingerprint（tls_mode: off 时为 null）。

sldataapi cert show     # 查看模式 / 指纹 / 有效期
sldataapi cert regen    # 重新生成并热替换（仅对新连接生效；已 pin 的客户端须重新确认指纹）

cert 子命令同样仅限本地控制台，regen 会写入控制审计日志。

🔌 接口速览

类型	地址
数据	`GET http://<host>:8081/get_sl_data` + `Authorization: Bearer <verify_token>`
控制 HTTP	`POST http://<host>:8081/control/...` + API Key 头
控制 WS	`ws://<host>:8081/control` + 握手 API Key 头（`control_transport: ws`）
语音	`ws://<host>:8082/ws` · `GET :8082/status` + API Key
TLS	以上均可同端口改用 `https://` / `wss://`（`tls_mode` 非 `off`；自签证书，按指纹固定）

示例：全服广播

POST /control/broadcast
Authorization: Bearer <admin_key>
Content-Type: application/json

{"message":"服务器将于 5 分钟后重启","duration_seconds":10}

示例：假人管理 /control/dummies（admin）

POST /control/dummies
Authorization: Bearer <admin_key>
Content-Type: application/json

{"action":"spawn","nickname":"Bot","role":"ClassD"}

action 可选 spawn | list | remove；同时最多 5 个；remove 的 target 为假人 PlayerId / 昵称，或 all。

📚 完整文档：HTTP-API（端点表与 curl 示例）· WS-Control-Protocol · Voice-Forwarding

🌐 生态

官方客户端

📱 SLConsole

Android 原生管理 + 监控客户端（Kotlin · Jetpack Compose），直连 SLDataAPI，无需中间平台，凭据经 AndroidKeyStore 加密只存本机。

概览监控、玩家管理、远程控制台
种子重建地图，玩家实时定位，灯光 / 门 / 电梯控制
实时事件流与 48 kHz 语音监听
封禁、日志、审计、插件、文件、举报管理
多服务器一键切换

🖥️ Foundation Console

服主团队自部署的 Web 管理平台（React 19 · Node.js），浏览器不持有游戏服凭据，全部由平台后端代理。

多服务器统一管理，单条 WebSocket 多路复用状态与控制
admin / user / guest 三级角色，后端强制鉴权
注册登录、2FA、服务端会话
凭据 AES-256-GCM 加密存储，无外部数据库、无遥测
状态与语音 WebSocket 代理

集成与扩展

项目	说明
astrbot_plugin_sl_query	AstrBot 插件：`/bindlab <IP> <verify_token>` 后，`/sl` 显示 `[LAB]` 标记
AdaptedPluginSample	适配插件示例：把你自己的插件状态与操作挂到 SLDataAPI 上

🛠️ 开发

文档：Development-Guide · Architecture · Building
开发 skill 与冒烟脚本：最新 Release 附件 SLDataAPI-DevKit-v<版本>_<代号>.zip

逻辑回归测试

tests/ 下有四套独立的 net8.0 xUnit 项目，直接编译对应的纯逻辑源文件，不引用主工程 SLDataAPI.csproj，因此不需要游戏程序集、LabAPI 或 Unity，也不会编译、签名或打包 SLDataAPI.dll。

套件	覆盖范围
`SLDataAPI.Auth.Tests`	鉴权、API Key 交付、端点 ACL、路径沙箱、TLS 策略、WS 调用闸门
`SLDataAPI.Features.Tests`	节日闸门、端点入参规则、玩家查找、反射查找
`SLDataAPI.Update.Tests`	更新检查与强名称判定
`SLDataAPI.WebDav.Tests`	WebDAV 上传规则

dotnet test tests/SLDataAPI.Auth.Tests/SLDataAPI.Auth.Tests.csproj -c Release
dotnet test tests/SLDataAPI.Features.Tests/SLDataAPI.Features.Tests.csproj -c Release
dotnet test tests/SLDataAPI.Update.Tests/SLDataAPI.Update.Tests.csproj -c Release
dotnet test tests/SLDataAPI.WebDav.Tests/SLDataAPI.WebDav.Tests.csproj -c Release

Note

这些测试只做逻辑回归，不能代替进服集成，也不能说明完整插件在 SCP:SL 里可用。官方插件的编译与发布仍在本机完成。

CI 说明

推送、Pull Request 和手动 workflow_dispatch 会触发 .github/workflows/functional-tests.yml：在 GitHub 托管的 ubuntu-24.04 上分别运行四套测试。任一失败会使该检查失败，其余套件仍会跑完；控制台日志和作业摘要中有每套的通过 / 失败 / 跳过数量。

仓库的 Actions 策略只允许 DNTOF 拥有的 action，所以工作流用 git 检出、官方 dotnet-install.sh 安装 .NET 8，不调用其他组织的 action。可下载的 TRX 制品目前不可用，要等所有者允许官方的 artifact action 之后才能保留。

💬 支持

💭 QQ 群：984840871
🐛 问题反馈：GitHub Issues
❓ 常见问题：Wiki Q&A
❤️ 赞助：爱发电

📄 许可证

本项目已由 GPL-3.0-only 变更为 Apache-2.0：在遵守 Apache-2.0 与 NOTICE 的前提下允许闭源使用与再分发，不再要求衍生作品强制开源。

复用或改写本项目代码（尤其语音流相关实现）时，须：

保留源文件版权 / SPDX 头与本仓库 NOTICE；
注明来自 DNTOF/SLDataAPI；
禁止删除或篡改版权与来源信息后重新发布（含「删名字 + 换皮当自己项目」）。

如果 SLDataAPI 对你有帮助，欢迎点一个 ⭐ Star！

Name		Name	Last commit message	Last commit date
.github		.github
Auth		Auth
Capture		Capture
Commands		Commands
Control		Control
Data		Data
Integrations		Integrations
Map		Map
Services		Services
Voice		Voice
docs/assets		docs/assets
examples/AdaptedPluginSample		examples/AdaptedPluginSample
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Config.cs		Config.cs
LICENSE		LICENSE
Log.cs		Log.cs
NOTICE		NOTICE
Plugin.cs		Plugin.cs
README.md		README.md
SECURITY.md		SECURITY.md
SLDataAPI.csproj		SLDataAPI.csproj

📊 数据一手掌握一个请求拿到人数、回合、核弹、玩家 SteamID 与坐标、游戏版本、当前节日，机器人和面板直接用。	🎮 远程全面掌控玩家、物品栏、回合、地图、CASSIE、封禁、控制台、文件……40+ 端点覆盖日常运维，HTTP 或 WebSocket 任选。	⚡ 事件实时推送回合、进出、死亡、逃脱、核弹、重生波次、SCP 收容……19 种游戏事件经 WebSocket 实时推送。
🎙️ 语音转发与取证全频道 48 kHz PCM 实时转发；分轨 WAV + 时间轴 TSV 按局归档，可自动上传到 WebDAV。	🔐 安全默认开启 API Key 分级授权、仅存指纹；弱口令 fail-closed；同端口自签 TLS + 指纹固定；侵入性操作全程审计。	🧩 开放可扩展其它插件可注册为「适配插件」，通过 SLDataAPI 对外暴露状态与操作，无需自建 HTTP 服务。

Navigation Menu

Repository navigation

About

Repository files navigation

SLDataAPI

✨ 为什么选择 SLDataAPI

📊 数据一手掌握

🎮 远程全面掌控

⚡ 事件实时推送

🎙️ 语音转发与取证

🔐 安全默认开启

🧩 开放可扩展

📦 功能一览

🚀 快速开始

1. 准备依赖

2. 安装插件

3. 完成初始化

4. 发出第一个请求

🔧 配置

多语言与稳定 code / Language & stable codes

🔐 鉴权与安全

API Key 管理

同端口自签 TLS

🔌 接口速览

🌐 生态

官方客户端

📱 SLConsole

🖥️ Foundation Console

集成与扩展

🛠️ 开发

逻辑回归测试

💬 支持

📄 许可证

About

Releases

Sponsor this project

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

SLDataAPI

✨ 为什么选择 SLDataAPI

📊 数据一手掌握

🎮 远程全面掌控

⚡ 事件实时推送

🎙️ 语音转发与取证

🔐 安全默认开启

🧩 开放可扩展

📦 功能一览

🚀 快速开始

1. 准备依赖

2. 安装插件

3. 完成初始化

4. 发出第一个请求

🔧 配置

多语言与稳定 code / Language & stable codes

🔐 鉴权与安全

API Key 管理

同端口自签 TLS

🔌 接口速览

🌐 生态

官方客户端

📱 SLConsole

🖥️ Foundation Console

集成与扩展

🛠️ 开发

逻辑回归测试

💬 支持

📄 许可证

About

Topics

Resources

Security policy

Stars

Watchers

Forks

Releases

Sponsor this project

Contributors

Languages