telegram-web-proxy-stack/README.ru.md

Telegram WEB proxy: установка и настройка

Этот проект разворачивает собственный WEB proxy для Telegram в Docker и подключает его к уже работающему Nginx Proxy Manager. Контейнер не публикует порты на хосте: входящие HTTPS-соединения принимает Nginx Proxy Manager и передаёт их контейнеру через общую Docker-сеть.

WEB proxy пока является новым типом транспорта. Для подключения нужен клиент Telegram, в котором есть тип прокси WEB. Если такого пункта в настройках нет, установленная версия клиента этот транспорт ещё не поддерживает.

Самый простой вариант: чистый VPS и один вопрос

Этот вариант подходит, если вы только что купили отдельный чистый VPS и не хотите настраивать Nginx Proxy Manager. Скрипт сам установит Docker, запустит прокси вместе с Caddy и получит HTTPS-сертификат. Он спросит только домен.

Понадобятся:

• 64-битный VPS x86_64 с Ubuntu или Debian;
• один домен или поддомен с единственной DNS-записью A, которая уже указывает прямо на публичный IPv4 этого VPS;
• открытые у провайдера сервера входящие TCP-порты 80 и 443.

Подключитесь к VPS по SSH и целиком скопируйте этот блок команд:

sudo apt update
sudo apt install -y git
git clone https://gitea.sibdata.ru/dir/telegram-web-proxy-stack.git
cd telegram-web-proxy-stack
sudo ./quick-install.sh

После запуска нужно ввести только подготовленный домен. Пароли или токены Gitea для публичного репозитория не требуются.

Можно случайно вставить домен вместе с https:// — установщик уберёт схему и лишний путь. После проверки DNS он автоматически:

1. установит системные компоненты и Docker из официального репозитория;
2. соберёт Telegram WEB proxy;
3. запустит Caddy и выпустит HTTPS-сертификат;
4. проверит уникальным ответом, что домен открывает именно этот прокси;
5. покажет сервер, секрет и готовую ссылку подключения.

Для автоматического запуска домен разрешается передать сразу:

sudo ./quick-install.sh --domain proxy.example.com

Секрет сохраняется в Docker-томе и остаётся прежним при повторном запуске. Для обновления используйте только быстрый установщик:

git pull --ff-only
sudo ./quick-install.sh

Если проверка домена или выпуск сертификата не завершились, проверьте DNS и правила входящего трафика у провайдера VPS, затем запустите ту же команду ещё раз. Успешная установка означает, что DNS, сертификат и ответ именно этого экземпляра прокси проверены автоматически. Этот вариант не использует Nginx Proxy Manager и не требует входа в какую-либо панель.

Остановить быструю установку, не удаляя секрет и сертификат:

docker compose --env-file .env -f compose.yml -f compose.quick.yml down

Повторно запустить:

docker compose --env-file .env -f compose.yml -f compose.quick.yml up -d

Ниже описан второй, отдельный вариант для сервера, где Nginx Proxy Manager уже установлен.

Схема работы

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-хосте:

git clone https://gitea.sibdata.ru/dir/telegram-web-proxy-stack.git
cd telegram-web-proxy-stack
./install.sh

Установщик запросит только необходимые значения:

1. публичное доменное имя прокси;
2. публичный IPv4 Docker-хоста;
3. Docker-сеть Nginx Proxy Manager, если её не удалось определить автоматически.

Два криптографических секрета генерируются локально. Они не отправляются в Gitea, не записываются в .env и остаются в Docker-томе tg_webproxy_data.

Для автоматической установки те же параметры можно передать явно:

./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. Должна появиться нейтральная страница, а сертификат должен определяться как действительный.

Проверить состояние контейнера можно так:

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, можно сформировать локально:

tg://webproxy?server=proxy.example.com&secret=<СЕКРЕТ_КЛИЕНТА>

Не публикуйте эту ссылку: содержащийся в ней секрет предоставляет доступ к прокси. Адрес bridge с параметром ?bridge= также считается секретным.

Обновление

Получите проверенные изменения и снова запустите установщик:

git pull --ff-only
./install.sh

Именованный Docker-том сохраняется, поэтому клиентский секрет не меняется при обычном обновлении. Не удаляйте том tg_webproxy_data, если хотите сохранить действующие подключения.

Остановка

Остановить контейнер, сохранив данные и секреты:

docker compose --env-file .env down

Повторный запуск:

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.

Перед публикацией запускайте:

./scripts/audit-public.sh

Для проверки собственных доменов, сетей и других частных идентификаторов можно создать локальный файл .audit-private-patterns, записав по одному точному значению в строке. Этот файл исключён из Git и не публикуется.

Дополнительные эксплуатационные проверки и порядок отката описаны в docs/runbook.md.