Llegar al relay por un Cloudflare Tunnel

Un Cloudflare Tunnel le da a tu relay una dirección HTTPS pública sin un servidor propio y sin abrir un puerto en tu router. OAR puede ejecutar el programa cloudflared de Cloudflare por ti: lo arranca con el relay, lo reinicia cuando se cae y muestra su estado en el punto de estado. Elígelo cuando tengas un dominio en Cloudflare y quieras llegar al relay desde un teléfono u otra red, o cuando necesites HTTPS para instalar la página como app y para las notificaciones push.

cloudflared se conecta hacia fuera, a Cloudflare. El relay sigue escuchando solo en esta máquina (localhostOnly sigue en true), y Cloudflare lleva las solicitudes a tu nombre de host por esa conexión hasta el puerto del relay.

Lo que necesitas #

• Una cuenta de Cloudflare con Zero Trust, y un dominio (una zona) en ella para el nombre de host público.
• cloudflared instalado en la máquina que ejecuta el relay. OAR no lo incluye ni lo instala.
• Un túnel que crees en Cloudflare. OAR lo ejecuta a partir del token del túnel.

El relay ejecuta el programa indicado en cloudflaredTunnel.binary o, si no, el cloudflared que encuentre en su PATH. Instálalo con:

En Windows, un lanzador .cmd o .bat no funciona. OAR arranca un archivo .exe o .com.

Configurarlo #

1. En tu cuenta de Cloudflare Zero Trust, crea un túnel. Copia su token.
2. Dale al túnel un nombre de host público en tu zona, por ejemplo relay.example.com, y apúntalo a http://localhost:3333. Si cambiaste port en config.json, usa ese puerto. Este enrutamiento vive en Cloudflare, no en tu máquina.
3. Añade el bloque cloudflaredTunnel a config.json con el token (consulta Claves de configuración).
4. Reinicia el relay con oar restart.

Abre https://relay.example.com/ en un navegador. Inicias sesión con el token de acceso como siempre.

El bloque de configuración #

{
  "cloudflaredTunnel": {
    "mode": "managed",
    "required": false,
    "token": "<tunnel token>",
    "binary": "cloudflared",
    "extraArgs": []
  }
}

La forma antigua "enabled": true sigue funcionando para mode: "managed". Tres variables de entorno sustituyen al archivo: COPILOT_CLOUDFLARED_MODE, COPILOT_CLOUDFLARED_TOKEN y COPILOT_CLOUDFLARED_BINARY. La referencia de config.json lista las claves junto con los demás ajustes del túnel, y la página de variables de entorno lista las variables.

El relay le pasa el token a cloudflared como argumento de la línea de comandos (cloudflared tunnel run --token <token>), no a través del entorno. En una máquina con otros usuarios, el token puede aparecer por tanto en la lista de procesos en ejecución. El registro del relay lo muestra como <redacted>.

Cómo se comporta #

• Arranque y parada. El relay arranca cloudflared cuando arranca y lo detiene (con una señal de terminación) cuando se apaga.
• Conectado. El túnel cuenta como conectado cuando cloudflared informa de una conexión registrada o, a falta de eso, cuando lleva cinco segundos en ejecución.
• Caídas. Cuando cloudflared termina, el relay lo vuelve a arrancar tras una espera de unos 5, 10, 20, 40 y luego 60 segundos, cada una con hasta un 20 % añadido. Los pasos vuelven a empezar tras una conexión que duró más de 30 segundos.
• Token incorrecto o túnel eliminado. Si cloudflared termina en menos de 10 segundos tres veces seguidas, el relay informa del error auth-or-config y a partir de entonces solo lo reintenta aproximadamente una vez por minuto.
• Sin cloudflared. El relay arranca como siempre y el túnel queda desactivado. Vuelve a mirar cada minuto y arranca el túnel en cuanto el programa está ahí. Si lo instalaste en una carpeta que no está en el PATH del relay, reinicia el relay.

Túnel obligatorio #

Con required: true el relay no toma mensajes de la queue mientras el túnel no está conectado. Eso incluye el tiempo hasta la primera conexión y la falta de cloudflared o del token. Úsalo cuando el relay solo te sirva si puedes llegar a él desde fuera. Los mensajes esperan en la queue y se ejecutan en cuanto el túnel está conectado (consulta los turns y la queue).

Ver el estado #

El relay no conoce tu nombre de host público, porque el enrutamiento vive en Cloudflare, así que ninguno de estos lo muestra.

Distinguir el tráfico del túnel #

Cloudflare añade una cabecera cf-ray a cada solicitud que reenvía. El relay la usa para distinguir una solicitud que llegó por el túnel de una hecha en esta máquina. Para tratar también así las cabeceras que añade tu propio edge, lístalas en tunnelMarkerHeaders. publicHostnames lista los nombres de host que llegan al relay, y trustProxy indica de qué proxies se fía el relay en cuanto a la dirección reenviada. El valor predeterminado, "loopback", sirve para cloudflared en la misma máquina. Las tres están en la referencia de config.json.

Un segundo nombre de host para las vistas previas #

Las vistas previas necesitan su propio nombre de host, para que una app en vista previa nunca comparta una cookie de inicio de sesión con el relay. Añádelo al mismo túnel como un segundo nombre de host público que apunte al listener de las vistas previas (http://127.0.0.1:3334 de forma predeterminada). La página de vistas previas tiene el ejemplo de ingress y el bloque previews. Pon el nombre de host del relay en publicHostnames.

Cloudflare Access delante del relay #

Una aplicación de Cloudflare Access sobre el nombre de host del relay se aplica a todos los visitantes, incluidos los espectadores de una conversación compartida. Sin una excepción, se les pide que inicien sesión y el enlace no funciona. Deja pasar /shared/* y /api/shared/* sin inicio de sesión.

No añadas una regla de caché de Cloudflare para /api/shared/*. Una página compartida vuelve a cargar esa dirección para seguir la conversación, y una respuesta en caché seguiría mostrando un estado antiguo. El relay marca cada respuesta de la API con Cache-Control: no-store, y cada respuesta con CDN-Cache-Control y Cloudflare-CDN-Cache-Control fijados a no-store. Cloudflare obedece esas dos antes que una regla de caché de tu zona.

Seguridad #

Un túnel pone el relay en internet. Lo que mantiene fuera a los demás es el token de acceso. Consulta El token de acceso y quién llega al relay y Qué expone OAR.

Los workers de sesión del relay se conectan por sockets que solo funcionan en esta máquina. Como un túnel público reenvía todas las rutas, el relay responde 403 a una solicitud en esas rutas que lleve cf-ray o una de tus tunnelMarkerHeaders, y el registro lo anota con [tunnel-guard]. Los enlaces compartidos, que llegan por el túnel sin inicio de sesión, no se ven afectados.

Solución de problemas #