tgvpn

Версия: 0.20.0 · Релизы

Telegram-бот на Go (базовое приветствие; далее — VPN-функции).

Требования

Компонент	Минимум
Docker	24+
Docker Compose	v2 (docker compose)
Токен бота	@BotFather
Сеть	Исходящий HTTPS к api.telegram.org (порт 443)

Для запуска без Docker: Go 1.22+.

---

Быстрый старт (Docker Compose)

1. Клонирование

git clone https://git.evilfox.cc/test/tgvpn.git
cd tgvpn

2. Переменные окружения

cp .env.example .env

Отредактируйте .env:

BOT_TOKEN=ваш_токен_от_BotFather
BOT_DEBUG=false
TELEGRAM_ADMIN_ID=123456789
REMNAWAVE_PANEL_NAME=Панель 1
REMNAWAVE_PANEL_URL=https://panel.example.com
REMNAWAVE_API_TOKEN=токен_из_панели
REMNAWAVE_SUBSCRIPTION_URL=https://sub.example.com

Важно: файл .env не попадает в git и не копируется в образ. Compose передаёт переменные в контейнер при старте.

3. Сборка и запуск

docker compose up -d --build

4. Проверка

# логи (должно быть: «бот @имя_бота запущен»)
docker compose logs -f bot

# статус контейнера
docker compose ps

В Telegram откройте бота и отправьте /start.

5. Остановка

docker compose down

---

Развёртывание на VPS (Linux)

Ниже — пошаговая установка на чистый сервер (Ubuntu 22.04/24.04, Debian 12). Аналогично на других дистрибутивах с Docker.

Шаг 1. Подключение к серверу

ssh user@your-server-ip

Шаг 2. Установка Docker

sudo apt-get update
sudo apt-get 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-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo usermod -aG docker $USER

Выйдите из SSH и зайдите снова, чтобы группа docker применилась:

exit
ssh user@your-server-ip
docker --version
docker compose version

Шаг 3. Клонирование проекта

sudo mkdir -p /opt/tgvpn
sudo chown $USER:$USER /opt/tgvpn
cd /opt/tgvpn
git clone https://git.evilfox.cc/test/tgvpn.git .

Шаг 4. Настройка .env

cp .env.example .env
nano .env   # или vim / vi

Укажите реальный BOT_TOKEN. Для продакшена оставьте BOT_DEBUG=false.

Права на секреты:

chmod 600 .env

Шаг 5. Запуск в фоне

docker compose up -d --build

Проверка:

docker compose ps
docker compose logs --tail=50 bot

Шаг 6. Автозапуск после перезагрузки сервера

В docker-compose.yml уже указано restart: unless-stopped. После перезагрузки VPS контейнер поднимется сам, если Docker запущен:

sudo systemctl enable docker
sudo systemctl start docker

Шаг 7. Обновление

См. раздел Обновление бота ниже.

---

Обновление бота

Инструкция для уже работающей установки: подтянуть код из git, пересобрать контейнер и убедиться, что бот запустился.

Перед обновлением

1. Убедитесь, что .env сохранён на сервере (он не в git).
2. Посмотрите, не появились ли новые переменные в .env.example:

cd /opt/tgvpn   # или каталог, куда клонировали проект
git fetch origin
git diff HEAD origin/main -- .env.example

Если в .env.example есть новые строки — добавьте их в свой .env вручную.

Обновление на VPS (Docker)

cd /opt/tgvpn

# 1. Скачать изменения
git pull origin main

# 2. Пересобрать и перезапустить (простой даунтайм ~10–30 сек)
docker compose up -d --build

# 3. Проверить логи
docker compose ps
docker compose logs --tail=50 bot

В логах должны быть строки вида: бот @имя_бота запущен и администратор ID ….

Проверка в Telegram (от аккаунта админа):

• /start — бот отвечает
• /admin check — проверка панели Remnawave

Обновление на Windows (Docker Desktop)

cd tgvpn
git pull origin main
docker compose up -d --build
docker compose logs --tail=50 bot

Обновление без Docker (локально)

cd tgvpn
git pull origin main
go build -o bot .
# остановите старый процесс бота, затем:
./bot

Если изменили только .env

Пересборка не нужна — достаточно пересоздать контейнер:

docker compose up -d --force-recreate

Откат на предыдущую версию

cd /opt/tgvpn
git log --oneline -5          # найти нужный коммит
git checkout <хеш_коммита>    # например: git checkout f360d53
docker compose up -d --build

Вернуться на актуальную ветку:

git checkout main
git pull origin main
docker compose up -d --build

Очистка старых образов Docker (опционально)

После нескольких обновлений на диске копятся неиспользуемые слои:

docker image prune -f

Частые проблемы при обновлении

Симптом	Решение
git pull конфликтует с локальными правками	git stash → git pull → git stash pop или сбросить локальные изменения: git checkout -- .
Бот не стартует после pull	docker compose logs bot — часто не хватает новой переменной в .env
Старый код в контейнере	Обязательно --build: docker compose up -d --build
Нет доступа к git	Проверьте SSH/HTTPS-доступ к git.evilfox.cc

---

Развёртывание на Windows

Docker Desktop

1. Установите Docker Desktop.
2. В PowerShell:

git clone https://git.evilfox.cc/test/tgvpn.git
cd tgvpn
Copy-Item .env.example .env
# отредактируйте .env — вставьте BOT_TOKEN
docker compose up -d --build
docker compose logs -f bot

---

Локальная разработка (без Docker)

cp .env.example .env
# укажите BOT_TOKEN в .env
go run .

или

go build -o bot .
./bot

---

Переменные окружения

Переменная	Обязательно	Описание
BOT_TOKEN	да	Токен от @BotFather
TELEGRAM_ADMIN_ID	да	Числовой Telegram user ID администратора (например, @userinfobot)
REMNAWAVE_PANEL_NAME	нет	Название панели в админ-меню (по умолчанию «Панель 1»)
REMNAWAVE_PANEL_URL	да	URL панели — сюда же идут запросы API (/api/...). Пример: https://panel.example.com (док)
REMNAWAVE_API_TOKEN	да	Токен из Remnawave Settings → API Tokens, заголовок Authorization: Bearer
CADDY_AUTH_API_TOKEN	нет	X-Api-Key, если включён Caddy with security (как в оф. .env subscription-page)
REMNAWAVE_SUBSCRIPTION_URL	нет	Опционально: домен Subscription Page (sub.*), отдельная проверка
BOT_DEBUG	нет	true — подробные логи Telegram API (только для отладки)

Админ-меню в боте

Только пользователь с TELEGRAM_ADMIN_ID:

• /admin — админ-меню (панель 1, Remnawave)
• /admin check — полная проверка: веб панели, API (статистика, users, nodes), подписка (settings + API), страница подписки
• /admin config — конфиг панели в боте
• Кнопки снизу (после /start): «Проверить панель», «Конфиг панели»

---

Remnawave API (по официальной документации)

Как в Bundled Subscription Page:

REMNAWAVE_PANEL_URL=https://panel.example.com
REMNAWAVE_API_TOKEN=API_TOKEN_FROM_REMNAWAVE
CADDY_AUTH_API_TOKEN=

• Отдельного REMNAWAVE_API_URL нет — API всегда на том же хосте, что и панель: {REMNAWAVE_PANEL_URL}/api/...
• Авторизация: Authorization: Bearer {REMNAWAVE_API_TOKEN}
• Внутри Docker-сети Remnawave: REMNAWAVE_PANEL_URL=http://remnawave:3000
• Домен sub.* — это Subscription Page, не панель; для API используйте panel.*

Пример проверки с сервера:

curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $REMNAWAVE_API_TOKEN" \
  "$REMNAWAVE_PANEL_URL/api/system/stats/recap"

---

Полезные команды Docker

# пересобрать образ и перезапустить
docker compose up -d --build

# логи в реальном времени
docker compose logs -f bot

# последние 100 строк логов
docker compose logs --tail=100 bot

# зайти в контейнер (обычно не нужно)
docker compose exec bot sh

# удалить контейнер (образ останется)
docker compose down

# удалить контейнер и неиспользуемые образы проекта
docker compose down --rmi local

---

Сеть и безопасность

• Бот использует long polling: входящие запросы на ваш сервер не нужны, порты открывать не требуется.
• Нужен только исходящий доступ к https://api.telegram.org.
• Не коммитьте .env в git. Не публикуйте BOT_TOKEN.
• Контейнер запускается от непривилегированного пользователя bot (UID 10001).

Если позже добавите webhook, понадобится reverse proxy (nginx/Caddy), TLS и открытый порт 443 — это описывается отдельно при появлении функции.

---

Устранение неполадок

BOT_TOKEN не задан / TELEGRAM_ADMIN_ID не задан

• Проверьте, что файл .env лежит рядом с docker-compose.yml.
• В .env нет пробелов вокруг =: BOT_TOKEN=123:ABC, не BOT_TOKEN = ....
• TELEGRAM_ADMIN_ID — только цифры, без @username.
• После правки: docker compose up -d --force-recreate.

Authentication failed / 401 Unauthorized

• Неверный или отозванный токен. Создайте новый в @BotFather → /token → обновите .env → docker compose up -d --force-recreate.

Бот не отвечает в Telegram

docker compose ps          # State должен быть running
docker compose logs bot    # ошибки сети, токена

• Убедитесь, что на сервере нет блокировки Telegram (firewall, провайдер).
• Проверьте: curl -I https://api.telegram.org с хоста.

API возвращает 502, веб-панель — 200

Частая причина: в REMNAWAVE_PANEL_URL указан домен страницы подписки (sub.example.com), а не админ-панели (panel.example.com).

1. Укажите URL панели (не sub): REMNAWAVE_PANEL_URL=https://panel.evilfox.cc
2. Токен API: REMNAWAVE_API_TOKEN=... (Settings → API Tokens)
3. Страницу подписки — опционально: REMNAWAVE_SUBSCRIPTION_URL=https://sub.evilfox.cc
4. Проверьте на сервере: docker compose ps (Remnawave Panel запущен), логи reverse proxy

Контейнер постоянно перезапускается

docker compose logs --tail=200 bot

Чаще всего — пустой BOT_TOKEN или ошибка при старте.

Нет доступа к docker без sudo

sudo usermod -aG docker $USER
# перелогиньтесь

---

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

tgvpn/
├── main.go
├── internal/
│   ├── bot/             # обработчики Telegram, админ-меню
│   ├── config/          # переменные окружения
│   └── remnawave/       # клиент API панели
├── Dockerfile           # multi-stage сборка
├── docker-compose.yml   # оркестрация
├── .env.example         # шаблон переменных
├── .dockerignore
├── go.mod / go.sum
├── CHANGELOG.md
└── README.md

---

Репозиторий

https://git.evilfox.cc/test/tgvpn.git