diff --git a/README.md b/README.md index ccd9604..34209a2 100644 --- a/README.md +++ b/README.md @@ -1,64 +1,97 @@ -# AmneziaVPN Telegram Bot +# amnezia-bot (форк) -Телеграм-бот на Python для управления [AmneziaVPN](https://github.com/amnezia-vpn/amnezia-client). Этот бот позволяет легко управлять клиентами. +Telegram-бот на Python для управления сервером AmneziaVPN / AmneziaWG: выдача и отзыв клиентских конфигов, срок действия подписки, промокоды, резервные копии. Бот работает на том же сервере, где развёрнут AmneziaWG в Docker-контейнере, и управляет им через `docker exec` и правку `wg0.conf`. -Используется библиотека `aiogram` версии 2.25.2. -Протестировано на Ubuntu, версии 20.04, 22.04, 24.04. +Форк сделан как резервная копия исходного проекта [stevefoxru/amnezia-bot](https://github.com/stevefoxru/amnezia-bot) в самохостовом Gitea — чтобы код оставался доступен независимо от судьбы репозитория на GitHub. -## Оглавление +Документация оригинала (установка, возможности, поддержка) сохранена в [README.upstream.md](README.upstream.md). -- [Возможности](#возможности) -- [Установка](#установка) -- [Запуск](#запуск) -- [Заметки](#заметки) -- [Поддержка](#поддержка) +## Отличия от оригинала -## Возможности +Изменений нет. Все 85 коммитов принадлежат автору оригинала (`stevefoxru`), собственных правок владельца форка в истории нет. Форк взят как резервная копия. -- Добавление администраторов и модераторов для упралением VPN -- Добавление клиентов -- Удаление клиентов -- Получение информации об IP-адресе клиента (берется из Endpoint, используется API ресурса [ip-api.com](http://ip-api.com)) -- Создание ключа в формате `vpn://` при генерации нового клиента (так же, при получении конфигурации клиента), для использования в [AmneziaVPN](https://github.com/amnezia-vpn/amnezia-client) -- Создание резервной копии -- Инструкции по работе с VPN +## Стек -## Установка +- Python 3.11 +- aiogram 2.25.2 (Telegram Bot API, inline-меню, FSM) +- aiohttp 3.8.6, aiofiles — HTTP-запросы и асинхронный файловый ввод-вывод +- APScheduler 3.10.4 — планировщик (истечение срока подписок) +- pytz, humanize, Babel — время и форматирование +- yookassa 2.4.0, YooMoney 0.1.0 — заявлены в `requirements.txt`, в коде не используются +- Bash-скрипты + Docker CLI + `wg`/`awg` для управления WireGuard/AmneziaWG +- Хранение данных — JSON-файлы (не БД) -1. Установите [AmneziaVPN](https://github.com/amnezia-vpn/amnezia-client) (без данного шага бот РАБОТАТЬ НЕ БУДЕТ). -2. Пройдите первоначальную [инициализацию](https://docs.amnezia.org/ru/documentation/instructions/install-vpn-on-server/), выбрав протокол AmneziaWG, в клиенте [AmneziaVPN](https://github.com/amnezia-vpn/amnezia-client). +## Структура -3. Создайте бота в Telegram: +| Путь | Назначение | +|---|---| +| `awg/bot_manager.py` | Точка входа бота (`executor.start_polling`), ~1000 строк: inline-меню, все callback-обработчики (добавление/удаление клиентов, список, конфиги, промокоды, бэкапы, настройки цен, админы/модераторы) | +| `awg/db.py` | Слой данных: чтение/запись JSON-файлов `files/config.json`, `files/user_expiration.json`, `files/user_telegram.json`, `files/promocodes.json`; работа со списком клиентов и промокодами | +| `awg/wg.py` | Генерация пары ключей WireGuard, выделение IP из подсети `10.0.0.0/24`, добавление пира в `wg0.conf`, `wg syncconf` внутри контейнера `amnezia-awg` | +| `awg/awg-decode.py` | Кодирование/декодирование конфига в ссылку формата `vpn://` (Qt-совместимое zlib-сжатие + base64) для импорта в клиент AmneziaVPN | +| `awg/newclient.sh` | Создание клиента: аргументы `CLIENT_NAME ENDPOINT WG_CONFIG_FILE DOCKER_CONTAINER`, генерация `.conf` | +| `awg/removeclient.sh` | Удаление клиента из конфигурации сервера | +| `handlers/add_client.py` | Отдельный FSM-обработчик `/add_client` с выбором протокола WireGuard/XRay; **не подключён** к боту (импортирует несуществующий модуль `loader`) | +| `install.sh` | Bash-скрипт: клонирование репозитория в `/root/amnezia-bot`, проверка обновлений через GitHub API, самообновление, пересоздание venv, перезапуск службы `awg_bot` | +| `requirements.txt` | Пиннутые версии Python-зависимостей | +| `LICENSE` | GPL-3.0 | -- Откройте Telegram и найдите бота [BotFather](https://t.me/BotFather). -- Начните диалог, отправив команду `/start`. -- Введите команду `/newbot`, чтобы создать нового бота. -- Следуйте инструкциям BotFather, чтобы: - - Придумать имя для вашего бота (например, `AmneziaWGBot`). - - Придумать уникальное имя пользователя для бота (например, `AmneziaWGManagerBot_bot`). Оно должно оканчиваться на `_bot`. -- После создания бота BotFather отправит вам токен для доступа к API. Его запросит бот во время первоначальной инициализации. +Каталог `awg/files/` (конфиги, JSON-состояние, `wg0.conf`) в репозиторий не входит и создаётся на сервере при работе. -4. Получите ваш Telegram ID с помощью [Get My ID](https://t.me/getmyid_bot), просто написав боту. +## Как собрать/запустить -5. Загрузите и запустите скрипт `install.sh`, с помощью которого будет автоматически установлен бот, со всеми зависимостями, в том числе, в качестве системной службы (автозапуск): +Предполагается уже установленный и инициализированный AmneziaVPN с протоколом AmneziaWG. - ```bash - curl -O https://raw.githubusercontent.com/stevefoxru/amnezia-bot/main/install.sh && chmod +x install.sh && ./install.sh - ``` +Установка/обновление через штатный скрипт (от root): -## Запуск +```bash +curl -O https://raw.githubusercontent.com/stevefoxru/amnezia-bot/main/install.sh +chmod +x install.sh +./install.sh # интерактивная проверка обновлений +./install.sh --check-update # то же без вопросов +``` -1. Добавьте бота в Telegram и отправьте команду `/start` или `/help` для начала работы. +Скрипт требует `git`, `curl`, `jq`, `python3.11`, работает с каталогом `/root/amnezia-bot` и службой systemd `awg_bot`. -## Заметки +Ручной запуск: -Для обновления бота, необходимо запустить скрипт `install.sh`. В меню, необходимо выбрать пункт `Проверить обновления`. +```bash +python3.11 -m venv myenv +source myenv/bin/activate +pip install -r requirements.txt +cd awg && python3.11 bot_manager.py +``` -При создании резервной копии, в архив добавляется директория connections (создается и содержит в себе логи подключений клиентов), conf, png, и сам конфигурационный файл. +Перед запуском должен существовать `awg/files/config.json` — без обязательных полей бот завершается с ошибкой. -## Поддержка +## Конфигурация -Поддержать разработчика можете следующими способами: +Все настройки — в `awg/files/config.json` (в репозиторий не входит). Обязательные поля: +| Ключ | Назначение | +|---|---| +| `bot_token` | Токен Telegram-бота от BotFather — реальное значение хранить только в `config.json` на сервере | +| `admin_ids` | Список Telegram ID администраторов (полный доступ) | +| `moderator_ids` | Список Telegram ID модераторов (ограниченное меню) | +| `wg_config_file` | Путь к конфигурации WireGuard/AmneziaWG на сервере | +| `docker_container` | Имя Docker-контейнера AmneziaWG (в коде `wg.py` жёстко `amnezia-awg`) | +| `endpoint` | Внешний адрес сервера, подставляемый в клиентские конфиги | +| `pricing` | Необязательный словарь цен: `1_month`, `3_months`, `6_months`, `12_months` (по умолчанию 1000/2500/4500/8000) | -Если у вас возникли вопросы или проблемы с установкой и использованием бота, создайте [issue](https://github.com/stevefoxru/amnezia-bot/issues) в этом репозитории или обратитесь к разработчику. +Прочие файлы состояния в `awg/files/`: `user_expiration.json` (сроки и лимиты трафика), `user_telegram.json` (привязка клиента к Telegram ID), `promocodes.json` (промокоды). + +Пути `/root/amnezia-bot/...` захардкожены в `wg.py` и `install.sh` — при установке в другой каталог потребуется правка кода. + +Секретов в репозитории нет: токены и ключи в код не закоммичены. + +## Состояние + +Рабочий, но заброшенный: 85 коммитов, последний — 28.04.2025 (`stevefoxru`, «Update install.sh»). Собственных коммитов владельца форка нет, поэтому дата последней своей правки отсутствует. + +## Что не доделано + +- `handlers/add_client.py` — нерабочий: импортирует модуль `loader`, которого в репозитории нет; ветка XRay (`amnezia client add --proto xray`) нигде больше не используется. Фактически заготовка. +- `install.sh` в текущем виде только клонирует репозиторий и проверяет обновления. Он не создаёт systemd-юнит `awg_bot` и не формирует `files/config.json`, хотя README оригинала описывает его как полноценный установщик с интерактивной инициализацией (первая версия скрипта была на 305 строк против нынешних 190). +- В `install.sh` список пакетов при обновлении зависимостей задан отдельно от `requirements.txt` и с другими версиями (`aiogram==2.25.1`, `humanize==4.9.0`, `pytz==2023.3.post1`) — рассинхронизация. +- `yookassa` и `YooMoney` в `requirements.txt` не используются ни в одном модуле: оплата подписок, судя по коду, не реализована (есть только цены и промокоды). +- Явных меток TODO/FIXME в коде нет. diff --git a/README.upstream.md b/README.upstream.md new file mode 100644 index 0000000..ccd9604 --- /dev/null +++ b/README.upstream.md @@ -0,0 +1,64 @@ +# AmneziaVPN Telegram Bot + +Телеграм-бот на Python для управления [AmneziaVPN](https://github.com/amnezia-vpn/amnezia-client). Этот бот позволяет легко управлять клиентами. + +Используется библиотека `aiogram` версии 2.25.2. +Протестировано на Ubuntu, версии 20.04, 22.04, 24.04. + +## Оглавление + +- [Возможности](#возможности) +- [Установка](#установка) +- [Запуск](#запуск) +- [Заметки](#заметки) +- [Поддержка](#поддержка) + +## Возможности + +- Добавление администраторов и модераторов для упралением VPN +- Добавление клиентов +- Удаление клиентов +- Получение информации об IP-адресе клиента (берется из Endpoint, используется API ресурса [ip-api.com](http://ip-api.com)) +- Создание ключа в формате `vpn://` при генерации нового клиента (так же, при получении конфигурации клиента), для использования в [AmneziaVPN](https://github.com/amnezia-vpn/amnezia-client) +- Создание резервной копии +- Инструкции по работе с VPN + +## Установка + +1. Установите [AmneziaVPN](https://github.com/amnezia-vpn/amnezia-client) (без данного шага бот РАБОТАТЬ НЕ БУДЕТ). +2. Пройдите первоначальную [инициализацию](https://docs.amnezia.org/ru/documentation/instructions/install-vpn-on-server/), выбрав протокол AmneziaWG, в клиенте [AmneziaVPN](https://github.com/amnezia-vpn/amnezia-client). + +3. Создайте бота в Telegram: + +- Откройте Telegram и найдите бота [BotFather](https://t.me/BotFather). +- Начните диалог, отправив команду `/start`. +- Введите команду `/newbot`, чтобы создать нового бота. +- Следуйте инструкциям BotFather, чтобы: + - Придумать имя для вашего бота (например, `AmneziaWGBot`). + - Придумать уникальное имя пользователя для бота (например, `AmneziaWGManagerBot_bot`). Оно должно оканчиваться на `_bot`. +- После создания бота BotFather отправит вам токен для доступа к API. Его запросит бот во время первоначальной инициализации. + +4. Получите ваш Telegram ID с помощью [Get My ID](https://t.me/getmyid_bot), просто написав боту. + +5. Загрузите и запустите скрипт `install.sh`, с помощью которого будет автоматически установлен бот, со всеми зависимостями, в том числе, в качестве системной службы (автозапуск): + + ```bash + curl -O https://raw.githubusercontent.com/stevefoxru/amnezia-bot/main/install.sh && chmod +x install.sh && ./install.sh + ``` + +## Запуск + +1. Добавьте бота в Telegram и отправьте команду `/start` или `/help` для начала работы. + +## Заметки + +Для обновления бота, необходимо запустить скрипт `install.sh`. В меню, необходимо выбрать пункт `Проверить обновления`. + +При создании резервной копии, в архив добавляется директория connections (создается и содержит в себе логи подключений клиентов), conf, png, и сам конфигурационный файл. + +## Поддержка + +Поддержать разработчика можете следующими способами: + + +Если у вас возникли вопросы или проблемы с установкой и использованием бота, создайте [issue](https://github.com/stevefoxru/amnezia-bot/issues) в этом репозитории или обратитесь к разработчику.