awg-gus-bot/README.md

AWG для Гуся

Отдельный бот GusVoice для управления уже установленным AWG Toolza (awg2). Работает рядом с Telegram-ботом: своя служба, настройки и состояние; оба интерфейса управляют одними VPN-клиентами. Telegram Mini App не используется.

Версия 0.2.0 — v2, несколько Гусей → один AWG.

Добавить второго Гуся к существующей установке

Обновите программу, затем добавьте подключение:

sudo awg-gus-bot update
sudo awg-gus-bot add

Или повторно запустите скачанный новый установщик командой из раздела ниже и выберите «2. Добавить ещё одного Гуся». Он сначала обновит общую программу, затем откроет настройку нового подключения.

1. На втором сервере GusVoice создайте бота в «Настройки → Мои боты».
2. Введите короткое имя подключения, например gus2, адрес второго Гуся и его токен.
3. Отправьте показанный /start <код> этому боту в личку на втором Гусе.
4. После установки отправьте /menu — будут доступны те же AWG-клиенты.

Для третьего и следующих Гусей снова выполните sudo awg-gus-bot add. Имя подключения: до 32 символов, строчная латиница, цифры, _, -; первая — буква. Можно сразу задать его: sudo awg-gus-bot add gus2.

На каждом независимом Гусе нужен свой аккаунт бота и токен: боты GusVoice принадлежат своему инстансу. Программа и возможности одинаковые; один и тот же токен не нужно запускать несколькими процессами. Повторное добавление уже настроенного аккаунта отклоняется до начала polling.

У каждого подключения отдельные владелец, события, подтверждения, уведомления, SQLite и служба systemd. Падение/отключение одного Гуся не останавливает остальные. add запускает только новую службу; обновление общего кода кратковременно перезапускает работавшие службы ботов.

Первая установка 0.1.0 сохраняется как default: её токен, владелец, настройки, служба и база остаются на прежних местах. Повторная привязка первого бота при обновлении не требуется. Telegram продолжает управлять тем же AWG.

Установка

На том Linux-сервере, где уже работает awg2:

sudo bash -c 'set -e; f=$(mktemp); trap '\''rm -f -- "$f"'\'' EXIT; curl -fsSL https://gitea.bvrdo.online/wenil/awg-gus-bot/raw/branch/main/install.sh -o "$f"; bash "$f"'

Можно скачать и прочитать скрипт отдельно:

curl -fsSL https://gitea.bvrdo.online/wenil/awg-gus-bot/raw/branch/main/install.sh -o awg-gus-install.sh
less awg-gus-install.sh
sudo bash awg-gus-install.sh

Понадобятся:

1. Linux с systemd, Python 3.10+, работающая команда awg2 api version. Типичные системы: Debian 12/13, Ubuntu 22.04/24.04. Сам AWG установщик этого проекта не устанавливает и не обновляет.
2. GusVoice с Bot API 3+, включёнными ботами, кнопками, командами и HTML-разметкой.
3. Отдельный новый бот в «Настройки → Мои боты». Приватного режима достаточно для владельца.
4. HTTPS-адрес сайта Гуся и токен бота. Сертификат должен быть доверенным на AWG-сервере.

Установщик запросит адрес и токен (токен вводится скрыто), проверит API и покажет одноразовую команду /start <код>. Отправьте её в личную беседу с созданным ботом. Код действует 10 минут; случайное первое сообщение доступ не выдаёт. После подтверждения владелец будет записан по UUID. Затем отправьте /menu.

Адрес AWG-сервера вводить не нужно: бот выполняет локальный awg2 api. Если адрес сайта и API Гуся отличаются, официальный SDK определит API через config.json сайта. Нужен исходящий HTTPS-доступ от AWG-сервера к Гусю; открывать входящие порты не требуется — используется polling.

При отсутствии зависимостей установщик использует apt для python3, curl, tar, qrencode, ca-certificates. На других дистрибутивах установите эти программы самостоятельно. Python SDK включён в репозиторий; pip/PyPI для установки не нужны.

Возможности бота

• Главное меню со статусом сервера и клиента: работает/офлайн, IP, трафик.
• Список клиентов с перелистыванием, создание, переименование и удаление.
• Выдача .conf и PNG QR-кода одним сообщением; конфиг передаётся в qrencode через stdin.
• Перевыпуск ключа, сроки доступа, месячный/общий лимит трафика, скорость, сброс счётчика лимита.
• Диагностика AWG, перезапуск интерфейса после подтверждения.
• Создание и отправка резервной копии, экспорт клиентских конфигов.
• Уведомления об изменении состояния AWG и выбранных клиентов. По умолчанию выключены.

Все операции изменения AWG требуют кнопки подтверждения, действующей 2 минуты. Список разрешённых awg2 api операций зафиксирован в коде. Произвольных команд оболочки из чата нет. Проверка владельца и личной беседы выполняется для сообщений и кнопок.

Команды: /menu, /status, /clients, /new, /cancel, /whoami, /help.

Мониторинг проверяет состояние раз в минуту; клиент считается офлайн спустя 5 минут без рукопожатия. Включите «Следить» в карточке нужного клиента. Отдельный переключатель состояния сервера — в «Уведомлениях». После запуска бот запоминает текущее состояние без рассылки и пишет только при изменении.

Через меню awg2 остаются: установка/обновление AWG и модулей ядра, создание сервера, настройка туннелей/DNS/обфускаторов, массовое создание, восстановление бэкапа и удаление всей установки. Это отдельный нативный клиент основных функций, а не полная копия всех экранов Telegram-бота.

Сосуществование с Telegram

Компонент	Первое подключение default	Дополнительное gus2
Служба	awg-gus-bot.service	awg-gus-bot@gus2.service
Настройки (права 600)	/etc/awg-gus-bot.json	/etc/awg-gus-bot/instances/gus2.json
Состояние	/var/lib/awg-gus-bot/state.sqlite3	/var/lib/awg-gus-bot/instances/gus2/state.sqlite3

Общий код: /opt/awg-gus-bot/current → отдельная версия в releases/. Команда управления: /usr/local/bin/awg-gus-bot.

Установщик не меняет файлы и службу awg-bot, не обновляет awg2 и не перезапускает VPN. Данные VPN общие: если удалить клиента через любого Гуся, он исчезнет во всех Гусях и в Telegram. В проверенном upstream awg2 api изменяющие команды сериализованы общим flock. Если другой интерфейс занят длительной операцией, AWG может попросить повторить действие позже.

Бот работает от root, поскольку это требуется локальному awg2 api. Настройки, токены и база состояния не входят в git. В журнал пишутся типы ошибок, без токенов и конфигов VPN. Архивы и конфиги отправляются только владельцу в личку; в них содержатся ключи VPN.

Обновление и управление

sudo awg-gus-bot                 # меню управления подключениями
sudo awg-gus-bot add             # добавить ещё одного Гуся
sudo awg-gus-bot list            # имена, адреса, состояния всех подключений
sudo awg-gus-bot update          # обновить общий код из Gitea
sudo awg-gus-bot check           # проверить все подключения, включая недоступные
sudo awg-gus-bot check gus2      # проверить только второго Гуся
sudo awg-gus-bot status gus2
sudo awg-gus-bot logs gus2
sudo awg-gus-bot restart gus2
sudo awg-gus-bot stop gus2
sudo awg-gus-bot start gus2
sudo awg-gus-bot disable gus2    # остановить и убрать из автозапуска; настройки сохраняются
sudo awg-gus-bot enable gus2     # вернуть в автозапуск и запустить
sudo awg-gus-bot setup gus2      # повторная привязка того же аккаунта / замена его токена

Без имени logs/start/stop/restart/setup обращаются к default, а status/list/check — ко всем подключениям. Если default отсутствует и подключений несколько, имя нужно указывать явно.

Повторный запуск нового установщика предлагает обновить код или добавить подключение. Для обновления без меню: sudo bash install.sh --update. Настройки сохраняются без повторного запроса токена. Новая версия сначала скачивается и проверяется, затем переключается current. Если после обновления служба не запустилась, установщик возвращает прежний код и службы, затем запускает ранее работавшие подключения. Остановленные подключения обновляются вместе со всеми, но автоматически не включаются. Если не удалось добавить/перенастроить одного Гуся, восстанавливаются настройки и состояние только этого подключения. Старые версии программы автоматически не удаляются.

При смене на другой аккаунт бота база специально не переиспользуется: старые chat UUID и курсор событий принадлежат прежнему боту. Для другого аккаунта/инстанса используйте add; setup рассчитан на перепривязку того же аккаунта или обновление его токена.

Ограничения и проверка на сервере

• Файл до 25 МиБ. Большой архив остаётся на сервере — заберите его по SSH.
• Слишком длинный конфиг выдаётся файлом без QR. Если в журнале ошибка QR, проверьте qrencode --version.
• Отправка/редактирование ограничены примерно одним сообщением в секунду; ответы на кнопки выполняются отдельно.
• Пока длится действие в личке, новые нажатия получают ответ «операция выполняется».
• Курсор событий сохраняется до запуска действия, поэтому при сбое действие не повторится автоматически. После перезапуска бот сообщит о прерванной обработке. Проверьте фактическое состояние перед повтором. Это не обещание транзакции между чатом и AWG: действие могло выполниться до сбоя доставки ответа.
• Кнопки подтверждения и незавершённый ввод сбрасываются при перезапуске.
• Вторая копия с тем же токеном или ранее настроенный webhook мешают polling; используйте выделенного бота.

Первый ручной прогон:

1. /menu → проверить версию AWG, число клиентов, список и карточку существующего клиента.
2. Создать временного клиента, например gus-test-01, на 1 день.
3. Проверить скачивание .conf и отображение QR; импортировать конфиг и проверить соединение.
4. Убедиться, что этот же клиент появился в Telegram-боте.
5. Изменить срок/лимит, перезапустить только awg-gus-bot, повторно открыть /menu.
6. Добавить второго Гуся, проверить тот же список клиентов. Уведомления включаются отдельно в каждом боте.
7. Выполнить sudo awg-gus-bot stop gus2, проверить работу первого Гуся и Telegram, затем start gus2.
8. Удалить временного клиента с подтверждением; проверить, что он исчез во всех интерфейсах.

Разработка и происхождение

python3 -m unittest discover -s tests -v
bash -n install.sh
bash -n awg-gus-bot

Тесты проверяют права владельца, личку, подтверждения/отмену, повторные события после перезапуска, создание клиента, файлы и QR, лимиты, мониторинг, параллельные подключения с одинаковыми update ID, защиту от повторного polling, сохранение v1, добавление отдельной службы и откат настройки/базы при ошибке. Транспортные тесты используют настоящий включённый SDK и локальный HTTP-стенд. Вызовы AWG имитируются: эти тесты не меняют VPN и не подтверждают установку на реальном systemd-сервере.

• GusVoice Python SDK 0.1.0 включён без изменений в vendor/gusvoice_bot/ (MIT). Источник: Gleb1290/gusvoice, commit 3113f3106b8d0d0924449ae17489c81d076a4cb5.
• Контракт awg2 api сверялся с pumbaX/awg-multi-script, commit aedff0bc4b0099a3584bc3c519fa42758b5e672e (AWG Toolza bot 3.4.40). Идея экранов и ограничения имён/QR основаны на этом проекте (MIT).
• Лицензии и уведомления находятся в licenses/; лицензия этого проекта — MIT.

Официальный API: https://github.com/Gleb1290/gusvoice/blob/main/docs/bots.ru.md

AWG Toolza: https://github.com/pumbaX/awg-multi-script