Руководство по конфигурационным файлам
Описывает папку данных Saba-chan, файл настроек config.json, папки экземпляров и файлы токенов на основе того, что реально делает код.
Руководство по конфигурационным файлам
Настройки и состояние Saba-chan хранятся в папке данных %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_tokenТокен подключения к Discord (облачный ретранслятор). Сохраняется демоном при сопряженииТокен подключения к Discord (облачный ретранслятор). Сохраняется демоном при сопряжении
- instances\Экземпляры серверовЭкземпляры серверов
- order.jsonПорядок в спискеПорядок в списке
- <id>\
- instance.jsonСведения об экземпляреСведения об экземпляре
- settings.jsonЗначения игровых настроек модуляЗначения игровых настроек модуля
- logs\Журналы консоли сервераЖурналы консоли сервера
- backups\БэкапыБэкапы
- server\Место установки по умолчанию (файлы игрового сервера)Место установки по умолчанию (файлы игрового сервера)
- modules\Установленные игровые модулиУстановленные игровые модули
- extensions\Установленные расширенияУстановленные расширения
- logs\Журналы GUI (saba-chan-<timestamp>.log)Журналы GUI (saba-chan-<timestamp>.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: файл со всеми настройками
Пользовательские настройки хранятся в одном файле config.json, сгруппированные по пространствам имён (ключам верхнего уровня).
| Пространство имён | Содержимое | Где меняется |
|---|---|---|
gui | Поведение GUI, тема, язык, порт демона | Настройки GUI |
relay | Интеграция с Discord (префикс, псевдонимы, настройки по серверам Discord) | Страница Discord в GUI |
updates | Интервал проверки обновлений, автозагрузка, канал обновлений (channel) | Настройки GUI |
remote | Удалённый демон: удалённый порт и сопряжённые ПК | Настройки GUI → Подключение → Удалённый демон |
boot | Последний выбранный режим загрузки (GUI / CLI / только демон) | Выбор режима загрузки |
extensions | Список включённых расширений enabled, настройки по расширениям settings | Настройки GUI → Расширения |
chatbot | Настройки Говорящей Saba-chan (ИИ-чат) | Страница Discord в GUI |
sandbox | Согласие на запуск непроверенных компонентов без изоляции | Запрос при заблокированном запуске, Настройки → Дополнительно |
cli и др. | Собственные настройки каждого клиента | Соответствующий клиент |
Сохранение и автоматическое восстановление
- Сохранение атомарное (запись во временный файл, затем замена), а последняя исправная копия непосредственно перед заменой сохраняется как
config.json.bak. - Если
config.jsonповреждён и не читается, демон отодвигает его вconfig.json.corrupt-<timestamp>и восстанавливает настройки из.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 (мс) | 2000 | Интервал опроса состояния в GUI. Слишком малое значение повышает нагрузку на CPU |
consoleBufferSize | number | 2000 | Число строк, которые хранит консоль GUI |
portConflictCheck | boolean | true | Проверка конфликтов портов перед запуском сервера |
language | string | определяется по ОС | Язык (ko, en, ja, de, es, fr, pt-BR, ru, zh-CN, zh-TW). Используется также для ответов модулей и Discord |
theme | string | нет (GUI использует auto) | "dark" / "light" / "auto" |
osNotifications | boolean | true | Отправлять сбои и неожиданные запуски или остановки также системными уведомлениями |
daemonView | string | нет (switch) | Вид списка серверов при наличии удалённых демонов. "switch" — только выбранный демон, "unified" — все демоны вместе |
mainDaemon | string | нет (этот ПК) | ID ПК удалённого демона, который показывается первым при открытии приложения (главный демон) |
Есть и ключи оформления — цвета, масштаб шрифта, размер окна; всё, что вы меняете в настройках GUI, сохраняется как есть.
4. relay: интеграция с Discord
Discord-бот работает только на облачном ретрансляторе, поэтому на вашем ПК нет ни процесса бота, ни токена бота. В этом пространстве имён хранятся префикс, обращения и настройки по серверам Discord, которые вы редактируете в GUI; после сопряжения демон синхронизирует их с ретранслятором.
| Ключ | Тип | По умолчанию | Описание |
|---|---|---|---|
prefixes | string | [] | Префиксы текстовых команд, которые используются, если для сервера Discord префикс не задан отдельно (до 10, каждый от 1 до 32 символов без пробелов). Префиксы по серверам Discord хранятся в nodeSettings и меняются в приложении на вкладке «Серверы Discord» → Настройки бота. Если список пуст, используется значение по умолчанию для языка бота на этом сервере Discord (если не задан — языка приложения на ПК) (корейский 사바쨩, японский サバちゃん, иначе Saba-chan). После префикса, оканчивающегося буквой, должен идти пробел (или запятая либо двоеточие), чтобы сообщение считалось командой |
serverWords | object | {} | Для каждого сервера (ID экземпляра) — слова, которыми называют этот сервер и его команды: {words, commands}. Меняются на вкладке Discord экрана сервера |
newGuildInstances | string | "auto" | Открывать ли сразу все серверы этого ПК для сервера Discord, только что подключённого по коду сопряжения (auto), или выбрать позже (manual) |
nodeSettings | object | {} | Настройки по серверам Discord (разрешённые экземпляры, права на команды, язык, префикс, вид слэш-команд, настройки поющей и читающей вслух Saba-chan, уточняющие вопросы и т. д.) |
cloud | object | relayUrl, hostId. Заполняются при сопряжении |
Прежние общие псевдонимы (
moduleAliases,commandAliases,instanceAliases) демон при запуске переносит вserverWordsи очищает.
Настройки прав и Discord внутри
nodeSettingsменяются только через предназначенные для них экраны (API); сохранение всей конфигурации бота их не перезаписывает.
Синтаксис команд
Saba-chan <server name or alias> <command> [arguments…]
Saba-chan minecraft startSaba-chan mc stop(псевдоним)Saba-chan palworld statusSaba-chan list: список серверов,Saba-chan help: справка
У каждого сервера есть команды по умолчанию start, stop и status; остальные команды определяет модуль. Дополнительные функции, например музыку, предоставляет бот на стороне сервера-ретранслятора.
remote: удалённый демон
Удалённый порт, к которому подключаются другие ваши ПК, и список удалённых демонов, к которым подключается этот ПК. Меняется в приложении в Настройки → Подключение → Удалённый демон или через saba-chan-cli remote. В экспорт настроек не входит. Как пользоваться: Удалённый демон. Это ключ верхнего уровня в config.json, отдельный от relay.
| Ключ | Тип | По умолчанию | Описание |
|---|---|---|---|
enabled | boolean | true | Открывает удалённый порт |
port | number | 57480 | Удалённый порт (TLS) |
address | string | нет | Публичный IP или имя хоста, доступные вашим другим ПК. Если пусто, подключение только через ретранслятор |
transport | string | "direct" | Способ подключения. Пока есть только "direct", оставьте как есть |
clients | array | [] | ПК, сопряжённые с этим демоном (токены хранятся только как хеш) |
daemons | array | [] | Удалённые демоны, к которым подключается этот ПК |
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); тогда демон назначает каждому экземпляру порт и случайный пароль и подключается только через loopback (127.0.0.1). Остальные игровые команды отправляются в консоль сервера (stdin), а Palworld использует свой REST API. Оставшиеся в старых файлах ключи RCON удаляются при загрузке. extension_data— зарезервированное хранилище для расширений. Например, для модулей, установленных через SteamCMD, здесь хранятся способ установки и сведения о приложении.- При сохранении настроек сервера (настройки сервера в GUI,
PATCH /api/instance/:id) ключи, которые не являются ни общими полями экземпляра, ни настройками, объявленными модулем, отклоняются с ошибкойunknown_setting. - Удаление экземпляра удаляет всю папку
instances\<id>\, включая файлы игрового сервера в месте установки по умолчанию (server\) иbackups\.
Править эти файлы вручную можно только когда демон не запущен. Если править их во время работы демона, они разойдутся с состоянием в его памяти, и следующее сохранение перезапишет вашу правку.
6. Файлы токенов (.ipc_token / .node_token)
| Файл | Формат | Когда создаётся | Кто использует |
|---|---|---|---|
.ipc_token | UUID v4 (одна строка) | Создаётся заново при каждом запуске демона | 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: <contents of the .ipc_token file>
- Токен меняется при каждом перезапуске демона. При ошибке аутентификации GUI и CLI заново читают файл токена, так что делать ничего не нужно.
- Расположение файла токена можно изменить через
SABA_TOKEN_PATH.
Токен узла
.node_token — это секрет, связывающий этот ПК с 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 | Демон / 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\: вместе с ней пропадут список серверов и файлы игр, установленные в место по умолчанию.