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

Версия 0.1.0 — первая версия для проверки на реальном сервере.

Установка

На том 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

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

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

Что умеет 0.1.0

Главное меню со статусом сервера и клиента: работает/офлайн, 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

Компонент	Этот бот
Служба	`awg-gus-bot.service`
Программа	`/opt/awg-gus-bot/current` → отдельная версия в `releases/`
Настройки	`/etc/awg-gus-bot.json`, права `600`
Состояние	`/var/lib/awg-gus-bot`, отдельная SQLite-база
Управление	`/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 update    # загрузить новую версию из Gitea
sudo awg-gus-bot check     # проверить токен, возможности Гуся и awg2 api
sudo awg-gus-bot status
sudo awg-gus-bot logs
sudo awg-gus-bot restart
sudo awg-gus-bot stop
sudo awg-gus-bot start
sudo awg-gus-bot setup     # повторная настройка/привязка того же бота

Повторная установка тоже обновляет программу. Настройки сохраняются без повторного запроса токена. Новая версия сначала скачивается и проверяется, затем переключается current. Если служба не запустилась, установщик возвращает прежние программу/службу/настройки и запускает прежнюю службу, если она работала до обновления. Старые версии автоматически не удаляются.

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

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

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

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

/menu → проверить версию AWG, число клиентов, список и карточку существующего клиента.
Создать временного клиента, например gus-test-01, на 1 день.
Проверить скачивание .conf и отображение QR; импортировать конфиг и проверить соединение.
Убедиться, что этот же клиент появился в Telegram-боте.
Изменить срок/лимит, перезапустить только awg-gus-bot, повторно открыть /menu.
Удалить временного клиента с подтверждением; проверить, что Telegram-бот продолжает работать.

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

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

Тесты проверяют права владельца, личку, подтверждения/отмену, повторные события после перезапуска, создание клиента, файлы и QR, лимиты, мониторинг. Транспортные тесты используют настоящий включённый 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

README.md Unescape Escape

AWG для Гуся