199 lines
18 KiB
Markdown
199 lines
18 KiB
Markdown
# AWG для Гуся
|
||
|
||
Отдельный бот GusVoice для управления **уже установленным AWG Toolza (`awg2`)**.
|
||
Работает рядом с Telegram-ботом: своя служба, настройки и состояние; оба интерфейса управляют одними VPN-клиентами.
|
||
Telegram Mini App не используется.
|
||
|
||
Версия **0.2.0 — v2, несколько Гусей → один AWG**.
|
||
|
||
## Добавить второго Гуся к существующей установке
|
||
|
||
Обновите программу, затем добавьте подключение:
|
||
|
||
```bash
|
||
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`:
|
||
|
||
```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 для установки не нужны.
|
||
|
||
## Возможности бота
|
||
|
||
- Главное меню со статусом сервера и клиента: работает/офлайн, 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.
|
||
|
||
## Обновление и управление
|
||
|
||
```bash
|
||
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. Удалить временного клиента с подтверждением; проверить, что он исчез во всех интерфейсах.
|
||
|
||
## Разработка и происхождение
|
||
|
||
```bash
|
||
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
|