# 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