docs: add Russian installation guide

2026-10-14 17:04:24 +07:00
parent a91a7ca11a
commit 1e1dfa7b92
2 changed files with 219 additions and 0 deletions
@@ -1,5 +1,7 @@
 # Telegram WEB proxy

+[Инструкция по установке и настройке на русском языке](README.ru.md).
+
 Self-hosted Telegram WEB proxy deployment for Docker and Nginx Proxy Manager.
 The repository contains no deployment-specific hostname, public address,
 credential or generated client secret.
@@ -0,0 +1,217 @@
+# Telegram WEB proxy: установка и настройка
+
+Этот проект разворачивает собственный WEB proxy для Telegram в Docker и
+подключает его к уже работающему Nginx Proxy Manager. Контейнер не публикует
+порты на хосте: входящие HTTPS-соединения принимает Nginx Proxy Manager и
+передаёт их контейнеру через общую Docker-сеть.
+
+> WEB proxy пока является новым типом транспорта. Для подключения нужен клиент
+> Telegram, в котором есть тип прокси `WEB`. Если такого пункта в настройках
+> нет, установленная версия клиента этот транспорт ещё не поддерживает.
+
+## Схема работы
+
+```text
+Telegram с поддержкой WEB proxy
+    -> HTTPS / WebSocket, порт 443
+Nginx Proxy Manager
+    -> tg-web-proxy:8088
+WEB relay
+    -> локальный MTProxy
+    -> дата-центры Telegram
+```
+
+Обычный запрос к домену показывает небольшую нейтральную страницу. Запрос от
+поддерживаемого клиента получает защищённый bridge и используется как транспорт
+для Telegram.
+
+## Что потребуется
+
+- сервер `x86_64` с Linux;
+- Docker Engine и плагин Docker Compose;
+- работающий Nginx Proxy Manager на том же Docker-хосте;
+- отдельное доменное имя, например `proxy.example.com`;
+- DNS-запись `A`, указывающая на публичный IPv4 сервера;
+- исходящий доступ по HTTPS для сборки образа и загрузки конфигурации Telegram.
+
+Публичный IPv4 и домен в репозитории не сохраняются. Инсталлятор записывает их
+только в локальный файл `.env`, который исключён из Git.
+
+## 1. Подготовьте DNS
+
+Создайте у DNS-провайдера запись:
+
+| Тип | Имя | Значение |
+| --- | --- | --- |
+| `A` | выбранный поддомен | публичный IPv4 Docker-хоста |
+
+Дождитесь обновления DNS. Если на домене включено проксирование CDN, на время
+первой проверки лучше использовать обычную DNS-запись без дополнительного
+прокси между клиентом и Nginx Proxy Manager.
+
+## 2. Скачайте и запустите установщик
+
+Скопируйте URL репозитория на его странице в Gitea, затем выполните на
+Docker-хосте:
+
+```sh
+git clone <URL_РЕПОЗИТОРИЯ>
+cd telegram-web-proxy-stack
+./install.sh
+```
+
+Установщик запросит только необходимые значения:
+
+1. публичное доменное имя прокси;
+2. публичный IPv4 Docker-хоста;
+3. Docker-сеть Nginx Proxy Manager, если её не удалось определить автоматически.
+
+Два криптографических секрета генерируются локально. Они не отправляются в
+Gitea, не записываются в `.env` и остаются в Docker-томе
+`tg_webproxy_data`.
+
+Для автоматической установки те же параметры можно передать явно:
+
+```sh
+./install.sh \
+  --hostname proxy.example.com \
+  --public-ip <ПУБЛИЧНЫЙ_IPV4> \
+  --npm-network <DOCKER_СЕТЬ_NPM> \
+  --yes
+```
+
+После успешного запуска установщик выведет параметры для Nginx Proxy Manager и
+секрет клиента. Сохраните секрет в надёжном месте и не публикуйте вывод
+установщика.
+
+## 3. Настройте Nginx Proxy Manager
+
+Откройте **Hosts → Proxy Hosts → Add Proxy Host** и заполните поля:
+
+| Поле | Значение |
+| --- | --- |
+| Domain Names | домен, введённый при установке |
+| Scheme | `http` |
+| Forward Hostname / IP | `tg-web-proxy` |
+| Forward Port | `8088` |
+| Websockets Support | включено |
+| Block Common Exploits | допустимо включить |
+
+На вкладке **SSL**:
+
+1. запросите или выберите сертификат для этого домена;
+2. включите **Force SSL**;
+3. включите **HTTP/2 Support**;
+4. сохраните Proxy Host.
+
+Nginx Proxy Manager и `tg-web-proxy` должны находиться в одной Docker-сети.
+Публиковать порт `8088` на самом сервере не требуется.
+
+## 4. Проверьте сервер
+
+Откройте в браузере ваш домен по HTTPS. Должна появиться нейтральная страница,
+а сертификат должен определяться как действительный.
+
+Проверить состояние контейнера можно так:
+
+```sh
+docker ps --filter name=tg-web-proxy
+docker logs --tail 100 tg-web-proxy
+```
+
+Не публикуйте журналы без просмотра: в диагностических данных могут оказаться
+сведения о вашей конфигурации.
+
+## 5. Подключите Telegram
+
+В клиенте с поддержкой WEB proxy откройте настройки соединения и добавьте новый
+прокси типа **WEB**. Введите:
+
+| Поле | Значение |
+| --- | --- |
+| Сервер | только домен, например `proxy.example.com` |
+| Секрет | 32-символьный секрет, выведенный `install.sh` |
+
+В поле сервера не нужно добавлять `https://`, порт, параметры запроса или символ
+`/` в конце. Для корневой конфигурации порт `443` используется автоматически.
+
+Если клиент поддерживает ссылки WEB proxy, можно сформировать локально:
+
+```text
+tg://webproxy?server=proxy.example.com&secret=<СЕКРЕТ_КЛИЕНТА>
+```
+
+Не публикуйте эту ссылку: содержащийся в ней секрет предоставляет доступ к
+прокси. Адрес bridge с параметром `?bridge=` также считается секретным.
+
+## Обновление
+
+Получите проверенные изменения и снова запустите установщик:
+
+```sh
+git pull --ff-only
+./install.sh
+```
+
+Именованный Docker-том сохраняется, поэтому клиентский секрет не меняется при
+обычном обновлении. Не удаляйте том `tg_webproxy_data`, если хотите сохранить
+действующие подключения.
+
+## Остановка
+
+Остановить контейнер, сохранив данные и секреты:
+
+```sh
+docker compose --env-file .env down
+```
+
+Повторный запуск:
+
+```sh
+docker compose --env-file .env up -d
+```
+
+## Частые проблемы
+
+### Nginx Proxy Manager показывает 502
+
+- проверьте, что контейнер `tg-web-proxy` запущен и имеет статус `healthy`;
+- убедитесь, что оба контейнера подключены к одной Docker-сети;
+- проверьте имя `tg-web-proxy` и порт `8088` в Proxy Host.
+
+### Домен не открывается по HTTPS
+
+- проверьте DNS-запись `A`;
+- убедитесь, что входящие порты `80` и `443` доступны Nginx Proxy Manager;
+- проверьте выпуск и срок действия сертификата.
+
+### Страница открывается, но Telegram не подключается
+
+- убедитесь, что в клиенте действительно доступен тип прокси `WEB`;
+- используйте только домен без схемы и порта;
+- перепроверьте секрет клиента;
+- убедитесь, что в Nginx Proxy Manager включена поддержка WebSocket;
+- не включайте перенаправление на другой домен.
+
+### Установщик не находит сеть Nginx Proxy Manager
+
+Посмотрите сети контейнера Nginx Proxy Manager в Portainer или Docker и
+запустите установщик с параметром `--npm-network`.
+
+## Безопасность перед публикацией изменений
+
+Не добавляйте в Git `.env`, клиентский секрет, bridge-ссылки, файлы ключей,
+экспорт Docker-тома или резервную копию Portainer.
+
+Перед публикацией запускайте:
+
+```sh
+./scripts/audit-public.sh
+```
+
+Для проверки собственных доменов, сетей и других частных идентификаторов можно
+создать локальный файл `.audit-private-patterns`, записав по одному точному
+значению в строке. Этот файл исключён из Git и не публикуется.
+
+Дополнительные эксплуатационные проверки и порядок отката описаны в
+[`docs/runbook.md`](docs/runbook.md).