Руководство по конфигурационным файлам

Описывает папку данных Saba-chan, файл настроек config.json, папки экземпляров и файлы токенов на основе того, что реально делает код.

Руководство по конфигурационным файлам

Настройки и состояние Saba-chan хранятся в папке данных %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_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.

КлючТипПо умолчаниюОписание
ipcPortnumber57474Порт HTTP API демона (всегда открывается только на 127.0.0.1)
autoRefreshbooleantrueАвтоматическое обновление состояния в GUI
refreshIntervalnumber (мс)2000Интервал опроса состояния в GUI. Слишком малое значение повышает нагрузку на CPU
consoleBufferSizenumber2000Число строк, которые хранит консоль GUI
portConflictCheckbooleantrueПроверка конфликтов портов перед запуском сервера
languagestringопределяется по ОСЯзык (ko, en, ja, de, es, fr, pt-BR, ru, zh-CN, zh-TW). Используется также для ответов модулей и Discord
themestringнет (GUI использует auto)"dark" / "light" / "auto"
osNotificationsbooleantrueОтправлять сбои и неожиданные запуски или остановки также системными уведомлениями
daemonViewstringнет (switch)Вид списка серверов при наличии удалённых демонов. "switch" — только выбранный демон, "unified" — все демоны вместе
mainDaemonstringнет (этот ПК)ID ПК удалённого демона, который показывается первым при открытии приложения (главный демон)

Есть и ключи оформления — цвета, масштаб шрифта, размер окна; всё, что вы меняете в настройках GUI, сохраняется как есть.


4. relay: интеграция с Discord

Discord-бот работает только на облачном ретрансляторе, поэтому на вашем ПК нет ни процесса бота, ни токена бота. В этом пространстве имён хранятся префикс, обращения и настройки по серверам Discord, которые вы редактируете в GUI; после сопряжения демон синхронизирует их с ретранслятором.

КлючТипПо умолчаниюОписание
prefixesstring[]Префиксы текстовых команд, которые используются, если для сервера Discord префикс не задан отдельно (до 10, каждый от 1 до 32 символов без пробелов). Префиксы по серверам Discord хранятся в nodeSettings и меняются в приложении на вкладке «Серверы Discord» → Настройки бота. Если список пуст, используется значение по умолчанию для языка бота на этом сервере Discord (если не задан — языка приложения на ПК) (корейский 사바쨩, японский サバちゃん, иначе Saba-chan). После префикса, оканчивающегося буквой, должен идти пробел (или запятая либо двоеточие), чтобы сообщение считалось командой
serverWordsobject{}Для каждого сервера (ID экземпляра) — слова, которыми называют этот сервер и его команды: {words, commands}. Меняются на вкладке Discord экрана сервера
newGuildInstancesstring"auto"Открывать ли сразу все серверы этого ПК для сервера Discord, только что подключённого по коду сопряжения (auto), или выбрать позже (manual)
nodeSettingsobject{}Настройки по серверам Discord (разрешённые экземпляры, права на команды, язык, префикс, вид слэш-команд, настройки поющей и читающей вслух Saba-chan, уточняющие вопросы и т. д.)
cloudobjectrelayUrl, hostId. Заполняются при сопряжении

Прежние общие псевдонимы (moduleAliases, commandAliases, instanceAliases) демон при запуске переносит в serverWords и очищает.

Настройки прав и Discord внутри nodeSettings меняются только через предназначенные для них экраны (API); сохранение всей конфигурации бота их не перезаписывает.

Синтаксис команд

Saba-chan <server name or alias> <command> [arguments…]
  • Saba-chan minecraft start
  • Saba-chan mc stop (псевдоним)
  • Saba-chan palworld status
  • Saba-chan list: список серверов, Saba-chan help: справка

У каждого сервера есть команды по умолчанию start, stop и status; остальные команды определяет модуль. Дополнительные функции, например музыку, предоставляет бот на стороне сервера-ретранслятора.

remote: удалённый демон

Удалённый порт, к которому подключаются другие ваши ПК, и список удалённых демонов, к которым подключается этот ПК. Меняется в приложении в Настройки → Подключение → Удалённый демон или через saba-chan-cli remote. В экспорт настроек не входит. Как пользоваться: Удалённый демон. Это ключ верхнего уровня в config.json, отдельный от relay.

КлючТипПо умолчаниюОписание
enabledbooleantrueОткрывает удалённый порт
portnumber57480Удалённый порт (TLS)
addressstringнетПубличный IP или имя хоста, доступные вашим другим ПК. Если пусто, подключение только через ретранслятор
transportstring"direct"Способ подключения. Пока есть только "direct", оставьте как есть
clientsarray[]ПК, сопряжённые с этим демоном (токены хранятся только как хеш)
daemonsarray[]Удалённые демоны, к которым подключается этот ПК

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_tokenUUID v4 (одна строка)Создаётся заново при каждом запуске демона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: <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_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\: вместе с ней пропадут список серверов и файлы игр, установленные в место по умолчанию.