Template
391 lines
10 KiB
Markdown
391 lines
10 KiB
Markdown
# 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 <URL_РЕПОЗИТОРИЯ> .
|
||
```
|
||
|
||
Или с локальной машины:
|
||
|
||
```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.
|