diff --git a/README.md b/README.md index 11c4f09..6b9d948 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/README.ru.md b/README.ru.md new file mode 100644 index 0000000..b6aa510 --- /dev/null +++ b/README.ru.md @@ -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 +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 \ + --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).