設定ファイルガイド

サバちゃんのデータフォルダー、設定ファイル config.json、インスタンスフォルダー、トークンファイルを、実際のコードの動作に基づいて説明します。

設定ファイルガイド

サバちゃんの設定と状態は、データフォルダー %APPDATA%\saba-chan(= C:\Users\<ユーザー名>\AppData\Roaming\saba-chan)の下にあります。このドキュメントでは、その中のファイルを 実際のコードがどう使っているか をまとめ、手で編集しても安全なファイルと触ってはいけないファイルを区別します。

すべての処理はデーモン(saba-core)が行い、GUI と CLI はデーモンのローカル HTTP API を呼び出すだけです。そのため、設定は GUI か CLI から変更するのが最も安全です。保存時にデーモンが形式をチェックするからです。


1. フォルダー構成

%APPDATA%\saba-chan\
  • config.jsonすべてのユーザー設定(名前空間ごと)すべてのユーザー設定(名前空間ごと)
  • config.json.bak直前の正常なコピー(自動復旧用)直前の正常なコピー(自動復旧用)
  • .ipc_tokenデーモン ↔ GUI/CLI の認証トークン(デーモンが起動するたびに再生成)デーモン ↔ GUI/CLI の認証トークン(デーモンが起動するたびに再生成)
  • .node_tokenDiscord(クラウドリレー)の接続トークン。ペアリング時にデーモンが保存Discord(クラウドリレー)の接続トークン。ペアリング時にデーモンが保存
  • 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: すべての設定を保持するファイル

ユーザー設定は 1つのファイル config.json に、名前空間(トップレベルのキー)ごとにまとめて保存されます。

名前空間内容変更する場所
guiGUI の動作、テーマ、言語、デーモンのポートGUI の設定
relayDiscord 連携(プレフィックス、エイリアス、Discord サーバーごとの設定)GUI の Discord ページ
updatesアップデートの確認間隔、自動ダウンロード、アップデートチャンネル(channel)GUI の設定
remoteリモートデーモン: リモートポート、ペアになった PCGUI の設定 → 接続 → リモートデーモン
boot最後に選んだ起動モード(GUI / CLI / デーモンのみ)起動モードの選択画面
extensions有効なエクステンションの一覧 enabled、エクステンションごとの設定 settingsGUI の設定 → 拡張機能
chatbotおしゃべりサバちゃん(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 が読みます。

キー型既定値説明
ipcPortnumber57474デーモンの HTTP API ポート(常に 127.0.0.1 でのみ開く)
autoRefreshbooleantrueGUI の状態を自動で更新
refreshIntervalnumber (ms)2000GUI の状態ポーリング間隔。下げすぎると CPU 使用率が上がる
consoleBufferSizenumber2000GUI のコンソールが保持する行数
portConflictCheckbooleantrueサーバーの起動前にポートの競合をチェック
languagestringOS から推定言語(ko、en、ja、de、es、fr、pt-BR、ru、zh-CN、zh-TW)。モジュールや Discord の返答にも使われる
themestringなし(GUI は auto を使用)"dark" / "light" / "auto"
osNotificationsbooleantrueクラッシュや予期しない起動・終了を OS 通知でも送る
daemonViewstringなし(switch)リモートデーモンがあるときのサーバー一覧の形。"switch" 選んだデーモンのみ、"unified" すべてのデーモンをまとめて表示
mainDaemonstringなし(この PC)アプリを開いたときに最初に表示するリモートデーモンの PC id(メインデーモン)

ほかに、色、フォントの倍率、ウィンドウサイズなどの外観に関するキーもあり、GUI の設定で変更した内容がそのまま保存されます。


4. relay: Discord 連携

Discord ボットはクラウドリレー上でのみ動作するため、PC にはボットのプロセスもボットのトークンもありません。この名前空間には、GUI で編集するプレフィックス、呼び名、Discord サーバーごとの設定が保存されます。ペアリング後、デーモンがそれらをリレーに同期します。

キー型既定値説明
prefixesstring[]Discord サーバーごとにプレフィックスを決めていないときに使うチャットコマンドのプレフィックス一覧(10個まで、それぞれスペースなしの1〜32文字)。Discord サーバーごとのプレフィックスは nodeSettings に入り、アプリの Discord サーバー → ボット設定 タブで変更します。空なら その Discord サーバーのボット言語(未設定なら PC アプリの言語)の既定値(韓国語 사바쨩、日本語 サバちゃん、その他 Saba-chan)を使う。文字で終わるプレフィックスの後ろにはスペース(またはカンマ・コロン)が必要
serverWordsobject{}サーバー(インスタンス ID)ごとの、そのサーバーとコマンドの呼び名 {words, commands}。サーバー画面の Discord タブで変更します
newGuildInstancesstring"auto"ペアリングコードで新しく接続した Discord サーバーに、この PC のサーバーをすべてすぐ開くか(auto)、後で選ぶか(manual)
nodeSettingsobject{}Discord サーバーごとの設定(許可するインスタンス、コマンドの権限、言語・プレフィックス・スラッシュコマンドの形・歌うサバちゃん・読み上げるサバちゃん・聞き返しの設定など)
cloudobjectrelayUrl、hostId。ペアリング時に設定される

以前のグローバルなエイリアス(moduleAliases、commandAliases、instanceAliases)は、デーモンの起動時に serverWords へ移して空にします。

nodeSettings 内の権限と Discord の設定は、それぞれ専用の画面(API)からのみ変更され、ボット設定全体を保存しても上書きされません。

コマンドの書式

サバちゃん <サーバー名またはエイリアス> <コマンド> [引数…]
  • サバちゃん minecraft start
  • サバちゃん mc stop(エイリアス)
  • サバちゃん palworld status
  • サバちゃん list: サーバー一覧、サバちゃん help: ヘルプ

すべてのサーバーに既定のコマンド start、stop、status があり、その他のコマンドはモジュールが定義します。音楽などの追加機能は、リレーサーバー側のボットが提供します。

remote: リモートデーモン

自分の他の PC がこのデーモンにつなぐリモートポートと、この PC がつなぐリモートデーモンの一覧です。アプリの設定 → 接続 → リモートデーモンか saba-chan-cli remote で変え、設定のエクスポートには含まれません。使い方はリモートデーモン。relay とは別に、config.json の最上位キーに保存されます。

キー型既定値説明
enabledbooleantrueリモートポートを開きます
portnumber57480リモートポート(TLS)
addressstringなし他の PC から届くグローバル IP やホスト名。空ならリレー経由でのみつなぎます
transportstring"direct"接続方式。今は "direct" だけなので、そのままにします
clientsarray[]このデーモンとペアになった PC(トークンはハッシュだけ保存)
daemonsarray[]この PC がつなぐリモートデーモン

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": {}
}
  • RCON はモジュールが supported = ["rcon"] と宣言したゲーム(コンソールも REST API もないゲーム)でのみ使い、その場合デーモンがインスタンスごとにポートとランダムなパスワードを割り当て、ループバック(127.0.0.1)でのみ接続します。それ以外のゲームのコマンドはサーバーのコンソール(stdin)に送られ、Palworld は REST API を使います。古いファイルに残っている RCON のキーは、読み込み時に削除されます。
  • extension_data はエクステンション用に予約された保存領域です。たとえば SteamCMD でインストールしたモジュールでは、インストール方法とアプリの情報がここに入ります。
  • サーバーの設定を保存するとき(GUI のサーバー設定、PATCH /api/instance/:id)、インスタンス共通のフィールドでもモジュールが宣言した設定でもないキーは、unknown_setting エラーで拒否されます。
  • インスタンスを削除すると、既定のインストール先(server\)にあるゲームサーバーのファイルと backups\ を含め、instances\<id>\ フォルダー全体が削除されます。

これらのファイルを手で編集するのは デーモンが動いていないときだけ にしてください。動作中に編集するとデーモンのメモリ上の状態とずれてしまい、次の保存で編集内容が上書きされます。


6. トークンファイル(.ipc_token / .node_token)

ファイル形式作成されるタイミング使用者
.ipc_tokenUUID v4(1行)デーモンが起動するたびに再生成GUI / CLI / モジュールとエクステンション(ローカル API の呼び出し)
.node_tokensbn_<hostId>.<secret>Discord のペアリング完了時にデーモンが保存デーモンのリレー接続

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 は、この PC を Discord ボット(クラウドリレー)に接続するための秘密情報です。デーモンはこれを HTTPS でリレーに送って認証します。絶対に誰にも見せないでください。漏えいが疑われる場合は、GUI からもう一度ペアリングしてください。再ペアリングすると古いトークンは無効になります。


7. エクステンションと隔離の設定(extensions / sandbox)

  • extensions.enabled: 有効なエクステンション ID の一覧。
  • extensions.settings: エクステンションごとの設定値 { "<id>": { "<key>": value } }。デーモン API PUT /api/extensions/:id/config で変更します。
  • sandbox.unisolated: 隔離環境を用意できなかったコンポーネントを、隔離せずに実行することへの同意です。コンポーネントのファイルのフィンガープリントとして保存され、いずれかのファイルが変わると再び確認されます。GUI の 設定 → セキュリティ →「隔離せずに実行」、または saba-chan-cli sandbox revoke <component> で取り消せます。

8. 主な環境変数

変数対象説明
SABA_IPC_PORTデーモン / CLIgui.ipcPort を上書き
SABA_DAEMONCLIコマンドを送るリモートデーモン。--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\ フォルダーは削除しないでください。サーバーの一覧と、既定の場所にインストールしたゲームファイルが一緒に消えてしまいます。