入门指南
Saba-chan 的安装、设置与运维指南,涵盖运行时架构与运行行为。
入门指南
本文档介绍 Saba-chan 的基本安装、设置与服务器创建步骤。远程集成与问题处理请参阅 Discord 机器人 和 故障排查 文档。
1. 下载与安装
系统要求:Windows 10 或 11(64 位)、Microsoft Edge WebView2 运行时(Windows 11 和较新的 Windows 10 已自带),以及网络连接。在 Linux(x86_64)上用一行命令安装(见下方 1.1)。macOS(Apple 芯片)请在首页下载 .dmg,并把应用拖到“应用程序”文件夹。本应用未经 Apple 公证,首次打开被阻止时,请在“系统设置”>“隐私与安全性”中允许打开。
- 通过网站上的下载按钮或 GitHub Releases 下载安装程序
saba-chan-installer.exe。 - 运行安装程序,选择安装位置、要先安装的游戏模块以及快捷方式选项,然后点击
安装。- 默认安装位置为
C:\Program Files\Saba-chan。如果选择的文件夹中已有其他文件,安装程序会在其中创建一个Saba-chan文件夹。 - 游戏模块也可以稍后在应用中添加。
- 默认安装位置为
- 安装程序会配置以下组件。视网络状况而定,可能需要几分钟。
- 检查最新的已签名版本,然后下载并部署守护进程、GUI、CLI、语言文件等组件(每个文件都会校验哈希)。安装程序也会放在安装文件夹里,之后用来应用更新和卸载 Saba-chan
- 安装所选的游戏模块及其所需的扩展(例如 SteamCMD)
- 下载便携版 Python 并创建
venv环境(安装在 Saba-chan 文件夹中,不会修改系统PATH) - 将已安装组件的版本记录到
installed-manifest.json
- 安装完成后,点击
启动 Saba-chan打开 GUI。也可以通过桌面或开始菜单快捷方式启动。
设置、游戏服务器文件、世界和备份都保存在 %APPDATA%\saba-chan 中。删除程序文件夹不会删除你的服务器数据。
重新安装:如果安装中途失败或文件损坏,请再次运行安装程序。它会重新下载程序文件,并删除损坏的 Python 运行时后重新下载。你的设置和服务器数据会被保留。比当前版本旧的安装程序会被阻止,因此请务必下载最新的安装程序。
1.1 Linux
在 Linux(x86_64)上用一行命令安装。需要 curl、unzip、sha256sum、python3。
curl -fsSL https://raw.githubusercontent.com/WareAoba/saba-chan/main/install.sh | sh
- 如果是带图形界面的桌面系统,会连应用(GUI)一起安装,把 Saba-chan 加入应用菜单,然后启动应用。和 Windows 一样,由应用启动守护进程。应用窗口需要 WebKitGTK。没有的话,安装程序会告诉你安装命令(例如:
sudo apt install libwebkit2gtk-4.1-0 libayatana-appindicator3-1)。 - 如果是没有屏幕的服务器,只安装守护进程和 CLI,并以 systemd 用户服务启动守护进程。也可以用
--gui・--no-gui自行指定。 - 安装程序会获取最新的正式版本,用发布哈希和已签名的清单校验文件后安装,并创建
~/.local/bin/saba-chan-cli。在没有屏幕的服务器上,会以 systemd 用户服务(saba-chan.service)启动守护进程。用sh -s -- --dir <文件夹> --modules <模块…>选择安装文件夹和模块。 - 在没有屏幕的服务器上,想在不登录的情况下开机启动,运行一次
sudo loginctl enable-linger $USER。 - 数据文件夹是
~/.config/saba-chan。 - 没有屏幕的 Linux 服务器通过另一台电脑上的应用以远程守护进程的方式管理。连接 Discord 和打开远程连接的方法见远程守护进程一章。
2. 了解 Saba-chan 的架构
下图展示 Saba-chan 各组件的关系和通信方式:
- 守护进程(
saba-core.exe):执行 Saba-chan 所有功能的核心。它运行并管理服务器进程、收集日志,并且只在本地地址127.0.0.1:57474上提供 HTTP API。 - GUI:调用守护进程 API 的桌面应用。
- CLI:调用守护进程 API 的命令行工具。不带参数运行时会打开交互式 shell。
- 运行器(
saba-runner):附加在每个服务器上的小型监视进程。即使守护进程重启,也能让服务器控制台和日志保持连续。 - Server-chan(中继服务器):运行 Discord 机器人的云服务。配对后,守护进程会主动向外连接(长轮询)以接收 Discord 管理命令,所有请求都通过 HTTPS 使用配对时获得的节点令牌进行认证。Server-chan 只传递 Discord 命令、执行结果和服务器概要,不承载游戏流量,因此加入游戏的玩家所需的网络访问需要另行配置。
游戏服务器运行在你自己的电脑上。GUI 和 CLI 只向守护进程发送请求,从不自行编辑文件或启动进程。
以“仅关闭界面”关闭窗口时,守护进程和游戏服务器会在后台继续运行。重新打开 GUI 会重新连接守护进程,并接续现有的服务器状态和控制台日志。如果守护进程重启,它会重新附加(re-attach)到正在运行的现有服务器进程并恢复监控(因断电或系统重启而终止的进程不会恢复)。要停止单个游戏服务器,请在界面中点击
停止。
3. 创建第一个服务器(使用 GUI)
首次启动 Saba-chan 时,服务器列表是空的,“下一步”卡片会引导你安装游戏模块并创建第一个服务器。如果还没有安装任何游戏模块,请先在应用的 Saba 存储 中安装。然后按以下步骤创建服务器:
- 添加服务器:点击
添加服务器,选择作为新服务器添加。若要关联你已经在使用的服务器文件夹,请改选迁移现有服务器。 - 选择游戏:从已安装的游戏模块中选择一个(官方模块:Minecraft、Palworld、Project Zomboid 和 Terraria)。
- 设置服务器:输入服务器名称,并填写模块要求的选项(例如 Minecraft 的服务器类型)和推荐配置。端口(游戏用来接受玩家连接的编号)会自动分配,避免与其他服务器冲突。
- 同意条款:对于 Minecraft 等需要同意条款(EULA)的游戏,你必须亲自阅读条款并勾选复选框,才能创建服务器。Saba-chan 从不自动接受条款。
- 开始安装:点击
添加服务器后,守护进程会按以下顺序执行设置任务:- 检查模块所需的扩展(例如 Palworld 和 Project Zomboid 需要 SteamCMD)。如果所需扩展处于关闭状态,会提示你在 设置 → 扩展 中启用。
- 将实例数据保存到
%APPDATA%\saba-chan\instances\<实例 ID>\文件夹 - 运行
server.post_create钩子 - 将最新版本的游戏服务器文件下载到实例文件夹的
server\目录中(Minecraft 和 Terraria 使用官方服务器下载,Palworld 和 Project Zomboid 使用 SteamCMD)。进度会显示在进度条上。
- 启动:点击
启动后,守护进程会检查条款同意情况并执行启动前检查,运行server.pre_start钩子,然后用模块的启动命令(get_launch_command)启动进程。服务器控制台输出会实时显示在 GUI 控制台中。
所有游戏命令都经由守护进程,按 stdin(服务器控制台)→ REST → RCON 的顺序发送。有控制台或 REST API(如 Palworld)的游戏在关闭 RCON 的状态下运行。只有仅支持 RCON 的游戏才使用 RCON,端口和随机密码由守护进程为每个实例分配,并且只通过回环地址(127.0.0.1)连接。
4. 运行中需要了解的行为
4.1 停止超时
对于由守护进程直接管理的进程,用户点击 停止 后,守护进程会按以下顺序尝试关闭。配置值定义在 src/supervisor/mod.rs 中。
- 正常停止:将模块的
stop_command(例如 Minecraft 的stop、Zomboid 的quit)发送到服务器控制台(stdin)。对于没有控制台输入的游戏(Palworld),模块会通过 REST API 请求服务器保存并关闭。随后守护进程等待停止等待时间(服务器的 Saba-chan 标签页中设置的值,没有则取module.toml中的[config].stop_timeout,再没有则为 30 秒)。超时后,守护进程会强制终止进程,并额外等待 2 秒。 - 强制结束:强制终止时,会立即结束进程树,并最多等待 5 秒。
- 停止冷却:停止后的 30 秒 内,会暂停自动崩溃检测。这样可以避免把正常关闭记录为崩溃。
4.2 崩溃处理
服务器退出时,守护进程会将原因分类为 手动停止、游戏内停止、崩溃 或 原因不明,并记录到该服务器的“最近的退出记录”列表中。只有在存在异常退出码或模块声明的崩溃文件等证据时,才会判定为崩溃;没有证据就不视为崩溃。
- 自动重启:在服务器界面 Saba-chan 标签页的“自动重启”中开启或关闭。
崩溃后重启默认开启,原因不明时也重启默认关闭。你自己停止的服务器或在游戏内停止的服务器永远不会被重启。 - 重启间隔:第一次重启在 5 秒后进行,之后每次重启等待时间翻倍。10 分钟内重启超过 3 次后,Saba-chan 会停止重启。请检查日志并手动启动服务器。
4.3 日志位置
- GUI 日志:
%APPDATA%\saba-chan\logs\(由 GUI 启动的守护进程的输出也记录在这里)。也可以用saba-chan-cli daemon logs查看守护进程日志。 - 服务器控制台日志:
%APPDATA%\saba-chan\instances\<实例 ID>\logs\。通过运行器运行的服务器每次运行都会在sessions\下创建一个文件,默认保留 20 个。 - 控制台视图:守护进程会为每个实例在内存中保留最近 10,000 行。GUI 带游标轮询端点
GET /api/instance/:id/console?since=…,最多获取到其显示上限consoleBufferSize(默认 2000 行)。
5. 后续步骤
- 启动与停止服务器、备份、计划任务等日常运维:管理服务器
- 通过 Discord 命令远程管理服务器:Discord 机器人 & Server-chan
- 配置设置文件(
config.json):配置文件指南 - 常见错误排查:故障排查
- 开发自定义游戏模块:模块开发指南