入门指南

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 公证,首次打开被阻止时,请在“系统设置”>“隐私与安全性”中允许打开。

  1. 通过网站上的下载按钮或 GitHub Releases 下载安装程序 saba-chan-installer.exe。
  2. 运行安装程序,选择安装位置、要先安装的游戏模块以及快捷方式选项,然后点击 安装。
    • 默认安装位置为 C:\Program Files\Saba-chan。如果选择的文件夹中已有其他文件,安装程序会在其中创建一个 Saba-chan 文件夹。
    • 游戏模块也可以稍后在应用中添加。
  3. 安装程序会配置以下组件。视网络状况而定,可能需要几分钟。
    • 检查最新的已签名版本,然后下载并部署守护进程、GUI、CLI、语言文件等组件(每个文件都会校验哈希)。安装程序也会放在安装文件夹里,之后用来应用更新和卸载 Saba-chan
    • 安装所选的游戏模块及其所需的扩展(例如 SteamCMD)
    • 下载便携版 Python 并创建 venv 环境(安装在 Saba-chan 文件夹中,不会修改系统 PATH)
    • 将已安装组件的版本记录到 installed-manifest.json
  4. 安装完成后,点击 启动 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 各组件的关系和通信方式:

你的电脑
GUI 应用桌面应用 · 可选
CLI命令和交互式 Shell · 可选
Saba-chan 守护进程 (saba-core)独自负责服务器、设置和 Discord 连接
游戏服务器由守护进程启动并看护
模块每款游戏的说明书 · Python
扩展额外功能 · Python
云端
Discord 中继Saba-chan 机器人 · 连接 Discord 和你的电脑
Discord用聊天下命令
游戏服务器在你的电脑上运行。与中继往来的只有 Discord 命令和结果,以及服务器列表、状态等摘要,不会为远程控制开放任何端口。
  • 守护进程(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 存储 中安装。然后按以下步骤创建服务器:

  1. 添加服务器:点击 添加服务器,选择 作为新服务器添加。若要关联你已经在使用的服务器文件夹,请改选 迁移现有服务器。
  2. 选择游戏:从已安装的游戏模块中选择一个(官方模块:Minecraft、Palworld、Project Zomboid 和 Terraria)。
  3. 设置服务器:输入服务器名称,并填写模块要求的选项(例如 Minecraft 的服务器类型)和推荐配置。端口(游戏用来接受玩家连接的编号)会自动分配,避免与其他服务器冲突。
  4. 同意条款:对于 Minecraft 等需要同意条款(EULA)的游戏,你必须亲自阅读条款并勾选复选框,才能创建服务器。Saba-chan 从不自动接受条款。
  5. 开始安装:点击 添加服务器 后,守护进程会按以下顺序执行设置任务:
    • 检查模块所需的扩展(例如 Palworld 和 Project Zomboid 需要 SteamCMD)。如果所需扩展处于关闭状态,会提示你在 设置 → 扩展 中启用。
    • 将实例数据保存到 %APPDATA%\saba-chan\instances\<实例 ID>\ 文件夹
    • 运行 server.post_create 钩子
    • 将最新版本的游戏服务器文件下载到实例文件夹的 server\ 目录中(Minecraft 和 Terraria 使用官方服务器下载,Palworld 和 Project Zomboid 使用 SteamCMD)。进度会显示在进度条上。
  6. 启动:点击 启动 后,守护进程会检查条款同意情况并执行启动前检查,运行 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 中。

  1. 正常停止:将模块的 stop_command(例如 Minecraft 的 stop、Zomboid 的 quit)发送到服务器控制台(stdin)。对于没有控制台输入的游戏(Palworld),模块会通过 REST API 请求服务器保存并关闭。随后守护进程等待停止等待时间(服务器的 Saba-chan 标签页中设置的值,没有则取 module.toml 中的 [config].stop_timeout,再没有则为 30 秒)。超时后,守护进程会强制终止进程,并额外等待 2 秒。
  2. 强制结束:强制终止时,会立即结束进程树,并最多等待 5 秒。
  3. 停止冷却:停止后的 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. 后续步骤