Skip to content

v2.6.1 Mores

Choose a tag to compare

View all tags
@DNTOF DNTOF released this 17 Oct 05:50
v2.6.1_Mores
38287d2

v2.6.1 Mores

正式版：SLDataAPI 2.6.1，开发代号 Mores（相对 2.6.0 PEAK）。源码已在 main。

本版本在 10-04 发布的 2.6.1-preview RIDGE 预发布版基础上，加入同端口自签 TLS，并转为正式版。2.6.0 PEAK 的更新检查会提示本版本。

重要提示（请先读）

  • TLS 默认 optional：升级后首次启动会自动生成自签证书，同一端口同时接受 TLS 与明文，现有明文客户端（http:// / ws://）无需改动。不想启用可设 tls_mode: off。
  • 两项内测功能（适配插件写操作、FileRoot 分块 WS）仍然默认关闭，带鉴权的端到端流程尚未完整测试，请只在测试服打开。
  • 发现问题请积极开 Issue（附版本号 v2.6.1 Mores、LabAPI/游戏版本、相关日志与复现步骤）：https://github.com/DNTOF/SLDataAPI/issues
  • 安全/权限类问题请按模板脱敏，不要贴明文 API Key / verify_token / WebDAV 密码 / 证书口令。

新增：同端口自签 TLS（contract v1）

怎么开

config.yml：

tls_mode: optional   # off | optional | required
  • optional（默认）：HTTP/WS 主端口（默认 8081）与语音端口（默认 8082）同端口首字节嗅探：TLS 握手走 TLS，其余按明文。https:// / wss:// 与 http:// / ws:// 用同一个端口。
  • required：明文 HTTP、明文控制 WS / 语音 WS 一律返回 426，{"success":false,"message":"…","data":{"code":"tls_required"}}。
  • off：不生成也不加载证书，行为与 2.6.0 一致。
  • 非法值按 optional 处理并告警。改完需重启服务器。

证书与指纹固定

  • 首次启动在插件配置目录（LabAPI/configs/<端口>/SLDataAPI/）生成 sld_tls.pfx 与随机口令文件 sld_tls.pwd：RSA-2048 / SHA-256 / 约 10 年，CN=SLDataAPI。优先用游戏自带 Mono.Security 生成，失败回退 BouncyCastle。证书损坏时改名 .bad-<时间> 后重新生成。
  • 启动日志打印 TLS: <mode>, SHA-256 <指纹>。客户端应固定（pin）这个指纹，不要依赖 CA 校验（自签证书本来也过不了 CA 校验）。
  • 控制 WS 与语音 WS 的 hello 新增 tls（本连接是否加密）与 cert_fingerprint（off 时为 null），客户端可据此核对。
  • 不要把 sld_tls.pfx / sld_tls.pwd 发给任何人或贴到 Issue。

新命令（仅本地控制台）

sldataapi cert show     # 查看模式 / 指纹 / 有效期
sldataapi cert regen    # 重新生成并热替换（只对新连接生效）
  • 只能在**服务器本地控制台（LocalAdmin）**执行；RemoteAdmin 与远程控制通道一律拒绝（比 apikey 更严格）。
  • regen 后指纹会变，已固定指纹的客户端需要重新确认；regen 会写入控制审计日志。

其他

  • 主端口 TLS 握手计入 Slowloris 时限并另设 10s 上限；语音端口握手在后台线程进行。
  • 修复：语音端口未完成握手的连接超时改用真实时钟（服务器 idle mode 时 Time.time 停滞，原先静默连接可无限期占用名额）。
  • 已与 App 端联调：指纹固定、监控 / 控制 / 语音全链路加密均验证通过。

TLS 已知限制

  • Windows 上 sld_tls.pfx / sld_tls.pwd 的文件权限（ACL）实际未收紧，沿用目录继承权限。请自行限制服务器配置目录的访问。
  • required 模式的 426 响应没有 Upgrade 头。
  • cert show|regen 在 RemoteAdmin / 远程通道被拒绝的逻辑尚未运行时实测（代码路径已覆盖）。
  • 游戏自带 Mono 实际只协商 TLS 1.2。
  • DevKit 冒烟脚本尚未覆盖 TLS / 指纹校验。

自 2.6.1 预发布版保留的内测功能（默认关闭）

1. 适配插件写操作：beta_adapted_plugin_actions: true

  • 第三方插件在 TryRegister 之后，可调用 PluginEndpointRegistry.TryRegisterActions(id, actions, out error) 注册写 / 动作路由（每个插件最多 16 个，请求体 ≤64KB）。TryRegister 签名不变。
  • 调用：POST /control/adapted/<plugin_id>/<action>（HTTP 与 WS call 同一路由），主线程执行，超时 3s；一律按写操作计并写入 control_log。
  • 示例插件 AdaptedPluginSample 1.1.0 带 echo / bump 动作。

2. FileRoot 的 WS 适配：beta_file_root_ws: true

  • 新增 /control/files/stat、/control/files/read_chunk（分块读，单块 ≤160KB）、/control/files/write_chunk（分块上传会话，总计 ≤512KB，120s 过期）。仍需配置 file_root，沿用原有沙箱。

控制 WS hello 的 beta 数组列出已开启的内测能力（adapted_actions / file_chunks）。

权限（ACL）

  • /control/adapted/ 与 /control/files/ 默认拒绝（含 admin），需要在 apikey.config 对应 Key 的 endpoints_override 中显式放开。

安全加固（不受开关影响）

  • FileRoot 沙箱拒绝经过**符号链接 / 目录联接（junction）**的路径，对全部文件端点生效。如果你的 file_root 里有意放了链接，升级后相关路径会被拒绝。

其他变化

  • 修复：适配插件动作注册日志不再附带依赖加载顺序的误导提示
  • 许可证：全部源码加 SPDX 头（GPL-3.0-only），新增双语 NOTICE

安装 / 更新

  1. 备份现有 config.yml / apikey.config
  2. 将 SLDataAPI.dll 放入 LabAPI/plugins/global/（示例插件 AdaptedPluginSample.dll 可选）
  3. 确认依赖：0Harmony.dll、Newtonsoft.Json.dll
  4. 重启服务器
  5. 首次加载后 config.yml 会补上 tls_mode: optional，配置目录生成 sld_tls.pfx / sld_tls.pwd；在启动日志或本地控制台 sldataapi cert show 查看指纹，配置到客户端

DevKit

附件 SLDataAPI-DevKit-v2.6.1_Mores.zip 含开发 skill（已补充 TLS 说明）与冒烟脚本：

.\scripts\Test-ControlEndpoints.ps1 -BaseUrl http://127.0.0.1:8081 `
  -VerifyToken "<verify_token>" -ApiKey "<admin_key>"

仅对自有服务器冒烟；勿把真实密钥写进脚本。

文档

已知问题

  • 见上文「TLS 已知限制」
  • 内测功能带鉴权的端到端流程尚未完整测试
  • 语音端口被占用时语音服务启动失败，暂无自动回退；请换一个空闲的 voice_port
  • /control/plugins 在 admin 默认 ACL 下仍为拒绝，需要 endpoints_override 显式放开
  • /control/player/inventory、/control/dummies 仍为 501

遇到异常请开 Issue，反馈越具体修得越快。

Assets 5
Loading