From 4332990fd55f2000ef223afaf89ba79be0b3316a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=92=D0=B8=D1=82=D0=B0=D0=BB=D0=B8=D0=B9=20=D0=9B=D0=B8?= =?UTF-8?q?=D1=82=D0=B2=D0=B8=D0=BD=D0=BE=D0=B2?= Date: Sun, 26 Apr 2026 12:53:21 +0300 Subject: [PATCH] Expand project documentation for users and agents --- DOCS_AI.md | 76 ++++++++++++++++++++++++++++------------- DOCS_HUMAN.md | 94 +++++++++++++++++++++++++++++++++++++-------------- README.md | 80 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 200 insertions(+), 50 deletions(-) create mode 100644 README.md diff --git a/DOCS_AI.md b/DOCS_AI.md index e73d24a..b75d7e0 100644 --- a/DOCS_AI.md +++ b/DOCS_AI.md @@ -2,13 +2,30 @@ **Версия:** 2.5.0 **Репозиторий:** `anten-ka/gotelegram_pro` -**Активная ветка:** `main` — основной код и продакшен. +**Активная ветка:** `main` — основной код и продакшен. `beta` и `alpha` существуют для следующих сборок. **Целевая ОС:** Ubuntu 20.04+, Debian 11+ Этот документ описывает устройство проекта с максимальным количеством нюансов — все ловушки, на которые мы уже наступали, все причины «почему именно так», формат всех внешних интерфейсов, и checklist действий для типовых задач. Цель: чтобы новый агент мог продолжить работу без повторения ошибок и без регрессий. --- +## 0. Быстрый старт для нового ИИ + +Если ты агент, который впервые открыл репозиторий: + +1. Не трогай токены, ключи VPS и BotFather-токены в истории диалога; не печатай их в ответах и не клади в файлы. +2. Основной код устанавливается из `main`; `bootstrap.sh` по умолчанию скачивает `main`, если не задан `GOTELEGRAM_BRANCH`. +3. Рабочая модель веток: `alpha` для ранних экспериментов, `beta` для проверочных сборок, `main` для продакшена. +4. Главный код установки — `install.sh` + `lib/*.sh`. Не исправляй Telegram-бот или web-admin в отрыве от bash-слоя: все три интерфейса должны показывать одно и то же состояние. +5. Главный конфиг пользователя — `/opt/gotelegram/config.json`; главный runtime-конфиг ядра — `/etc/telemt/config.toml`. +6. `telemt` использует TOML v3, не совместимый со старым `mtg`. Не возвращай старые секции `[security]`, `[[users]]`, `bind_to`. +7. Любая bash-функция, которую вызывают через `$()`, обязана писать UI и логи в stderr (`>&2`), а в stdout возвращать только значение. +8. Перед пушем запускай проверки из раздела 20. Для документации минимум: bash syntax, unit tests, py_compile, node check, `git diff --check`. +9. Если меняешь поведение, обновляй `DOCS_HUMAN.md`, `DOCS_AI.md`, changelog и при необходимости `GOTELEGRAM_VERSION`. +10. Если меняешь бэкапы, сохраняй обратную совместимость restore для старых архивов. + +--- + ## 1. Общая картина goTelegram Pro — это менеджер MTProxy для Telegram, собранный вокруг Rust-ядра **telemt** (порт mtproto-proxy с поддержкой fake-TLS, v3.3.x). Проект даёт три вещи: @@ -43,15 +60,17 @@ tls_domain = google.com (или любой из QUICK_DOMAINS) ``` anten-ka/gotelegram_pro -└── main ← основной код и продакшен +├── main ← продакшен и дефолтная установка +├── beta ← следующая публичная сборка для проверки пользователями +└── alpha ← ранние личные сборки владельца ``` -**Правило коммитов:** изменения идут в `main` только после локальных проверок. Перед любым рискованным переносом или force-update создавай rollback tag/release для текущего состояния `main`. +**Правило коммитов:** новые рискованные изменения сначала идут в `alpha`, затем после ручной проверки в `beta`. В `main` попадает только код, который можно считать установочным по умолчанию. Перед любым рискованным переносом или force-update создавай rollback tag/release для текущего состояния целевой ветки. **Инструменты для коммитов:** - Основной путь — обычный `git commit` + `git push` в нужную ветку после локальной проверки. - Если окружение не может пушить напрямую, используй GitHub REST API с PAT из переменной окружения `GOTELEGRAM_PAT`. -- Workflow через GitHub API: `POST git/blobs` для каждого файла → `POST git/trees` (с `base_tree` от текущего HEAD) → `POST git/commits` (parents=[текущий HEAD]) → `PATCH git/refs/heads/main` (sha=новый commit) → при необходимости `POST /releases`. +- Workflow через GitHub API: `POST git/blobs` для каждого файла → `POST git/trees` (с `base_tree` от текущего HEAD) → `POST git/commits` (parents=[текущий HEAD]) → `PATCH git/refs/heads/` (sha=новый commit) → при необходимости `POST /releases`. - **Важно про `base_tree`:** при частичном обновлении (1-2 файла) ОБЯЗАТЕЛЬНО передавать `base_tree` — иначе дерево получится только из переданных файлов, и все остальные файлы пропадут из коммита. `base_tree` можно опускать только при коммите с полным набором файлов. --- @@ -59,12 +78,13 @@ anten-ka/gotelegram_pro ## 3. Карта файлов ``` -install.sh главная точка входа, CLI-меню из 14 пунктов +install.sh главная точка входа, CLI-меню из 5 разделов install_gotelegram_bot.sh legacy-установщик бота (функционал продублирован в install.sh) bootstrap.sh установщик приватного репо через raw.githubusercontent.com с PAT templates_catalog.json каталог 1801 шаблонов, 18 категорий, 4 источника (~460KB) DOCS_HUMAN.md документация для пользователя (этот каталог) DOCS_AI.md этот файл +README.md короткая входная точка проекта lib/common.sh цвета, log_*, confirm, select_option, _valid_ip, config_get, save_gotelegram_config, get_server_ip, run_with_spinner, @@ -88,7 +108,12 @@ gotelegram-bot/bot.py Telegram-бот (python-telegram-bot v21+) gotelegram-bot/config.example.env gotelegram-bot/requirements.txt gotelegram-bot/README.md -gotelegram-bot/locales/*.json 99 ключей i18n для бота с per-user persistence +gotelegram-bot/lang/*.json i18n для бота с per-user persistence + +admin-web/server.py backend локальной админки на Python stdlib +admin-web/static/index.html shell интерфейса админки +admin-web/static/app.js frontend логика, API calls, графики, таблицы +admin-web/static/styles.css responsive light/dark UI ``` **Где что лежит на VPS после установки:** @@ -362,12 +387,12 @@ Fallback: если по известным правилам index.html не на Ключевые моменты: - **Admin ID** — бот отвечает только пользователю с `ADMIN_TG_ID` из `.env`. Всё остальное игнорируется. - **safe_edit_message** — обёртка над `query.edit_message_text` + `query.edit_message_caption`, глотает `BadRequest: message is not modified`. Начиная с v2.4.2 принимает опциональный `disable_web_page_preview` — не забудь прокинуть его если показываешь ссылку-превью (раньше вызов с этим kwarg ловил TypeError в runtime). Используй её всегда вместо прямого вызова. -- **Language per-user** — файл `locales/users.json` хранит `{user_id: "ru"/"en"}`. При каждом сообщении бот читает язык пользователя и подставляет строку через `t(key, lang)`. +- **Language per-user** — файл `/opt/gotelegram-bot/user_langs.json` хранит `{user_id: "ru"/"en"}`. При каждом сообщении бот читает язык пользователя и подставляет строку через `t(user_id, key)` / `tf(user_id, key, ...)`. - **QR-коды** — генерятся в `/tmp/gotelegram_qr_*.png`, отправляются как `InputFile`, удаляются в `finally`. - **Шаблон preview в HTML** — URL экранируется через `html.escape(url, quote=True)` (баг #11). - **Системные действия (v2.4.2+)** — бот реально умеет менять шаблон и домен маскировки. Хелпер `run_bot_action(action, **kwargs)` вызывает `subprocess.run(["/opt/gotelegram/install.sh", "--action=X", "--json", ...])` и парсит JSON. Два коллбэка: `cb_pro_confirm` (change-template) и `cb_lite_domain` (change-lite-domain). Оба обёрнуты в `async with _BOT_ACTION_LOCK` (глобальный `asyncio.Lock()`) — сериализуют параллельные callback'и внутри процесса бота. Входы валидируются ДО subprocess: `_TPL_ID_RE = r"^[A-Za-z0-9_-]{1,64}$"`, `_DOMAIN_RE` (RFC-like). Малформный ввод отвергается с понятным сообщением, не доходя до shell. - **Поле `template_id` в config.json** — канонический ключ для текущего шаблона. Раньше (до v2.4.2) бот читал `config['template']` и писал в него же в `handle_text_message`, но `save_gotelegram_config` всегда писал `template_id` → поле статуса никогда не отображалось. Используй только `template_id`. -- **Устанавливается** из меню `install.sh → 12) Telegram-бот → Установить`. Пользователь вводит BotFather token + свой Telegram ID, `.env` пишется в `/opt/gotelegram-bot/.env`. +- **Устанавливается** из меню `install.sh → 4) Telegram-бот → Установить`. Пользователь вводит BotFather token + свой Telegram ID, `.env` пишется в `/opt/gotelegram-bot/.env`. - **Обновляется автоматически (v2.5.0+)** при повторном bootstrap/update: `auto_update_bot_if_possible` сравнивает новые файлы в `$SCRIPT_DIR/gotelegram-bot/` с установленными `/opt/gotelegram-bot/{bot.py,i18n.py,requirements.txt,lang/*.json}`. Если есть отличия и сервис уже установлен, вызывается `bot_install >/dev/null`, `.env` сохраняется, зависимости обновляются, systemd unit переписывается и `gotelegram-bot` перезапускается. Это закрывает сценарий 2.4.x → 2.5.0, где bootstrap обновлял `/opt/gotelegram/gotelegram-bot/`, но рабочий сервис продолжал запускать старый `/opt/gotelegram-bot/bot.py`. ### 11.1 Non-interactive action bridge (install.sh ↔ bot) @@ -502,7 +527,7 @@ Traffic retention: обе CSV-истории хранятся максимум 3 import os, base64, json, urllib.request, ssl TOKEN = os.environ["GOTELEGRAM_PAT"] REPO = "anten-ka/gotelegram_pro" - BRANCH = "main" + BRANCH = "main" # или beta/alpha для соответствующей ветки API = f"https://api.github.com/repos/{REPO}" headers = { "Authorization": f"Bearer {TOKEN}", @@ -621,7 +646,15 @@ with socket.create_connection(("95.163.176.222", 443), timeout=5) as s: ## 16. Меню (install.sh) ``` -── Прокси ── +Главный экран: + 1) submenu_proxy (установка, статус, ссылка, share, restart, logs, change mode) + 2) submenu_stats (show_traffic_stats, toggle_stats, install_stats_collector) + 3) submenu_manage (backup, restore, update_telemt, website/SSL, remove, language) + 4) menu_bot (install/start/stop/logs/change token/remove bot, installs admin web) + 5) submenu_about (version info, promo) + 0) exit + +Раздел Proxy: 1) menu_install (Lite/Pro выбор, domain, template, certbot) 2) menu_status (telemt_status + show_proxy_info) 3) menu_link (ссылка + QR) @@ -630,18 +663,13 @@ with socket.create_connection(("95.163.176.222", 443), timeout=5) as s: 6) menu_logs (telemt_logs 40) 7) menu_change_mode (lite↔pro, смена шаблона, смена домена маскировки) -── Управление ── - 8) interactive_backup (create_backup) - 9) interactive_restore (select_backup + restore_backup) -10) update_telemt (check_telemt_update → download → restart) -11) menu_website (nginx restart, certbot renew) - -── Бот и прочее ── -12) menu_bot (install_bot / start / stop / logs / change_token / remove) -13) menu_remove (только прокси / только бот / всё) -14) menu_promo (подарочные ссылки — маркетинг) - - 0) exit +Раздел Management: + 1) interactive_backup (create_backup) + 2) interactive_restore (select_backup + restore_backup) + 3) update_telemt (check_telemt_update → download → restart) + 4) menu_website (nginx restart, certbot renew) + 5) menu_remove (только прокси / только бот / всё) + 6) menu_language (switch_language ru|en) ``` Диспатчер в `install.sh` (`bot_action_dispatch`) принимает `--action=` для автоматизации из бота. Полный контракт описан в разделе 11.1. @@ -705,7 +733,7 @@ with socket.create_connection(("95.163.176.222", 443), timeout=5) as s: ## 20. Контрольные точки и инварианты -Перед любым пушем в `main`: +Перед любым пушем в `main`/`beta`/`alpha`: 1. `bash -n install.sh lib/*.sh` — синтаксис bash ОК. 2. Все новые `$()`-вызываемые функции пишут UI через `>&2`. 3. Все пути к lib/ идут через `$SCRIPT_DIR/lib/...`, а `SCRIPT_DIR` — через `readlink -f`. @@ -716,7 +744,7 @@ with socket.create_connection(("95.163.176.222", 443), timeout=5) as s: После пуша: 1. Подождать пока нужная ветка обновится (GitHub API мгновенно, raw кеш ~30 сек). -2. На VPS: повторить bootstrap из ветки `main` с `GOTELEGRAM_PAT`; скрипт сам скачает файлы, обновит установленный бот/админку и покажет меню. +2. На VPS: повторить bootstrap из целевой ветки с `GOTELEGRAM_PAT` и при необходимости `GOTELEGRAM_BRANCH=beta|alpha|main`; скрипт сам скачает файлы, обновит установленный бот/админку и покажет меню. 3. `telemt_status` → running. `journalctl -u telemt` → нет ошибок. Ссылка открывается в Telegram-клиенте. --- diff --git a/DOCS_HUMAN.md b/DOCS_HUMAN.md index 8ffad5d..47c273a 100644 --- a/DOCS_HUMAN.md +++ b/DOCS_HUMAN.md @@ -4,6 +4,8 @@ **Репозиторий:** `anten-ka/gotelegram_pro` **Для кого:** владельцы VPS, которым нужен надёжный MTProxy для Telegram с маскировкой под обычный HTTPS-сайт. +Если ты впервые видишь проект: установщик сам скачивает нужные файлы, ставит ядро прокси, создаёт меню `gotelegram`, умеет выпустить SSL-сертификат, поднять сайт-маскировку, Telegram-бота, локальную web-админку и бэкапы. Для обычной работы не нужно вручную редактировать `/etc/telemt/config.toml`. + --- ## 1. Что это такое @@ -14,7 +16,16 @@ goTelegram Pro — это готовый менеджер прокси-серв 2. Запускает рядом обычный HTTPS-сайт на настоящем домене, так что провайдеру со стороны всё выглядит как посещение безобидного лендинга — а на самом деле в том же соединении ходит Telegram-трафик. Это называется «stealth» или «Pro-режим». 3. Даёт Telegram-бота, через которого можно управлять прокси со смартфона: ссылка, статус, перезапуск, бекап, смена маскировочного домена, выбор шаблона сайта. -Всё управляется одним меню из 14 пунктов (`gotelegram` в терминале) — не нужно лазить по конфигам. +Всё управляется одним меню `gotelegram` в терминале. Внутри есть 5 понятных разделов: прокси, статистика, управление, Telegram-бот и информация о проекте. + +### Простая модель в голове + +- **telemt** — само ядро MTProxy, принимает Telegram-клиентов. +- **nginx** — показывает обычный сайт, когда на домен заходит браузер. +- **config.json** — память goTelegram Pro: режим, домен, язык, шаблон, настройки. +- **Telegram-бот** — мобильное управление без SSH. +- **Web-админка** — красивая локальная панель через SSH-туннель. +- **Бэкап** — архив с ключами, сайтом, ботом, сертификатами, настройками и статистикой. --- @@ -26,7 +37,7 @@ goTelegram Pro — это готовый менеджер прокси-серв export GOTELEGRAM_PAT="YOUR_PAT"; bash <(curl -sL -H "Authorization: token $GOTELEGRAM_PAT" "https://raw.githubusercontent.com/anten-ka/gotelegram_pro/main/bootstrap.sh") ``` -Если нужно поставить строго зафиксированный prerelease, укажи ветку/тег явно: +Если нужно поставить строго зафиксированный релиз или тег, укажи ветку/тег явно: ```bash 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") @@ -36,9 +47,9 @@ export GOTELEGRAM_PAT="YOUR_PAT" GOTELEGRAM_BRANCH="v2.5.0"; bash <(curl -sL -H Дальше в меню: -- **1) Установить / обновить** — ставит прокси, спрашивает режим (Lite или Pro) и домен маскировки. -- **2) Статус** — показывает, жив ли telemt, IP, порт, маскировку и готовую `tg://proxy?...` ссылку. -- **3) Ссылка** — тот же ключ отдельно, вместе с QR-кодом. +- **1) Прокси → 1) Установить / обновить** — ставит прокси, спрашивает режим Lite/Pro, домен и шаблон. +- **1) Прокси → 2) Подробный статус** — показывает, жив ли telemt, IP, порт, режим и домен. +- **1) Прокси → 3) Ссылка** — показывает `tg://proxy?...` и QR-код. Дальше можно открыть Telegram → Настройки → Данные и память → Прокси → добавить по ссылке. Готово. @@ -71,25 +82,43 @@ export GOTELEGRAM_PAT="YOUR_PAT" GOTELEGRAM_BRANCH="v2.5.0"; bash <(curl -sL -H ## 4. Меню целиком ``` -── Прокси ── - 1) Установить / обновить — первый раз или апгрейд - 2) Статус — IP, порт, маскировка, живость - 3) Ссылка — tg://proxy?... + QR - 4) Поделиться — текстовое сообщение «для друзей» - 5) Перезапуск — systemctl restart telemt - 6) Логи — последние 40 строк telemt - 7) Сменить режим / шаблон — Lite↔Pro, сменить сайт-шаблон +Главный экран + 1) Прокси + 2) Статистика + 3) Управление + 4) Telegram-бот + 5) О программе + 0) Выход -── Управление ── - 8) Бекап — tar.gz всех конфигов и ключей - 9) Восстановить — откат из бекапа -10) Обновить telemt — скачать свежий бинарник -11) Сайт (SSL) — ручная перегенерация сертификата +Раздел 1) Прокси + 1) Установить / обновить — первый запуск или повторная установка + 2) Подробный статус — IP, порт, режим, домен, состояние telemt + 3) Ссылка — tg://proxy?... и QR + 4) Поделиться — готовое сообщение для пользователя + 5) Перезапуск — restart telemt + 6) Логи — последние строки journalctl -u telemt + 7) Сменить режим — Lite/Pro, домен, шаблон + 0) Назад -── Бот и прочее ── -12) Telegram-бот — установить / настроить бота -13) Удалить всё — снести прокси / бота / вообще всё -14) Промо — подарочные ссылки +Раздел 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) Выход ``` @@ -98,7 +127,7 @@ export GOTELEGRAM_PAT="YOUR_PAT" GOTELEGRAM_BRANCH="v2.5.0"; bash <(curl -sL -H ## 5. Telegram-бот -Пункт меню **12) Telegram-бот** разворачивает отдельный Python-сервис (`python-telegram-bot` v21+), который: +Раздел **4) Telegram-бот** разворачивает отдельный Python-сервис (`python-telegram-bot` v21+), который: - Показывает статус прокси, ссылку и QR. - Умеет перезапускать telemt прямо из чата. @@ -127,9 +156,9 @@ CLI и бот переведены на русский и английский. ## 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/`. +Раздел **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/`. -Пункт 9 принимает такой архив и восстанавливает всё обратно (конфиг, сервис, ссылка — всё то же, что было). Перед восстановлением из админки или Telegram-бота автоматически создаётся свежий safety-бекап текущего состояния. +Раздел **3) Управление → 2) Восстановить** принимает такой архив и восстанавливает всё обратно (конфиг, сервис, ссылка — всё то же, что было). Перед восстановлением из админки или Telegram-бота автоматически создаётся свежий safety-бекап текущего состояния. В web-админке и Telegram-боте есть сценарии автобэкапов: выключено, каждый день, каждую неделю или каждый месяц. Это systemd timer `gotelegram-backup.timer`; автоматическая чистка оставляет последние 30 архивов, чтобы каталог не рос бесконечно. Старые простые архивы `backup_*.tar.gz`, которые создавал ранний Telegram-бот только из двух конфигов, тоже распознаются при восстановлении как legacy-формат. @@ -147,6 +176,19 @@ CLI и бот переведены на русский и английский. - есть светлая/тёмная тема, вкладки и адаптивная вёрстка под desktop/mobile; - Telegram-бот показывает инструкцию для Termius и обычную команду `ssh -L 1984:127.0.0.1:1984 root@SERVER`. +Как открыть через Termius: + +1. Открой нужный Host или создай новый. +2. Укажи `Address` = IP сервера, `Username` = `root`, пароль или ключ SSH. +3. Открой настройки Host → `Port Forwarding` / `Tunnels`. +4. Добавь tunnel типа `Local`. +5. `Local host`: `localhost`. +6. `Local port`: `1984`. +7. `Destination host`: `127.0.0.1`. +8. `Destination port`: `1984`. +9. Подключись к серверу через этот Host. +10. Открой в браузере `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 часа / месяц детализация остаётся полной. @@ -253,7 +295,7 @@ A: Сам MTProxy — да, это публичная технология из - Баги и пожелания — issues в репозитории `anten-ka/gotelegram_pro`. - Владелец: Vitalii (`anten-ka`). -- Основная ветка: `main`. Старые alpha/beta/test/codex ветки закрыты, rollback-точки сохранены в релизах и тегах. +- Ветки: `main` — основная стабильная установка; `beta` — следующая публичная сборка для проверки; `alpha` — ранние личные эксперименты владельца. --- diff --git a/README.md b/README.md new file mode 100644 index 0000000..8c5c878 --- /dev/null +++ b/README.md @@ -0,0 +1,80 @@ +# goTelegram Pro + +**goTelegram Pro** — установщик и панель управления Telegram MTProxy на базе ядра `telemt`. Проект ставит на VPS прокси, сайт-маскировку, Telegram-бота, локальную web-админку, сбор статистики и бэкапы. + +Главная идея: снаружи сервер выглядит как обычный HTTPS-сайт, а Telegram-клиенты используют тот же домен/порт для MTProxy. Управлять можно из SSH-меню, Telegram-бота или локальной web-панели через SSH-туннель. + +## Что Входит + +- ядро `telemt` с fake-TLS маскировкой; +- CLI-меню `gotelegram`; +- Lite-режим без домена и Pro-режим с доменом/сайтом/Let's Encrypt; +- Telegram-бот для статуса, ссылок, QR, бэкапов, шаблонов, ключей и статистики; +- локальная web-админка на `127.0.0.1:1984`; +- глобальная и per-key история трафика; +- ручные и scheduled бэкапы; +- shared-443 схема для совместной работы с 3x-ui/Xray. + +## Установка + +Запускать под `root` на Ubuntu/Debian: + +```bash +export GOTELEGRAM_PAT="YOUR_READ_ONLY_GITHUB_TOKEN"; bash <(curl -sL -H "Authorization: token $GOTELEGRAM_PAT" https://raw.githubusercontent.com/anten-ka/gotelegram_pro/main/bootstrap.sh) +``` + +`bootstrap.sh` скачает файлы в `/opt/gotelegram`, создаст `/usr/local/bin/gotelegram` и откроет главное меню. + +## Режимы + +**Lite** работает сразу без домена. Клиент подключается к `IP:443`, а прокси имитирует TLS под популярный домен вроде `google.com`. + +**Pro** требует домен, который указывает на VPS. Telegram-клиенты и обычные браузеры используют один публичный домен на `443`: Telegram-трафик идёт в `telemt`, браузер открывает сайт-маскировку через nginx. + +## Web-Админка + +Админка слушает только локально на сервере: + +```text +127.0.0.1:1984 +``` + +Открой через SSH-туннель: + +```bash +ssh -L 1984:127.0.0.1:1984 root@SERVER_IP +``` + +Потом в браузере: + +```text +http://127.0.0.1:1984/ +``` + +Внутри есть dashboard, сервисы, проверка сайта, кто слушает `443`, графики трафика, ключи пользователей, QR, IP-лимиты, бэкапы, логи, переключение языка и светлая/тёмная тема. + +## Ветки + +- `main` — продакшен и ветка установки по умолчанию. +- `beta` — публичная бета для следующих сборок и пользовательского тестирования. +- `alpha` — ранние личные сборки владельца. + +Новые изменения сначала идут в `alpha`, потом после проверки в `beta`, и только затем в `main`. + +## Документация + +- [DOCS_HUMAN.md](DOCS_HUMAN.md) — человеческое руководство с нуля. +- [DOCS_AI.md](DOCS_AI.md) — подробная техническая карта для ИИ-агентов и разработчиков. +- [gotelegram-bot/README.md](gotelegram-bot/README.md) — заметки по Telegram-боту. + +## Проверки Перед Пушем + +Перед пушем: + +```bash +bash -n bootstrap.sh install.sh lib/*.sh +python3 -m unittest tests.test_admin_features tests.test_bot_features +PYTHONPYCACHEPREFIX=/tmp/gotelegram-pycache python3 -m py_compile gotelegram-bot/bot.py admin-web/server.py +node --check admin-web/static/app.js +git diff --check +```