設定ファイルガイド
サバちゃんのデータフォルダー、設定ファイル config.json、インスタンスフォルダー、トークンファイルを、実際のコードの動作に基づいて説明します。
設定ファイルガイド
サバちゃんの設定と状態は、データフォルダー %APPDATA%\saba-chan(= C:\Users\<ユーザー名>\AppData\Roaming\saba-chan)の下にあります。このドキュメントでは、その中のファイルを 実際のコードがどう使っているか をまとめ、手で編集しても安全なファイルと触ってはいけないファイルを区別します。
すべての処理はデーモン(saba-core)が行い、GUI と CLI はデーモンのローカル HTTP API を呼び出すだけです。そのため、設定は GUI か CLI から変更するのが最も安全です。保存時にデーモンが形式をチェックするからです。
1. フォルダー構成
- 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 に、名前空間(トップレベルのキー)ごとにまとめて保存されます。
| 名前空間 | 内容 | 変更する場所 |
|---|---|---|
gui | GUI の動作、テーマ、言語、デーモンのポート | GUI の設定 |
relay | Discord 連携(プレフィックス、エイリアス、Discord サーバーごとの設定) | GUI の Discord ページ |
updates | アップデートの確認間隔、自動ダウンロード、アップデートチャンネル(channel) | GUI の設定 |
remote | リモートデーモン: リモートポート、ペアになった PC | GUI の設定 → 接続 → リモートデーモン |
boot | 最後に選んだ起動モード(GUI / CLI / デーモンのみ) | 起動モードの選択画面 |
extensions | 有効なエクステンションの一覧 enabled、エクステンションごとの設定 settings | GUI の設定 → 拡張機能 |
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 が読みます。
| キー | 型 | 既定値 | 説明 |
|---|---|---|---|
ipcPort | number | 57474 | デーモンの HTTP API ポート(常に 127.0.0.1 でのみ開く) |
autoRefresh | boolean | true | GUI の状態を自動で更新 |
refreshInterval | number (ms) | 2000 | GUI の状態ポーリング間隔。下げすぎると CPU 使用率が上がる |
consoleBufferSize | number | 2000 | GUI のコンソールが保持する行数 |
portConflictCheck | boolean | true | サーバーの起動前にポートの競合をチェック |
language | string | OS から推定 | 言語(ko、en、ja、de、es、fr、pt-BR、ru、zh-CN、zh-TW)。モジュールや Discord の返答にも使われる |
theme | string | なし(GUI は auto を使用) | "dark" / "light" / "auto" |
osNotifications | boolean | true | クラッシュや予期しない起動・終了を OS 通知でも送る |
daemonView | string | なし(switch) | リモートデーモンがあるときのサーバー一覧の形。"switch" 選んだデーモンのみ、"unified" すべてのデーモンをまとめて表示 |
mainDaemon | string | なし(この PC) | アプリを開いたときに最初に表示するリモートデーモンの PC id(メインデーモン) |
ほかに、色、フォントの倍率、ウィンドウサイズなどの外観に関するキーもあり、GUI の設定で変更した内容がそのまま保存されます。
4. relay: Discord 連携
Discord ボットはクラウドリレー上でのみ動作するため、PC にはボットのプロセスもボットのトークンもありません。この名前空間には、GUI で編集するプレフィックス、呼び名、Discord サーバーごとの設定が保存されます。ペアリング後、デーモンがそれらをリレーに同期します。
| キー | 型 | 既定値 | 説明 |
|---|---|---|---|
prefixes | string | [] | Discord サーバーごとにプレフィックスを決めていないときに使うチャットコマンドのプレフィックス一覧(10個まで、それぞれスペースなしの1〜32文字)。Discord サーバーごとのプレフィックスは nodeSettings に入り、アプリの Discord サーバー → ボット設定 タブで変更します。空なら その Discord サーバーのボット言語(未設定なら PC アプリの言語)の既定値(韓国語 사바쨩、日本語 サバちゃん、その他 Saba-chan)を使う。文字で終わるプレフィックスの後ろにはスペース(またはカンマ・コロン)が必要 |
serverWords | object | {} | サーバー(インスタンス ID)ごとの、そのサーバーとコマンドの呼び名 {words, commands}。サーバー画面の Discord タブで変更します |
newGuildInstances | string | "auto" | ペアリングコードで新しく接続した Discord サーバーに、この PC のサーバーをすべてすぐ開くか(auto)、後で選ぶか(manual) |
nodeSettings | object | {} | Discord サーバーごとの設定(許可するインスタンス、コマンドの権限、言語・プレフィックス・スラッシュコマンドの形・歌うサバちゃん・読み上げるサバちゃん・聞き返しの設定など) |
cloud | object | relayUrl、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 の最上位キーに保存されます。
| キー | 型 | 既定値 | 説明 |
|---|---|---|---|
enabled | boolean | true | リモートポートを開きます |
port | number | 57480 | リモートポート(TLS) |
address | string | なし | 他の PC から届くグローバル IP やホスト名。空ならリレー経由でのみつなぎます |
transport | string | "direct" | 接続方式。今は "direct" だけなので、そのままにします |
clients | array | [] | このデーモンとペアになった PC(トークンはハッシュだけ保存) |
daemons | array | [] | この 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_token | UUID v4(1行) | デーモンが起動するたびに再生成 | GUI / CLI / モジュールとエクステンション(ローカル API の呼び出し) |
.node_token | sbn_<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 } }。デーモン APIPUT /api/extensions/:id/configで変更します。sandbox.unisolated: 隔離環境を用意できなかったコンポーネントを、隔離せずに実行することへの同意です。コンポーネントのファイルのフィンガープリントとして保存され、いずれかのファイルが変わると再び確認されます。GUI の 設定 → セキュリティ →「隔離せずに実行」、またはsaba-chan-cli sandbox revoke <component>で取り消せます。
8. 主な環境変数
| 変数 | 対象 | 説明 |
|---|---|---|
SABA_IPC_PORT | デーモン / CLI | gui.ipcPort を上書き |
SABA_DAEMON | CLI | コマンドを送るリモートデーモン。--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\ フォルダーは削除しないでください。サーバーの一覧と、既定の場所にインストールしたゲームファイルが一緒に消えてしまいます。