Proxmox-Coolify-Manager/docs/ISSUE_cloudflare-tunnel_routing_websocket-tls-handshake.md

# ISSUE: cloudflare-tunnel · routing · websocket-tls-handshake

**ID:** `cloudflare-tunnel_routing_websocket-tls-handshake`  
**Tags:** `cloudflare-tunnel` `routing` `websocket` `tls` `coolify` `terminal` `realtime` `6001` `6002`  
**Severidad:** Alta — terminal de Coolify inoperativa, websockets de la UI rotos  
**Fecha:** 2026-04-11

---

## Síntoma

- La terminal dentro de Coolify muestra `Terminal websocket connection lost`
- La UI de Coolify se comporta de forma inestable (reconexiones constantes)
- Los logs de `cloudflared` muestran:

```
tls: first record does not look like a TLS handshake
originService=https://192.168.0.117:6001

tls: first record does not look like a TLS handshake
originService=https://192.168.0.117:6002
```

---

## Causa Raíz

Las rutas del Cloudflare Tunnel para los puertos 6001 (realtime/websocket) y 6002 (terminal/websocket) están configuradas con `https://` como prefijo del servicio de origen.

Estos puertos **no hablan HTTPS** — solo HTTP plano. Cloudflared intenta establecer un handshake TLS con un servicio que responde en texto plano, causando el error.

---

## Dónde vive la configuración (importante)

El túnel está **gestionado desde el dashboard de Cloudflare** (remotely-managed),
no por el `config.yml` local. El `/etc/cloudflared/config.yml` dentro del contenedor
solo tiene el UUID del túnel, las credenciales y el comodín `*.urieljareth.org`:

```yaml
tunnel: 5f0e5c5b-a180-46f2-a090-44d151006a62
credentials-file: /etc/cloudflared/credentials.json
ingress:
  - hostname: "*.urieljareth.org"
    service: https://192.168.0.117:443
  - service: http_status:404
```

**Las rutas de `coolify.urieljareth.org` (incluidas 6001/6002) NO están en ese
archivo — vienen del dashboard/API.** La firma de esto en los logs es la línea
`INF Updated to new configuration version=N`. Consecuencia práctica: **este problema
no se arregla editando archivos en el servidor**, sino en el dashboard (rápido) o
por la API de Cloudflare (control total — ver runbook).

---

## Configuración Correcta del Tunnel (coolify-tunnel)

El orden importa: Cloudflare evalúa las rutas de **arriba hacia abajo**. Las rutas específicas deben ir ANTES del comodín.

| # | Dominio | Ruta | Servicio | Protocolo |
|---|---------|------|---------|-----------|
| 1 | `coolify.dominio.com` | `/build/*` | `http://192.168.0.117:8000` | HTTP |
| 2 | `coolify.dominio.com` | `/app/*` | `http://192.168.0.117:6001` | HTTP ⚠️ |
| 3 | `coolify.dominio.com` | `/terminal/ws*` | `http://192.168.0.117:6002` | HTTP ⚠️ |
| 4 | `coolify.dominio.com` | `*` | `http://192.168.0.117:8000` | HTTP |
| 5 | `*.dominio.com` | `*` | `https://192.168.0.117:443` | HTTPS |

### Reglas Críticas

- Los puertos **6001 y 6002 deben usar `http://`**, nunca `https://`
- La ruta `/terminal/ws*` se escribe **sin barra final** (no `/terminal/ws/*`)
- El comodín `*.dominio.com` va **siempre al final**
- El comodín de Coolify (ruta 4) también usa `http://`

---

## Diagnóstico

Dentro del CT 102 (referencia):

```bash
# Ver errores actuales del tunnel
docker logs cloudflared --tail 30

# Confirmar configuración activa del tunnel
docker logs cloudflared --tail 50 | grep "Updated to new configuration"
```

Desde este repo (PowerShell, vía el path SSH habitual):

```powershell
# Errores recientes del túnel
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 102 -- docker logs cloudflared --tail 40"

# Configuración activa (toma el version=N más alto)
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 102 -- docker logs cloudflared --tail 60" |
  Select-String "Updated to new configuration"
```

En la configuración activa (línea `INF Updated to new configuration version=N`), verificar que los servicios de 6001 y 6002 digan `http://` y no `https://`. El runbook
[runbooks/cloudflare-tunnel.md](runbooks/cloudflare-tunnel.md) tiene el procedimiento completo paso a paso.

---

## Solución

1. Ir a **Cloudflare Zero Trust → Networks → Tunnels → coolify-tunnel → Public Hostnames**
2. Editar la ruta `/app/*` → cambiar servicio de `https://IP:6001` a `http://IP:6001`
3. Editar la ruta `/terminal/ws*` → cambiar servicio de `https://IP:6002` a `http://IP:6002`
4. Guardar — Cloudflared aplica el cambio automáticamente sin reinicio

**Verificación:**

```bash
docker logs cloudflared --tail 10
```

Debe aparecer `INF Updated to new configuration version=<N>` con los servicios correctos en el JSON.

---

## Notas Adicionales

- Los errores previos en los logs son residuales de conexiones ya abiertas — desaparecen solos
- Si el orden de las rutas también está mal (comodín antes que las específicas), el tráfico de websocket nunca llega a las rutas correctas
- Este error es silencioso desde la perspectiva del usuario — solo ve que la terminal no conecta

---

## Reincidencia verificada (2026-06-03)

El problema volvió a presentarse (`Terminal websocket connection lost`). Hallazgos
de esa intervención:

- Config activa (`version=14`) tenía **`/app/*` (6001) y `/terminal/ws/` (6002) en `https://`**.
- Variante observada: la ruta de terminal estaba como **`/terminal/ws/`** (con barra
  final, sin comodín), además del `https://` — ambos errores juntos.
- Solución aplicada desde el **dashboard**: 6001 y 6002 a `http://`, y path de terminal
  corregido a `/terminal/ws*`. Cloudflared aplicó solo (`version=14 → 15 → 16`).
- Resultado: terminal de Coolify operativa. Los errores TLS residuales desaparecieron solos.
- Pendiente menor: `app/*` quedó sin barra inicial (`/app/*` sería lo ideal); no es
  crítico porque el protocolo ya es correcto.