151 lines
13 KiB
Markdown
151 lines
13 KiB
Markdown
# AWG для Гуся
|
||
|
||
Отдельный бот GusVoice для управления **уже установленным AWG Toolza (`awg2`)**.
|
||
Работает рядом с Telegram-ботом: своя служба, настройки и состояние; оба интерфейса управляют одними VPN-клиентами.
|
||
Telegram Mini App не используется.
|
||
|
||
Версия **0.1.0 — первая версия для проверки на реальном сервере**.
|
||
|
||
## Установка
|
||
|
||
На том Linux-сервере, где уже работает `awg2`:
|
||
|
||
```bash
|
||
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"'
|
||
```
|
||
|
||
Можно скачать и прочитать скрипт отдельно:
|
||
|
||
```bash
|
||
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 для установки не нужны.
|
||
|
||
## Что умеет 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.
|
||
|
||
## Обновление и управление
|
||
|
||
```bash
|
||
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; используйте выделенного бота.
|
||
|
||
Первый ручной прогон:
|
||
|
||
1. `/menu` → проверить версию AWG, число клиентов, список и карточку существующего клиента.
|
||
2. Создать временного клиента, например `gus-test-01`, на 1 день.
|
||
3. Проверить скачивание `.conf` и отображение QR; импортировать конфиг и проверить соединение.
|
||
4. Убедиться, что этот же клиент появился в Telegram-боте.
|
||
5. Изменить срок/лимит, перезапустить только `awg-gus-bot`, повторно открыть `/menu`.
|
||
6. Удалить временного клиента с подтверждением; проверить, что Telegram-бот продолжает работать.
|
||
|
||
## Разработка и происхождение
|
||
|
||
```bash
|
||
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
|