gotelegram_pro/DOCS_HUMAN.md

# 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
export GOTELEGRAM_PAT="YOUR_PAT"; bash <(curl -sL -H "Authorization: token $GOTELEGRAM_PAT" "https://raw.githubusercontent.com/anten-ka/gotelegram_pro/beta/bootstrap.sh")
```

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

```bash
export GOTELEGRAM_PAT="YOUR_PAT" GOTELEGRAM_BRANCH="v2.5.0-beta.1"; bash <(curl -sL -H "Authorization: token $GOTELEGRAM_PAT" "https://raw.githubusercontent.com/anten-ka/gotelegram_pro/v2.5.0-beta.1/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 (чтобы никто кроме тебя бота не использовал). Меню подсказывает где что ввести.

При обновлении 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. Бекап и восстановление

Пункт 8 делает один файл `.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/`.

Пункт 9 принимает такой архив и восстанавливает всё обратно (конфиг, сервис, ссылка — всё то же, что было). Перед восстановлением из админки или 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`.

В админке есть 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-входа можно включить маршрут:

```bash
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`.