Add v2 support for independent GusVoice connections to one AWG server

README.md

@@ -4,7 +4,39 @@
 Работает рядом с Telegram-ботом: своя служба, настройки и состояние; оба интерфейса управляют одними VPN-клиентами.
 Telegram Mini App не используется.
 
-Версия **0.1.0 — первая версия для проверки на реальном сервере**.
+Версия **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.
 
 ## Установка
 
@@ -41,7 +73,7 @@ sudo bash awg-gus-install.sh
 При отсутствии зависимостей установщик использует apt для `python3`, `curl`, `tar`, `qrencode`, `ca-certificates`.
 На других дистрибутивах установите эти программы самостоятельно. Python SDK включён в репозиторий; pip/PyPI для установки не нужны.
 
-## Что умеет 0.1.0
+## Возможности бота
 
 - Главное меню со статусом сервера и клиента: работает/офлайн, IP, трафик.
 - Список клиентов с перелистыванием, создание, переименование и удаление.
@@ -61,22 +93,23 @@ sudo bash awg-gus-install.sh
 Включите «Следить» в карточке нужного клиента. Отдельный переключатель состояния сервера — в «Уведомлениях».
 После запуска бот запоминает текущее состояние без рассылки и пишет только при изменении.
 
-В первой версии через меню `awg2` остаются: установка/обновление AWG и модулей ядра, создание сервера,
+Через меню `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` |
+| Компонент | Первое подключение `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.
+**Данные VPN общие:** если удалить клиента через любого Гуся, он исчезнет во всех Гусях и в Telegram.
 В проверенном upstream `awg2 api` изменяющие команды сериализованы общим `flock`.
 Если другой интерфейс занят длительной операцией, AWG может попросить повторить действие позже.
 
@@ -87,24 +120,35 @@ sudo bash awg-gus-install.sh
 ## Обновление и управление
 
 ```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     # повторная настройка/привязка того же бота
+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 и курсор событий принадлежат прежнему боту.
-Для такого переноса сначала сохраните текущую установку и подготовьте новое состояние; `setup` рассчитан на перепривязку того же аккаунта
-или обновление его токена.
+Для другого аккаунта/инстанса используйте `add`; `setup` рассчитан на перепривязку того же аккаунта или обновление его токена.
 
 ## Ограничения и проверка на сервере
 
@@ -125,7 +169,9 @@ sudo awg-gus-bot setup     # повторная настройка/привяз
 3. Проверить скачивание `.conf` и отображение QR; импортировать конфиг и проверить соединение.
 4. Убедиться, что этот же клиент появился в Telegram-боте.
 5. Изменить срок/лимит, перезапустить только `awg-gus-bot`, повторно открыть `/menu`.
-6. Удалить временного клиента с подтверждением; проверить, что Telegram-бот продолжает работать.
+6. Добавить второго Гуся, проверить тот же список клиентов. Уведомления включаются отдельно в каждом боте.
+7. Выполнить `sudo awg-gus-bot stop gus2`, проверить работу первого Гуся и Telegram, затем `start gus2`.
+8. Удалить временного клиента с подтверждением; проверить, что он исчез во всех интерфейсах.
 
 ## Разработка и происхождение
 
@@ -136,7 +182,9 @@ bash -n awg-gus-bot
 ```
 
 Тесты проверяют права владельца, личку, подтверждения/отмену, повторные события после перезапуска,
-создание клиента, файлы и QR, лимиты, мониторинг. Транспортные тесты используют настоящий включённый SDK
+создание клиента, файлы и QR, лимиты, мониторинг, параллельные подключения с одинаковыми update ID,
+защиту от повторного polling, сохранение v1, добавление отдельной службы и откат настройки/базы при ошибке.
+Транспортные тесты используют настоящий включённый SDK
 и локальный HTTP-стенд. Вызовы AWG имитируются: эти тесты не меняют VPN и не подтверждают установку на реальном systemd-сервере.
 
 - GusVoice Python SDK **0.1.0** включён без изменений в `vendor/gusvoice_bot/` (MIT).