viktor/amnezia-bot
1
0
Форкнуть 0
Код Задачи Запросы на слияние Действия Пакеты Проекты Релизы Вики Активность

docs: подробный README (разбор проекта при переносе в Gitea)

Просмотр исходного кода 
Старый README сохранён как README.upstream.md.
Этот коммит содержится в:
viktor
2026-08-20 04:18:28 +09:00
родитель 90b00d971d
Коммит 2b5a8a005b
2 изменённых файлов: 139 добавлений и 42 удалений
Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы
README.md
+75 -42
Просмотреть файл
@@ -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 в коде нет.
README.upstream.md
+64
Просмотреть файл
@@ -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) в этом репозитории или обратитесь к разработчику.