Proxy inverso y TLS
Proxy inverso y TLS
Toda petición a una instancia de lazyit llega a través de Caddy, el proxy inverso. Termina el HTTPS, enruta el tráfico a la web y a la API, y es el único servicio que publica puertos al servidor. Todo lo demás permanece en la red interna.
Qué hace Caddy
- Termina el TLS y obtiene los certificados automáticamente (ver más abajo).
- Enruta por ruta sobre un único origen. El navegador llama a un solo origen; Caddy envía las
peticiones de página a la web y las peticiones bajo
/api/a la API (quitando el prefijo/api). Como todo es del mismo origen, una misma imagen web funciona en cualquier dominio. - Añade cabeceras de seguridad básicas a cada respuesta y oculta el identificador del servidor.
La configuración de Caddy vive en infra/caddy/Caddyfile. En la mayoría de los despliegues no lo editas:
defines valores en el archivo de entorno y, para un dominio público, descomentas dos líneas.
TLS: certificados automáticos
Caddy aprovisiona certificados con cero configuración, en uno de dos modos:
- Autoridad de certificación interna — usada para
localhosty despliegues privados. El certificado es TLS real pero los navegadores no confían en él por defecto, así que verás un aviso hasta que confíes en el certificado raíz de Caddy. Este es el modo para pruebas tipo producción local y para redes privadas o aisladas. - Let’s Encrypt — usado para un dominio real y accesible públicamente. Los certificados son de confianza pública (sin aviso) y se renuevan automáticamente. Requiere que tu dominio resuelva al servidor y que los puertos 80 y 443 sean accesibles.
También existe una opción sin TLS para una LAN de confianza: el modo LAN del arranque sirve HTTP plano en cualquier IP o nombre de host, sin certificado que aprovisionar ni en el que confiar. Entonces las sesiones no van cifradas, así que úsalo solo en una red local que controles — consulta Modos de red y TLS.
Salir en vivo con un dominio real
Para un despliegue público con HTTPS de confianza, define esto en infra/env/.env.prod:
- Tu dirección del sitio con tu nombre de dominio completo.
- La URL de origen público (
https://tudominio.com, sin barra final). - Un correo de contacto ACME para Let’s Encrypt — y descomenta la línea
emailen el Caddyfile. - Los puertos publicados con los estándar
80y443(los predeterminados son puertos altos para pruebas locales).
Para un dominio público real, activa además HSTS descomentando la línea import hsts en el bloque
del sitio del Caddyfile. HSTS indica a los navegadores que fuercen HTTPS durante un año.
Activa HSTS solo en un dominio real y de confianza pública. Nunca lo actives en una instalación
localhosto con CA interna: dejaría tu navegador fijado en HTTPS-solo paralocalhosten todos los proyectos.
Confiar en el certificado local
En un despliegue tipo producción local, acepta el aviso del navegador o confía una vez en el certificado raíz de Caddy. Puedes exportarlo del contenedor en marcha:
docker compose -f compose.yaml -f infra/docker-compose.prod.yaml --profile prod \
cp caddy:/data/caddy/pki/authorities/local/root.crt ./caddy-local-root.crt
Luego añade caddy-local-root.crt al almacén de confianza de tu sistema operativo o navegador. En un
dominio real con Let’s Encrypt no hay aviso ni nada que confiar manualmente.
Una nota sobre la documentación de la API
La página interactiva de documentación de la API no se sirve a propósito en el origen público. Una
petición a /api/docs en una instancia en vivo devuelve 404: es un endurecimiento intencionado, no
una instalación rota. La documentación sigue siendo accesible en la red interna y en desarrollo local.
Confianza y cabeceras reenviadas
Caddy actúa como el único salto delante de la API y reenvía la IP del cliente verificada. La API está configurada para confiar exactamente en ese único salto, de modo que las funciones basadas en la IP de la petición (limitación de tasa, la auditoría del primer arranque) ven al cliente real y no una cabecera falsificada. Esto viene preconfigurado; no necesitas cambiarlo para un despliegue estándar en un único servidor.
El asistente de IA y los agentes externos
Cuando la IA está activada, importan dos cosas:
- El chat transmite sus respuestas en streaming. Caddy pasa el stream sin buffer y sin comprimir. Si
ponés otro proxy o balanceador delante de Caddy, tampoco tiene que bufferear ni comprimir
text/event-stream(nginx:proxy_buffering off;en la location de lazyit); si no, cada respuesta aparece recién cuando está completa. - El inicio de sesión de MCP necesita HTTPS y una dirección fija. Caddy enruta el endpoint MCP
(
/mcp) y las rutas de OAuth a la API. Los agentes de IA externos inician sesión con OAuth solo cuando el origen público (WEB_ORIGIN) es una direcciónhttps://; en una instancia HTTP plana (modo LAN) usan tokens personales. Un proxy TLS delante de una instancia en modo LAN no alcanza: configuráWEB_ORIGINcon la direcciónhttps://y reiniciá la API. Los conectores en la nube (claude.ai, ChatGPT) además necesitan que la instancia sea accesible desde internet con un certificado de confianza pública. Mirá Agentes de IA externos (MCP).
Content-Security-Policy
La aplicación web envía su propia Content-Security-Policy en cada página. Es una segunda línea de defensa: si algo llegara a escaparse del saneado de los artículos de la Base de conocimiento o de las respuestas de la IA, el navegador igual se niega a ejecutar scripts inyectados o a cargar imágenes y conexiones de otros sitios. Los scripts se permiten con un valor de un solo uso generado para cada página, y las imágenes vienen solo del propio lazyit.
Hoy la política funciona en modo solo informe (report-only): el navegador la evalúa y anota
cualquier infracción en su consola de desarrollador como un mensaje [Report Only], pero no bloquea
nada. Insertar lazyit dentro de otro sitio (framing) ya está bloqueado en cualquier modo. Una
versión posterior pasa la política a modo de bloqueo.
Qué significa para ti:
- Nada que configurar con el Caddy incluido. La política la envía la aplicación web, no Caddy.
- Tu propio proxy inverso delante de lazyit no debería agregar una segunda
Content-Security-Policy. Los navegadores aplican todas las políticas que reciben, así que una segunda puede bloquear los scripts que la aplicación permite. Si tu organización exige una en el proxy, deja pasar sin cambios la cabecera de la aplicación. - Las imágenes de otros sitios no se cargan, ni en artículos ni en ningún otro lugar — es a propósito. Sube la imagen como adjunto del artículo; los adjuntos los sirve el propio lazyit.