Configuration

配置参考

对齐 2.6.0 PEAK。键名均为 snake_case（LabAPI UnderscoredNamingConvention）。

路径

文件	位置
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/plugins/global/SLDataAPI/properties.yml（可用 /control/plugins 代写）

---

常见坑

• 错误键名被静默忽略。
• 任一值格式错误可能导致整文件回退默认（启动日志会打 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 端口
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/*
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 后是否复制剪贴板

更新检查

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

WebDAV

• 默认关。启用后每局录音 zip 定稿可 PUT 到 webdav_url。
• 只接受 https://；http:// 会被拒绝并跳过上传。
• 不影响插件自身 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 分钟自动删）；命令只回路径。

---

传输互斥

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

/get_sl_data 始终 HTTP，不受此项影响。