From 7362606b41b6b1a69c82959585050a8ce99dbd58 Mon Sep 17 00:00:00 2001 From: Andrey Prokopyuk Date: Mon, 2 Nov 2026 14:09:56 +0300 Subject: [PATCH] docs: clarify proxy routing and update deployment guides --- README.md | 15 ++++++++++----- docs/en/README.md | 8 +++++--- docs/ru/README.md | 6 ++++-- 3 files changed, 19 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index bc1201b..9704206 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,8 @@

Manage Telegram proxies on Debian and Ubuntu with Ansible: MTG FakeTLS or official -MTProxy (classic/FakeTLS), direct or SSH/SOCKS5 egress, and an SSH/SNI ingress jump. [MIT licensed](LICENSE). +MTProxy (classic/FakeTLS), with optional SSH tunnels and SNI routing through a jump +server. [MIT licensed](LICENSE). **[English guide](docs/en/README.md)** · **[Руководство на русском](docs/ru/README.md)** @@ -16,11 +17,15 @@ and SSH access to each server. Use an existing non-root administrator with sudo, or create one with the two-phase `bootstrap` command described in the guides. Official MTProxy is built on each target from pinned official source, using a minimal -`scratch` runtime. Choose an inventory example: +`scratch` runtime. Both engines can connect to Telegram directly or through an +SSH tunnel with a SOCKS5 listener. Separately, a jump server can route incoming +connections to backends by FakeTLS SNI, with a default route for non-TLS traffic. -- [MTG, direct](inventory.example.yml) -- [MTG, SSH/SOCKS5 exit](inventory.ssh.example.yml) -- [Official MTProxy, direct](inventory.mtproxy.example.yml) +Start with an inventory example: + +- [MTG](inventory.example.yml) +- [MTG with SSH egress](inventory.ssh.example.yml) +- [Official MTProxy](inventory.mtproxy.example.yml) Follow the guide to create a private inventory and Vault password file, then run: diff --git a/docs/en/README.md b/docs/en/README.md index 9cfa428..0375437 100644 --- a/docs/en/README.md +++ b/docs/en/README.md @@ -8,7 +8,7 @@ [Setup](#setup) · [Commands](#commands) · [Inventory](#inventory) · [Secrets](#secrets) · [SSH egress](#ssh-egress) · [System](#system) · -[Hooks](#hooks) · [Operations](#operations) · [Troubleshooting](#troubleshooting) +[Hooks](#hooks) · [Operations](#operations) · [Troubleshooting](#troubleshooting) · [Bootstrap and jump](#bootstrap-and-ingress-jump) ## Setup @@ -73,6 +73,7 @@ that group's vars. Keep it outside the public repository. inventory-path, .hooks | Variable | Meaning / default | |---|---| | `ansible_host`, `ansible_user`, `ansible_port` | Management address, existing administrator, SSH port (22) | +| `ansible_python_interpreter` | Remote Python path; examples pin `/usr/bin/python3` | | `ansible_ssh_private_key_file` | Optional local administrative private-key path | | `tg_admin.user`, `tg_admin.public_key` | Managed non-root administrator and public key | | `tg_endpoint` | Address published in client links; defaults to ansible_host | @@ -82,7 +83,7 @@ that group's vars. Keep it outside the public repository. inventory-path, .hooks | `tg_secret` | Vault-encrypted 32-hex-character key; required | | `tg_domain` | FakeTLS SNI hostname; keep the existing value when importing MTG | | `tg_egress` | `direct` or `ssh` (both engines) | -| `tg_image` | MTG defaults to nineseconds/mtg:2.2.8; official MTProxy to telegrammessenger/proxy:latest | +| `tg_image` | MTG defaults to nineseconds/mtg:2.2.8; official MTProxy is built locally as `megatg/mtproxy:-minimal` | | `tg_container_name` | Set explicitly: mtg-proxy or mtproto-proxy; verify also uses it | | `tg_publish_ipv6` | Publish the proxy on IPv6 as well as IPv4; false by default | | `tg_mtg_template` | MTG template name: mtg.toml.j2 by default, or mtg-tuned.toml.j2 for the tuning profile | @@ -197,7 +198,8 @@ One-off migration scripts/playbooks belong outside the production repository. Apply runs across hosts in parallel using the default Ansible strategy (up to 5 forks by default). Set `--forks N` (`-f N`) to control concurrency. Container recreation interrupts sessions. verify is a readiness check, not an MTProto -session: test messages/media in Telegram from the affected network before proceeding. +session: test messages/media in Telegram from the affected network after deployment. +To update one host at a time, run separate applies with `--limit HOST`. A failed verification leaves changes applied. If recovery is needed, restore the prior inventory values and previous image/source revision, reapply, and verify. Images removed by cleanup must be pulled or built again. This does not undo diff --git a/docs/ru/README.md b/docs/ru/README.md index 8991442..8fdb0ea 100644 --- a/docs/ru/README.md +++ b/docs/ru/README.md @@ -8,7 +8,7 @@ [Подготовка](#подготовка) · [Команды](#команды) · [Inventory](#inventory) · [Секреты](#секреты) · [SSH-выход](#ssh-выход) · [Система](#система) · -[Хуки](#хуки) · [Эксплуатация](#эксплуатация) · [Диагностика](#диагностика) +[Хуки](#хуки) · [Эксплуатация](#эксплуатация) · [Диагностика](#диагностика) · [Bootstrap и jump](#bootstrap-и-входной-jump) ## Подготовка @@ -74,6 +74,7 @@ export ANSIBLE_VAULT_PASSWORD_FILE="$HOME/.config/mega-tg-proxy/vault-password" | Переменная | Смысл / значение по умолчанию | |---|---| | `ansible_host`, `ansible_user`, `ansible_port` | Адрес управления, существующий администратор, SSH-порт (22) | +| `ansible_python_interpreter` | Путь Python на сервере; в примерах закреплён `/usr/bin/python3` | | `ansible_ssh_private_key_file` | Необязательный локальный путь к административному приватному ключу | | `tg_admin.user`, `tg_admin.public_key` | Управляемый непривилегированный администратор и публичный ключ | | `tg_endpoint` | Адрес в клиентских ссылках; по умолчанию ansible_host | @@ -198,7 +199,8 @@ storage извлеките ключ до пересоздания. Разовы Apply выполняется параллельно по хостам с обычной стратегией Ansible (по умолчанию до 5 forks). Число параллельных процессов можно задать через `--forks N` (`-f N`). Пересоздание контейнера обрывает сессии. verify проверяет готовность, а не MTProto-сессию: -перед следующим хостом проверьте сообщения/медиа в Telegram из проблемной сети. +после раскатки проверьте сообщения/медиа в Telegram из проблемной сети. +Для обновления по одному хосту запускайте отдельные apply с `--limit HOST`. При ошибке verify изменения остаются применёнными. Для восстановления верните прежние значения inventory и прежнюю версию образа/исходников, повторите apply и verify. Удалённый очисткой образ потребуется заново скачать или собрать. Это не