mirror of https://github.com/anten-ka/gotelegram_pro.git synced 2026-05-19 11:26:03 +00:00

Files

Виталий Литвинов 4332990fd5 Expand project documentation for users and agents

2026-04-26 12:53:21 +03:00

30 KiB

Raw Blame History

goTelegram Pro — руководство пользователя

Версия: 2.5.0 Репозиторий: anten-ka/gotelegram_pro Для кого: владельцы VPS, которым нужен надёжный MTProxy для Telegram с маскировкой под обычный HTTPS-сайт.

Если ты впервые видишь проект: установщик сам скачивает нужные файлы, ставит ядро прокси, создаёт меню gotelegram, умеет выпустить SSL-сертификат, поднять сайт-маскировку, Telegram-бота, локальную web-админку и бэкапы. Для обычной работы не нужно вручную редактировать /etc/telemt/config.toml.

1. Что это такое

goTelegram Pro — это готовый менеджер прокси-сервера MTProxy для Telegram. Он делает три вещи, которые иначе пришлось бы собирать вручную:

Ставит и настраивает ядро telemt (это современный Rust-порт mtproto-proxy с fake-TLS маскировкой).
Запускает рядом обычный HTTPS-сайт на настоящем домене, так что провайдеру со стороны всё выглядит как посещение безобидного лендинга — а на самом деле в том же соединении ходит Telegram-трафик. Это называется «stealth» или «Pro-режим».
Даёт Telegram-бота, через которого можно управлять прокси со смартфона: ссылка, статус, перезапуск, бекап, смена маскировочного домена, выбор шаблона сайта.

Всё управляется одним меню gotelegram в терминале. Внутри есть 5 понятных разделов: прокси, статистика, управление, Telegram-бот и информация о проекте.

Простая модель в голове

telemt — само ядро MTProxy, принимает Telegram-клиентов.
nginx — показывает обычный сайт, когда на домен заходит браузер.
config.json — память goTelegram Pro: режим, домен, язык, шаблон, настройки.
Telegram-бот — мобильное управление без SSH.
Web-админка — красивая локальная панель через SSH-туннель.
Бэкап — архив с ключами, сайтом, ботом, сертификатами, настройками и статистикой.

2. Быстрый старт

На чистом Ubuntu/Debian VPS под root:

export GOTELEGRAM_PAT="YOUR_PAT"; bash <(curl -sL -H "Authorization: token $GOTELEGRAM_PAT" "https://raw.githubusercontent.com/anten-ka/gotelegram_pro/main/bootstrap.sh")

Если нужно поставить строго зафиксированный релиз или тег, укажи ветку/тег явно:

export GOTELEGRAM_PAT="YOUR_PAT" GOTELEGRAM_BRANCH="v2.5.0"; bash <(curl -sL -H "Authorization: token $GOTELEGRAM_PAT" "https://raw.githubusercontent.com/anten-ka/gotelegram_pro/v2.5.0/bootstrap.sh")

bootstrap.sh скачает все файлы из приватного репозитория, создаст симлинк /usr/local/bin/gotelegram и запустит главное меню. Через минуту команда gotelegram уже будет работать откуда угодно.

Дальше в меню:

1) Прокси → 1) Установить / обновить — ставит прокси, спрашивает режим Lite/Pro, домен и шаблон.
1) Прокси → 2) Подробный статус — показывает, жив ли telemt, IP, порт, режим и домен.
1) Прокси → 3) Ссылка — показывает tg://proxy?... и 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) Статистика
 3) Управление
 4) Telegram-бот
 5) О программе
 0) Выход

Раздел 1) Прокси
 1) Установить / обновить     — первый запуск или повторная установка
 2) Подробный статус          — IP, порт, режим, домен, состояние telemt
 3) Ссылка                    — tg://proxy?... и QR
 4) Поделиться                — готовое сообщение для пользователя
 5) Перезапуск                — restart telemt
 6) Логи                      — последние строки journalctl -u telemt
 7) Сменить режим             — Lite/Pro, домен, шаблон
 0) Назад

Раздел 2) Статистика
 1) Включить/выключить сбор   — переключает stats_enabled
 2) Сборщик статистики        — установка/перезапуск gotelegram-stats
 0) Назад

Раздел 3) Управление
 1) Бэкап                     — создать архив состояния
 2) Восстановить              — восстановить из архива
 3) Обновить telemt           — обновить только бинарник ядра
 4) Сайт / SSL                — операции с сайтом и сертификатом
 5) Удалить                   — удалить прокси, бота или всё целиком
 6) Язык                      — русский / английский
 0) Назад

Раздел 4) Telegram-бот
  Установка, токен BotFather, admin ID, статус, логи, перезапуск.

Раздел 5) О программе
  Версия, стек, промо-раздел.

 0) Выход

5. Telegram-бот

Раздел 4) Telegram-бот разворачивает отдельный Python-сервис (python-telegram-bot v21+), который:

Показывает статус прокси, ссылку и QR.
Умеет перезапускать telemt прямо из чата.
Делает бекап и восстанавливает.
Переключает режим (Lite ↔ Pro).
Меняет маскировочный домен.
Меняет сайт-шаблон из каталога на 1800+ готовых HTML-шаблонов (4 источника: html5up, startbootstrap, ThemeWagon, dawidolko).
Поддерживает 2 языка: русский и английский. Каждый пользователь выбирает свой, настройка сохраняется.

Чтобы запустить бота, нужны только два параметра — токен от @BotFather и твой Telegram ID (чтобы никто кроме тебя бота не использовал). Меню подсказывает где что ввести.

При обновлении goTelegram Pro установленный бот обновляется автоматически: новые bot.py, i18n.py, языковые файлы и requirements.txt копируются в /opt/gotelegram-bot/, зависимости проверяются, сервис gotelegram-bot перезапускается. Файл /opt/gotelegram-bot/.env с токеном и администраторами сохраняется.

6. Язык интерфейса

CLI и бот переведены на русский и английский. Выбор языка идёт:

В CLI — при первом запуске спрашивает один раз и запоминает в config.json.
В боте — отдельная кнопка «🇬🇧/🇷🇺», переключение на лету, сохранение per-user.

Вся логика интерфейса, ошибок, подсказок, меню — переведена.

7. Бекап и восстановление

Раздел 3) Управление → 1) Бэкап делает один файл .tar.gz со всем, что нужно: /etc/telemt/config.toml, /opt/gotelegram/config.json, /opt/gotelegram/disabled_users.json, данные nginx-сайта, сертификаты Let's Encrypt (live/archive/renewal), пользовательские шаблоны, каталог шаблонов, историю трафика, состояние Telegram-бота и локальной web-админки. По умолчанию архивы лежат в /opt/gotelegram/backups/.

Раздел 3) Управление → 2) Восстановить принимает такой архив и восстанавливает всё обратно (конфиг, сервис, ссылка — всё то же, что было). Перед восстановлением из админки или Telegram-бота автоматически создаётся свежий safety-бекап текущего состояния.

В web-админке и Telegram-боте есть сценарии автобэкапов: выключено, каждый день, каждую неделю или каждый месяц. Это systemd timer gotelegram-backup.timer; автоматическая чистка оставляет последние 30 архивов, чтобы каталог не рос бесконечно. Старые простые архивы backup_*.tar.gz, которые создавал ранний Telegram-бот только из двух конфигов, тоже распознаются при восстановлении как legacy-формат.

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.

Как открыть через Termius:

Открой нужный Host или создай новый.
Укажи Address = IP сервера, Username = root, пароль или ключ SSH.
Открой настройки Host → Port Forwarding / Tunnels.
Добавь tunnel типа Local.
Local host: localhost.
Local port: 1984.
Destination host: 127.0.0.1.
Destination port: 1984.
Подключись к серверу через этот Host.
Открой в браузере http://localhost:1984.

В админке есть dashboard, проверка сайта https://домен/ на HTTP 200, статус сервисов, полезный блок «кто слушает порт 443» по данным ss, управление ключами [access.users] с добавлением, удалением и быстрым отключением через switch, лимит одновременных уникальных IP на ключ через [access.user_max_unique_ips] (0 — безлимит), генерация ссылок и QR-кодов для импорта в Telegram, traffic history по периодам 15 минут / 1 час / 24 часа / месяц с переключателем график/строки, такая же статистика по каждому ключу, кнопка разового обновления статистики, кнопка перезапуска сборщика, список/создание/восстановление бекапов, расписание автобэкапов и просмотр логов с количеством строк и статусом journalctl.

История трафика хранится максимум 1 год. Чтобы файлы не разрастались, последние 31 день пишутся поминутно, а более старая история автоматически уплотняется до одной точки в час. Для обычного просмотра 15 минут / 1 час / 24 часа / месяц детализация остаётся полной.

8.1 3x-ui / VLESS на том же 443

Один порт 443 не могут одновременно слушать telemt и Xray напрямую. Для совместной работы используется схема shared-443: публичный 443 занимает nginx stream-диспетчер, goTelegram telemt переносится на 127.0.0.1:7443, сайт остаётся на 127.0.0.1:8443, а inbound 3x-ui/Xray нужно в панели перенести на внутренний адрес, например 127.0.0.1:9443.

После переноса Xray-входа можно включить маршрут:

source /opt/gotelegram/lib/shared443.sh
shared443_enable my-domain.com xray-domain.com 127.0.0.1:9443

goTelegram Pro не переписывает базу 3x-ui автоматически, потому что панель может перегенерировать Xray-конфиг. Админка показывает карту 443: публичный edge, telemt, сайт и Xray-маршруты.

Отключённые ключи убираются из активного telemt-конфига и сохраняются в /opt/gotelegram/disabled_users.json, поэтому их можно включить обратно без потери secret. Основной ключ main защищён от удаления и отключения.

Лимит IP хранится в /etc/telemt/config.toml в секции [access.user_max_unique_ips]. Значение 0 в UI означает отсутствие строки в этой секции и безлимит. Значение 1, 2 и выше ограничивает количество одновременно активных уникальных IP для выбранного ключа; если лимит уже занят, новый IP не проходит, пока один из старых не отключится.

9. Обновление

Два типа обновлений:

Обновление ядра telemt (пункт 10) — тянет свежий бинарник с GitHub Releases telemt/telemt, сохраняет старый в .bak, перезапускает сервис. Конфиг остаётся как был.
Обновление самого goTelegram Pro (повторный запуск bootstrap или пункт 1 после скачивания новых файлов) — переустанавливает скрипты и lib/, обновляет локальную web-админку и уже установленный Telegram-бот. config.json, ключи, домен и /opt/gotelegram-bot/.env не трогаются.

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 должен быть свободен. Для совместной работы с 3x-ui/Xray используйте shared-443 и переносите Xray inbound на внутренний порт, например 127.0.0.1:9443.
Для 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: Да, через shared-443: nginx stream слушает публичный 443, goTelegram telemt работает на 127.0.0.1:7443, а Xray/3x-ui — на внутреннем порту вроде 127.0.0.1:9443. Напрямую два процесса на 0.0.0.0:443 работать не будут.

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).
Ветки: main — основная стабильная установка; beta — следующая публичная сборка для проверки; alpha — ранние личные эксперименты владельца.

Changelog (коротко)

2.5.0 — единая версия по коду и документации; удалён дефолтный PAT из bootstrap.sh; исправлена статистика в боте (CSV header больше не ломает чтение истории, бот сам обновляет snapshot); установленный Telegram-бот теперь автоматически обновляется при повторном bootstrap/update без потери .env; CLI-смена шаблона теперь обновляет config.json.template_id, поэтому бот показывает текущий шаблон; telemt TOML включает локальный API 127.0.0.1:9091 и metrics на 127.0.0.1:9090; добавлено меню Telegram-бота для отдельных ключей пользователей ([access.users]): список, добавление, отключение/включение, удаление, ссылка, QR-код, текущий runtime, лимит уникальных IP через [access.user_max_unique_ips] и история трафика по ключу; добавлена локальная web-админка goTelegram Pro на 127.0.0.1:1984 под SSH tunnel без отдельного токена, с вкладками, иконками, promo-разделом раз в 24 часа, i18n от языка установки, ручным переключателем RU/EN, проверкой сайта на HTTP 200, тёмной темой, адаптивом, быстрыми switch-переключателями ключей, настройкой IP-лимита, QR-кодами, блоком реальных TCP/UDP-слушателей 443, подсказками к техническим терминам, traffic history по периодам 15 минут / 1 час / 24 часа / месяц и per-user traffic history; backup/restore сохраняет bot .env, языки бота, отключённые ключи, web-admin server/static, custom templates, stats history, user stats history, shared-443 config и структуру Let's Encrypt для переезда на новый VPS; добавлены ручные/ежедневные/еженедельные/ежемесячные бэкапы, восстановление из админки/бота с safety-бекапом и legacy-restore для старых backup_*.tar.gz; добавлен безопасный детект 3x-ui/Xray на 443 и управляемый nginx stream shared-443 dispatcher.
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.

30 KiB Raw Blame History Unescape Escape