Configuration

配置参考

对齐 2.6.1 RIDGE（预发布；稳定版 2.6.0 PEAK 除两个 beta_* 键外相同）。键名均为 snake_case（LabAPI UnderscoredNamingConvention）。

改配置后必须重启服务器才生效（包括 control_transport、http_port、voice_port、file_root、beta_* 等全部键）。SLDataAPI 的端口、传输方式、各服务都在插件启用时按当时的配置建立；/control/plugins 的 reload 会跳过 SLDataAPI 自身，控制台 reload configs 也不会重建已启动的 HTTP / WS / 语音服务，结果可能是「半旧半新」。请以重启为准。

路径

文件	位置
config.yml	LabAPI/configs/<端口或 global>/SLDataAPI/config.yml
apikey.config	同上目录（启用控制相关功能时生成/使用）
control_log.json / reports.json	同上目录
update_check_state.json	同上目录（更新检查节流）
apikey_once_<id>.txt	同上目录（apikey create 一次性明文；约 5 分钟后自动删）
插件启停	LabAPI/configs/<端口>/<插件名>/properties.yml（每个插件一份，如 LabAPI/configs/7777/SLDataAPI/properties.yml；可用 /control/plugins 的 stage + apply 代写，重启生效）

---

常见坑

• 错误键名被静默忽略。
• 任一值格式错误可能导致整文件回退默认（启动日志会打 YamlDotNet 行号）。
• verify_token：建议 ASCII 双引号包裹。裸值以 */&/! 开头或含未引号 # 会破坏 YAML。
• 弯引号 “” 会进入 token 内容，导致鉴权失败。
• 弱 / 出厂 verify_token → fail-closed（数据口关闭；控制面未开则不绑 HTTP），见 Security-Model。
• control_token：已废弃，写入会被忽略并警告；控制面只认 API Key。

---

config.yml

键	类型	默认	说明
debug	bool	false	调试日志
verify_token	string	your_secret_token	数据口；必须改成强随机，否则 fail-closed
http_port	int	8081	HTTP 端口：数据口常驻；控制 WS（/control、/ws/control）也在此端口
push_interval_seconds	int	8	快照刷新间隔（秒）
control_enabled	bool	false	关则 /control/* 全 404
control_token	string	""	已废弃，忽略并警告
control_transport	string	http	http | ws，硬互斥；重启后生效
auto_update_check	bool	true	检查 GitHub Release（启动 + 周期）
auto_update_install	bool	true	自动下 DLL；未强签名构建拒绝安装；跳过非正式 tag
auto_update_check_interval_hours	int	72	距上次检查不足则跳过；0=仅启动查一次
file_root	string	""	空=禁用 /control/files/*；路径中的符号链接 / junction 一律拒绝（2.6.1 起）
log_directory	string	""	空=自动探测
voice_enabled	bool	false	语音 WS
voice_port	int	8082	语音端口
voice_record_enabled	bool	false	需 voice_enabled
voice_record_max_rounds	int	10	0/负=不清理
voice_record_dir	string	""	空=默认目录
webdav_upload_enabled	bool	false	定稿 zip 自动上传
webdav_url	string	""	仅 https:// 目录 URL 或含 {filename}/{file} 的模板
webdav_username	string	""	Basic Auth（可空）
webdav_password	string	""	Basic Auth（可空；永不入日志）
webdav_remote_path_prefix	string	""	目录前缀（模板 URL 下忽略）
webdav_timeout_seconds	int	30	单次 PUT 超时
webdav_max_retries	int	5	首次失败后最多重试次数
webdav_retry_interval_seconds	int	15	重试基础间隔（指数退避）
report_enabled	bool	false	SSS 举报
report_max_records	int	50
report_rate_limit	int	5	窗口内每人次数
report_rate_window_minutes	int	30
control_log_enabled	bool	true	侵入性操作审计
control_log_max_records	int	500
apikey_copy_to_clipboard	bool	false	Windows 创建 Key 后是否复制剪贴板
beta_adapted_plugin_actions	bool	false	2.6.1 内测：适配插件写操作 POST /control/adapted/<id>/<action>，见 Beta-Features
beta_file_root_ws	bool	false	2.6.1 内测：/control/files/stat、read_chunk、write_chunk（仍需 file_root），见 Beta-Features

更新检查

• auto_update_check: true：启动 + 默认每 72h 静默复查 GitHub Releases。
• auto_update_install：仅稳定正式包；当前 DLL 未强签名时拒绝自动安装。
• 节流状态写在 update_check_state.json。

WebDAV

• 默认关。启用后每局录音 zip 定稿可 PUT 到 webdav_url。
• webdav_url 必须以 https:// 开头；填 http:// 时启动日志警告「WebDAV 上传已启用但配置无效」，并跳过全部上传（防止 Basic Auth 明文泄露）。
• 不影响插件自身 HTTP/控制端口。

控制审计（control_log）

记录写操作；不记录只读查询。路径见 HTTP-API；duty 对 /control/audit/list 有 ACL 限制，见 Security-Model。

---

apikey.config

与 config.yml 同目录；勿手写明文 Key（用 sldataapi apikey create）。

keys:
  - id: bot-read
    template: duty          # create 时写入（duty|admin）
    fingerprint: "sha256:..."
    created_at: "2026-..."
    note: ""

Key 列表由 sldataapi apikey 命令维护；勿手改 fingerprint。创建时明文写入一次性文件（约 5 分钟自动删）；命令只回路径。

按 Key 细调权限用 endpoints_override（值可为 true / false 或 { read: bool, write: bool }；最长前缀匹配）：

keys:
  - id: platform
    template: admin
    fingerprint: "sha256:..."
    endpoints_override:
      "/control/files/": { read: true, write: false }
      "/control/adapted/dntof.sample_adapted/": true

文件顶部的 endpoint_catalog 决定 admin 模板展开哪些端点；其中 /control/console/、/control/plugins、/control/plugins/、/control/files/、/control/adapted/ 默认 false。改 apikey.config 后建议重启服务器。

---

传输互斥

control_transport	HTTP /control/*	WS /control
http（默认）	可用	404 + transport_mismatch
ws	404 + transport_mismatch	可用

/get_sl_data、/plugins/* 数据口始终走 HTTP，不受此项影响。

启动横幅怎么读

SLDataAPI v2.6.1 (2.6.1 RIDGE / LabAPI) enabled. HTTP on port 8081. Control API: WS 模式，API Key. Voice: 启用(端口 8082).

• HTTP on port 8081 指的是常驻的 HTTP 监听（数据口 /get_sl_data、/plugins/*），无论 control_transport 是什么都会绑定（数据口 fail-closed 且控制面未启用时除外）。
• Control API: WS 模式 表示控制面只接受 ws://<host>:8081/control 的 WS 升级（与数据口共用同一端口），HTTP /control/* 返回 404 transport_mismatch；HTTP 模式 则相反。
• 语音在单独的 voice_port。该端口被占用时语音服务启动失败（无自动回退），请换一个空闲端口。
• 改 control_transport 后要重启服务器，横幅才会变化。

内测开关（2.6.1）

beta_adapted_plugin_actions、beta_file_root_ws 默认 false；升级后首次加载由 LabAPI 自动补进 config.yml。打开后需重启，并给 Key 显式授权 /control/adapted/、/control/files/（admin 不自动获得）。详见 Beta-Features。