tgvpn
304 lines
7.8 KiB
Markdown
304 lines
7.8 KiB
Markdown
# tgvpn
|
||
|
||
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
|
||
```
|
||
|
||
> **Важно:** файл `.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. Обновление версии бота
|
||
|
||
```bash
|
||
cd /opt/tgvpn
|
||
git pull
|
||
docker compose up -d --build
|
||
docker compose logs --tail=30 bot
|
||
```
|
||
|
||
Старый образ можно удалить (опционально):
|
||
|
||
```bash
|
||
docker image prune -f
|
||
```
|
||
|
||
---
|
||
|
||
## Развёртывание на 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 |
|
||
| `BOT_DEBUG` | нет | `true` — подробные логи Telegram API (только для отладки) |
|
||
|
||
---
|
||
|
||
## Полезные команды 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 не задан`
|
||
|
||
- Проверьте, что файл `.env` лежит рядом с `docker-compose.yml`.
|
||
- В `.env` нет пробелов вокруг `=`: `BOT_TOKEN=123:ABC`, не `BOT_TOKEN = ...`.
|
||
- После правки: `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` с хоста.
|
||
|
||
### Контейнер постоянно перезапускается
|
||
|
||
```bash
|
||
docker compose logs --tail=200 bot
|
||
```
|
||
|
||
Чаще всего — пустой `BOT_TOKEN` или ошибка при старте.
|
||
|
||
### Нет доступа к `docker` без sudo
|
||
|
||
```bash
|
||
sudo usermod -aG docker $USER
|
||
# перелогиньтесь
|
||
```
|
||
|
||
---
|
||
|
||
## Структура проекта
|
||
|
||
```
|
||
tgvpn/
|
||
├── main.go # логика бота
|
||
├── Dockerfile # multi-stage сборка
|
||
├── docker-compose.yml # оркестрация
|
||
├── .env.example # шаблон переменных
|
||
├── .dockerignore
|
||
├── go.mod / go.sum
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## Репозиторий
|
||
|
||
https://git.evilfox.cc/test/tgvpn.git
|