Telemt: веб-прокси для Telegram (WEB-режим) — как работает и как установить

Ссылка, чтобы проверить, как работает установленный TeleMT

В Telegram появился тип прокси WEB. Клиент открывает встроенный WebView, загружает с сервера служебную страницу и передаёт через неё MTProto внутри обычных HTTPS-запросов или WebSocket. Telemt поддерживает этот режим начиная с версии 3.5.1. Статья описывает, как режим устроен и как его развернуть. Все конфигурации проверены на версии 3.5.7.

От Fake TLS из статьи про установку Telemt WEB-режим отличается следующим:

Оба режима могут работать в одном процессе Telemt одновременно.

Как это работает

Клиент Telegram (WebView)
    | HTTPS или WSS, порт 443
    v
Caddy / NGINX / HAProxy — завершает TLS, передаёт Host и один адрес в X-Forwarded-For
    | HTTP/1.1 по частной сети или loopback
    v
WEB-listener Telemt
    |-- запрос с верными учётными данными --> MTProto-relay --> дата-центры Telegram
    `-- любой другой запрос --> сайт-прикрытие (decoy)

Telemt в этой схеме TLS не завершает. Он принимает обычный HTTP от reverse proxy и по заголовку Host выбирает виртуальный хост (vhost) с его профилями и сайтом-прикрытием.

Последовательность обмена:

1. Capability. Из секрета пользователя и имени хоста клиент вычисляет 32-байтовое значение: HMAC-SHA256, ключ — секрет (для режима dd с байтом 0xdd впереди), данные — строка tdesktop-web-proxy-bridge-v1\n и имя хоста. Результат кодируется в base64url и передаётся в запросе GET /?bridge=<43 символа>. Сам секрет по сети не передаётся.
2. Bridge-страница. Telemt сверяет capability со всеми профилями vhost за постоянное время. При совпадении он отдаёт HTML-страницу со скриптом и одноразовый bootstrap-токен со сроком жизни 120 секунд. Страница выполняется внутри WebView клиента и обменивается с ним данными через MessagePort. Политика CSP разрешает странице соединения только со своим хостом.
3. Сессия. Страница отправляет POST /api/v1/session с bootstrap-токеном и получает токен сессии.
4. Передача данных. Исходящие данные уходят запросами POST /api/v1/up с порядковым номером в заголовке X-Up-Seq. Входящие данные клиент получает длинными запросами GET /api/v1/down (long poll, по умолчанию 25 секунд) с курсором в X-Down-Cursor. В режимах WebSocket вместо этой пары используется GET /api/v1/ws.
5. Кадры. Данные упакованы в кадры с заголовком 8 байт: тип, 24-битный идентификатор потока, длина. Типы кадров: OPEN, DATA, CLOSE, WINDOW, PING, PONG, служебные HELLO, WELCOME, BYE.
6. Потоки. Одна WEB-сессия несёт много логических потоков. Каждый поток — отдельное MTProxy-соединение: Telemt выполняет для него обычный MTProto-handshake с секретом того пользователя, который указан в профиле, и передаёт поток в тот же relay, что обслуживает обычные подключения (напрямую к дата-центрам или через Middle Proxy).

Запрос без верных учётных данных, с ошибкой формата или с неизвестным путём Telemt передаёт на сайт-прикрытие. Поэтому при проверке снаружи домен ведёт себя как обычный сайт: на / отвечает страницей, на несуществующий путь — кодом 404 этого сайта.

Способы передачи (carrier)

Carrier — способ, которым кадры передаются между bridge-страницей и Telemt. Их четыре:

Параметр web.carrier задаёт carrier по умолчанию. Если в web.carriers указан непустой массив, клиент и сервер при создании сессии согласуют carrier из этого списка, а web.carrier остаётся последним вариантом.

Telegram для iOS поддерживает только https. Если ссылкой пользуются клиенты на разных платформах, значение carrier = "https" — единственное, которое работает у всех. Согласование в этом случае отключается: параметр carriers не задаётся.

Что нужно заранее

• Telemt версии 3.5.1 или новее.
• Отдельное доменное имя (FQDN) с A-записью на публичный IP сервера.
• Порт 443 на этом IP. Клиент не принимает другой порт: в ссылке tg://webproxy порта нет.
• Reverse proxy с действующим сертификатом: Caddy, NGINX или HAProxy.
• Сайт-прикрытие: каталог со статическими файлами или HTTP-сервер в частной сети.
• Клиент Telegram с поддержкой типа прокси WEB.

Если на сервере уже работает Telemt в режиме Fake TLS на порту 443, порт нужно разделить. Варианты описаны в разделе «Порт 443: WEB и Fake TLS на одном сервере».

Шаг 1. Каталоги и секрет

install -d -m 0750 /opt/telemt-web/config /opt/telemt-web/public
cd /opt/telemt-web
openssl rand -hex 16

Секрет — 32 hex-символа, как и для обычного MTProxy. Префикс dd в конфиг не пишется, Telemt добавит его в ссылку сам.

В каталог public положите файлы сайта-прикрытия, как минимум index.html. Telemt читает каталог при старте и при перезагрузке конфигурации. Символические ссылки и пути за пределы каталога он отклоняет.

Шаг 2. Конфиг config/config.toml

[general]
use_middle_proxy = false
log_level = "normal"

[general.modes]
classic = false
secure = true
tls = false

[general.links]
show = ["web-user"]

[server]
port = 443
metrics_port = 9090
metrics_whitelist = ["127.0.0.1/32", "::1/128"]

[server.api]
enabled = true
listen = "0.0.0.0:9091"
whitelist = ["127.0.0.1/32", "172.30.0.0/24"]
auth_header = "Bearer замените-на-случайную-строку"
read_only = false

[[server.listeners]]
ip = "0.0.0.0"

# WEB-listener: обычный HTTP, только для reverse proxy
[[server.listeners]]
ip = "0.0.0.0"
port = 18080
transport = "web"
proxy_protocol = false
reuse_allow = false
web_client_ip_source = "x_forwarded_for"
web_trusted_proxy_cidrs = ["172.30.0.2/32"]

[web]
enabled = true
carrier = "https"

[[web.vhosts]]
host = "proxy.example.com"
public_addr = "203.0.113.10:443"

[web.vhosts.decoy]
mode = "static_directory"
directory = "/var/lib/telemt/public"
index = "index.html"

[[web.vhosts.profiles]]
user = "web-user"
secret_mode = "dd"
max_sessions = 8
max_streams = 512
max_streams_per_session = 64

[access.users]
web-user = "0123456789abcdef0123456789abcdef"

Пояснения к параметрам:

• transport = "web" превращает listener в HTTP-приёмник WEB-режима. Для него обязательны proxy_protocol = false и reuse_allow = false.
• web_trusted_proxy_cidrs — адреса reverse proxy, от которых Telemt принимает заголовок X-Forwarded-For. Список не может быть пустым, сеть /0 отклоняется. В примере это адрес контейнера Caddy. От остальных адресов заголовок игнорируется.
• host — имя домена в нижнем регистре, без порта. Telemt принимает заголовок Host только в виде proxy.example.com или proxy.example.com:443. На любой другой Host он отвечает 404 без обращения к сайту-прикрытию.
• public_addr — публичный IP, на который указывает домен, с портом 443. Это адрес reverse proxy, а не адрес Telemt. Он входит в параметры внутреннего MTProto-маршрута, поэтому должен совпадать с фактическим адресом, на который подключаются клиенты.
• secret_mode — plain или dd. Секреты формата ee в WEB-режиме не поддерживаются.
• user должен существовать в [access.users]. Один пользователь может иметь и WEB-профиль, и обычные MTProxy-ссылки с тем же секретом.
• max_sessions, max_streams, max_streams_per_session ограничивают профиль. Лимиты относятся к логическим потокам, а не к HTTP-соединениям.

Сайт-прикрытие можно отдать и с отдельного HTTP-сервера:

[web.vhosts.decoy]
mode = "http_upstream"
upstream = "http://10.0.0.10:9010"

В upstream допускается только http:// с IP-адресом из частной сети, loopback или link-local. Доменное имя и публичный адрес Telemt отклонит.

Шаг 3. docker-compose.yml

Telemt и Caddy работают в одной сети Docker с фиксированными адресами. Фиксированный адрес Caddy нужен для web_trusted_proxy_cidrs.

services:
  telemt:
    image: ghcr.io/telemt/telemt:3.5.7
    container_name: telemt
    restart: unless-stopped
    working_dir: /run/telemt
    command: ["/etc/telemt/config.toml"]
    ports:
      - "127.0.0.1:9090:9090"
      - "127.0.0.1:9091:9091"
    volumes:
      - ./config:/etc/telemt:rw
      - ./public:/var/lib/telemt/public:ro
    tmpfs:
      - /run/telemt:rw,mode=1777,size=4m
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE
    read_only: true
    security_opt:
      - no-new-privileges:true
    ulimits:
      nofile:
        soft: 65536
        hard: 262144
    networks:
      web:
        ipv4_address: 172.30.0.3

  caddy:
    image: caddy:2
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
    networks:
      web:
        ipv4_address: 172.30.0.2

networks:
  web:
    ipam:
      config:
        - subnet: 172.30.0.0/24

volumes:
  caddy_data:

Порт 18080 наружу не публикуется: WEB-listener принимает HTTP без шифрования и аутентификации на транспортном уровне, доступ к нему должен иметь только reverse proxy. Каталог config смонтирован на запись, потому что Control API при изменении конфигурации перезаписывает файл.

Шаг 4. Caddy

proxy.example.com {
    reverse_proxy telemt:18080
}

Сертификат Caddy получит сам. Дополнительные настройки не требуются по следующим причинам:

• Caddy заменяет входящий X-Forwarded-For адресом клиента, если клиент не указан в trusted_proxies. Telemt получает один адрес, как и требуется.
• Соединение с Telemt идёт по HTTP/1.1, WebSocket Upgrade передаётся без настройки.
• Повторные попытки при ошибке upstream по умолчанию отключены. Включать их нельзя: bridge-страница повторяет запросы сама, и повтор на стороне reverse proxy нарушит нумерацию.
• Журнал запросов по умолчанию выключен. Включать его для этого сайта не следует: строка запроса содержит capability, заголовок Authorization — токены.

В Telemt направляется весь сайт целиком. Если reverse proxy отправляет в Telemt только пути /api/v1/* и запросы с ?bridge=, а остальное отдаёт сам, то ответы на обычные и на служебные запросы формируют разные серверы, и это различие можно обнаружить снаружи. Разделять пути допустимо, когда на домене уже работает настоящий сайт и перенести его за Telemt нельзя. В этом случае тот же сайт нужно указать как http_upstream в [web.vhosts.decoy], чтобы отклонённые служебные запросы получали его ответы.

Шаг 5. Вариант с NGINX

Конфигурация из документации Telemt. Блок map размещается в контексте http.

map $http_upgrade $telemt_connection_upgrade {
    default upgrade;
    ''      '';
}

upstream telemt_web {
    server 127.0.0.1:18080;
    keepalive 64;
}

server {
    listen 443 ssl;
    http2 on;
    server_name proxy.example.com;
    access_log off;

    ssl_certificate     /etc/letsencrypt/live/proxy.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/proxy.example.com/privkey.pem;

    client_max_body_size 2m;

    location / {
        proxy_pass http://telemt_web;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $telemt_connection_upgrade;

        proxy_connect_timeout 5s;
        proxy_send_timeout 65s;
        proxy_read_timeout 65s;
        proxy_request_buffering off;
        proxy_buffering off;
        proxy_next_upstream off;
    }
}

Что здесь существенно:

• X-Forwarded-For задаётся через $remote_addr, а не через $proxy_add_x_forwarded_for. Telemt принимает ровно один адрес.
• client_max_body_size не меньше web.limits.max_body_bytes (по умолчанию 2 МиБ).
• Таймауты чтения и отправки больше интервала long poll. Значение 65 секунд покрывает настройки по умолчанию.
• proxy_next_upstream off и access_log off — по тем же причинам, что описаны для Caddy.
• Для https-lanes на публичной стороне обязателен HTTP/2, для WebSocket — доступность HTTP/1.1.

Если NGINX работает на хосте, а Telemt в Docker, опубликуйте порт listener только на loopback (127.0.0.1:18080:18080) и укажите в web_trusted_proxy_cidrs адрес шлюза сети Docker — в примере выше это 172.30.0.1/32. При установке Telemt без Docker listener размещается на 127.0.0.1, в списке доверенных — 127.0.0.1/32.

Шаг 6. Запуск и ссылка

cd /opt/telemt-web
docker compose up -d
docker compose logs telemt | grep -A2 "WEB proxy links"

В журнале появится ссылка:

MAESTRO: WEB proxy links
MAESTRO: User: web-user (Dd)
MAESTRO: WEB: tg://webproxy?server=proxy.example.com&secret=dd0123456789abcdef0123456789abcdef

Ссылки печатаются для пользователей из [general.links].show и только при полном старте процесса. После добавления профиля через перезагрузку конфигурации ссылку нужно собрать вручную: tg://webproxy?server=<домен>&secret=dd<секрет>. Для secret_mode = "plain" префикс не добавляется.

Строка Listening on TCP endpoint addr=0.0.0.0:18080 transport=Web в журнале подтверждает, что listener поднят.

Шаг 7. Проверка

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

curl -sI https://proxy.example.com/                        # 200, сайт-прикрытие
curl -sI https://proxy.example.com/no-such-page            # 404 сайта-прикрытия
curl -sI 'https://proxy.example.com/?bridge=fake'          # 200, сайт-прикрытие
curl -s -o /dev/null -w '%{http_code}\n' \
  -X POST https://proxy.example.com/api/v1/session         # 404, токена нет

Ответ 404 на POST /api/v1/session без токена — штатное поведение, а не ошибка.

Состояние WEB-режима доступно в Control API:

export TELEMT_API_AUTH="Bearer замените-на-случайную-строку"

curl -s http://127.0.0.1:9091/v1/runtime/web/status \
  -H "Authorization: ${TELEMT_API_AUTH}" | jq '.data | {lifecycle, listeners, ingress}'

Рабочее состояние: lifecycle равен running, ingress.accepting_connections равен true. Список активных сессий — GET /v1/runtime/web/sessions.

Метрики Prometheus для WEB-режима имеют префикс telemt_web_. Для наблюдения достаточно четырёх: telemt_web_tcp_accept_total, telemt_web_session_incarnations_total, telemt_web_streams_total, telemt_web_carrier_bytes_total.

Последняя проверка — добавить ссылку в клиент Telegram и убедиться, что соединение установлено, а сообщения и медиафайлы передаются.

Порт 443: WEB и Fake TLS на одном сервере

Режим Fake TLS из статьи «Telemt: установка MTProxy для Telegram в Docker на порту 443 с Fake TLS» занимает порт 443 самим Telemt, WEB-режим требует тот же порт для reverse proxy. На одном IP-адресе это решается маршрутизацией по SNI до завершения TLS. Соединения с SNI домена-маски уходят в Telemt, соединения с SNI вашего домена — в reverse proxy.

Пример для NGINX, модуль stream:

stream {
    map $ssl_preread_server_name $backend_443 {
        github.com          127.0.0.1:8443;   # Telemt, Fake TLS
        proxy.example.com   127.0.0.1:4443;   # Caddy или NGINX http
        default             127.0.0.1:4443;
    }

    server {
        listen 443;
        ssl_preread on;
        proxy_pass $backend_443;
    }
}

Telemt и reverse proxy при этом слушают порты 8443 и 4443 на loopback. Reverse proxy за таким маршрутизатором видит адрес 127.0.0.1 вместо адреса клиента. Чтобы лимиты по IP в Telemt работали, адрес клиента нужно передать по PROXY protocol: proxy_protocol on; в блоке server модуля stream и приём PROXY protocol на стороне reverse proxy и listener Fake TLS.

Список SNI в маршрутизаторе и значение tls_domain в Telemt ведутся отдельно. При смене домена-маски нужно менять оба.

Другие варианты — второй IP-адрес на сервере или отдельный сервер под WEB-режим.

Схема с отдельным фронтом

Есть вариант с отдельным фронтом: публичный адрес и сертификат находятся на одном сервере, а Telemt работает на другом, в частной сети, и публичного адреса не имеет. Схема такая:

клиент --> фронт (публичный IP, Caddy, сертификат)
               | частная сеть
               v
           сервер Telemt, listener 10.0.0.58:18080
               |-- relay --> Telegram
               `-- decoy  --> http://10.0.0.10:9010 (сайт в той же сети)

Отличия от установки на одном сервере:

• Listener размещён на адресе частной сети, а не на loopback: ip = "10.0.0.58".
• Firewall на сервере Telemt пропускает порт 18080 только с адреса фронта. В web_trusted_proxy_cidrs указан тот же адрес с маской /32.
• В public_addr указан публичный IP фронта.
• Сайт-прикрытие — отдельный контейнер NGINX со статической страницей, подключён как http_upstream.
• Один listener обслуживает несколько доменов: на каждый домен свой блок [[web.vhosts]], выбор идёт по заголовку Host. На фронте для каждого домена достаточно блока reverse_proxy 10.0.0.58:18080.

Что выяснилось при эксплуатации

Смена публичного IP. Если адрес фронта меняется, public_addr нужно обновлять сразу после смены. Это делается через Control API без перезапуска:

curl -s http://127.0.0.1:9091/v1/config -H "Authorization: ${TELEMT_API_AUTH}" \
  | jq '.data.web.vhosts' > vhosts.json

# изменить public_addr в vhosts.json

jq -n --slurpfile v vhosts.json '{web: {vhosts: $v[0]}}' \
  | curl -s -X PATCH 'http://127.0.0.1:9091/v1/config?reload=drain&timeout_secs=30' \
      -H "Authorization: ${TELEMT_API_AUTH}" \
      -H 'Content-Type: application/json' -d @-

Без параметра reload запрос только записывает файл и возвращает runtime_reload_required: true. С параметром reload=drain Telemt сразу применяет новую конфигурацию и отвечает кодом 202, в ответе должно быть restart_required: false.

Вложенные таблицы при PATCH объединяются по полям, а массивы заменяются целиком. Запрос, в котором у vhost указан только public_addr, удалит его профили и сайт-прикрытие. Поэтому сначала читается текущий массив web.vhosts, в нём меняется одно поле, и массив отправляется обратно полностью.

Что требует перезапуска. Состав listener и все значения [web.limits] применяются только при перезапуске процесса. Остальное — vhost, профили, сайт-прикрытие, carrier, таймауты — применяется перезагрузкой конфигурации:

curl -s -X POST http://127.0.0.1:9091/v1/system/reload \
  -H "Authorization: ${TELEMT_API_AUTH}" \
  -H 'Content-Type: application/json' \
  -d '{"mode":"drain","timeout_secs":30,"failure_policy":"rollback"}'

Если в ответе поле deferred_process_fields содержит server.listeners или web.limits, конфигурация сохранена, но эти параметры вступят в силу после перезапуска.

Лимит числа профилей. При добавлении WEB-профилей всем пользователям экземпляра (около 80) процесс не запустился с ошибкой WEB profiles exceed web.limits.max_profiles. Лимит нужно поднять до перезапуска:

[web.limits]
max_profiles = 200

Control API. Пока API слушал только loopback, он работал без токена. Когда к нему понадобился доступ с фронта, были добавлены auth_header и whitelist с конкретными адресами. Whitelist проверяет адрес TCP-соединения и не учитывает X-Forwarded-For.

Отзыв доступа. Запрос POST /v1/users/<имя>/disable сразу закрывает активные WEB-сессии пользователя. После смены секрета (rotate-secret) capability пересчитывается автоматически, старая ссылка перестаёт работать.

Несколько процессов. Реестры bootstrap-токенов и сессий хранятся в памяти одного процесса. Если за одним доменом стоят несколько экземпляров Telemt, все запросы одного клиента должны попадать на один экземпляр.

Типовые ошибки

Справочник параметров

Полный перечень параметров приведён в документации Telemt: docs/WEB/WEB_PROXY.en.md и docs/Config_params/CONFIG_PARAMS.en.md. Русская версия документа отстаёт от английской, сверяться следует с английской.

Итог

WEB-режим переносит MTProto в обычный HTTPS на собственном домене. TLS завершает reverse proxy с настоящим сертификатом, Telemt принимает от него HTTP и отвечает сайтом-прикрытием на всё, что не прошло проверку. Для работы нужны домен, порт 443, listener с transport = "web", блок [[web.vhosts]] с верным public_addr и reverse proxy, который передаёт в Telemt сайт целиком. Если на сервере остаётся Fake TLS, порт 443 делится маршрутизацией по SNI. Звонки Telegram через MTProxy не работают и в этом режиме.

Ссылка, чтобы проверить, как работает установленный TeleMT