tgvpn
458 lines
15 KiB
Markdown
458 lines
15 KiB
Markdown
# tgvpn
|
||
|
||
**Версия:** [0.20.0](CHANGELOG.md) · [Релизы](https://git.evilfox.cc/test/tgvpn/releases)
|
||
|
||
Telegram-бот на Go (базовое приветствие; далее — VPN-функции).
|
||
|
||
## Требования
|
||
|
||
| Компонент | Минимум |
|
||
|-----------|---------|
|
||
| Docker | 24+ |
|
||
| Docker Compose | v2 (`docker compose`) |
|
||
| Токен бота | [@BotFather](https://t.me/BotFather) |
|
||
| Сеть | Исходящий HTTPS к `api.telegram.org` (порт 443) |
|
||
|
||
Для запуска **без Docker**: Go 1.22+.
|
||
|
||
---
|
||
|
||
## Быстрый старт (Docker Compose)
|
||
|
||
### 1. Клонирование
|
||
|
||
```bash
|
||
git clone https://git.evilfox.cc/test/tgvpn.git
|
||
cd tgvpn
|
||
```
|
||
|
||
### 2. Переменные окружения
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
Отредактируйте `.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. Сборка и запуск
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
### 4. Проверка
|
||
|
||
```bash
|
||
# логи (должно быть: «бот @имя_бота запущен»)
|
||
docker compose logs -f bot
|
||
|
||
# статус контейнера
|
||
docker compose ps
|
||
```
|
||
|
||
В Telegram откройте бота и отправьте `/start`.
|
||
|
||
### 5. Остановка
|
||
|
||
```bash
|
||
docker compose down
|
||
```
|
||
|
||
---
|
||
|
||
## Развёртывание на VPS (Linux)
|
||
|
||
Ниже — пошаговая установка на чистый сервер (Ubuntu 22.04/24.04, Debian 12). Аналогично на других дистрибутивах с Docker.
|
||
|
||
### Шаг 1. Подключение к серверу
|
||
|
||
```bash
|
||
ssh user@your-server-ip
|
||
```
|
||
|
||
### Шаг 2. Установка Docker
|
||
|
||
```bash
|
||
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` применилась:
|
||
|
||
```bash
|
||
exit
|
||
ssh user@your-server-ip
|
||
docker --version
|
||
docker compose version
|
||
```
|
||
|
||
### Шаг 3. Клонирование проекта
|
||
|
||
```bash
|
||
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`
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
nano .env # или vim / vi
|
||
```
|
||
|
||
Укажите реальный `BOT_TOKEN`. Для продакшена оставьте `BOT_DEBUG=false`.
|
||
|
||
Права на секреты:
|
||
|
||
```bash
|
||
chmod 600 .env
|
||
```
|
||
|
||
### Шаг 5. Запуск в фоне
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
Проверка:
|
||
|
||
```bash
|
||
docker compose ps
|
||
docker compose logs --tail=50 bot
|
||
```
|
||
|
||
### Шаг 6. Автозапуск после перезагрузки сервера
|
||
|
||
В `docker-compose.yml` уже указано `restart: unless-stopped`. После перезагрузки VPS контейнер поднимется сам, если Docker запущен:
|
||
|
||
```bash
|
||
sudo systemctl enable docker
|
||
sudo systemctl start docker
|
||
```
|
||
|
||
### Шаг 7. Обновление
|
||
|
||
См. раздел [Обновление бота](#обновление-бота) ниже.
|
||
|
||
---
|
||
|
||
## Обновление бота
|
||
|
||
Инструкция для уже работающей установки: подтянуть код из git, пересобрать контейнер и убедиться, что бот запустился.
|
||
|
||
### Перед обновлением
|
||
|
||
1. Убедитесь, что `.env` сохранён на сервере (он не в git).
|
||
2. Посмотрите, не появились ли новые переменные в `.env.example`:
|
||
|
||
```bash
|
||
cd /opt/tgvpn # или каталог, куда клонировали проект
|
||
git fetch origin
|
||
git diff HEAD origin/main -- .env.example
|
||
```
|
||
|
||
Если в `.env.example` есть новые строки — добавьте их в свой `.env` вручную.
|
||
|
||
### Обновление на VPS (Docker)
|
||
|
||
```bash
|
||
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)
|
||
|
||
```powershell
|
||
cd tgvpn
|
||
git pull origin main
|
||
docker compose up -d --build
|
||
docker compose logs --tail=50 bot
|
||
```
|
||
|
||
### Обновление без Docker (локально)
|
||
|
||
```bash
|
||
cd tgvpn
|
||
git pull origin main
|
||
go build -o bot .
|
||
# остановите старый процесс бота, затем:
|
||
./bot
|
||
```
|
||
|
||
### Если изменили только `.env`
|
||
|
||
Пересборка не нужна — достаточно пересоздать контейнер:
|
||
|
||
```bash
|
||
docker compose up -d --force-recreate
|
||
```
|
||
|
||
### Откат на предыдущую версию
|
||
|
||
```bash
|
||
cd /opt/tgvpn
|
||
git log --oneline -5 # найти нужный коммит
|
||
git checkout <хеш_коммита> # например: git checkout f360d53
|
||
docker compose up -d --build
|
||
```
|
||
|
||
Вернуться на актуальную ветку:
|
||
|
||
```bash
|
||
git checkout main
|
||
git pull origin main
|
||
docker compose up -d --build
|
||
```
|
||
|
||
### Очистка старых образов Docker (опционально)
|
||
|
||
После нескольких обновлений на диске копятся неиспользуемые слои:
|
||
|
||
```bash
|
||
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](https://www.docker.com/products/docker-desktop/).
|
||
2. В PowerShell:
|
||
|
||
```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)
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# укажите BOT_TOKEN в .env
|
||
go run .
|
||
```
|
||
|
||
или
|
||
|
||
```bash
|
||
go build -o bot .
|
||
./bot
|
||
```
|
||
|
||
---
|
||
|
||
## Переменные окружения
|
||
|
||
| Переменная | Обязательно | Описание |
|
||
|--------------|-------------|----------|
|
||
| `BOT_TOKEN` | да | Токен от @BotFather |
|
||
| `TELEGRAM_ADMIN_ID` | да | Числовой Telegram user ID администратора (например, [@userinfobot](https://t.me/userinfobot)) |
|
||
| `REMNAWAVE_PANEL_NAME` | нет | Название панели в админ-меню (по умолчанию «Панель 1») |
|
||
| `REMNAWAVE_PANEL_URL` | да | URL панели — сюда же идут запросы API (`/api/...`). Пример: `https://panel.example.com` ([док](https://docs.rw/docs/install/subscription-page/bundled)) |
|
||
| `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](https://docs.rw/docs/install/subscription-page/bundled):
|
||
|
||
```env
|
||
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.*`
|
||
|
||
Пример проверки с сервера:
|
||
|
||
```bash
|
||
curl -s -o /dev/null -w "%{http_code}" \
|
||
-H "Authorization: Bearer $REMNAWAVE_API_TOKEN" \
|
||
"$REMNAWAVE_PANEL_URL/api/system/stats/recap"
|
||
```
|
||
|
||
---
|
||
|
||
## Полезные команды Docker
|
||
|
||
```bash
|
||
# пересобрать образ и перезапустить
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
### Контейнер постоянно перезапускается
|
||
|
||
```bash
|
||
docker compose logs --tail=200 bot
|
||
```
|
||
|
||
Чаще всего — пустой `BOT_TOKEN` или ошибка при старте.
|
||
|
||
### Нет доступа к `docker` без sudo
|
||
|
||
```bash
|
||
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
|