配置文件指南
基于代码的实际行为,讲解 Saba-chan 的数据文件夹、设置文件 config.json、实例文件夹和令牌文件。
配置文件指南
Saba-chan 的设置和状态位于数据文件夹 %APPDATA%\saba-chan(= C:\Users\<你的用户名>\AppData\Roaming\saba-chan)下。本文档总结实际代码如何使用其中的文件,并区分哪些文件可以安全地手动编辑、哪些文件不应触碰。
所有工作都由守护进程(saba-core)完成;GUI 和 CLI 只调用守护进程的本地 HTTP API。因此通过 GUI 或 CLI 修改设置最为安全:守护进程在保存时会检查格式。
1. 文件夹结构
- 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 中。
| 命名空间 | 内容 | 修改位置 |
|---|---|---|
gui | GUI 行为、主题、语言、守护进程端口 | GUI 设置 |
relay | Discord 集成(前缀、别名、各 Discord 服务器设置) | GUI 的 Discord 页面 |
updates | 更新检查间隔、自动下载、更新渠道(channel) | GUI 设置 |
remote | 远程守护进程:远程端口、已配对的电脑 | GUI 设置 → 连接 → 远程守护进程 |
boot | 上次选择的启动模式(GUI / CLI / 仅守护进程) | 启动模式选择界面 |
extensions | 已启用扩展列表 enabled、各扩展的设置 settings | GUI 设置 → 扩展 |
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 读取。
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
ipcPort | number | 57474 | 守护进程 HTTP API 端口(始终只在 127.0.0.1 上打开) |
autoRefresh | boolean | true | GUI 状态自动刷新 |
refreshInterval | number (ms) | 2000 | GUI 状态轮询间隔。设得太低会提高 CPU 占用 |
consoleBufferSize | number | 2000 | GUI 控制台保留的行数 |
portConflictCheck | boolean | true | 启动服务器前检查端口冲突 |
language | string | 根据操作系统推断 | 语言(ko、en、ja、de、es、fr、pt-BR、ru、zh-CN、zh-TW)。也用于模块和 Discord 的回复 |
theme | string | 无(GUI 使用 auto) | "dark" / "light" / "auto" |
osNotifications | boolean | true | 把崩溃、意外启动或停止也作为系统通知发送 |
daemonView | string | 无(switch) | 有远程守护进程时的服务器列表样式。"switch" 仅所选守护进程,"unified" 合并显示所有守护进程 |
mainDaemon | string | 无(这台电脑) | 打开应用时最先查看的远程守护进程的电脑 id(主守护进程) |
还有颜色、字体缩放、窗口大小等外观相关的键;你在 GUI 设置中修改的内容会原样保存。
4. relay:Discord 集成
Discord 机器人只运行在 Server-chan 上,因此你的电脑上没有机器人进程,也没有机器人令牌。这个命名空间保存你在 GUI 中编辑的前缀、称呼和各 Discord 服务器设置;配对后,守护进程会把它们同步到 Server-chan。
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
prefixes | string | [] | 没有为 Discord 服务器单独设置前缀时使用的聊天命令前缀列表(最多 10 个,每个 1–32 个字符且不含空格)。各 Discord 服务器的前缀保存在 nodeSettings 中,在应用的 Discord 服务器 → 机器人设置 标签页修改。为空时使用 该 Discord 服务器机器人语言(未设置时为 PC 应用语言)的默认值(韩语 사바쨩、日语 サバちゃん,其他 Saba-chan)。以字母结尾的前缀后必须跟空格(或逗号、冒号),消息才会被视为命令 |
serverWords | object | {} | 每个服务器(实例 ID)称呼该服务器和命令的词 {words, commands}。在服务器界面的 Discord 标签页修改 |
newGuildInstances | string | "auto" | 对用配对代码新连接的 Discord 服务器,是立即开放这台电脑的所有服务器(auto),还是之后再选(manual) |
nodeSettings | object | {} | 各 Discord 服务器设置(允许的实例、命令权限、语言・前缀・斜杠命令样式・音乐・会朗读的 Saba-chan・确认设置等) |
cloud | object | relayUrl、hostId。配对时填入 |
以前的全局别名(
moduleAliases、commandAliases、instanceAliases)会在守护进程启动时迁移到serverWords并清空。
nodeSettings中的权限和 Discord 设置只能通过各自专用的界面(API)修改;保存整个机器人配置不会覆盖它们。
命令语法
Saba-chan <服务器名称或别名> <命令> [参数…]
Saba-chan minecraft startSaba-chan mc stop(别名)Saba-chan palworld statusSaba-chan list:服务器列表,Saba-chan help:帮助
每个服务器都有默认命令 start、stop 和 status;其他命令由模块定义。音乐等额外功能由 Server-chan 端的机器人提供。
remote:远程守护进程
你的其他电脑连接本守护进程所用的远程端口,以及本机要连接的远程守护进程列表。在应用的设置 → 连接 → 远程守护进程或用 saba-chan-cli remote 修改,不包含在设置导出中。用法见远程守护进程。它与 relay 分开,保存在 config.json 的顶层键中。
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
enabled | boolean | true | 打开远程端口 |
port | number | 57480 | 远程端口(TLS) |
address | string | 无 | 其他电脑能访问到的公网 IP 或主机名。留空则只能经由 Server-chan 连接 |
transport | string | "direct" | 连接方式。目前只有 "direct",请保持不变 |
clients | array | [] | 与本守护进程配对的电脑(令牌只保存哈希) |
daemons | array | [] | 本机要连接的远程守护进程 |
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_token | UUID v4(单行) | 守护进程每次启动时重新生成 | GUI / CLI / 模块和扩展(本地 API 调用) |
.node_token | sbn_<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 } }。通过守护进程 APIPUT /api/extensions/:id/config修改。sandbox.unisolated:同意在不隔离的情况下运行无法准备隔离环境的组件。它以组件文件的指纹形式保存,任何文件发生变化都会再次询问。可以在 GUI 的 设置 → 安全 →“不隔离运行”中撤销,或使用saba-chan-cli sandbox revoke <component>。
8. 主要环境变量
| 变量 | 作用对象 | 说明 |
|---|---|---|
SABA_IPC_PORT | 守护进程 / CLI | 覆盖 gui.ipcPort |
SABA_DAEMON | CLI | 接收命令的远程守护进程,与 --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\ 文件夹:你的服务器列表以及安装在默认位置的游戏文件都会随之消失。