Начало работы
Руководство по установке, настройке и эксплуатации Saba-chan: архитектура во время работы и поведение системы при эксплуатации.
Начало работы
В этом документе описаны базовые шаги установки, настройки и создания сервера в Saba-chan. Об удалённой интеграции и решении проблем читайте в документах Discord-бот и Устранение неполадок.
1. Загрузка и установка
Требования: Windows 10 или 11 (64-бит), Microsoft Edge WebView2 Runtime (входит в Windows 11 и свежие версии Windows 10) и подключение к интернету. Демон и CLI можно также установить на Linux-сервер без экрана (x86_64, см. 1.1 ниже). На macOS (Apple silicon) скачайте .dmg на главной странице и перетащите приложение в «Программы». Приложение не нотаризовано Apple: если macOS заблокирует его при первом запуске, разрешите открытие в «Системных настройках» → «Конфиденциальность и безопасность».
- Скачайте установщик
saba-chan-installer.exeкнопкой загрузки на сайте или со страницы GitHub Releases. - Запустите установщик, выберите место установки, игровые модули для первоначальной установки и параметры ярлыков, затем нажмите
Install.- Место установки по умолчанию —
C:\Program Files\Saba-chan. Если выбрать папку, в которой уже есть другие файлы, установщик создаст внутри неё папкуSaba-chan. - Игровые модули можно добавить и позже, из приложения.
- Место установки по умолчанию —
- Установщик настраивает следующие компоненты. В зависимости от подключения это может занять несколько минут.
- Проверяет последний подписанный релиз, затем загружает и разворачивает демон, GUI, CLI, файлы локализации и другие компоненты (хеш каждого файла сверяется). Установщик также остаётся в папке установки: он понадобится позже, чтобы применять обновления и удалять Saba-chan
- Устанавливает выбранные игровые модули и нужные им расширения (например, SteamCMD)
- Загружает портативный Python и создаёт окружение
venv(устанавливается в папку Saba-chan; системныйPATHне меняется) - Записывает версии установленных компонентов в
installed-manifest.json
- Когда установка завершится, нажмите
Launch Saba-chan, чтобы открыть GUI. Запустить его можно и с ярлыка на рабочем столе или в меню «Пуск».
Настройки, файлы игровых серверов, миры и бэкапы хранятся в %APPDATA%\saba-chan. Удаление папки программы не удаляет данные ваших серверов.
Переустановка: если установка прервалась на полпути или файлы повреждены, запустите установщик ещё раз. Он заново загрузит файлы программы, а повреждённую среду выполнения Python удалит и скачает снова. Ваши настройки и данные серверов сохранятся. Установщик старше текущего релиза блокируется, поэтому всегда скачивайте последнюю версию установщика.
1.1 Linux-сервер
На Linux-сервер без экрана (x86_64) устанавливаются только демон и CLI, без экранов приложения. Нужны curl, unzip, sha256sum и python3.
curl -fsSL https://raw.githubusercontent.com/WareAoba/saba-chan/main/install.sh | sh
- Установщик скачивает последний стабильный релиз, сверяет файлы с хешами релиза и его подписанным манифестом, устанавливает его, создаёт
~/.local/bin/saba-chan-cliи запускает демон как пользовательскую службу systemd (saba-chan.service). Папка установки и модули выбираются так:sh -s -- --dir <папка> --modules <модуль…>. - Чтобы он запускался при загрузке без входа в систему, один раз выполните
sudo loginctl enable-linger $USER. - Папка данных —
~/.config/saba-chan. - Linux-сервером управляют из приложения на ПК с Windows как удалённым демоном. Подключение к Discord и включение удалённых подключений описаны в главе Удалённый демон.
2. Архитектура Saba-chan
Схема ниже показывает, как связаны компоненты Saba-chan и как они обмениваются данными:
- Демон (
saba-core.exe): ядро, которое выполняет все функции Saba-chan. Он запускает процессы серверов и управляет ими, собирает журналы и открывает HTTP API только на локальном адресе127.0.0.1:57474. - GUI: настольное приложение, которое вызывает API демона.
- CLI: инструмент командной строки, который вызывает API демона. При запуске без аргументов открывает интерактивную оболочку.
- Раннер (
saba-runner): небольшой процесс-наблюдатель, прикреплённый к каждому серверу. Он сохраняет непрерывность консоли и журналов сервера даже при перезапуске демона. - Сервер-ретранслятор (relay): облачный сервис, на котором работает Discord-бот. После сопряжения демон подключается наружу (long-polling), чтобы получать команды управления из Discord, и каждый запрос аутентифицируется по HTTPS токеном узла, полученным при сопряжении. Ретранслятор передаёт только команды Discord, их результаты и сводки по серверам, но не игровой трафик, поэтому сетевой доступ для игроков, заходящих в игру, нужно настраивать отдельно.
Игровые серверы работают на вашем собственном ПК. GUI и CLI только отправляют запросы демону; сами они никогда не редактируют файлы и не запускают процессы.
Если закрыть окно через «Закрыть интерфейс», демон и игровые серверы продолжат работать в фоне. При повторном открытии GUI переподключается к демону и подхватывает текущее состояние серверов и журналы консоли. Если демон перезапустится, он заново подключится (re-attach) к работающим процессам серверов и возобновит мониторинг (процессы, завершившиеся из-за отключения питания или перезагрузки системы, не восстанавливаются). Чтобы остановить отдельный игровой сервер, нажмите
Остановитьв интерфейсе.
3. Создание первого сервера (через GUI)
При первом запуске Saba-chan список серверов пуст, а карточка «Следующий шаг» подскажет, как установить игровой модуль и создать первый сервер. Если ни одного игрового модуля ещё нет, сначала установите его из Saba Хранилище в приложении. Затем создайте сервер по шагам:
- Добавьте сервер: нажмите
Добавить сервери выберитеДобавить как новый сервер. Чтобы подключить папку сервера, которой вы уже пользуетесь, выберитеМиграция сервера. - Выберите игру: выберите один из установленных игровых модулей (официальные модули: Minecraft, Palworld, Project Zomboid и Terraria).
- Настройте сервер: введите имя сервера и заполните параметры, которые запрашивает модуль (например, тип сервера Minecraft), а также рекомендуемую конфигурацию. Порт (номер, по которому игра принимает игроков) назначается автоматически, чтобы не пересекаться с другими серверами.
- Примите условия: в играх, требующих принять условия (EULA), например в Minecraft, нужно самому прочитать условия и отметить флажок, прежде чем сервер можно будет создать. Saba-chan никогда не принимает условия автоматически.
- Начните установку: после нажатия
Добавить сервердемон выполняет задачи настройки в следующем порядке:- Проверяет расширения, нужные модулю (например, Palworld и Project Zomboid требуют SteamCMD). Если нужное расширение выключено, вам предложат включить его в Настройки → Расширения.
- Сохраняет данные экземпляра в папку
%APPDATA%\saba-chan\instances\<ID экземпляра>\ - Выполняет хук
server.post_create - Загружает последнюю версию файлов игрового сервера в каталог
server\папки экземпляра (официальная загрузка сервера для Minecraft и Terraria, SteamCMD для Palworld и Project Zomboid). Ход загрузки отображается на индикаторе прогресса.
- Запустите: при нажатии
Запуститьдемон проверяет, приняты ли нужные условия, и выполняет предстартовые проверки, выполняет хукserver.pre_start, а затем запускает процесс командой запуска модуля (get_launch_command). Вывод консоли сервера в реальном времени отображается в консоли GUI.
Каждая игровая команда проходит через демон в порядке stdin (консоль сервера) → REST → RCON. Игры с консолью или REST API (как Palworld) запускаются с выключенным RCON. RCON использует только игра, которая не поддерживает ничего, кроме RCON; порт и случайный пароль для каждого экземпляра назначает демон, подключение — только через loopback (127.0.0.1).
4. Что важно знать при эксплуатации
4.1 Тайм-аут остановки
Для процессов, которыми демон управляет напрямую, при нажатии Остановить демон пытается завершить их в следующем порядке. Значения определены в src/supervisor/mod.rs.
- Корректная остановка: отправляет
stop_commandмодуля (например,stopв Minecraft,quitв Zomboid) в консоль сервера (stdin). Для игры без консольного ввода (Palworld) модуль через REST API просит сервер сохраниться и выключиться. Затем демон ждёт время ожидания остановки (значение, заданное на вкладке Saba-chan экрана сервера; если его нет, то[config].stop_timeoutизmodule.toml; если и его нет, то 30 секунд). Если тайм-аут превышен, демон принудительно завершает процесс и ждёт ещё 2 секунды. - Принудительное завершение: при принудительном завершении дерево процессов немедленно уничтожается, после чего следует ожидание до 5 секунд.
- Пауза после остановки: в течение 30 секунд после остановки автоматическое обнаружение сбоев приостанавливается. Так штатное завершение не будет записано как сбой.
4.2 Обработка сбоев
Когда сервер завершается, демон классифицирует причину как Остановлен вами, Остановлен из игры, Сбой или Неизвестно и записывает её в список «Последние завершения» сервера. Завершение считается сбоем только при наличии доказательств, например ненормального кода выхода или файла сбоя, объявленного модулем; без доказательств оно не считается сбоем.
- Автоперезапуск: включается и выключается в разделе «Автоперезапуск» на вкладке Saba-chan экрана сервера.
Перезапускать после сбояпо умолчанию включено, аПерезапускать и при неизвестной причинепо умолчанию выключено. Серверы, которые вы остановили сами или которые были остановлены из игры, никогда не перезапускаются. - Интервал перезапуска: первый перезапуск происходит через 5 секунд, и с каждым перезапуском ожидание удваивается. После более чем 3 перезапусков за 10 минут Saba-chan прекращает перезапуски. Проверьте журналы и запустите сервер вручную.
4.3 Расположение журналов
- Журналы GUI:
%APPDATA%\saba-chan\logs\(сюда же записывается вывод демона, запущенного из GUI). Журналы демона можно также посмотреть командойsaba-chan-cli daemon logs. - Журналы консоли сервера:
%APPDATA%\saba-chan\instances\<ID экземпляра>\logs\. Серверы, запущенные через раннер, создают файл вsessions\при каждом запуске и по умолчанию хранят 20 таких файлов. - Просмотр консоли: демон хранит в памяти последние 10 000 строк каждого экземпляра. GUI опрашивает эндпоинт
GET /api/instance/:id/console?since=…с курсором, в пределах своего лимита отображенияconsoleBufferSize(по умолчанию 2000 строк).
5. Что дальше
- Повседневная работа — запуск и остановка серверов, бэкапы и задачи по расписанию: Управление серверами
- Удалённое управление серверами командами Discord: Discord-бот и облачный ретранслятор
- Настройка файла настроек (
config.json): Руководство по конфигурационным файлам - Решение типичных ошибок: Устранение неполадок
- Разработка собственных игровых модулей: Руководство по разработке модулей