tgvpn/README.md

tgvpn

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=токен_из_панели

Важно: файл .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. Обновление версии бота

cd /opt/tgvpn
git pull
docker compose up -d --build
docker compose logs --tail=30 bot

Старый образ можно удалить (опционально):

docker image prune -f

---

Развёртывание на 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 панели Remnawave, например https://vpn.example.com
REMNAWAVE_API_TOKEN	да	API-токен: панель → Settings → API Tokens (документация)
REMNAWAVE_CADDY_TOKEN	нет	Доп. заголовок X-Api-Key, если панель за Caddy
REMNAWAVE_SUBSCRIPTION_URL	нет*	URL страницы подписки для проверки в /admin check (*рекомендуется)
BOT_DEBUG	нет	true — подробные логи Telegram API (только для отладки)

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

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

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

---

Полезные команды 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 с хоста.

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

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
└── README.md

---

Репозиторий

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