# 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