配置文件指南

基于代码的实际行为,讲解 Saba-chan 的数据文件夹、设置文件 config.json、实例文件夹和令牌文件。

配置文件指南

Saba-chan 的设置和状态位于数据文件夹 %APPDATA%\saba-chan(= C:\Users\<你的用户名>\AppData\Roaming\saba-chan)下。本文档总结实际代码如何使用其中的文件,并区分哪些文件可以安全地手动编辑、哪些文件不应触碰。

所有工作都由守护进程(saba-core)完成;GUI 和 CLI 只调用守护进程的本地 HTTP API。因此通过 GUI 或 CLI 修改设置最为安全:守护进程在保存时会检查格式。


1. 文件夹结构

%APPDATA%\saba-chan\
  • config.json所有用户设置(按命名空间)所有用户设置(按命名空间)
  • config.json.bak上一份正常副本(用于自动恢复)上一份正常副本(用于自动恢复)
  • .ipc_token守护进程 ↔ GUI/CLI 认证令牌(守护进程每次启动时重新生成)守护进程 ↔ GUI/CLI 认证令牌(守护进程每次启动时重新生成)
  • .node_tokenDiscord(Server-chan)连接令牌。配对时由守护进程保存Discord(Server-chan)连接令牌。配对时由守护进程保存
  • instances\服务器实例服务器实例
  • order.json列表顺序列表顺序
  • <id>\
  • instance.json实例信息实例信息
  • settings.json各模块的游戏设置值各模块的游戏设置值
  • logs\服务器控制台日志服务器控制台日志
  • backups\备份备份
  • server\默认安装位置(游戏服务器文件)默认安装位置(游戏服务器文件)
  • modules\已安装的游戏模块已安装的游戏模块
  • extensions\已安装的扩展已安装的扩展
  • logs\GUI 日志(saba-chan-<时间戳>.log)GUI 日志(saba-chan-<时间戳>.log)
  • audit.log服务器启动/停止/命令记录(敏感信息已遮蔽)服务器启动/停止/命令记录(敏感信息已遮蔽)
  • updates\更新暂存区更新暂存区
  • installed-manifest.json已安装组件的版本已安装组件的版本
  • 便携版 Python 运行时(python-standalone\、python-env\)如果安装文件夹可写,就创建在安装文件夹中,否则创建在这个数据文件夹中。
  • 还有一些由守护进程自行管理的文件(daemon.lock、scan-verdicts.json、sandbox-temp\ 等)。请不要碰它们。
  • 可以用 SABA_DATA_DIR 环境变量覆盖数据根目录本身,但一般不推荐。

2. config.json:保存所有设置的文件

用户设置按命名空间(顶层键)分组,保存在一个文件 config.json 中。

命名空间内容修改位置
guiGUI 行为、主题、语言、守护进程端口GUI 设置
relayDiscord 集成(前缀、别名、各 Discord 服务器设置)GUI 的 Discord 页面
updates更新检查间隔、自动下载、更新渠道(channel)GUI 设置
remote远程守护进程:远程端口、已配对的电脑GUI 设置 → 连接 → 远程守护进程
boot上次选择的启动模式(GUI / CLI / 仅守护进程)启动模式选择界面
extensions已启用扩展列表 enabled、各扩展的设置 settingsGUI 设置 → 扩展
chatbot会说话的 Saba-chan(AI 对话)设置GUI 的 Discord 页面
sandbox同意不隔离运行未验证组件启动被阻止时的提示、设置 → 高级
cli 等各客户端自己的设置对应客户端

保存与自动恢复

  • 保存是原子性的(先写入临时文件再替换),替换前的上一份正常副本会保留为 config.json.bak。
  • 如果 config.json 损坏无法读取,守护进程会把它移到一旁并命名为 config.json.corrupt-<时间戳>,然后从 .bak 恢复。
  • 写入 gui 或 relay 中的未知键会在保存时被丢弃。

3. gui:GUI / 守护进程共享设置

守护进程启动时,如果没有设置 SABA_IPC_PORT 环境变量,就读取 gui.ipcPort;如果也没有,则使用默认值 57474。其他键主要由 GUI 读取。

键类型默认值说明
ipcPortnumber57474守护进程 HTTP API 端口(始终只在 127.0.0.1 上打开)
autoRefreshbooleantrueGUI 状态自动刷新
refreshIntervalnumber (ms)2000GUI 状态轮询间隔。设得太低会提高 CPU 占用
consoleBufferSizenumber2000GUI 控制台保留的行数
portConflictCheckbooleantrue启动服务器前检查端口冲突
languagestring根据操作系统推断语言(ko、en、ja、de、es、fr、pt-BR、ru、zh-CN、zh-TW)。也用于模块和 Discord 的回复
themestring无(GUI 使用 auto)"dark" / "light" / "auto"
osNotificationsbooleantrue把崩溃、意外启动或停止也作为系统通知发送
daemonViewstring无(switch)有远程守护进程时的服务器列表样式。"switch" 仅所选守护进程,"unified" 合并显示所有守护进程
mainDaemonstring无(这台电脑)打开应用时最先查看的远程守护进程的电脑 id(主守护进程)

还有颜色、字体缩放、窗口大小等外观相关的键;你在 GUI 设置中修改的内容会原样保存。


4. relay:Discord 集成

Discord 机器人只运行在 Server-chan 上,因此你的电脑上没有机器人进程,也没有机器人令牌。这个命名空间保存你在 GUI 中编辑的前缀、称呼和各 Discord 服务器设置;配对后,守护进程会把它们同步到 Server-chan。

键类型默认值说明
prefixesstring[]没有为 Discord 服务器单独设置前缀时使用的聊天命令前缀列表(最多 10 个,每个 1–32 个字符且不含空格)。各 Discord 服务器的前缀保存在 nodeSettings 中,在应用的 Discord 服务器 → 机器人设置 标签页修改。为空时使用 该 Discord 服务器机器人语言(未设置时为 PC 应用语言)的默认值(韩语 사바쨩、日语 サバちゃん,其他 Saba-chan)。以字母结尾的前缀后必须跟空格(或逗号、冒号),消息才会被视为命令
serverWordsobject{}每个服务器(实例 ID)称呼该服务器和命令的词 {words, commands}。在服务器界面的 Discord 标签页修改
newGuildInstancesstring"auto"对用配对代码新连接的 Discord 服务器,是立即开放这台电脑的所有服务器(auto),还是之后再选(manual)
nodeSettingsobject{}各 Discord 服务器设置(允许的实例、命令权限、语言・前缀・斜杠命令样式・音乐・会朗读的 Saba-chan・确认设置等)
cloudobjectrelayUrl、hostId。配对时填入

以前的全局别名(moduleAliases、commandAliases、instanceAliases)会在守护进程启动时迁移到 serverWords 并清空。

nodeSettings 中的权限和 Discord 设置只能通过各自专用的界面(API)修改;保存整个机器人配置不会覆盖它们。

命令语法

Saba-chan <服务器名称或别名> <命令> [参数…]
  • Saba-chan minecraft start
  • Saba-chan mc stop(别名)
  • Saba-chan palworld status
  • Saba-chan list:服务器列表,Saba-chan help:帮助

每个服务器都有默认命令 start、stop 和 status;其他命令由模块定义。音乐等额外功能由 Server-chan 端的机器人提供。

remote:远程守护进程

你的其他电脑连接本守护进程所用的远程端口,以及本机要连接的远程守护进程列表。在应用的设置 → 连接 → 远程守护进程或用 saba-chan-cli remote 修改,不包含在设置导出中。用法见远程守护进程。它与 relay 分开,保存在 config.json 的顶层键中。

键类型默认值说明
enabledbooleantrue打开远程端口
portnumber57480远程端口(TLS)
addressstring无其他电脑能访问到的公网 IP 或主机名。留空则只能经由 Server-chan 连接
transportstring"direct"连接方式。目前只有 "direct",请保持不变
clientsarray[]与本守护进程配对的电脑(令牌只保存哈希)
daemonsarray[]本机要连接的远程守护进程

5. instances\:服务器实例

你在 GUI 中创建的每个服务器都保存为单独的 instances\<id>\ 文件夹。<id> 是一个 UUID。

  • instance.json:名称、模块、可执行文件/工作文件夹、端口、REST 连接信息、计划任务、扩展数据(extension_data)等。
  • settings.json:模块声明的游戏设置值(例如最大玩家数、难度)。
  • order.json:GUI 列表的顺序。
// instances\<id>\instance.json(节选)
{
  "id": "3f6c…",
  "name": "My Minecraft Server",
  "module_name": "minecraft",
  "working_dir": null,
  "port": 25565,
  "extension_data": {}
}
  • 只有模块声明了 supported = ["rcon"] 的游戏(既无控制台也无 REST API)才使用 RCON,此时守护进程为每个实例分配端口和随机密码,并且只通过回环地址(127.0.0.1)连接。其他游戏命令发送到服务器控制台(stdin),Palworld 使用其 REST API。旧文件中残留的 RCON 键会在加载时被移除。
  • extension_data 是为扩展预留的存储空间。例如,对于通过 SteamCMD 安装的模块,安装方式和应用信息就存放在这里。
  • 保存服务器设置时(GUI 服务器设置、PATCH /api/instance/:id),既不是实例通用字段、也不是模块声明的设置的键会被拒绝,并返回 unknown_setting 错误。
  • 删除实例会删除整个 instances\<id>\ 文件夹,包括默认安装位置(server\)中的游戏服务器文件和 backups\。

请仅在守护进程未运行时手动编辑这些文件。在运行期间编辑会与守护进程内存中的状态产生偏差,下一次保存会覆盖你的修改。


6. 令牌文件(.ipc_token / .node_token)

文件格式创建时机使用者
.ipc_tokenUUID v4(单行)守护进程每次启动时重新生成GUI / CLI / 模块和扩展(本地 API 调用)
.node_tokensbn_<hostId>.<secret>Discord 配对完成时由守护进程保存守护进程的 Server-chan 连接

IPC 令牌

守护进程 API 只监听 127.0.0.1,除 /health 外的所有请求都需要 X-Saba-Token 请求头。

GET /api/servers HTTP/1.1
Host: 127.0.0.1:57474
X-Saba-Token: <.ipc_token 文件的内容>
  • 守护进程每次重启,令牌都会改变。GUI 和 CLI 在认证失败时会重新读取令牌文件,你无需做任何操作。
  • 令牌文件的位置可以用 SABA_TOKEN_PATH 修改。

节点令牌

.node_token 是将这台电脑连接到 Discord 机器人(Server-chan)的密钥。守护进程通过 HTTPS 将其发送给 Server-chan 进行认证。绝不要给任何人看;如果怀疑已泄露,请在 GUI 中重新配对。重新配对会使旧令牌失效。


7. 扩展与隔离设置(extensions / sandbox)

  • extensions.enabled:已启用的扩展 ID 列表。
  • extensions.settings:各扩展的设置值 { "<id>": { "<key>": value } }。通过守护进程 API PUT /api/extensions/:id/config 修改。
  • sandbox.unisolated:同意在不隔离的情况下运行无法准备隔离环境的组件。它以组件文件的指纹形式保存,任何文件发生变化都会再次询问。可以在 GUI 的 设置 → 安全 →“不隔离运行”中撤销,或使用 saba-chan-cli sandbox revoke <component>。

8. 主要环境变量

变量作用对象说明
SABA_IPC_PORT守护进程 / CLI覆盖 gui.ipcPort
SABA_DAEMONCLI接收命令的远程守护进程,与 --daemon <名称> 相同
SABA_DATA_DIR守护进程重新指定数据根目录本身(高级)
SABA_TOKEN_PATH守护进程IPC 令牌文件路径
SABA_MODULES_PATH / SABA_EXTENSIONS_DIR / SABA_INSTANCES_PATH守护进程重新指定模块、扩展和实例文件夹
RUST_LOG守护进程日志过滤器(默认 info)
SABA_IPC_URL模块/扩展子进程守护进程 API 地址。由守护进程注入子进程
SABA_LANG模块/扩展子进程当前语言(gui.language)
PYTHONPATH模块/扩展子进程合并模块和扩展路径后注入
SABA_ENABLED_EXTENSIONS模块/扩展子进程已启用扩展 ID 列表(以 , 分隔)
PYTHONIOENCODING模块/扩展子进程始终为 utf-8
PYTHONUNBUFFERED模块/扩展子进程1:立即刷新 stdout

如果你怀疑自己弄坏了什么,请先停止守护进程,然后删除相关文件并重新启动;大多数文件会以默认值重新生成。删除 config.json 会重置所有设置,包括 Discord 集成设置,所以请先尝试恢复 config.json.bak。不要删除 instances\ 文件夹:你的服务器列表以及安装在默认位置的游戏文件都会随之消失。