Discord-бот и облачный ретранслятор

Настройка Discord-бота Saba-chan и порядок сопряжения с облачным ретранслятором, который позволяет управлять сервером без проброса портов.

Discord-бот и облачный ретранслятор

Server-chan (сервер-ретранслятор) — старшая сестра Saba-chan; она передаёт команды между Discord и вашим ПК. Discord-бот Saba-chan — это официальный бот, работающий на Server-chan. Вам не нужно самостоятельно запускать процесс бота или управлять токеном Discord. Пригласите официального бота на свой сервер Discord, а затем один раз выполните сопряжение с помощью кода из приложения Saba-chan.


1. Как это работает

Облако
DiscordКоманды через чат
Ретранслятор DiscordБот Saba-chan · облако
Ваш ПК
Демон Saba-chanВаш ПК
Игровой серверВаш ПК
  1. 1
    Демон Saba-chanРетранслятор Discord

    Ждать новые команды (long polling)

  2. 2
    DiscordРетранслятор Discord

    Отправить команду /saba … или чат

  3. 3
    Ретранслятор DiscordДемон Saba-chan

    Передать команду

  4. 4
    Демон Saba-chan

    Проверить права

  5. 5
    Демон Saba-chanИгровой сервер

    Запуск · консольная команда

  6. 6
    Демон Saba-chanРетранслятор Discord

    Отправить результат

  7. 7
    Ретранслятор DiscordDiscord

    Ответить результатом

ПК сам подключается наружу и забирает команды, поэтому порт на роутере открывать не нужно. Запросы подписываются токеном, выданным при сопряжении. Каждые 60 секунд демон сообщает ретранслятору список серверов и их состояние.
  • Сам бот работает внутри сервера-ретранслятора. На ваш ПК ничего, связанного с ботом, не устанавливается.
  • Игровые серверы работают на вашем ПК. Демон 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 Схема процесса

Ваш ПК
GUI-приложениеВаш ПК
Демон Saba-chanВаш ПК
Облако
Ретранслятор DiscordБот Saba-chan · облако
DiscordСлеш-команда
  1. 1
    GUI-приложениеДемон Saba-chan

    Запросить код сопряжения

  2. 2
    Демон Saba-chanРетранслятор Discord

    Выпустить код

  3. 3
    Ретранслятор DiscordДемон Saba-chan

    Код + секрет опроса (5 мин)

  4. 4
    Демон Saba-chanGUI-приложение

    Показать код

  5. 5
    DiscordРетранслятор Discord

    /saba connect code:…

  6. 6
    Ретранслятор Discord

    Зарегистрировать ПК · выдать токен узла

  7. 7
    GUI-приложениеДемон Saba-chan

    Проверять статус каждые 3 с

  8. 8
    Демон Saba-chanРетранслятор Discord

    Проверить статус (с секретом)

  9. 9
    Ретранслятор DiscordДемон Saba-chan

    Подключено + токен узла (один раз)

  10. 10
    Демон Saba-chan

    Сохранить токен · начать связь с ретранслятором

  11. 11
    Демон Saba-chanGUI-приложение

    Показать «подключено»

Даже если кто-то увидит код, без секрета опроса токен не получить. Токен выдаётся только один раз, и сохраняет его демон, а не GUI. Для сопряжения на сервере Discord нужно право «Управлять сервером».
  • Код сопряжения состоит из 32 символов, а pollSecret из 48 символов. Код действует 5 минут.
  • Токен выдаётся ровно один раз (атомарный обмен). Сохраняет его в .node_token сразу по получении демон, а не GUI, и тут же начинает подключение к ретранслятору. Приложение передаёт секрет опроса только демону на вашем ПК, а демон отправляет его ретранслятору в заголовке, а не в URL.
  • Даже если кто-то увидит ваш код сопряжения, без pollSecret перехватить токен невозможно.
  • К одному аккаунту Discord можно подключить несколько ПК. При подключении с аккаунта, у которого уже есть ПК, появляются кнопки Подключить как новый ПК и Переподключить для прежних ПК. После переподключения прежний токен этого ПК перестаёт работать. К одному серверу Discord можно подключить ПК нескольких людей (Discord).

2.2 Шаги в приложении

  1. В приложении Saba-chan откройте Discord → Подключение и нажмите Подключить сервер Discord.
  2. Если официального бота Saba-chan ещё нет на вашем сервере Discord, сначала пригласите его кнопкой Пригласить бота.
  3. На экране появятся код подключения и команда для ввода. Нажмите Копировать и введите её в канале Discord как /saba connect code:<code> (приложение может показывать корейское название /사바쨩 연결 코드:<code>; это та же команда).
  4. Выполнить эту команду могут только участники с правом Управлять сервером на этом сервере Discord. Если отправить её боту в личные сообщения, к вашему аккаунту подключается только ПК, без сервера Discord.
  5. Если это ваш первый раз с этим аккаунтом Discord, бот сначала предложит зарегистрироваться. По кнопке Зарегистрироваться вы ознакомитесь с условиями на сайте и зарегистрируетесь, после чего этот ответ сменится подтверждением подключения. Пока вы не согласились, ПК не подключается.
  6. Когда бот покажет кнопку с вопросом, подключать ли, нажмите Подключить. Если ввести чужой код, ПК этого человека подключится к вашему аккаунту, поэтому нажимайте, только если код получен прямо в приложении Saba-chan.
  7. Приложение каждые 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 не доходят до ПКЕсли при сопряжении в другом месте вы выбрали этот ПК кнопкой Переподключить, прежнее подключение этого ПК обрывается. Выполните сопряжение этого ПК заново

Более подробные сценарии диагностики — в документе Устранение неполадок.