Expand project documentation for users and agents

2026-05-19 14:36:05 +00:00 · 2026-04-26 12:53:21 +03:00
parent f483028c53
commit 4332990fd5
3 changed files with 200 additions and 50 deletions
--- 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` — ранние личные эксперименты владельца.

 ---