故障排查
运行 Saba-chan 时常见的问题,以及基于代码实际行为的解决步骤。

故障排查
本文档按用户实际遇到的症状进行整理,说明守护进程代码的实际行为以及解决步骤。命令示例和路径以 Windows 为准。在 Linux 上,数据文件夹是 ~/.config/saba-chan。
1. 守护进程无法启动 / GUI 无法连接
1.1 端口冲突 / 守护进程已在运行
守护进程(saba-core)默认在端口 57474 上监听,且只监听 127.0.0.1。
- 每台电脑只运行一个守护进程。如果已有守护进程在运行,新启动的守护进程会立即退出,GUI 和 CLI 会连接到正在运行的那个。
- 如果有其他程序占用了该端口,守护进程会以 2 秒间隔重试 10 次,然后退出。
# Windows: 查看是谁在占用
Get-NetTCPConnection -LocalPort 57474 | Select-Object OwningProcess
Get-Process -Id <pid>
- 可以在不带令牌的情况下通过
http://127.0.0.1:57474/health检查守护进程是否存活。saba-chan-cli daemon status显示同样的信息。 - 如果还残留着无响应的守护进程,请用
saba-chan-cli daemon stop停止它。如果仍然无法结束,请运行Stop-Process -Name saba-core -Force。 - 如果需要更换端口,请编辑
config.json中的gui.ipcPort并重启。或者设置环境变量,例如SABA_IPC_PORT=57480。
1.2 IPC 令牌不匹配
守护进程每次启动都会创建新的 .ipc_token。认证失败(401)时,GUI 和 CLI 会重新读取令牌文件并重试一次,因此通常会自行恢复。
如果“身份验证失败”反复出现:
- 确认 GUI 和守护进程使用的是同一个数据文件夹。如果只为其中一方设置了
SABA_DATA_DIR或SABA_TOKEN_PATH,令牌文件的位置就会不同。 - 完全退出 GUI 后重新启动。
2. 服务器启动/停止行为异常
2.1 点击停止后很久没有反应
这可能是正常的。守护进程按以下顺序处理:
- 对于有控制台的服务器,它会把模块的
stop_command发送到控制台(stdin)。对于 Palworld 等没有控制台的游戏,模块会通过 REST 请求服务器保存并关闭。 - 等待服务器自行退出。默认为 30 秒;模块可以通过
module.toml中的[config] stop_timeout修改,用户可以在服务器界面 Saba-chan 标签页的 停止等待时间 中按服务器修改。世界很大、保存耗时较长时请调大。 - 如果仍然存活,则强制结束。
- 停止后的 30 秒 内,会抑制崩溃检测。
如果总是以强制结束告终,说明服务器没有收到停止命令。请检查服务器控制台中是否出现了停止命令。例如:Minecraft 的 stop、Zomboid 的 quit。
2.2 服务器不断重新启动
服务器退出时,守护进程会将原因分类为 手动停止 / 游戏内停止 / 崩溃 / 原因不明。默认情况下,只有崩溃时才会自动重启;等待时间从 5 秒开始,每次翻倍,10 分钟内重启超过 3 次后停止重启。
解决方法:
- 在服务器界面的“最近的退出记录”中查看分类。
- 若要停止重启,请在服务器界面 Saba-chan 标签页的“自动重启”中关闭“崩溃后重启”。如果你开启了“原因不明时也重启”,也请一并检查。
- 在服务器控制台日志(
instances\<id>\logs\)中查看崩溃原因。如果是 Java OOM(OutOfMemoryError),请增加内存设置。
2.3 启动时出现“端口冲突”错误
启动前检查发现服务器的端口正被另一个正在运行的实例或其他程序使用。通常是之前的进程还残留着,或者另一个游戏服务器使用了同一端口。
- 找到占用该端口的进程并停止它。
- 如果无法停止,请在实例设置中更换端口后重新启动。
- 可以在 GUI 设置中通过“端口冲突检测”(
gui.portConflictCheck)关闭这项检查,但不推荐。
2.4 “需要同意协议”(Minecraft EULA 等)
对于模块声明了条款的游戏(例如 Minecraft EULA),必须先阅读并同意条款才能启动服务器。在同意之前,启动会被 agreement_required 阻止。
- 在 GUI 中启动服务器时,阅读弹出对话框中的条款,勾选复选框后启动。
- 不能从 Discord 同意条款。在你电脑上的 Saba-chan 中同意一次后,也就可以从 Discord 启动服务器了。
2.5 保存服务器设置被拒绝
unknown_setting:该键既不是实例通用字段,也不是模块声明的设置。可能是拼写错误或其他游戏的设置。validation_failed/invalid_format:值的范围或格式与模块的声明不符。请修正错误中指出的字段。- “设置已保存,但无法写入游戏配置文件”:设置已保存,但模块无法编辑游戏的配置文件。请确认游戏文件没有被其他程序锁定,然后再次保存。
2.6 未验证的组件无法运行
不是从官方目录安装的模块和扩展,或之后文件被修改过的,会被标记为“未验证”。Saba-chan 不会用杀毒软件扫描它们。在 Windows 上用 AppContainer、在 Linux 上用 bubblewrap 隔离运行;在无法隔离的环境(没有 bubblewrap 或无法使用 bubblewrap 的 Linux、macOS)中,只有在你对其当前文件表示同意后才会运行。如果运行被阻止,会显示以下代码之一。
| 代码 | 含义 | 解决方法 |
|---|---|---|
launch_outside_instance | 模块试图运行服务器文件夹之外的程序 | 检查模块的来源 |
sandbox_unavailable | 无法在这台电脑上准备隔离环境 | 见下文 |
出现 sandbox_unavailable 时,GUI 会询问“不隔离直接运行?”。请只对你信任的组件允许。一旦允许,该组件就能以你账户的权限访问所有文件和网络。只能在这台电脑上同意,且组件文件发生变化时会再次询问。可以在 设置 → 安全 →“不隔离运行”中撤销同意。
最可靠的解决办法是从官方目录重新安装该模块或扩展。已验证的组件会跳过这些检查。
3. 安装 / 更新问题
3.1 安装中途失败
- 安装程序停止时,错误界面会显示原因代码(
fetch_failed、download_failed、extract_failed、elevation_failed、installer_outdated)和日志路径。日志写入%TEMP%\saba-chan-installer.log。 installer_outdated表示安装程序比最新版本旧。请下载并运行最新的安装程序。- 如果是网络问题,请检查连接后点击 重试,或重新运行安装程序。
- 准备 Python 运行时时失败不会中止安装。守护进程首次启动时会再次准备;重新运行安装程序会删除损坏的运行时并重新下载。
3.2 服务器安装进度不显示或卡住(面向模块开发者)
服务器安装进度可以通过 GET /api/provision-progress/:name 获取。
- 确认模块/扩展以
PROGRESS:{json}格式将进度输出到 stderr。 - 确认 JSON 有效(对
message中的双引号和换行进行转义)。 - 成功的进度在完成 5 秒后会被移除,因此轮询太晚会看到已经是空的。失败的进度会一直保留到用户关闭为止;如果是新建的服务器,关闭时会删除该实例。
3.3 更新没有被应用
更新会根据 Server-chan 提供的已签名版本信息进行检查,并在应用前校验每个文件的哈希。如果签名或哈希不匹配,则不会应用任何内容。
- 如果更新后看到某些项目未能更新的通知,点击它即可查看哪些项目失败了。
- 在 GUI 设置中再次检查更新并应用。
- 替换守护进程、GUI 或安装程序本身的更新,会在守护进程退出后由安装程序(
saba-chan-installer)应用。应用期间请不要重新启动 Saba-chan。 - 如果仍然无效,请退出 Saba-chan,清空
updates\文件夹后再试。
4. Discord 机器人 / 云端配对
4.1 机器人没有响应
- 依次写出前缀(默认
Saba-chan)、空格、服务器名称和命令。示例:Saba-chan minecraft status。 - 必须在 GUI 中完成配对,使
.node_token得以保存。 - Saba-chan(守护进程)必须在运行。机器人运行在云端,但命令由这台电脑上的守护进程执行。
- 如果守护进程无法连接到 Server-chan,请在 GUI 的 设置 → 故障排除 →“诊断信息”中查看最近的警告。如果看到“older than relay minimum”,请更新 Saba-chan。
- 确认官方机器人已被邀请到你的 Discord 服务器且没有处于休眠。如果在休眠,用
/saba wake唤醒。
4.2 配对代码“已过期”
配对代码的有效期只有 5 分钟。请在 GUI 中重新签发代码。
4.3 Server-chan 连接被 401 拒绝
| 错误 | 原因 | 解决方法 |
|---|---|---|
TOKEN_REPLACED | 在其他地方配对时用 重新连接 选了这台电脑,这台电脑的令牌被替换 | 如果想继续使用这台电脑,请重新配对 |
INVALID_TOKEN / NODE_NOT_FOUND | .node_token 错误或已在服务器端被移除 | 重新配对(会使现有令牌失效) |
MISSING_TOKEN / INVALID_TOKEN_FORMAT | 令牌文件缺失或格式错误 | 重新配对 |
4.4 音乐命令不起作用
- 在 GUI 的 Discord 页面中,确认该 Discord 服务器的设置中已启用音乐。
- 发出命令的人必须已经在 Discord 语音频道中。如果机器人无法加入语音频道,请检查机器人的频道权限。
- 播放由官方音乐服务器负责,因此你的电脑上不需要 ffmpeg 或 yt-dlp。
4.5 连不上远程守护进程
| 显示内容 | 处理方法 |
|---|---|
那台电脑未开放远程连接 | 服务器电脑的设置 → 连接 → 远程守护进程中的允许远程连接处于关闭状态。打开并保存 |
无法连接远程守护进程 | 确认服务器电脑和它的 Saba-chan 已开启并联网。无法直接访问时会经由 Saba-chan 云连接,所以端口转发不是必需的 |
本机没有连接 Discord | 用同一个 Discord 账号为两台电脑配对 |
远程守护进程不再接受本机 | 服务器电脑断开了连接。请在你的电脑上重新点 连接 |
端口已被占用 | 其他程序在使用同一端口。请更换端口 |
这只能在那台电脑上直接操作 | 更新、自动启动等操作无法远程进行 |
4.6 Saba-chan 网页链接打不开
- 链接只能打开一次,且须在 5 分钟内。用
/saba web获取新链接。 - 出现
无法连接到你的电脑时,确认电脑上的 Saba-chan 正在运行且是最新版本。 - 没有电脑打开的链接中,服务器・模块・电脑菜单处于锁定状态。安装应用并执行
/saba connect后,再获取新链接。 - 关闭标签页或刷新会结束会话。这是正常行为。
5. 数据 / 配置恢复
5.1 config.json 损坏
- 守护进程会把损坏的
config.json移到一旁,命名为config.json.corrupt-<时间戳>,并自动从config.json.bak(上一份正常副本)恢复。 - 如果
.bak也缺失或损坏,则以默认值启动。包括 Discord 集成设置在内的所有设置都会被重置,请参考移走的.corrupt-文件,在 GUI 中重新输入需要的值。 - 服务器列表(
instances\)和.node_token与config.json是分开的,因此会被保留。
5.2 完全重置
1. 退出 Saba-chan 的 GUI、CLI 和守护进程
2. 备份并删除整个 %APPDATA%\saba-chan 文件夹
3. 启动 Saba-chan → 以默认值重新构建
注意:如果你把服务器安装在默认位置,游戏服务器文件和备份都位于 %APPDATA%\saba-chan\instances\ 中,会被一并删除。只有当你选择了此文件夹之外的服务器文件夹时,游戏文件才会保留。
6. 日志在哪里?
| 位置 | 内容 |
|---|---|
%APPDATA%\saba-chan\logs\saba-chan-*.log | GUI 日志。也包含由 GUI 启动的守护进程的输出 |
| GUI 守护进程控制台窗口 | 守护进程日志(内存缓冲,最近 10,000 行) |
| GUI 设置 → 故障排除 → 诊断信息 | 守护进程状态和最近的警告/错误。不包含密码或令牌 |
%APPDATA%\saba-chan\instances\<id>\logs\ | 服务器控制台日志(console.log、sessions\) |
| GUI 控制台标签页 | 各实例的游戏服务器输出 |
%APPDATA%\saba-chan\audit.log | 服务器启动/停止/命令的记录(含来源,敏感信息已遮蔽) |
%TEMP%\saba-chan-installer.log | 安装程序日志 |
直接运行守护进程时,可以用 RUST_LOG 环境变量更改守护进程的日志级别(默认 info)。
7. 问题报告检查清单
在提交新 issue 之前,请确认并附上以下内容。
- Saba-chan 版本(
saba-chan-cli version或 GUI 诊断信息)。 - 复现步骤。
- 相关日志(按时间戳截取的片段)。GUI 诊断信息中“复制”的输出也很有帮助。
- 操作系统 / 版本号(例如 Windows 10 x64 21H2)。
- 绝不要附上令牌文件(
.ipc_token、.node_token)或其内容。
仓库: