はじめに

サバちゃんのインストール、セットアップ、運用ガイド。実行時の構成と動作仕様を解説します。

はじめに

このドキュメントでは、サバちゃん(Saba-chan)の基本的なインストール、セットアップ、サーバー作成の手順を扱います。リモート連携や問題の解決については Discord Bot と トラブルシューティング を参照してください。


1. ダウンロード & インストール

動作環境:Windows 10 または 11 (64ビット)、Microsoft Edge WebView2 ランタイム(Windows 11 と最近の Windows 10 には同梱)、インターネット接続。画面のない Linux(x86_64)にデーモンと CLI をインストールできます(下の 1.1)。macOS(Appleシリコン)はトップページから .dmg をダウンロードし、アプリを「アプリケーション」フォルダにドラッグします。Appleの公証を受けていないため、初回起動でブロックされたら「システム設定」の「プライバシーとセキュリティ」から開くことを許可してください。

  1. Webサイトのダウンロードボタン、または GitHub Releases からインストーラー saba-chan-installer.exe をダウンロードします。
  2. インストーラーを実行し、インストール先、最初にインストールするゲームモジュール、ショートカットのオプションを選んで インストール をクリックします。
    • 既定のインストール先は C:\Program Files\Saba-chan です。すでに他のファイルがあるフォルダーを選ぶと、インストーラーはその中に Saba-chan フォルダーを作成します。
    • ゲームモジュールは後からアプリで追加することもできます。
  3. インストーラーは次のコンポーネントを構成します。ネットワーク環境によっては数分かかることがあります。
    • 最新の署名済みリリースを確認し、デーモン、GUI、CLI、ロケールなどのコンポーネントをダウンロードして配置(すべてのファイルをハッシュで検証)。インストーラー自体もインストールフォルダーに置かれ、後でアップデートを適用したりサバちゃんをアンインストールしたりするときに使います
    • 選択したゲームモジュールと、それが必要とするエクステンション(例:SteamCMD)をインストール
    • ポータブル Python をダウンロードし、venv 環境を作成(サバちゃんのフォルダー内にインストールされ、システムの PATH は変更しません)
    • インストールしたコンポーネントのバージョンを installed-manifest.json に記録
  4. インストールが終わったら サバちゃんを起動 をクリックして GUI を開きます。デスクトップまたはスタートメニューのショートカットから起動することもできます。

設定、ゲームサーバーのファイル、ワールド、バックアップは %APPDATA%\saba-chan に保存されます。プログラムのフォルダーを削除しても、サーバーのデータは消えません。

再インストール:インストールが途中で失敗した場合やファイルが破損した場合は、インストーラーをもう一度実行してください。プログラムのファイルを再ダウンロードし、破損した Python ランタイムは削除して再ダウンロードします。設定とサーバーのデータは保持されます。現在のリリースより古いインストーラーはブロックされるため、必ず最新のインストーラーをダウンロードしてください。

1.1 Linux サーバー

画面のない Linux(x86_64)には、アプリの画面なしでデーモンと CLI だけをインストールします。curl、unzip、sha256sum、python3 が必要です。

curl -fsSL https://raw.githubusercontent.com/WareAoba/saba-chan/main/install.sh | sh
  • インストーラーは最新の正式リリースを取得し、リリースのハッシュと署名付きマニフェストでファイルを確認してからインストールし、~/.local/bin/saba-chan-cli を作り、デーモンを systemd ユーザーサービス(saba-chan.service)として起動します。sh -s -- --dir <フォルダー> --modules <モジュール…> でインストール先とモジュールを選びます。
  • ログインしなくても起動時に立ち上げるには、sudo loginctl enable-linger $USER を一度実行します。
  • データフォルダーは ~/.config/saba-chan です。
  • Linux サーバーは Windows PC のアプリからリモートデーモンとして操作します。Discord への接続とリモート接続のオンはリモートデーモンの章にあります。

2. サバちゃんの構造を理解する

次の図は、サバちゃんの各コンポーネントの関係と通信の流れを示しています。

あなたのPC
GUIアプリデスクトップアプリ・任意
CLIコマンドと対話型シェル・任意
サバちゃんデーモン (saba-core)サーバー、設定、Discord連携をひとりでこなします
ゲームサーバーデーモンが起動して見守ります
モジュールゲームごとの説明書・Python
拡張機能追加機能・Python
クラウド
Discordリレーサバちゃんボット・DiscordとPCをつなぎます
Discordチャットでコマンド
ゲームサーバーはあなたのPCで動きます。リレーとやりとりするのはDiscordのコマンドと結果、サーバー一覧や状態などの要約だけで、リモート操作用のポートは開けません。
  • デーモン(saba-core.exe): サバちゃんのすべての機能を実行する中核です。サーバープロセスを実行・管理し、ログを収集し、ローカルアドレス 127.0.0.1:57474 でのみ HTTP API を公開します。
  • GUI: デーモン API を呼び出すデスクトップアプリです。
  • CLI: デーモン API を呼び出すコマンドラインツールです。引数なしで実行すると対話シェルが開きます。
  • ランナー(saba-runner): 各サーバーに付く小さな監視プロセスです。デーモンが再起動しても、サーバーのコンソールとログが途切れないようにします。
  • リレーサーバー: Discord Bot が動作するクラウドサービスです。ペアリング後、デーモンが外向きに接続(ロングポーリング)して Discord の管理コマンドを受け取り、すべてのリクエストはペアリング時に受け取ったノードトークンで HTTPS 上で認証されます。リレーが扱うのは Discord のコマンドと結果、サーバーの概要だけでゲームの通信は扱わないため、ゲームに参加するプレイヤー向けのネットワーク設定は別に行う必要があります。

ゲームサーバーは自分のPC上で動作します。GUI と CLI はデーモンにリクエストを送るだけで、ファイルの編集やプロセスの起動を自分で行うことはありません。

ウィンドウを閉じるときに「インターフェースのみ終了」を選ぶと、デーモンとゲームサーバーはバックグラウンドで動き続けます。GUI を再び開くとデーモンに再接続し、既存のサーバー状態とコンソールログを引き継ぎます。デーモンが再起動した場合は、実行中の既存のサーバープロセスに再接続(re-attach)してモニタリングを再開します(停電やシステムの再起動で終了したプロセスは復元されません)。個々のゲームサーバーを停止するには、インターフェースで 停止 をクリックします。


3. 最初のサーバーを作成する(GUI を使用)

サバちゃんを初めて起動するとサーバー一覧は空で、「次にやること」カードがゲームモジュールのインストールと最初のサーバーの作成を案内します。ゲームモジュールがまだインストールされていない場合は、まずアプリの サバ ストレージ からインストールしてください。そのうえで、次の手順でサーバーを作成します。

  1. サーバーを追加: サーバーを追加 をクリックし、新しいサーバーとして追加 を選びます。すでに使っているサーバーフォルダーを紐付ける場合は、代わりに 既存サーバーの移行 を選びます。
  2. ゲームを選ぶ: インストール済みのゲームモジュールから1つ選びます(公式モジュール:Minecraft、Palworld、Project Zomboid、Terraria)。
  3. サーバーを設定する: サーバー名を入力し、モジュールが求めるオプション(例:Minecraft のサーバー種類)と推奨セットアップを入力します。ポート(ゲームが参加者を受け付けるための番号)は他のサーバーと重ならないように自動で割り当てられます。
  4. 規約に同意する: Minecraft のように規約(EULA)への同意が必要なゲームでは、サーバーを作成する前に自分で規約を読んでチェックボックスにチェックを入れる必要があります。サバちゃんが自動で規約に同意することはありません。
  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 を通じてサーバーに保存と終了を要求します。その後、デーモンは停止の待機時間(サーバーの サバちゃん タブで決めた値、なければ module.toml の [config].stop_timeout、それもなければ 30秒)まで待ちます。タイムアウトを超えると、デーモンはプロセスを強制終了し、さらに2秒待ちます。
  2. 強制終了:強制終了では、プロセスツリーを直ちに終了させ、最大 5秒 待ちます。
  3. 停止後のクールダウン:停止後 30秒 の間は、クラッシュの自動検出を一時停止します。これで、正常な終了がクラッシュとして記録されません。

4.2 クラッシュの処理

サーバーが終了すると、デーモンは原因を 手動で停止、ゲーム内で停止、クラッシュ、原因不明 のいずれかに分類し、サーバーの「最近の終了履歴」に記録します。異常な終了コードやモジュールが宣言したクラッシュファイルのような根拠がある場合にのみクラッシュと判定し、根拠がなければクラッシュとして扱いません。

  • 自動再起動:サーバー画面の サバちゃん タブの「自動再起動」でオン・オフを切り替えます。クラッシュ時に再起動 は既定でオン、原因不明の終了でも再起動 は既定でオフです。自分で停止したサーバーやゲーム内から停止したサーバーは再起動されません。
  • 再起動の間隔:最初の再起動は5秒後に行われ、再起動のたびに待ち時間が2倍になります。10分以内に3回を超えて再起動すると、サバちゃんは再起動をやめます。ログを確認し、手動でサーバーを起動してください。

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. 次のステップ