commit a9c6c66e4187ebe52c295a3adbe9e229eefd72d8 Author: EvilFox Date: Sun Jul 26 23:17:21 2026 +0300 first commit diff --git a/README.md b/README.md new file mode 100644 index 0000000..56c80cc --- /dev/null +++ b/README.md @@ -0,0 +1,390 @@ +# VPN Telegram Bot + Remnawave Panel + +Telegram-бот для выдачи VPN-подписок через API панели **Remnawave**. + +Деплой: **Docker Compose** на Ubuntu (22.04 / 24.04 LTS). + +Сейчас контейнер запускает проверку API (`check_api.py`). Дальше — `bot.py`. + +--- + +## Содержание + +1. [Что понадобится](#1-что-понадобится) +2. [Токен API в Remnawave](#2-токен-api-в-remnawave) +3. [Установка Docker на Ubuntu](#3-установка-docker-на-ubuntu) +4. [Установка проекта](#4-установка-проекта) +5. [Настройка `.env`](#5-настройка-env) +6. [Сборка и проверка API](#6-сборка-и-проверка-api) +7. [Структура проекта](#7-структура-проекта) +8. [Постоянный запуск бота](#8-постоянный-запуск-бота) +9. [Полезные команды](#9-полезные-команды) +10. [Частые ошибки](#10-частые-ошибки) +11. [Что дальше](#11-что-дальше) + +--- + +## 1. Что понадобится + +| Компонент | Зачем | +|-----------|--------| +| VPS / сервер Ubuntu 22.04 или 24.04 | Где крутится Docker | +| Docker + Docker Compose plugin | Сборка и запуск контейнера | +| Доступ к панели Remnawave | URL, например `https://panel.example.com` | +| API Token из панели | Авторизация запросов к API | +| [@BotFather](https://t.me/BotFather) | `BOT_TOKEN` (на следующем этапе) | + +Официальные материалы Remnawave: + +- Панель: [https://remna.st](https://remna.st) +- Python SDK: [https://github.com/remnawave/python-sdk](https://github.com/remnawave/python-sdk) + +--- + +## 2. Токен API в Remnawave + +1. Открой панель (например `https://panel.example.com`). +2. Войди под админом. +3. **Settings → API Tokens** — создай токен. +4. Скопируй сразу и положи в `.env` на сервере. + +Если Caddy режет API отдельным ключом — понадобится ещё `CADDY_TOKEN`. + +--- + +## 3. Установка Docker на Ubuntu + +Подключись по SSH: + +```bash +ssh user@your-server-ip +``` + +### Официальный способ (рекомендуется) + +```bash +sudo apt update +sudo apt install -y ca-certificates curl + +sudo install -m 0755 -d /etc/apt/keyrings +sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc +sudo chmod a+r /etc/apt/keyrings/docker.asc + +echo \ + "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \ + $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \ + sudo tee /etc/apt/sources.list.d/docker.list > /dev/null + +sudo apt update +sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin +``` + +Проверка: + +```bash +docker --version +docker compose version +sudo docker run --rm hello-world +``` + +Чтобы не писать `sudo` каждый раз: + +```bash +sudo usermod -aG docker "$USER" +# выйди из SSH и зайди снова +newgrp docker +docker run --rm hello-world +``` + +### Быстрый вариант (snap, если так удобнее) + +```bash +sudo snap install docker +docker --version +``` + +На production обычно лучше пакеты с `download.docker.com`, как выше. + +--- + +## 4. Установка проекта + +### 4.0. Установщик в 1 команду (рекомендуется) + +На чистом Ubuntu 22.04 / 24.04, в каталоге с кодом: + +```bash +sudo bash install.sh +``` + +Скрипт спросит домен, Remnawave, `BOT_TOKEN`, Postgres, логин админки, SMTP (опционально), поставит Docker при необходимости, откроет 80/443 (UFW), запишет `.env`, поднимет **Postgres + бот + Caddy (Let's Encrypt SSL)**. + +Полезные флаги: + +```bash +sudo bash install.sh --help +sudo bash install.sh --reinstall # пересборка без опроса (.env уже есть) +sudo bash install.sh --env-only # только пересоздать .env +``` + +### 4.1. Положи код на сервер + +```bash +sudo mkdir -p /opt/vpn-telegram-bot +sudo chown "$USER":"$USER" /opt/vpn-telegram-bot +cd /opt/vpn-telegram-bot +``` + +Через git: + +```bash +git clone . +``` + +Или с локальной машины: + +```bash +scp -r ./vpn-telegram-bot/* user@your-server-ip:/opt/vpn-telegram-bot/ +``` + +В каталоге должны быть как минимум: + +- `Dockerfile` +- `docker-compose.yml` +- `requirements.txt` +- `check_api.py` +- `config.py` +- `remnawave_client.py` +- `.env.example` + +### 4.2. Docker Compose не ставит Python на хост + +Python и зависимости живут **внутри образа**. На хосте нужен только Docker. + +--- + +## 5. Настройка `.env` + +```bash +cd /opt/vpn-telegram-bot +cp .env.example .env +nano .env +chmod 600 .env +``` + +Пример: + +```env +REMNAWAVE_BASE_URL=https://panel.example.com +REMNAWAVE_TOKEN=вставь_сюда_токен_панели + +# Токен Telegram-бота от @BotFather +BOT_TOKEN=123456:AA... + +# ID админов через запятую +ADMIN_IDS=123456789 + +# CADDY_TOKEN= +``` + +Правила: + +- `REMNAWAVE_BASE_URL` — без `/` в конце, обычно без `/api`. +- `REMNAWAVE_TOKEN` — без слова `Bearer`. +- `BOT_TOKEN` — токен от [@BotFather](https://t.me/BotFather) (`/newbot`). +- `.env` не коммитить (есть в `.gitignore` и `.dockerignore`). + +Compose подхватывает `.env` через `env_file` и подставляет переменные в контейнер. + +--- + +## 6. Сборка и проверка API + +Из каталога проекта: + +```bash +cd /opt/vpn-telegram-bot + +# собрать образ +docker compose build + +# одноразовый прогон проверки API +docker compose run --rm bot +``` + +Или явно: + +```bash +docker compose run --rm bot python check_api.py +``` + +Успех — в логе что-то вроде: + +```text +✓ Remnawave API принимает запросы. Можно продолжать бота. +``` + +С verbose: + +```bash +docker compose run --rm bot python check_api.py --verbose +``` + +Пересобрать после смены кода: + +```bash +docker compose build --no-cache +``` + +--- + +## 7. Структура проекта + +```text +vpn-telegram-bot/ +├── Dockerfile +├── docker-compose.yml +├── .dockerignore +├── .env # секреты (не в git / не в образ) +├── .env.example +├── .gitignore +├── requirements.txt +├── config.py +├── remnawave_client.py +├── check_api.py +└── README.md +``` + +| Файл | Роль | +|------|------| +| `Dockerfile` | Образ Python 3.12 + зависимости | +| `docker-compose.yml` | Сервис `bot`, env, command | +| `check_api.py` | Проверка, что Remnawave API принимает запросы | + +--- + +## 8. Запуск бота + +`bot.py` отвечает на `/start` приветствием. + +```bash +docker compose up -d --build +docker compose ps +docker compose logs -f bot +``` + +В Telegram открой бота и нажми **Start** (или отправь `/start`). + +Остановить: + +```bash +docker compose down +``` + +Проверка API по-прежнему: + +```bash +docker compose run --rm bot python check_api.py +``` + +--- + +## 9. Полезные команды + +```bash +# статус +docker compose ps + +# логи +docker compose logs -f bot + +# перезапуск +docker compose restart bot + +# войти в контейнер +docker compose run --rm --entrypoint sh bot + +# проверить сеть до панели с хоста +curl -sS -o /dev/null -w "%{http_code}\n" https://panel.example.com/api/system/health + +# проверить из контейнера +docker compose run --rm bot curl -sS -o /dev/null -w "%{http_code}\n" https://panel.example.com/api/system/health +``` + +--- + +## 10. Частые ошибки + +### `REMNAWAVE_TOKEN не задан` + +Пустой `.env` или compose запущен не из каталога с `.env`. + +```bash +cd /opt/vpn-telegram-bot +grep REMNAWAVE_ .env +docker compose run --rm bot env | grep REMNAWAVE_ +``` + +### `401` / токен не принят + +Неверный или отозванный токен, лишние пробелы/переносы в `.env`. + +После правки `.env` перезапускать контейнер: + +```bash +docker compose run --rm bot python check_api.py +``` + +### Не собирается образ / нет Docker + +```bash +docker compose version +sudo systemctl status docker +sudo systemctl enable --now docker +``` + +### Сеть из контейнера + +Если с хоста панель открывается, а из контейнера нет — DNS/firewall Docker: + +```bash +docker compose run --rm bot curl -vI https://panel.example.com +``` + +### Permission denied на docker.sock + +Пользователь не в группе `docker` — см. раздел 3 (`usermod -aG docker`). + +### Caddy auth + +Раскомментируй `CADDY_TOKEN` в `.env`. + +--- + +## 11. Что дальше + +1. Убедиться, что `docker compose run --rm bot` проходит проверку API. +2. Добавить `BOT_TOKEN` в `.env`. +3. Написать `bot.py` (aiogram) и сменить `command` / `restart` в compose. +4. Поднять постоянно: `docker compose up -d --build`. + +--- + +## Краткая шпаргалка (Ubuntu + Docker Compose) + +```bash +# Docker (один раз) +sudo apt update +# ... установка docker-ce и docker-compose-plugin из раздела 3 ... + +# Проект +cd /opt/vpn-telegram-bot +cp .env.example .env +nano .env # REMNAWAVE_BASE_URL + REMNAWAVE_TOKEN +chmod 600 .env + +docker compose build +docker compose run --rm bot +``` + +Если проверка прошла — можно переходить к Telegram-боту в том же Compose.