@@ -1,15 +1,303 @@
# tgvpn
Telegram-бот на Go (базовое приветствие, дальш е
Telegram-бот на Go (базовое приветствие; дале е
## Запуск
## Требования
1. Скопируйте `.env.example` в `.env` и укажите `BOT_TOKEN` от [@BotFather ](https://t.me/BotFather ).
2. `go run .`
| Компонент | Минимум |
|-----------|---------|
| 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
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` | Токен бота (обязательно) |
| `BOT_DEBUG` | `true` — подробные логи API |
| Переменная | О бязательно | О писание |
|--------------|-------------| ----------|
| `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
tgvpn