VPN Telegram Bot + Remnawave Panel

Telegram-бот для выдачи VPN-подписок через API панели Remnawave.

Деплой: Docker Compose на Ubuntu (22.04 / 24.04 LTS).

Сейчас контейнер запускает проверку API (check_api.py). Дальше — bot.py.

---

Содержание

1. Что понадобится
2. Токен API в Remnawave
3. Установка Docker на Ubuntu
4. Установка проекта
5. Настройка .env
6. Сборка и проверка API
7. Структура проекта
8. Постоянный запуск бота
9. Полезные команды
10. Частые ошибки
11. Что дальше

---

1. Что понадобится

Компонент	Зачем
VPS / сервер Ubuntu 22.04 или 24.04	Где крутится Docker
Docker + Docker Compose plugin	Сборка и запуск контейнера
Доступ к панели Remnawave	URL, например https://panel.example.com
API Token из панели	Авторизация запросов к API
@BotFather	BOT_TOKEN (на следующем этапе)

Официальные материалы Remnawave:

• Панель: https://remna.st
• 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:

ssh user@your-server-ip

Официальный способ (рекомендуется)

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

Проверка:

docker --version
docker compose version
sudo docker run --rm hello-world

Чтобы не писать sudo каждый раз:

sudo usermod -aG docker "$USER"
# выйди из SSH и зайди снова
newgrp docker
docker run --rm hello-world

Быстрый вариант (snap, если так удобнее)

sudo snap install docker
docker --version

На production обычно лучше пакеты с download.docker.com, как выше.

---

4. Установка проекта

4.0. Установщик в 1 команду (рекомендуется)

На чистом Ubuntu 22.04 / 24.04, в каталоге с кодом:

sudo bash install.sh

Скрипт спросит домен, Remnawave, BOT_TOKEN, Postgres, логин админки, SMTP (опционально), поставит Docker при необходимости, откроет 80/443 (UFW), запишет .env, поднимет Postgres + бот + Caddy (Let's Encrypt SSL).

Полезные флаги:

sudo bash install.sh --help
sudo bash install.sh --reinstall   # пересборка без опроса (.env уже есть)
sudo bash install.sh --env-only    # только пересоздать .env

4.1. Положи код на сервер

sudo mkdir -p /opt/vpn-telegram-bot
sudo chown "$USER":"$USER" /opt/vpn-telegram-bot
cd /opt/vpn-telegram-bot

Через git:

git clone <URL_РЕПОЗИТОРИЯ> .

Или с локальной машины:

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

cd /opt/vpn-telegram-bot
cp .env.example .env
nano .env
chmod 600 .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 (/newbot).
• .env не коммитить (есть в .gitignore и .dockerignore).

Compose подхватывает .env через env_file и подставляет переменные в контейнер.

---

6. Сборка и проверка API

Из каталога проекта:

cd /opt/vpn-telegram-bot

# собрать образ
docker compose build

# одноразовый прогон проверки API
docker compose run --rm bot

Или явно:

docker compose run --rm bot python check_api.py

Успех — в логе что-то вроде:

✓ Remnawave API принимает запросы. Можно продолжать бота.

С verbose:

docker compose run --rm bot python check_api.py --verbose

Пересобрать после смены кода:

docker compose build --no-cache

---

7. Структура проекта

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 приветствием.

docker compose up -d --build
docker compose ps
docker compose logs -f bot

В Telegram открой бота и нажми Start (или отправь /start).

Остановить:

docker compose down

Проверка API по-прежнему:

docker compose run --rm bot python check_api.py

---

9. Полезные команды

# статус
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.

cd /opt/vpn-telegram-bot
grep REMNAWAVE_ .env
docker compose run --rm bot env | grep REMNAWAVE_

401 / токен не принят

Неверный или отозванный токен, лишние пробелы/переносы в .env.

После правки .env перезапускать контейнер:

docker compose run --rm bot python check_api.py

Не собирается образ / нет Docker

docker compose version
sudo systemctl status docker
sudo systemctl enable --now docker

Сеть из контейнера

Если с хоста панель открывается, а из контейнера нет — DNS/firewall Docker:

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)

# 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.