Telemt: proxy web para Telegram (modo WEB) — cómo funciona y cómo instalar

Enlace para comprobar cómo funciona TeleMT instalado

En Telegram apareció el tipo de proxy WEB. El cliente abre un WebView integrado, carga desde el servidor una página de servicio y transmite a través de ella MTProto dentro de peticiones HTTPS normales o WebSocket. Telemt soporta este modo a partir de la versión 3.5.1. El artículo describe cómo funciona el modo y cómo desplegarlo. Todas las configuraciones han sido verificadas en la versión 3.5.7.

Del Fake TLS del artículo sobre la instalación de Telemt el modo WEB difiere en lo siguiente:

Ambos modos pueden funcionar en un mismo proceso Telemt simultáneamente.

Cómo funciona

Cliente Telegram (WebView)
    | HTTPS o WSS, puerto 443
    v
Caddy / NGINX / HAProxy — termina TLS, pasa Host y una dirección en X-Forwarded-For
    | HTTP/1.1 por red privada o loopback
    v
WEB-listener Telemt
    |-- petición con credenciales válidas --> MTProto-relay --> centros de datos de Telegram
    `-- cualquier otra petición --> sitio de cobertura (decoy)

Telemt en este esquema no termina TLS. Acepta HTTP normal desde el reverse proxy y, según la cabecera Host, elige el host virtual (vhost) con sus perfiles y su sitio de cobertura.

Secuencia de intercambio:

1. Capability. A partir del secreto del usuario y del nombre del host, el cliente calcula un valor de 32 bytes: HMAC-SHA256, clave — el secreto (para el modo dd con el byte 0xdd delante), datos — la cadena tdesktop-web-proxy-bridge-v1\n y el nombre del host. El resultado se codifica en base64url y se pasa en la petición GET /?bridge=<43 caracteres>. El secreto en sí no se transmite por la red.
2. Página bridge. Telemt compara la capability con todos los perfiles del vhost en tiempo constante. Al coincidir, devuelve una página HTML con un script y un token bootstrap de un solo uso con vida útil de 120 segundos. La página se ejecuta dentro del WebView del cliente e intercambia datos con él mediante MessagePort. La política CSP permite a la página conexiones únicamente con su propio host.
3. Sesión. La página envía POST /api/v1/session con el token bootstrap y recibe un token de sesión.
4. Transferencia de datos. Los datos salientes se envían con peticiones POST /api/v1/up con número secuencial en la cabecera X-Up-Seq. Los datos entrantes el cliente los obtiene mediante peticiones largas GET /api/v1/down (long poll, por defecto 25 segundos) con un cursor en X-Down-Cursor. En modos WebSocket, en lugar de este par se usa GET /api/v1/ws.
5. Tramas. Los datos están empaquetados en tramas con cabecera de 8 bytes: tipo, identificador de flujo de 24 bits, longitud. Tipos de tramas: OPEN, DATA, CLOSE, WINDOW, PING, PONG, tramas de servicio HELLO, WELCOME, BYE.
6. Flujos. Una sesión WEB lleva muchos flujos lógicos. Cada flujo es una conexión MTProxy separada: Telemt realiza para él el handshake MTProto habitual con el secreto del usuario que figura en el perfil, y entrega el flujo al mismo relay que sirve las conexiones normales (directamente a los centros de datos o a través de Middle Proxy).

Una petición sin credenciales válidas, con formato erróneo o con ruta desconocida Telemt la envía al sitio de cobertura. Por eso al comprobar desde fuera, el dominio se comporta como un sitio web normal: en / responde con la página, en una ruta inexistente — con el código 404 de ese sitio.

Formas de transporte (carrier)

Carrier — la forma en que las tramas se transmiten entre la página bridge y Telemt. Hay cuatro:

El parámetro web.carrier establece el carrier por defecto. Si en web.carriers hay un arreglo no vacío, cliente y servidor negocian el carrier de esa lista al crear la sesión, y web.carrier queda como la última opción.

Telegram para iOS soporta solo https. Si el enlace lo usan clientes en distintas plataformas, carrier = "https" es el único valor que funciona en todas. En este caso la negociación se desactiva: el parámetro carriers no se define.

Qué se necesita de antemano

• Telemt versión 3.5.1 o más reciente.
• Un nombre de dominio separado (FQDN) con un registro A apuntando a la IP pública del servidor.
• Puerto 443 en esa IP. El cliente no acepta otro puerto: en el enlace tg://webproxy no hay puerto.
• Reverse proxy con certificado válido: Caddy, NGINX o HAProxy.
• Sitio de cobertura: un directorio con archivos estáticos o un servidor HTTP en la red privada.
• Cliente Telegram que soporte el tipo de proxy WEB.

Si en el servidor ya funciona Telemt en modo Fake TLS en el puerto 443, el puerto debe compartirse. Las opciones están descritas en la sección “Puerto 443: WEB y Fake TLS en un mismo servidor”.

Paso 1. Directorios y secreto

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

El secreto son 32 caracteres hex, igual que para un MTProxy normal. El prefijo dd no se escribe en la configuración, Telemt lo añadirá en el enlace automáticamente.

En el directorio public ponga los archivos del sitio de cobertura, al menos index.html. Telemt lee el directorio al arrancar y al recargar la configuración. Rechaza enlaces simbólicos y rutas fuera del directorio.

Paso 2. Config 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 reemplace-por-una-cadena-aleatoria"
read_only = false

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

# WEB-listener: HTTP normal, solo para 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"

Explicaciones de los parámetros:

• transport = "web" convierte el listener en receptor HTTP para el modo WEB. Para él son obligatorios proxy_protocol = false y reuse_allow = false.
• web_trusted_proxy_cidrs — direcciones del reverse proxy desde las cuales Telemt acepta la cabecera X-Forwarded-For. La lista no puede estar vacía, la red /0 se rechaza. En el ejemplo es la dirección del contenedor Caddy. Desde otras direcciones la cabecera se ignora.
• host — nombre de dominio en minúsculas, sin puerto. Telemt acepta la cabecera Host solo en las formas proxy.example.com o proxy.example.com:443. Ante cualquier otro Host responde 404 sin consultar el sitio de cobertura.
• public_addr — IP pública a la que apunta el dominio, con puerto 443. Es la dirección del reverse proxy, no la de Telemt. Forma parte de los parámetros de la ruta MTProto interna, por lo que debe coincidir con la dirección real a la que se conectan los clientes.
• secret_mode — plain o dd. Los secretos en formato ee no son soportados en el modo WEB.
• user debe existir en [access.users]. Un usuario puede tener tanto perfil WEB como enlaces MTProxy normales con el mismo secreto.
• max_sessions, max_streams, max_streams_per_session limitan el perfil. Los límites se aplican a flujos lógicos, no a conexiones HTTP.

El sitio de cobertura también puede servirse desde un servidor HTTP separado:

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

En upstream solo se permite http:// con una IP de red privada, loopback o link-local. Telemt rechazará un nombre de dominio o una dirección pública.

Paso 3. docker-compose.yml

Telemt y Caddy funcionan en una misma red Docker con direcciones fijas. La dirección fija de Caddy es necesaria para 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:

El puerto 18080 no se publica hacia fuera: el WEB-listener acepta HTTP sin cifrar y sin autenticación a nivel de transporte, el acceso debe tenerlo solo el reverse proxy. El directorio config se monta con permiso de escritura porque la API de Control reescribe el archivo al cambiar la configuración.

Paso 4. Caddy

proxy.example.com {
    reverse_proxy telemt:18080
}

Caddy obtendrá el certificado por sí mismo. No se requieren ajustes adicionales por las siguientes razones:

• Caddy sustituye el X-Forwarded-For entrante por la dirección del cliente si el cliente no está en trusted_proxies. Telemt recibe una sola dirección, como se requiere.
• La conexión a Telemt va por HTTP/1.1, la actualización WebSocket se transmite sin configuración adicional.
• Reintentos en caso de error upstream están desactivados por defecto. No deben activarse: la página bridge repite las peticiones por sí misma, y un reintento en el reverse proxy rompería la numeración.
• El registro de peticiones está desactivado por defecto. No debería activarse para este sitio: la query string contiene la capability y la cabecera Authorization contiene tokens.

A Telemt se le envía el sitio entero. Si el reverse proxy envía a Telemt solo las rutas /api/v1/* y peticiones con ?bridge=, y lo demás lo sirve él mismo, las respuestas a peticiones normales y a las de servicio las generan servidores distintos, y esta diferencia puede detectarse desde fuera. Dividir rutas es aceptable cuando en el dominio ya hay un sitio real que no se puede mover detrás de Telemt. En ese caso dicho sitio debe indicarse como http_upstream en [web.vhosts.decoy], para que las peticiones de servicio rechazadas reciban sus respuestas.

Paso 5. Opción con NGINX

Configuración de la documentación de Telemt. El bloque map se coloca en el contexto 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;
    }
}

Puntos importantes:

• X-Forwarded-For se establece usando $remote_addr, no $proxy_add_x_forwarded_for. Telemt acepta exactamente una dirección.
• client_max_body_size no debe ser menor que web.limits.max_body_bytes (por defecto 2 MiB).
• Los timeouts de lectura y envío deben ser mayores que el intervalo del long poll. 65 segundos cubre la configuración por defecto.
• proxy_next_upstream off y access_log off — por las mismas razones indicadas para Caddy.
• Para https-lanes en el lado público es obligatorio HTTP/2; para WebSocket — disponibilidad de HTTP/1.1.

Si NGINX corre en el host y Telemt en Docker, publique el puerto del listener solo en loopback (127.0.0.1:18080:18080) y ponga en web_trusted_proxy_cidrs la dirección de la puerta de enlace de la red Docker — en el ejemplo anterior es 172.30.0.1/32. Si instala Telemt sin Docker el listener se coloca en 127.0.0.1, en la lista de confianza — 127.0.0.1/32.

Paso 6. Arranque y enlace

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

En el registro aparecerá un enlace:

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

Los enlaces se imprimen para los usuarios en [general.links].show y solo al inicio completo del proceso. Tras añadir un perfil mediante recarga de configuración, el enlace debe montarse manualmente: tg://webproxy?server=<dominio>&secret=dd<secreto>. Para secret_mode = "plain" no se añade prefijo.

La línea Listening on TCP endpoint addr=0.0.0.0:18080 transport=Web en el registro confirma que el listener está en marcha.

Paso 7. Verificación

Desde fuera el dominio debe comportarse como un sitio normal:

curl -sI https://proxy.example.com/                        # 200, sitio de cobertura
curl -sI https://proxy.example.com/no-such-page            # 404 del sitio de cobertura
curl -sI 'https://proxy.example.com/?bridge=fake'          # 200, sitio de cobertura
curl -s -o /dev/null -w '%{http_code}\n' \
  -X POST https://proxy.example.com/api/v1/session         # 404, no hay token

La respuesta 404 en POST /api/v1/session sin token es comportamiento normal, no un error.

El estado del modo WEB está disponible en la Control API:

export TELEMT_API_AUTH="Bearer reemplace-por-una-cadena-aleatoria"

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

Estado operativo: lifecycle igual a running, ingress.accepting_connections igual a true. La lista de sesiones activas — GET /v1/runtime/web/sessions.

Las métricas Prometheus para el modo WEB tienen el prefijo telemt_web_. Para monitorizar bastan cuatro: telemt_web_tcp_accept_total, telemt_web_session_incarnations_total, telemt_web_streams_total, telemt_web_carrier_bytes_total.

La última verificación: añadir el enlace en el cliente Telegram y asegurarse de que la conexión se establece, y que mensajes y archivos se transmiten.

Puerto 443: WEB y Fake TLS en un mismo servidor

En el modo Fake TLS del artículo «Telemt: instalación de MTProxy para Telegram en Docker en el puerto 443 con TLS falso» el puerto 443 lo ocupa el propio Telemt, mientras que el modo WEB requiere el mismo puerto para el reverse proxy. En una misma IP esto se resuelve enroutando por SNI antes de terminar TLS. Conexiones con SNI del dominio-máscara van a Telemt, conexiones con SNI de su dominio — al reverse proxy.

Ejemplo para NGINX, módulo 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 o NGINX http
        default             127.0.0.1:4443;
    }

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

Telemt y el reverse proxy escuchan entonces puertos 8443 y 4443 en loopback. El reverse proxy tras tal enrutador verá la dirección 127.0.0.1 en lugar de la del cliente. Para que los límites por IP de Telemt funcionen, la dirección del cliente debe pasarse por PROXY protocol: proxy_protocol on; en el bloque server del módulo stream y aceptación de PROXY protocol en el reverse proxy y en el listener Fake TLS.

La lista de SNI en el enrutador y el valor tls_domain en Telemt se mantienen por separado. Al cambiar el dominio-máscara hay que modificar ambos.

Otras opciones — una segunda IP en el servidor o un servidor separado para el modo WEB.

Esquema con un frontend separado

Existe una variante con un frontal separado: la dirección pública y el certificado están en un servidor, mientras que Telemt funciona en otro, dentro de una red privada, y no tiene dirección pública. El esquema es:

cliente --> frontend (IP pública, Caddy, certificado)
               | red privada
               v
           servidor Telemt, listener 10.0.0.58:18080
               |-- relay --> Telegram
               `-- decoy  --> http://10.0.0.10:9010 (sitio en la misma red)

Diferencias respecto a la instalación en un solo servidor:

• El listener se coloca en una dirección de red privada, no en loopback: ip = "10.0.0.58".
• El firewall del servidor Telemt permite el puerto 18080 solo desde la dirección del frontend. En web_trusted_proxy_cidrs se indica la misma dirección con máscara /32.
• En public_addr se indica la IP pública del frontend.
• El sitio de cobertura es un contenedor NGINX separado con una página estática, conectado como http_upstream.
• Un listener sirve varios dominios: para cada dominio su bloque [[web.vhosts]], la selección se hace por la cabecera Host. En el frontend, para cada dominio es suficiente un bloque reverse_proxy 10.0.0.58:18080.

Lo que surgió en la operación

Cambio de IP pública. Si cambia la dirección del frontend, public_addr debe actualizarse inmediatamente después del cambio. Esto se hace vía Control API sin reinicio:

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

# cambiar public_addr en 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 @-

Sin el parámetro reload la petición solo escribe el archivo y devuelve runtime_reload_required: true. Con reload=drain Telemt aplica la nueva configuración inmediatamente y responde con código 202; en la respuesta debe aparecer restart_required: false.

Las tablas anidadas en PATCH se combinan por campos, y los arrays se reemplazan enteros. Una petición en la que el vhost incluye solo public_addr eliminará sus perfiles y sitio de cobertura. Por eso primero se lee el array actual web.vhosts, se modifica un campo y se envía el array completo de vuelta.

Qué requiere reinicio. La composición de listeners y todos los valores de [web.limits] se aplican solo al reiniciar el proceso. El resto — vhost, perfiles, sitio de cobertura, carrier, timeouts — se aplica recargando la configuración:

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"}'

Si en la respuesta el campo deferred_process_fields contiene server.listeners o web.limits, la configuración se ha guardado, pero esos parámetros entrarán en vigor tras el reinicio.

Límite de número de perfiles. Al añadir perfiles WEB para todos los usuarios de la instancia (unos 80), el proceso no arrancó con el error WEB profiles exceed web.limits.max_profiles. El límite debe aumentarse antes de reiniciar:

[web.limits]
max_profiles = 200

Control API. Mientras la API escuchaba solo en loopback, funcionaba sin token. Cuando necesitó acceso desde el frontend se añadieron auth_header y whitelist con direcciones concretas. La whitelist verifica la dirección de la conexión TCP y no tiene en cuenta X-Forwarded-For.

Revocar acceso. La petición POST /v1/users/<nombre>/disable cierra inmediatamente las sesiones WEB activas del usuario. Tras cambiar el secreto (rotate-secret) la capability se recalcula automáticamente y el enlace antiguo deja de funcionar.

Varios procesos. Los registros de tokens bootstrap y de sesiones se almacenan en la memoria de un proceso. Si hay varias instancias de Telemt tras un mismo dominio, todas las peticiones de un cliente deben ir a la misma instancia.

Errores típicos

Referencia de parámetros

La lista completa de parámetros está en la documentación de Telemt: docs/WEB/WEB_PROXY.en.md y docs/Config_params/CONFIG_PARAMS.en.md. La versión en ruso del documento está atrasada respecto a la inglesa; conviene cotejar con la versión en inglés.

Resumen

El modo WEB transpone MTProto a HTTPS normal en su propio dominio. TLS lo termina el reverse proxy con un certificado real, Telemt recibe HTTP de éste y responde con el sitio de cobertura a todo lo que no pase la comprobación. Para que funcione necesita un dominio, puerto 443, un listener con transport = "web", un bloque [[web.vhosts]] con public_addr correcto y un reverse proxy que envíe a Telemt el sitio entero. Si en el servidor queda Fake TLS, el puerto 443 se comparte mediante enrutado por SNI. Las llamadas Telegram por MTProxy no funcionan en este modo.

Enlace para comprobar cómo funciona TeleMT instalado