Устранение неполадок

Типичные проблемы при работе с Saba-chan и шаги по их решению, основанные на реальном поведении кода.

Устранение неполадок

Этот документ построен по симптомам, с которыми реально сталкиваются пользователи, и объясняет, как ведёт себя код демона, а также шаги по исправлению. Примеры команд и пути даны для Windows. В Linux папка данных — ~/.config/saba-chan.


1. Демон не запускается / GUI не может подключиться

1.1 Конфликт порта / демон уже запущен

Демон (saba-core) по умолчанию слушает порт 57474, только на 127.0.0.1.

  • На одном ПК работает только один демон. Если демон уже запущен, вновь запущенный сразу завершается, а GUI и CLI подключаются к уже работающему.
  • Если порт занят другой программой, демон делает 10 повторных попыток с интервалом 2 секунды и затем завершается.
# Windows: посмотреть, кто занимает порт
Get-NetTCPConnection -LocalPort 57474 | Select-Object OwningProcess
Get-Process -Id <pid>
  • Проверить, жив ли демон, можно без токена по адресу http://127.0.0.1:57474/health. saba-chan-cli daemon status показывает ту же информацию.
  • Если остался зависший демон, остановите его командой saba-chan-cli daemon stop. Если он всё равно не исчезает, выполните Stop-Process -Name saba-core -Force.
  • Если нужно сменить порт, отредактируйте gui.ipcPort в config.json и перезапустите. Либо задайте переменную окружения, например SABA_IPC_PORT=57480.

1.2 Несовпадение IPC-токена

Демон создаёт новый .ipc_token при каждом запуске. При ошибке аутентификации (401) GUI и CLI заново читают файл токена и повторяют запрос один раз, так что обычно проблема решается сама.

Если «ошибка аутентификации» повторяется снова и снова:

  • Проверьте, что GUI и демон смотрят в одну и ту же папку данных. Если SABA_DATA_DIR или SABA_TOKEN_PATH заданы только для одного из них, файлы токена окажутся в разных местах.
  • Полностью закройте GUI и запустите его снова.

2. Запуск/остановка сервера ведут себя странно

2.1 Нажал «Остановить», а какое-то время ничего не происходит

Это может быть нормой. Демон действует в таком порядке:

  1. Серверам с консолью он отправляет stop_command модуля в консоль (stdin). Для игр без консоли, например Palworld, модуль через REST просит сервер сохраниться и выключиться.
  2. Он ждёт, пока сервер завершится сам. По умолчанию — 30 секунд; модуль может изменить это значение через [config] stop_timeout в module.toml, а пользователь — для каждого сервера в поле Время ожидания остановки на вкладке Saba-chan экрана сервера. Если мир большой и сохранение занимает много времени, увеличьте его.
  3. Если сервер всё ещё жив, он завершается принудительно.
  4. В течение 30 секунд после остановки обнаружение сбоев подавляется.

Если сервер всегда завершается принудительно, значит, он не получает команду остановки. Проверьте, появляется ли команда остановки в консоли сервера. Примеры: stop в Minecraft, quit в Zomboid.

2.2 Сервер постоянно поднимается снова

Когда сервер завершается, демон классифицирует причину: остановлен вами / остановлен из игры / сбой / неизвестно. По умолчанию автоперезапуск происходит только при сбоях; ожидание начинается с 5 секунд и каждый раз удваивается, а после более чем 3 перезапусков за 10 минут демон прекращает перезапуски.

Решение:

  • Посмотрите классификацию в «Последние завершения» на экране сервера.
  • Чтобы прекратить перезапуски, выключите «Перезапускать после сбоя» в разделе «Автоперезапуск» на вкладке Saba-chan экрана сервера. Если вы включали «Перезапускать и при неизвестной причине», проверьте и его.
  • Причину сбоя ищите в журналах консоли сервера (instances\<id>\logs\). При OOM в Java (OutOfMemoryError) увеличьте настройку памяти.

2.3 Ошибка «конфликт порта» при запуске

Предстартовая проверка обнаружила, что порт сервера занят другим работающим экземпляром или другой программой. Обычно это значит, что предыдущий процесс ещё не завершился или тот же порт использует другой игровой сервер.

  • Найдите процесс, занимающий этот порт, и остановите его.
  • Если это невозможно, смените порт в настройках экземпляра и запустите снова.
  • Саму проверку можно выключить параметром «Обнаружение конфликта портов» в настройках GUI (gui.portConflictCheck), но делать это не рекомендуется.

2.4 «Требуется согласие» (EULA Minecraft и т. п.)

Для игр, модуль которых объявляет условия (например, EULA Minecraft), нужно прочитать и принять их, прежде чем сервер сможет запуститься. Пока вы этого не сделаете, запуск блокируется с кодом agreement_required.

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

2.5 Сохранение настроек сервера отклоняется

  • unknown_setting: ключ не является ни общим полем экземпляра, ни настройкой, объявленной модулем. Это опечатка или настройка другой игры.
  • validation_failed / invalid_format: диапазон или формат значения не соответствует объявлению модуля. Исправьте поле, указанное в ошибке.
  • «Настройки сохранены, но файл конфигурации игры обновить не удалось» — настройки сохранены, но модулю не удалось отредактировать конфигурационный файл игры. Убедитесь, что файл игры не заблокирован другой программой, и сохраните снова.

2.6 Непроверенный компонент не запускается

Модули и расширения, установленные не из официального каталога или чьи файлы были изменены позже, помечаются как «Не проверено». Saba-chan не проверяет их антивирусом. В Windows они запускаются в изолированной среде (AppContainer), в Linux — в bubblewrap; там, где изолировать нельзя (Linux без bubblewrap или с неработающим bubblewrap, macOS), они запускаются только после вашего согласия для их текущих файлов. Если запуск заблокирован, показывается один из этих кодов.

КодЗначениеЧто делать
launch_outside_instanceМодуль пытался запустить программу вне папки сервераПроверьте, откуда взялся модуль
sandbox_unavailableНа этом ПК не удалось подготовить изолированную средуСм. ниже

При sandbox_unavailable GUI спрашивает «Запустить без изоляции?». Разрешайте это только для компонентов, которым доверяете. Если разрешить, компонент получит доступ ко всем файлам и сети с правами вашей учётной записи. Дать согласие можно только на этом ПК, и оно запрашивается снова при изменении файлов компонента. Отозвать согласие можно в Настройки → Безопасность → «Запуск без изоляции».

Самое надёжное решение — переустановить модуль или расширение из официального каталога. Проверенные компоненты эти проверки пропускают.


3. Проблемы с установкой и обновлением

3.1 Установка прерывается на полпути

  • Когда установщик останавливается, на экране ошибки отображаются код причины (fetch_failed, download_failed, extract_failed, elevation_failed, installer_outdated) и путь к журналу. Журнал записывается в %TEMP%\saba-chan-installer.log.
  • installer_outdated означает, что установщик старше последнего релиза. Скачайте и запустите последнюю версию установщика.
  • При проблемах с сетью проверьте подключение, затем нажмите Retry или запустите установщик снова.
  • Сбой при подготовке среды выполнения Python не останавливает установку. Демон подготовит её заново при первом запуске, а повторный запуск установщика удалит повреждённую среду и скачает её заново.

3.2 Ход установки сервера не отображается или завис (для разработчиков модулей)

Ход установки сервера доступен по GET /api/provision-progress/:name.

  • Убедитесь, что модуль/расширение выводит прогресс в stderr в формате PROGRESS:{json}.
  • Убедитесь, что JSON корректен (экранируйте двойные кавычки и переводы строк внутри message).
  • Успешный прогресс удаляется через 5 секунд после завершения, поэтому при слишком позднем опросе он уже будет пуст. Неудачный прогресс остаётся, пока пользователь его не закроет, а если это был только что созданный сервер, закрытие удаляет этот экземпляр.

3.3 Обновление не применяется

Обновления проверяются по подписанным сведениям о релизах, которые предоставляет ретранслятор Saba-chan, а хеш каждого файла сверяется перед применением. Если подпись или хеш не совпадают, ничего не применяется.

  • Если после обновления появилось уведомление о том, что некоторые элементы обновить не удалось, нажмите на него, чтобы увидеть, какие именно.
  • Снова проверьте обновления в настройках GUI и примените их.
  • Обновления, заменяющие демон, GUI или сам установщик, применяются установщиком (saba-chan-installer) после завершения демона. Не запускайте Saba-chan заново, пока идёт применение.
  • Если это не помогает, закройте Saba-chan, очистите папку updates\ и попробуйте снова.

4. Discord-бот / облачное сопряжение

4.1 Бот не отвечает

  • Напишите префикс (по умолчанию Saba-chan), пробел, затем имя сервера и команду. Пример: Saba-chan minecraft status.
  • Сопряжение должно быть завершено в GUI, чтобы .node_token был сохранён.
  • Saba-chan (демон) должен быть запущен. Бот работает в облаке, но команды выполняет демон на этом ПК.
  • Если демон не может подключиться к ретранслятору, посмотрите последние предупреждения в GUI в Настройки → Устранение неполадок → «Диагностика». Если видите «older than relay minimum», обновите Saba-chan.
  • Убедитесь, что официальный бот приглашён на ваш сервер Discord и не спит. Если спит, разбудите его командой /saba wake.

4.2 Код сопряжения «истёк»

Код сопряжения действует всего 5 минут. Получите новый код в GUI.

4.3 Подключение к ретранслятору отклонено с кодом 401

ОшибкаПричинаЧто делать
TOKEN_REPLACEDПри сопряжении в другом месте этот ПК был выбран кнопкой Переподключить, и токен этого ПК заменёнВыполните сопряжение заново, если хотите продолжать пользоваться этим ПК
INVALID_TOKEN / NODE_NOT_FOUND.node_token неверен или был удалён на сервереВыполните сопряжение заново (старый токен аннулируется)
MISSING_TOKEN / INVALID_TOKEN_FORMATФайла токена нет или у него неверный форматВыполните сопряжение заново

4.4 Команды Поющей Saba-chan не работают

  • На странице Discord в GUI проверьте, включена ли Поющая Saba-chan в настройках этого сервера Discord.
  • Отправитель команды должен уже находиться в голосовом канале Discord. Если бот не может войти в голосовой канал, проверьте права бота в канале.
  • Воспроизведением занимается официальный музыкальный сервер, поэтому ffmpeg и yt-dlp на вашем ПК не нужны.

4.5 Не удаётся подключиться к удалённому демону

СообщениеЧто делать
Этот ПК не открыт для удалённых подключенийНа ПК-сервере Разрешить удалённые подключения в Настройки → Подключение → Удалённый демон выключено. Включите и сохраните
Не удалось связаться с удалённым демономПроверьте, что ПК-сервер и его Saba-chan включены и в сети. Если прямой доступ невозможен, подключение идёт через облако Saba-chan, так что проброс портов не обязателен
Этот ПК не подключён к DiscordСопрягите оба ПК с одним аккаунтом Discord
Удалённый демон больше не принимает этот ПКПК-сервер отключил этот ПК. Снова нажмите Подключить на своём ПК
Порт уже занятТот же порт использует другая программа. Смените порт
Это можно сделать только на том ПКОбновления, запуск при входе и подобное удалённо не делаются

4.6 Не открывается ссылка Saba-chan веб

  • Ссылка открывается один раз и в течение 5 минут. Получите новую через /saba web.
  • Если видите Не удалось подключиться к ПК, проверьте, что Saba-chan на ПК запущен и обновлён до последней версии.
  • В ссылке, открытой без ПК, меню серверов, модулей и ПК заблокированы. Установите приложение, выполните /saba connect и получите новую ссылку.
  • Закрытие вкладки или перезагрузка завершают сеанс. Это нормально.

5. Восстановление данных и настроек

5.1 config.json повреждён

  • Демон отодвигает повреждённый config.json в config.json.corrupt-<timestamp> и автоматически восстанавливает настройки из config.json.bak (последней исправной копии).
  • Если .bak тоже отсутствует или повреждён, демон запускается со значениями по умолчанию. Все настройки, включая настройки интеграции с Discord, сбрасываются, поэтому введите нужные значения в GUI заново, сверяясь с отодвинутым файлом .corrupt-.
  • Список серверов (instances\) и .node_token хранятся отдельно от config.json, поэтому они сохраняются.

5.2 Полный сброс

1. Закройте GUI, CLI и демон Saba-chan
2. Сделайте резервную копию и удалите всю папку %APPDATA%\saba-chan
3. Запустите Saba-chan → он создаст всё заново со значениями по умолчанию

Внимание: если вы устанавливали серверы в место по умолчанию, файлы игровых серверов и бэкапы находятся внутри %APPDATA%\saba-chan\instances\ и будут удалены вместе с ней. Файлы игр уцелеют, только если вы выбрали папку сервера вне этой папки.


6. Где найти журналы?

РасположениеСодержимое
%APPDATA%\saba-chan\logs\saba-chan-*.logЖурнал GUI. Содержит также вывод демона, запущенного из GUI
Окно консоли демона в GUIЖурнал демона (буфер в памяти, последние 10 000 строк)
Настройки GUI → Устранение неполадок → ДиагностикаСостояние демона и последние предупреждения/ошибки. Не содержит паролей и токенов
%APPDATA%\saba-chan\instances\<id>\logs\Журналы консоли сервера (console.log, sessions\)
Вкладка «Консоль» в GUIВывод игрового сервера для каждого экземпляра
%APPDATA%\saba-chan\audit.logЗапись запусков/остановок/команд серверов (с источником, секреты замаскированы)
%TEMP%\saba-chan-installer.logЖурнал установщика

Уровень журналирования демона можно изменить переменной окружения RUST_LOG при запуске демона напрямую (по умолчанию info).


7. Чек-лист для сообщения о проблеме

Перед тем как открыть новый issue, проверьте и приложите следующее.

  1. Версия Saba-chan (saba-chan-cli version или «Диагностика» в GUI).
  2. Шаги для воспроизведения.
  3. Соответствующие журналы (фрагменты, обрезанные по времени). Помогает и вывод кнопки «Копировать» в «Диагностике» GUI.
  4. ОС / сборка (например, Windows 10 x64 21H2).
  5. Никогда не прикладывайте файлы токенов (.ipc_token, .node_token) или их содержимое.

Репозитории: