Discord-бот и облачный ретранслятор
Настройка Discord-бота Saba-chan и порядок сопряжения с облачным ретранслятором, который позволяет управлять сервером без проброса портов.
Discord-бот и облачный ретранслятор
Server-chan (сервер-ретранслятор) — старшая сестра Saba-chan; она передаёт команды между Discord и вашим ПК. Discord-бот Saba-chan — это официальный бот, работающий на Server-chan. Вам не нужно самостоятельно запускать процесс бота или управлять токеном Discord. Пригласите официального бота на свой сервер Discord, а затем один раз выполните сопряжение с помощью кода из приложения Saba-chan.
1. Как это работает
- 1Демон Saba-chanРетранслятор Discord
Ждать новые команды (long polling)
- 2DiscordРетранслятор Discord
Отправить команду /saba … или чат
- 3Ретранслятор DiscordДемон Saba-chan
Передать команду
- 4Демон Saba-chan
Проверить права
- 5Демон Saba-chanИгровой сервер
Запуск · консольная команда
- 6Демон Saba-chanРетранслятор Discord
Отправить результат
- 7Ретранслятор DiscordDiscord
Ответить результатом
- Сам бот работает внутри сервера-ретранслятора. На ваш ПК ничего, связанного с ботом, не устанавливается.
- Игровые серверы работают на вашем ПК. Демон Saba-chan на вашем ПК подключается к ретранслятору исходящим соединением по long-polling, забирает команды и отправляет обратно результаты.
- Демон отправляет игровые команды в порядке stdin (консоль сервера) → REST → RCON. Palworld использует свой REST API. RCON используется только для игры, поддерживающей лишь RCON, и только через loopback (127.0.0.1).
- Трафик демон ↔ ретранслятор — это только исходящий HTTPS с вашего ПК. Проброс портов на роутере не нужен.
- Поющая Saba-chan обрабатывается на стороне ретранслятора, не проходя через ваш ПК, поэтому работает даже при выключенном ПК.
2. Сопряжение
Сопряжение регистрирует на сервере-ретрансляторе хост (демон Saba-chan) и узлы (серверы Discord). Оно завершается однократным вводом кода.
2.1 Схема процесса
- 1GUI-приложениеДемон Saba-chan
Запросить код сопряжения
- 2Демон Saba-chanРетранслятор Discord
Выпустить код
- 3Ретранслятор DiscordДемон Saba-chan
Код + секрет опроса (5 мин)
- 4Демон Saba-chanGUI-приложение
Показать код
- 5DiscordРетранслятор Discord
/saba connect code:…
- 6Ретранслятор Discord
Зарегистрировать ПК · выдать токен узла
- 7GUI-приложениеДемон Saba-chan
Проверять статус каждые 3 с
- 8Демон Saba-chanРетранслятор Discord
Проверить статус (с секретом)
- 9Ретранслятор DiscordДемон Saba-chan
Подключено + токен узла (один раз)
- 10Демон Saba-chan
Сохранить токен · начать связь с ретранслятором
- 11Демон Saba-chanGUI-приложение
Показать «подключено»
- Код сопряжения состоит из 32 символов, а
pollSecretиз 48 символов. Код действует 5 минут. - Токен выдаётся ровно один раз (атомарный обмен). Сохраняет его в
.node_tokenсразу по получении демон, а не GUI, и тут же начинает подключение к ретранслятору. Приложение передаёт секрет опроса только демону на вашем ПК, а демон отправляет его ретранслятору в заголовке, а не в URL. - Даже если кто-то увидит ваш код сопряжения, без
pollSecretперехватить токен невозможно. - К одному аккаунту Discord можно подключить несколько ПК. При подключении с аккаунта, у которого уже есть ПК, появляются кнопки
Подключить как новый ПКиПереподключитьдля прежних ПК. После переподключения прежний токен этого ПК перестаёт работать. К одному серверу Discord можно подключить ПК нескольких людей (Discord).
2.2 Шаги в приложении
- В приложении Saba-chan откройте Discord → Подключение и нажмите Подключить сервер Discord.
- Если официального бота Saba-chan ещё нет на вашем сервере Discord, сначала пригласите его кнопкой Пригласить бота.
- На экране появятся код подключения и команда для ввода. Нажмите Копировать и введите её в канале Discord как
/saba connect code:<code>(приложение может показывать корейское название/사바쨩 연결 코드:<code>; это та же команда). - Выполнить эту команду могут только участники с правом Управлять сервером на этом сервере Discord. Если отправить её боту в личные сообщения, к вашему аккаунту подключается только ПК, без сервера Discord.
- Если это ваш первый раз с этим аккаунтом Discord, бот сначала предложит зарегистрироваться. По кнопке
Зарегистрироватьсявы ознакомитесь с условиями на сайте и зарегистрируетесь, после чего этот ответ сменится подтверждением подключения. Пока вы не согласились, ПК не подключается. - Когда бот покажет кнопку с вопросом, подключать ли, нажмите
Подключить. Если ввести чужой код, ПК этого человека подключится к вашему аккаунту, поэтому нажимайте, только если код получен прямо в приложении Saba-chan. - Приложение каждые 3 секунды проверяет состояние через демон и переключается на «Подключено», как только демон сохранит
.node_token.
После сопряжения демон автоматически поддерживает long-poll-соединение с ретранслятором. Если выключить переключатель Передача команд в приложении, ваш ПК перестанет получать команды из Discord и бот не будет отвечать.
2.3 Подключение другого сервера Discord без кода
Если ваша учётная запись Discord уже сопряжена, на другом сервере Discord можно выполнить просто /saba connect (без кода).
- Бот сразу подключает к этому серверу Discord все ПК, привязанные к вашему аккаунту. Принимать что-либо на ПК или выбирать ПК не нужно.
- Если аккаунт новый, сначала регистрация. После неё этот сервер Discord тоже регистрируется в Saba-chan и, если ПК не подключён, остаётся сервером без ПК (§2.5). Если аккаунт зарегистрирован, но ПК нет, бот предложит подключиться по коду сопряжения.
- К такому подключённому серверу Discord сначала не привязан ни один игровой сервер. В приложении Saba-chan на ПК выберите, какие серверы использовать для этого сервера Discord.
- Сервер Discord, подключённый по коду сопряжения, подчиняется настройке Сразу открывать мои серверы для нового сервера Discord на экране подключения Discord в приложении. Если она включена, все серверы видны сразу, если выключена — вы выбираете их сами.
- Как и при подключении по коду, нужно право Управлять сервером. Если к серверу Discord уже подключён другой ПК, его не отбирают, а добавляют ваш ПК рядом с ним.
2.4 Отмена сопряжения
- Нажмите Отключить в приложении → демон останавливает передачу команд и удаляет
.node_token. Этот ПК отключается от всех серверов Discord. - Чтобы отвязать только один сервер Discord, выполните на нём
/saba disconnect. Это может сделать только тот, кто его подключил, или владелец сервера Discord; назначения каналов этого сервера тоже удаляются.
2.5 Серверы Discord без ПК
Даже те, кто не установил приложение Saba-chan, могут пригласить бота и пользоваться Поющей Saba-chan, Говорящей Saba-chan, Читающей Saba-chan, командами управления сервером и игровой статистикой.
- Настройки хранятся в Server-chan. Владелец сервера Discord или участник с правом Управлять сервером меняет язык, назначение каналов Говорящей и Поющей Saba-chan, увеличение эмодзи, настройки Говорящей Saba-chan и настройки Читающей Saba-chan. Это делается командами Discord
/sabaили в Saba-chan веб; при первом изменении нужна регистрация. - Уровней Saba-chan (лестницы прав) и команд игровых серверов нет. Каналы оповещений, игрового чата и панели состояния назначить нельзя, потому что их данные присылает ПК.
- Когда вы позже подключите ПК, настройки сохранятся, и с этого момента их источником становится этот ПК.
- Для обычного использования участниками, например прослушивания музыки или общения, регистрация не нужна.
3. Слэш-команды бота
Это команды под корневой командой официального бота. В клиентах Discord, где выбран язык, отличный от корейского, корневая команда отображается как /saba с английскими названиями подкоманд; на корейском — как /사바쨩. На сервере Discord без подключённого ПК видны только connect, assign, language, settings, reading, web, big-emoji и help, а вместо «владельца узла» их использует владелец сервера Discord или участник с правом «Управлять сервером». Остальные слэш-команды (/tts, /stats, /clear и другие) описаны в документе Команды.
| Команда | Кто | Действие |
|---|---|---|
/saba status | Любой | Показывает состояние ПК, подключённого к этому серверу, и каждого игрового сервера (CPU, RAM) |
/saba connect [code] | Право «Управлять сервером» | Подключает по коду сопряжения. Если оставить код пустым, подключает к этому серверу все ПК вашего аккаунта (§2.3). Если это первый раз, сначала регистрация |
/saba disconnect | Подключивший или владелец сервера | Отключает этот сервер от ПК |
/saba permission <level> [user] | Владелец узла | Если выбрать пользователя, выдаёт этому участнику уровень команд (пункт Снять в списке уровней удаляет индивидуальный уровень и возвращает уровень по умолчанию); если не выбирать, задаёт уровень по умолчанию для участников без собственного уровня (изначально Пользователь). Список уровней — это лестница прав этого сервера |
| Правый щелчок по участнику → Приложения → Изменить уровень Saba-chan | Владелец узла | Выбирает уровень команд этого участника из списка (есть и пункт Снять). То же, что /saba permission. Меню видно только тем, у кого есть право управлять сервером |
/saba sleep | Владелец узла | Усыпляет бота на этом сервере (игнорирует все сообщения) |
/saba wake | Владелец узла | Будит бота |
/saba assign kind:<Говорящая Saba-chan|Поющая Saba-chan|Оповещения|Игровой чат|Status board> | Владелец узла, владелец сервера | Назначает этот канал каналом Говорящей Saba-chan (несколько, до 20; Говорящая Saba-chan общается только в них), каналом Поющей Saba-chan (один; обычные сообщения удаляются, поэтому запрашивается подтверждение), каналом оповещений (один; уведомления о сбоях сервера, обновлениях, бэкапах и перезапусках по расписанию, а также кнопка Перезапустить в оповещениях о сбоях), каналом игрового чата (один; пересылает чат внутри игрового сервера) или каналом панели состояния (один; по одной карточке состояния на каждый запущенный сервер). Подробности — в разделе «Функции каналов» документа Команды. У канала может быть только один тип; повторный запуск того же типа снимает назначение. Также можно изменить на вкладке Управление сервером → Назначения Saba-chan сервера Discord в приложении |
/saba language <language> | Владелец узла | Язык, на котором бот отвечает на этом сервере (Авто = следовать языку привязанного приложения) |
/saba reading | Владелец узла | Громкость, скорость, высота голоса Читающей Saba-chan и обращение по имени на этом сервере. Видно только вам |
/saba big-emoji state:<On|Off> | Владелец узла, владелец сервера | Заменяет сообщение с единственным пользовательским эмодзи крупной картинкой (по умолчанию выключено) |
/saba web | Любой (свой аккаунт) | Одноразовая ссылка (5 минут) на Saba-chan веб. Если есть ПК, то и для него, иначе — только для настроек серверов Discord, которыми вы управляете. Видно только вам |
/saba settings | Владелец узла | Меняет настройки Говорящей Saba-chan на этом сервере (вкл./выкл., вмешательство в разговор, память, ИИ-модерация, уровень подтверждения перед выполнением, наборы инструментов по категориям, слова-триггеры). Инструмент, заблокированный в приложении в разделе «Все разрешённые инструменты», включить нельзя. Видно только вам |
/saba help | Любой | Показывает, как пользоваться Saba-chan, и список команд (видно только вам) |
/mysaba web | Любой (свой аккаунт) | То же, что /saba web. Работает на любом сервере и в личных сообщениях |
/mysaba my-pcs | Любой (свои ПК) | Список ПК, подключённых к вашему аккаунту Discord, переименование и удаление (видно только вам) |
/mysaba agent | Любой (свой аккаунт) | Просмотр и отключение ИИ-агентов (удалённый MCP), подключённых к вашему аккаунту Discord. Если их нет, показывает адрес, который нужно ввести в агенте. Работает в личных сообщениях, видно только вам (Подключение ИИ-агента) |
/saba update | Тот, кто подключил ПК | Проверяет обновления Saba-chan на ПК, подключённом к этому серверу, и применяет их после нажатия кнопки подтверждения |
/mysaba — команды вашего аккаунта, поэтому в списке участников сервера они не видны. Если после подключения ПК установить Saba-chan в свой аккаунт Discord кнопкой Установить в мой аккаунт, которую показывает бот, команды будут доступны на любом сервере и в личных сообщениях и видны только вам. В личных сообщениях с ботом их можно использовать и без установки: /saba web, /saba my-pcs, /saba agent.
На сервере Discord с подключённым ПК источником настроек прав, сна, языка, Поющей и Читающей Saba-chan является настройка Saba-chan на вашем ПК, поэтому эти команды действуют, пока ПК включён (для сервера без ПК см. §2.5). Те же настройки можно изменить на экране сервера Discord в приложении. Права — на экранах Уровни команд и Уровни участников, которые открываются нажатием на сервер на вкладке Экземпляры; Поющая и Читающая Saba-chan — на своих вкладках; язык, префикс и вид слэш-команд — на вкладке Настройки бота. Усыпить сразу все серверы Discord можно на экране Discord → Подключение.
3.1 Слэш-команды серверов и меню действий
После подключения бот регистрирует на каждом сервере Discord отдельные команды.
/<имя сервера> command:<команда> arg1:… arg2:…: по одной команде на каждый экземпляр игрового сервера. В списке команд Discord виден по одной строке на сервер. Нажмите поле command, и появится список команд, доступных на этом сервере (запуск, остановка, состояние, действия, команды модуля); если вводить буквы, список сужается по названию. Поля аргументов показывают, в зависимости от выбранной команды, список вариантов, да/нет, диапазон чисел или подсказку для ввода.- Из списка исключаются команды, недоступные вашему уровню, и команды, не подходящие текущему состоянию сервера (запуск запущенного сервера, остановка остановленного); недавно использованные вами на этом сервере команды идут первыми. Действительно ли команду можно выполнить, ещё раз решает приложение Saba-chan.
- Действия: действия, которые приложение Saba-chan открывает для Discord (перезапуск, резервная копия и т. д.), тоже попадают в тот же список команд. Действия, которым по настройкам уточняющих вопросов (§5) нужно подтверждение, показывают, что изменится, и запросивший должен нажать кнопку запуска. Обновления приложения Saba-chan нет в меню действий; используйте
/saba update. - Игроки: у серверов, чья игра это поддерживает, в списке появляется команда
игроки: сколько людей в сети и их имена. - Восстановить резервную копию: выберите копию из списка (ввод названия сужает список). Если сервер запущен, бот сначала спросит, остановить ли его; Остановить и продолжить остановит сервер и затем восстановит. Восстановление — опасное действие, поэтому подтверждение запрашивается ещё раз. Нажимать кнопки может только тот, кто попросил.
- Уведомление о готовности: если запустить или перезапустить сервер его командой
/<имя сервера>, кнопкой Перезапустить в уведомлении или через Говорящую Saba-chan, в тот же канал придёт сообщение, когда он начнёт принимать игроков. Если запуск не удался, придёт причина одной строкой. - Отображаются только экземпляры, разрешённые для этого сервера (вкладка Экземпляры сервера Discord в приложении).
4. Текстовые команды (префикс)
После сопряжения управлять серверами можно из текстовых каналов Discord с помощью команд с префиксом.
Saba-chan <server> <command> [args…]
Префикс по умолчанию — Saba-chan. Его можно изменить или дополнить для каждого сервера Discord на вкладке Настройки бота (Префикс команд) в разделе «Серверы Discord» приложения.
<server> — это имя экземпляра, псевдоним сервера либо имя или псевдоним модуля. Команды, общие для всех модулей:
| Команда | Описание |
|---|---|
start | Запускает сервер. Пример: Saba-chan minecraft start |
stop | Останавливает сервер |
status | Запрашивает состояние |
Слова, которыми называют сервер и его команды, задаются на вкладке Discord экрана сервера в приложении. Полный список команд — в документе Команды.
5. Уровни прав
Уровни: Владелец (3) > Админ (2) > Пользователь (1) > Гость (0) > Запрещён (-1). Уровни накопительные: верхний уровень может использовать все команды нижних.
- Владелец — это тот, кто подключил сервер (владелец узла). Он может использовать все команды, и его нельзя понизить.
- У каждой команды есть уровень риска (Безопасная, Осторожно, Опасная). С пресетом по умолчанию требуемые уровни таковы: Безопасная = Гость, Осторожно = Пользователь, Опасная = Админ. Пресет (Свободно, По умолчанию, Строго) выбирается, а чипы команд переносятся на другие уровни на лестнице Уровни команд: в приложении откройте вкладку Экземпляры сервера Discord и нажмите на сервер. Уровни участников и уровень по умолчанию задаются там же в Уровнях участников и действуют сразу для всех серверов этого сервера Discord.
- Справку и список может использовать любой, кроме участников с уровнем «Запрещён». Участники с уровнем Запрещён не могут пользоваться никакими функциями бота, включая Поющую и Говорящую Saba-chan.
- Запросы, проходящие через Говорящую Saba-chan, не могут превышать Предел Говорящей Saba-chan (по умолчанию уровень Гость).
Уточняющие вопросы: спрашивать ли у запросившего подтверждение кнопкой перед выполнением, задаётся в карточке Уточняющие вопросы на вкладке Настройки бота сервера Discord в приложении (или командой saba-chan-cli bot confirm). Для запросов, сделанных боту напрямую (префикс, слэш-команды), сначала спрашивают только про опасные команды, а Говорящая Saba-chan сначала спрашивает про все; в обоих случаях можно выбрать Все команды, Осторожно и выше, Только опасные или Не спрашивать. Уровень риска, по которому команда определяет, спрашивать ли, можно изменить в окне редактирования чипа на экране прав (требуемый уровень при этом не меняется). Административные действия, выбранные Говорящей Saba-chan, спрашиваются всегда, независимо от настройки. Нажать кнопку подтверждения может только тот, кто сделал запрос.
6. Поющая Saba-chan
Воспроизведением музыки занимается официальный музыкальный сервер (music-server), работающий рядом с сервером-ретранслятором.
- Когда вы выполняете команду вроде
Saba-chan play …, бот передаёт её музыкальному серверу, который транслирует звук в голосовой канал Discord. - Устанавливать ffmpeg/yt-dlp на ваш ПК не нужно.
- Музыкальные команды работают в любом канале. Если назначить канал Поющей Saba-chan командой
/saba assign kind:Поющая Saba-chan, в нём можно вводить команды без префикса (или просто поисковый запрос), и там отображается экран плеера. - Поющая Saba-chan включена по умолчанию; выключить её можно на вкладке Поющая Saba-chan сервера Discord в приложении. На серверах, где она включена, появляется слэш-команда
/music(Команды, раздел «Команды Поющей Saba-chan»).
7. Говорящая Saba-chan (ИИ-чат)
- Говорящая Saba-chan работает только после того, как вы зарегистрируете API-ключ в приложении и включите её для каждого сервера Discord (на вкладке Говорящая Saba-chan экрана сервера Discord или командой
/saba settings; для нового сервера она выключена). Ключ известен только вашему ПК и ретранслятору и никогда не показывается в Discord. - Инструменты (управление игровыми серверами, веб-поиск, статистика League of Legends, TFT и PUBG, персонажи MapleStory, поиск по нескольким играм, бытовая информация, генерация изображений) тоже включаются для каждого сервера Discord. Инструмент, заблокированный в общем меню приложения в разделе Все разрешённые инструменты, не используется ни на одном сервере. Если не включить инструмент игровых серверов, серверами она не управляет.
- Говорящая Saba-chan общается только в каналах, назначенных командой
/saba assign kind:Говорящая Saba-chan. В других каналах она не отвечает, даже если её позвать. - Говорящая Saba-chan может использовать только действия, которые модуль или расширение открыли для неё. Всё остальное отклоняется.
- Запросы данных выполняются сразу. Действия, которые что-то меняют, сначала превращаются в план и проходят через кнопку подтверждения в соответствии с уровнем уточняющих вопросов (§5, сначала — все команды). Административные действия всегда проходят через кнопку подтверждения. Нажать кнопку может только тот, кто попросил.
- Она никогда не выполняет команды выше предела Говорящей Saba-chan (§5).
- Если Говорящая Saba-chan включена, текстовую команду, которую демон не распознал, Говорящая Saba-chan превращает в точную команду и пробует выполнить ещё раз.
- Спросите Говорящую Saba-chan о логах — она прочитает логи сервера, включая прошлые запуски. Попросите файл — она приложит
.log, не пропуская его через ИИ (до 4 МиБ, сохраняется последняя часть; IP, секреты и пути скрыты).
8. Модель безопасности
- Демон отправляет токен узла, полученный при сопряжении (
sbn_{hostId}.{secret}), в заголовкеAuthorization: Bearerпо HTTPS. Ретранслятор сверяет этот токен с сохранённым хешем Argon2. - Сервер-ретранслятор никогда не хранит сам токен; он сравнивает его с хешем Argon2.
- Демон не принимает входящих соединений. Пароли игровых серверов на ретранслятор не отправляются.
9. Устранение неполадок
| Симптом | Причина / решение |
|---|---|
| Бот не отвечает | Проверьте префикс (по умолчанию Saba-chan) и наличие пробела после него. Бот должен быть на сервере, сопряжение должно быть завершено, а Передача команд в приложении — включена. Также проверьте, не усыплён ли бот командой /saba sleep |
Saba-chan … start → сервер не найден | Первое слово — сервер (имя/псевдоним экземпляра или имя/псевдоним модуля), второе — команда. Если у вас несколько серверов одной игры, используйте имя экземпляра или псевдоним сервера |
| Код сопряжения истёк | Код действует 5 минут, и это время прошло. Получите новый код в приложении |
| Приложение всё время ждёт | Проверьте, что слэш-команда /saba connect действительно была выполнена и что у вас есть право «Управлять сервером» |
| Команды из Discord не доходят до ПК | Если при сопряжении в другом месте вы выбрали этот ПК кнопкой Переподключить, прежнее подключение этого ПК обрывается. Выполните сопряжение этого ПК заново |
Более подробные сценарии диагностики — в документе Устранение неполадок.