mirror of
https://github.com/anten-ka/gotelegram_pro.git
synced 2026-05-19 14:36:05 +00:00
254 lines
22 KiB
Markdown
254 lines
22 KiB
Markdown
# goTelegram Pro — руководство пользователя
|
||
|
||
**Версия:** 2.5.0
|
||
**Репозиторий:** `anten-ka/gotelegram_pro`
|
||
**Для кого:** владельцы VPS, которым нужен надёжный MTProxy для Telegram с маскировкой под обычный HTTPS-сайт.
|
||
|
||
---
|
||
|
||
## 1. Что это такое
|
||
|
||
goTelegram Pro — это готовый менеджер прокси-сервера MTProxy для Telegram. Он делает три вещи, которые иначе пришлось бы собирать вручную:
|
||
|
||
1. Ставит и настраивает ядро **telemt** (это современный Rust-порт mtproto-proxy с fake-TLS маскировкой).
|
||
2. Запускает рядом обычный HTTPS-сайт на настоящем домене, так что провайдеру со стороны всё выглядит как посещение безобидного лендинга — а на самом деле в том же соединении ходит Telegram-трафик. Это называется «stealth» или «Pro-режим».
|
||
3. Даёт Telegram-бота, через которого можно управлять прокси со смартфона: ссылка, статус, перезапуск, бекап, смена маскировочного домена, выбор шаблона сайта.
|
||
|
||
Всё управляется одним меню из 14 пунктов (`gotelegram` в терминале) — не нужно лазить по конфигам.
|
||
|
||
---
|
||
|
||
## 2. Быстрый старт
|
||
|
||
На чистом Ubuntu/Debian VPS под root:
|
||
|
||
```bash
|
||
bash <(curl -sL "https://raw.githubusercontent.com/anten-ka/gotelegram_pro/test/bootstrap.sh?token=YOUR_PAT")
|
||
```
|
||
|
||
Для приватного репозитория безопаснее передавать токен через переменную окружения:
|
||
|
||
```bash
|
||
GOTELEGRAM_PAT=YOUR_PAT bash <(curl -sL "https://raw.githubusercontent.com/anten-ka/gotelegram_pro/test/bootstrap.sh")
|
||
```
|
||
|
||
`bootstrap.sh` скачает все файлы из приватного репозитория, создаст симлинк `/usr/local/bin/gotelegram` и запустит главное меню. Через минуту команда `gotelegram` уже будет работать откуда угодно.
|
||
|
||
Дальше в меню:
|
||
|
||
- **1) Установить / обновить** — ставит прокси, спрашивает режим (Lite или Pro) и домен маскировки.
|
||
- **2) Статус** — показывает, жив ли telemt, IP, порт, маскировку и готовую `tg://proxy?...` ссылку.
|
||
- **3) Ссылка** — тот же ключ отдельно, вместе с QR-кодом.
|
||
|
||
Дальше можно открыть Telegram → Настройки → Данные и память → Прокси → добавить по ссылке. Готово.
|
||
|
||
---
|
||
|
||
## 3. Lite vs Pro — что выбрать
|
||
|
||
### Lite (быстрый, без домена)
|
||
|
||
- Работает сразу без какого-либо домена.
|
||
- Ссылка выглядит как IP-адрес: `tg://proxy?server=95.163.176.222&port=443&secret=ee...`
|
||
- Провайдеру видно: кто-то сходил на IP:443, TLS с SNI=google.com (или другой популярный домен, который ты выберешь из списка).
|
||
- Минус: IP-адрес виден, и если провайдер блокирует по списку known-bad-IP, ключ перестанет работать.
|
||
- Подходит, если домена пока нет, а пользоваться нужно уже сейчас.
|
||
|
||
### Pro (стелс, со своим доменом)
|
||
|
||
- Нужен настоящий домен, который указывает A-записью на IP VPS.
|
||
- Провайдеру видно: HTTPS-трафик к `твой-домен.com:443` — выглядит как обычный сайт.
|
||
- По этому же домену снаружи открывается реальный HTML-сайт (любой из 1800+ шаблонов в каталоге).
|
||
- Внутри: telemt слушает 443, nginx слушает 127.0.0.1:8443, маскировочный трафик telemt проксирует на nginx через `dns_overrides`, так что сайт реально открывается в браузере. SSL — настоящий Let's Encrypt.
|
||
- Ссылка: `tg://proxy?server=твой-домен.com&port=443&secret=ee...`
|
||
- Плюс: выглядит идентично обычному сайту, провайдер не может отличить.
|
||
- Минус: нужен домен и корректно настроенный DNS (плюс несколько минут ожидания сертификата).
|
||
|
||
**Короткое правило:** есть домен — ставь Pro. Нет — начни с Lite и потом переключишься через пункт меню «Сменить режим».
|
||
|
||
---
|
||
|
||
## 4. Меню целиком
|
||
|
||
```
|
||
── Прокси ──
|
||
1) Установить / обновить — первый раз или апгрейд
|
||
2) Статус — IP, порт, маскировка, живость
|
||
3) Ссылка — tg://proxy?... + QR
|
||
4) Поделиться — текстовое сообщение «для друзей»
|
||
5) Перезапуск — systemctl restart telemt
|
||
6) Логи — последние 40 строк telemt
|
||
7) Сменить режим / шаблон — Lite↔Pro, сменить сайт-шаблон
|
||
|
||
── Управление ──
|
||
8) Бекап — tar.gz всех конфигов и ключей
|
||
9) Восстановить — откат из бекапа
|
||
10) Обновить telemt — скачать свежий бинарник
|
||
11) Сайт (SSL) — ручная перегенерация сертификата
|
||
|
||
── Бот и прочее ──
|
||
12) Telegram-бот — установить / настроить бота
|
||
13) Удалить всё — снести прокси / бота / вообще всё
|
||
14) Промо — подарочные ссылки
|
||
|
||
0) Выход
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Telegram-бот
|
||
|
||
Пункт меню **12) Telegram-бот** разворачивает отдельный Python-сервис (`python-telegram-bot` v21+), который:
|
||
|
||
- Показывает статус прокси, ссылку и QR.
|
||
- Умеет перезапускать telemt прямо из чата.
|
||
- Делает бекап и восстанавливает.
|
||
- Переключает режим (Lite ↔ Pro).
|
||
- Меняет маскировочный домен.
|
||
- Меняет сайт-шаблон из каталога на 1800+ готовых HTML-шаблонов (4 источника: html5up, startbootstrap, ThemeWagon, dawidolko).
|
||
- Поддерживает **2 языка**: русский и английский. Каждый пользователь выбирает свой, настройка сохраняется.
|
||
|
||
Чтобы запустить бота, нужны только два параметра — токен от `@BotFather` и твой Telegram ID (чтобы никто кроме тебя бота не использовал). Меню подсказывает где что ввести.
|
||
|
||
---
|
||
|
||
## 6. Язык интерфейса
|
||
|
||
CLI и бот переведены на русский и английский. Выбор языка идёт:
|
||
|
||
- В CLI — при первом запуске спрашивает один раз и запоминает в `config.json`.
|
||
- В боте — отдельная кнопка «🇬🇧/🇷🇺», переключение на лету, сохранение per-user.
|
||
|
||
Вся логика интерфейса, ошибок, подсказок, меню — переведена.
|
||
|
||
---
|
||
|
||
## 7. Бекап и восстановление
|
||
|
||
Пункт 8 делает один файл `.tar.gz` со всем, что нужно: `/etc/telemt/config.toml`, `/opt/gotelegram/config.json`, `/opt/gotelegram/disabled_users.json`, данные nginx-сайта, сертификаты, состояние Telegram-бота и локальной web-админки. По умолчанию в `/opt/gotelegram/backups/`.
|
||
|
||
Пункт 9 принимает такой архив и восстанавливает всё обратно (конфиг, сервис, ссылка — всё то же, что было).
|
||
|
||
Хорошая практика: делать бекап каждый раз перед пунктами 1 (переустановка) и 10 (обновление telemt).
|
||
|
||
---
|
||
|
||
## 8. Локальная web-админка
|
||
|
||
Начиная с **2.5.0** вместе с ботом ставится локальная web-админка:
|
||
|
||
- systemd service: `gotelegram-admin`;
|
||
- слушает только `127.0.0.1:1984`;
|
||
- наружу не публикуется и рассчитана на доступ через SSH tunnel;
|
||
- после туннеля открывается обычным URL `http://127.0.0.1:1984/`;
|
||
- язык берётся из `config.json.language` / `/opt/gotelegram/.language`, как в CLI и Telegram-боте; в верхней панели можно переключить RU/EN, выбор сохраняется в общий конфиг;
|
||
- есть светлая/тёмная тема, вкладки и адаптивная вёрстка под desktop/mobile;
|
||
- Telegram-бот показывает инструкцию для Termius и обычную команду `ssh -L 1984:127.0.0.1:1984 root@SERVER`.
|
||
|
||
В админке есть dashboard, проверка сайта `https://домен/` на HTTP 200, статус сервисов, полезный блок «кто слушает порт 443» по данным `ss`, управление ключами `[access.users]` с добавлением, удалением и быстрым отключением через switch, генерация ссылок, traffic history по периодам 15 минут / 1 час / 24 часа / месяц с переключателем график/строки, кнопка разового обновления статистики, кнопка перезапуска сборщика, список бекапов и просмотр логов с количеством строк и статусом `journalctl`.
|
||
|
||
Отключённые ключи убираются из активного telemt-конфига и сохраняются в `/opt/gotelegram/disabled_users.json`, поэтому их можно включить обратно без потери secret. Основной ключ `main` защищён от удаления и отключения.
|
||
|
||
---
|
||
|
||
## 9. Обновление
|
||
|
||
Два типа обновлений:
|
||
|
||
- **Обновление ядра telemt** (пункт 10) — тянет свежий бинарник с GitHub Releases `telemt/telemt`, сохраняет старый в `.bak`, перезапускает сервис. Конфиг остаётся как был.
|
||
- **Обновление самого goTelegram Pro** (пункт 1) — переустанавливает скрипты и lib/. Файл `config.json` не трогается, ключ и домен не меняются.
|
||
|
||
Bootstrap.sh умеет сам обновлять всё, если запустить его повторно.
|
||
|
||
Начиная с **2.5.0** первый запуск новой версии делает автоматическую миграцию старого состояния: создаёт pre-upgrade архив в `/opt/gotelegram/backups/`, вытаскивает все ключи из `[access.users]`, сохраняет домен, порт, режим, язык, историю статистики и фактически развёрнутый сайт. Если старый `template_id` был неправильным или отсутствовал, сайт помечается как `deployed_site`, чтобы Telegram-бот не показывал первый установленный шаблон вместо текущего.
|
||
|
||
---
|
||
|
||
## 10. Удаление
|
||
|
||
Пункт **13) Удалить всё** даёт выбор:
|
||
|
||
- Удалить только прокси (оставить бота).
|
||
- Удалить только бота.
|
||
- Удалить всё целиком, включая `/opt/gotelegram`, `/etc/telemt`, symlink `gotelegram`, systemd юниты, nginx-конфиг, бекапы и сайт из `/var/www/gotelegram-site`.
|
||
|
||
После «удалить всё» VPS возвращается к состоянию до установки (кроме скачанных пакетов типа `jq`, `nginx`, `certbot` — они остаются).
|
||
|
||
---
|
||
|
||
## 11. Требования к VPS
|
||
|
||
- **ОС:** Ubuntu 20.04+ или Debian 11+ (протестировано на Ubuntu 22.04).
|
||
- **RAM:** 512 МБ минимум, 1 ГБ комфортно (telemt сам по себе ест мало, но рядом nginx + бот).
|
||
- **Диск:** 2 ГБ (в основном под каталог шаблонов и бекапы).
|
||
- **Права:** root или sudo.
|
||
- **Порты:** 443 должен быть свободен (ни apache, ни nginx, ни ничего другого не должно на нём висеть). Если занят — скрипт предупредит.
|
||
- **Для Pro-режима:** домен с настроенным A-record на IP VPS. DNS должен отвечать ДО установки, иначе Let's Encrypt не выдаст сертификат.
|
||
|
||
---
|
||
|
||
## 12. Частые вопросы
|
||
|
||
**Q: Ключ перестал работать, telemt живой.**
|
||
A: 95% случаев — это когда после переустановки telemt не перечитал свежий конфиг (было исправлено в 2.4.1, см. changelog). Перезапусти вручную: `systemctl restart telemt`. Если не помогло — смотри логи (пункт 6 меню) и проверь `/etc/telemt/config.toml` на предмет правильного `tls_domain`.
|
||
|
||
**Q: Pro-режим не получил сертификат.**
|
||
A: Проверь, что домен резолвится в правильный IP: `dig +short твой-домен.com`. Должен быть IP VPS. Если DNS правильный — проверь, что 80 и 443 никем не заняты кроме telemt (certbot на момент выдачи сертификата временно занимает 80). Попробуй пункт 11 (ручная перегенерация SSL).
|
||
|
||
**Q: Как сменить домен маскировки в Lite-режиме?**
|
||
A: Пункт 7 → сменить режим/шаблон. Можно также просто переустановить (пункт 1) — текущий конфиг сохранится в бекапе.
|
||
|
||
**Q: Бот не реагирует.**
|
||
A: Посмотри логи бота в пункте 12 → «Логи бота». Чаще всего — неверный токен или неверный admin ID в `.env`.
|
||
|
||
**Q: Могу ли я поставить несколько прокси на одном VPS?**
|
||
A: На одном IP на порту 443 — нет, telemt один. На разных портах — можно, но скрипт этого не поддерживает из коробки, нужно руками.
|
||
|
||
**Q: Это легально?**
|
||
A: Сам MTProxy — да, это публичная технология из исходников Telegram. Запуск прокси, чтобы твои друзья могли пользоваться Telegram там, где он заблокирован — в большинстве юрисдикций легально. Проверь локальные законы.
|
||
|
||
---
|
||
|
||
## 12. Где что лежит
|
||
|
||
| Что | Где |
|
||
| --- | --- |
|
||
| Скрипты (`install.sh`, `lib/`) | `/opt/gotelegram/` |
|
||
| Симлинк запуска | `/usr/local/bin/gotelegram` |
|
||
| Конфиг telemt | `/etc/telemt/config.toml` |
|
||
| Конфиг goTelegram Pro (JSON) | `/opt/gotelegram/config.json` |
|
||
| Бинарник telemt | `/usr/local/bin/telemt` |
|
||
| Systemd юнит | `/etc/systemd/system/telemt.service` |
|
||
| Бот | `/opt/gotelegram-bot/` |
|
||
| Systemd юнит бота | `/etc/systemd/system/gotelegram-bot.service` |
|
||
| Сайт (Pro-режим) | `/var/www/gotelegram-site/` |
|
||
| nginx site | `/etc/nginx/sites-available/gotelegram` |
|
||
| Бекапы | `/opt/gotelegram/backups/` |
|
||
| Лог goTelegram Pro | `/var/log/gotelegram.log` |
|
||
| Логи telemt | `journalctl -u telemt` |
|
||
| Логи бота | `journalctl -u gotelegram-bot` |
|
||
|
||
---
|
||
|
||
## 13. Контакты и развитие
|
||
|
||
- Баги и пожелания — issues в репозитории `anten-ka/gotelegram_pro`.
|
||
- Владелец: Vitalii (`anten-ka`).
|
||
- Ветки: `test` (заморожена, stable для пользователей), `alfa-test` (активная разработка).
|
||
|
||
---
|
||
|
||
## Changelog (коротко)
|
||
|
||
- **2.5.0** — единая версия по коду и документации; удалён дефолтный PAT из `bootstrap.sh`; исправлена статистика в боте (CSV header больше не ломает чтение истории, бот сам обновляет snapshot); CLI-смена шаблона теперь обновляет `config.json.template_id`, поэтому бот показывает текущий шаблон; telemt TOML включает локальный API `127.0.0.1:9091` и metrics на `127.0.0.1:9090`; добавлено меню Telegram-бота для отдельных ключей пользователей (`[access.users]`): список, добавление, отключение/включение, удаление, ссылка и информация из API telemt; добавлена локальная web-админка goTelegram Pro на `127.0.0.1:1984` под SSH tunnel без отдельного токена, с вкладками, иконками, promo-разделом раз в 24 часа, i18n от языка установки, ручным переключателем RU/EN, проверкой сайта на HTTP 200, тёмной темой, адаптивом, быстрыми switch-переключателями ключей, блоком реальных TCP/UDP-слушателей 443, подсказками к техническим терминам и traffic history по периодам 15 минут / 1 час / 24 часа / месяц; backup/restore сохраняет bot `.env`, языки бота, отключённые ключи, web-admin server/static, custom templates, stats history и структуру Let's Encrypt для переезда на новый VPS; добавлен безопасный детект 3x-ui/Xray на 443 с предупреждением и заметкой по shared-443.
|
||
- **2.4.6** — ожидание apt/dpkg lock на свежих Ubuntu/Debian, чтобы установка nginx/certbot/Python не падала во время unattended-upgrades.
|
||
- **2.4.3** — фикс гонки в `bot_action_dispatch`: параллельные вызовы `change-lite-domain`/`change-template` (например, два пользователя бота одновременно) могли получить ошибку «no secret in config», если один процесс читал `config.json` в момент, когда другой его перезаписывал через `jq`. Теперь диспетчер оборачивается в `flock(1)` с таймаутом 30 с; `util-linux` (содержит `flock`) добавлен в критические зависимости.
|
||
- **2.4.2** — смена шаблона и домена маскировки **прямо из Telegram-бота** без SSH. Раньше эти пункты меню показывали сообщение «сделай через CLI», теперь бот вызывает `install.sh --action=change-template --json` / `--action=change-lite-domain --json` и разбирает ответ. Плюс: безопасный `safe_edit_message` принимает `disable_web_page_preview`; поле статуса шаблона наконец-то отображается (раньше читалось не из того ключа JSON); полный аудит и автоустановка системных зависимостей при первом запуске (`curl jq openssl git xxd tar dig flock` + опциональные `qrencode bc`); `asyncio.Lock` в боте сериализует параллельные callback'и; валидация tpl\_id (`[A-Za-z0-9_-]{1,64}`) и домена до subprocess.
|
||
- **2.4.1** — фикс: `start_telemt` теперь делает `restart` если сервис уже запущен. Раньше переустановка Lite поверх Pro оставляла в памяти старый конфиг, и клиенты получали «Unknown TLS SNI drop». Плюс полная документация проекта (этот файл и `DOCS_AI.md`).
|
||
- **2.4.0** — i18n EN/RU для CLI (328 ключей) и бота (99 ключей JSON с per-user persistence). Возможность загрузить свой шаблон сайта из произвольного git-репо (с валидацией URL, таймаутами, лимитом размера клона).
|
||
- **2.3.x** — каталог шаблонов расширен до 1801, 4 источника, 18 категорий. Поддержка StartBootstrap `dist/` структуры.
|
||
- **2.2.1** — критические фиксы `$()` capture (все UI-вывод через `>&2`), StartBootstrap dist-структура, symlink SCRIPT_DIR через `readlink -f`, XSS в HTML-превью бота, OS-release injection.
|
||
- **2.2** — переход с mtg на telemt v3, новый TOML-формат конфига, stealth-архитектура.
|
||
|
||
Полный changelog — в commit-истории `anten-ka/gotelegram_pro`.
|