Cómo configurar la terminación SSL para un contenedor Collabora CODE

La terminación SSL es ideal para un contenedor de Collabora Online Development Edition (CODE) cuando se desea un punto final HTTPS público y, al mismo tiempo, mantener la gestión de certificados en un proxy inverso como Nginx. En este diseño, el navegador se conecta a Nginx mediante HTTPS, Nginx descifra el tráfico y Collabora recibe HTTP sin cifrar en su puerto interno. El objetivo de calidad no se limita a que la página se cargue. Una implementación exitosa debe contar con un certificado público válido, un punto final de descubrimiento WOPI accesible, actualizaciones de WebSocket que funcionen correctamente y una sesión de edición de documentos real que se mantenga conectada.

La documentación del proxy de Collabora describe este patrón de descarga SSL como una conexión exclusivamente HTTP entre el proxy y Collabora, con ssl.enable=falsey ssl.termination=trueen el lado de Collabora. Consulte la configuración del proxy inverso de Collabora Online . Los ejemplos a continuación utilizan Nginx y Docker Compose, pero se puede lograr el mismo resultado con otros proxies inversos si conservan el comportamiento de host y WebSocket requerido.

Lo que debería lograr una buena configuración de terminación SSL

Paso 1: Confirme el límite de la red antes de cambiar Collabora

Decida dónde termina TLS y qué hosts pueden acceder al puerto 9980. Si Nginx se ejecuta en la misma máquina que Docker, vincular el puerto publicado a 127.0.0.1es una forma sencilla de evitar el acceso directo a Internet. Docker documenta que publicar un puerto a 127.0.0.1lo mantiene local al host; consulte la documentación de publicación de puertos de Docker .

Si Nginx se ejecuta en otro contenedor, una red Docker privada compartida suele ser más segura que publicar el puerto 9980 públicamente. El principio es el mismo: los clientes deben usar el nombre de host del proxy inverso HTTPS, no el contenedor de Collabora directamente.

Paso 2: Ejecutar CODE en modo de terminación SSL.

Para la terminación TLS del lado del proxy, Collabora debe saber que el esquema original orientado al cliente es HTTPS, aunque su conexión ascendente inmediata sea HTTP. La configuración documentada es:

--o:ssl.enable=false --o:ssl.termination=true

Un ejemplo mínimo de Compose se ve así:

services:
  collabora:
    image: collabora/code:YOUR_TESTED_TAG
    restart: unless-stopped
    ports:
      - "127.0.0.1:9980:9980"
    environment:
      - "extra_params=--o:ssl.enable=false --o:ssl.termination=true"
      - "server_name=office.example.com"

Sustituya YOUR_TESTED_TAGla versión por una que haya validado, en lugar de asumir automáticamente que latestes segura para un entorno de producción. Configure también los ajustes de host o alias de WOPI adecuados para su integración; estos valores dependen de si se conecta a Nextcloud, ownCloud, otro host de WOPI o una integración personalizada.

Tras iniciar el contenedor, confirme que se está ejecutando y que la asignación de puertos coincide con el límite previsto:

docker compose up -d
docker compose ps
docker logs --tail=100 collabora

Nota de versión para implementaciones 26.04

No considere las dos banderas SSL como la única variable al solucionar problemas con una imagen 26.04 actual. A mediados de 2026, Collabora detectó regresiones relacionadas con la imagen Docker sin distribución y las configuraciones con SSL deshabilitado. Un problema oficial en GitHub documenta una regresión al iniciar la versión 26.04, y la comunidad de Collabora informó que el comportamiento de terminación SSL afectado volvió a funcionar en una imagen posterior 26.04.2.4.1. Consulte el problema n.° 16019 de CollaboraOnline/online si una configuración de terminación que funcionaba correctamente deja de funcionar inmediatamente después de actualizar la imagen.

Esto también justifica fijar y probar la versión de la imagen. Un error de configuración y una regresión de la imagen del contenedor pueden tener un aspecto similar en Nginx: ambos pueden manifestarse como una respuesta 502 o una conexión fallida con el servidor de origen.

Paso 3: Configurar Nginx para finalizar TLS y actuar como proxy para las rutas de Collabora.

Nginx necesita un certificado válido para el nombre de host de Collabora y debe reenviar los puntos finales HTTP de Collabora, además del tráfico WebSocket. La guía de proxy de Collabora muestra ubicaciones específicas para los recursos del navegador, el descubrimiento, las capacidades, las conexiones WebSocket principales, las rutas de descarga/carga y el WebSocket de administración. La siguiente configuración sigue esa estructura, añadiendo encabezados de reenvío comunes:

server {
    listen 443 ssl;
    server_name office.example.com;

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

    location ^~ /browser {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }

    location ~ ^/cool/(.*)/ws$ {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_read_timeout 36000s;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }

    location ^~ /cool/adminws {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_read_timeout 36000s;
    }
}

Los encabezados de WebSocket no son cosméticos. La documentación oficial de Nginx explica que Upgradey Connectionson encabezados salto a salto y deben pasarse explícitamente para WebSockets con proxy inverso. Consulte Nginx WebSocket proxying . La documentación del módulo proxy estándar también cubre proxy_set_header, proxy_pass, y proxy_read_timeout: ngx_http_proxy_module .

Paso 4: Validar Nginx antes de recargar.

Pruebe la configuración de Nginx antes de reemplazar una configuración que se sabe que funciona correctamente:

sudo nginx -t

Recargue la aplicación solo si la prueba de sintaxis es exitosa:

sudo systemctl reload nginx

Luego, confirme que Nginx puede acceder al backend local de Collabora. En una configuración en el mismo host, una comprobación útil es:

curl -I http://127.0.0.1:9980/hosting/discovery

Los encabezados de respuesta exactos pueden variar según la versión de Collabora, pero el resultado fundamental es que la conexión TCP se establece correctamente y el punto final responde en lugar de agotar el tiempo de espera o rechazar la conexión. Si esta solicitud local falla, cambiar la configuración pública de TLS no solucionará el problema subyacente del contenedor o de la red.

Paso 5: Verificar el punto final HTTPS público

Desde un cliente que resuelve el nombre de host público, solicite el punto final de descubrimiento a través de Nginx:

curl -I https://office.example.com/hosting/discovery

Una solicitud del navegador https://office.example.com/hosting/discoverydebería devolver XML. Esta es una comprobación funcional mejor que depender de la URL raíz, ya que el comportamiento de la página raíz no es el contrato principal de WOPI y puede variar según la versión.

Además, compruebe la cadena de certificados con su navegador o una herramienta de diagnóstico TLS. El nombre de host debe coincidir con el certificado, la cadena debe ser de confianza y no debe haber advertencias de contenido mixto causadas por Collabora al mostrar URL HTTP simples en el navegador.

Paso 6: Pruebe un documento real y el WebSocket.

El éxito en la detección es necesario, pero no suficiente. Abra un documento desde su servidor WOPI y manténgalo abierto el tiempo suficiente para probar la sesión en vivo. En las herramientas para desarrolladores del navegador, la solicitud WebSocket de Collabora debería actualizarse correctamente en lugar de reconectarse repetidamente o devolver un error 400/502. Una sesión en buen estado debería permitirle escribir, guardar y volver a abrir el documento.

Si el editor se carga correctamente, pero el documento falla poco después, priorice la ruta de WebSocket, el tiempo de espera del proxy, la lista de permisos de WOPI y el comportamiento del encabezado del host. Si los registros de Nginx muestran un error de conexión ascendente antes de que se establezca cualquier WebSocket, inspeccione primero el oyente de CODE y la versión de la imagen.

Cómo diagnosticar los modos de falla más comunes

502 Puerta de enlace no válida

Un error 502 generalmente significa que Nginx no pudo obtener una respuesta válida del servidor ascendente configurado. Verifique si CODE está escuchando en el puerto 9980 y si está utilizando el protocolo ascendente correcto. En el diseño previsto de terminación SSL, el salto del proxy a CODE es HTTP. Si una regresión de la imagen provoca que CODE siga sirviendo HTTPS internamente a pesar de sus parámetros, los registros y una curlprueba directa revelarán la discrepancia. No cambie permanentemente a un servidor ascendente HTTPS solo para ocultar una regresión de configuración inexplicable; primero verifique el comportamiento de la imagen de CODE exacta que está ejecutando.

La función de búsqueda funciona, pero los documentos no se abren.

Esto suele indicar un problema con el reenvío de WebSocket o la autorización WOPI, en lugar de con TLS. Verifique la /cool/.../wsruta, los encabezados de actualización y el host que autorizó como origen WOPI. Collabora puede ser perfectamente accesible a través de HTTPS y, aun así, rechazar o fallar una sesión de edición.

URLs con contenido mixto o esquema incorrecto

Si un navegador ve una página HTTPS que hace referencia a recursos HTTP, verifique ssl.termination=trueel encabezado del esquema de reenvío y el nombre del servidor. El lado público de la implementación debe identificarse consistentemente como HTTPS, aunque el salto privado sea HTTP.

El contenedor informa de un estado anómalo a pesar de que la edición funciona.

Las versiones recientes 26.04 introdujeron un comportamiento de comprobación de estado que ha cambiado durante la transición a distroless-image. Collabora registró un caso en el que la sonda no respetó una configuración de backend HTTP tras la terminación TLS. Si las pruebas funcionales se superan, pero el estado de Docker es inesperadamente rojo, consulte el historial de problemas específico de la versión antes de rediseñar un proxy que funcione. Consulte el problema n.º 16032 de CollaboraOnline/online .

Cuándo utilizar un diseño diferente

La terminación SSL del lado del proxy es apropiada cuando el proxy inverso y Collabora se comunican a través de una interfaz local de confianza o una red privada aislada. Si el tráfico entre Nginx y CODE atraviesa una red no confiable, el protocolo HTTP simple en el salto interno podría no cumplir con sus requisitos de seguridad. En ese caso, utilice TLS también para el backend o coloque ambos servicios en una red protegida donde la interceptación no represente una amenaza real.

Asimismo, si ya utiliza una plataforma de entrada gestionada que maneja correctamente los certificados, el enrutamiento y los WebSockets, no tiene mucho sentido añadir una segunda capa Nginx solo para Collabora. La arquitectura correcta es aquella que proporciona un único límite TLS observable sin saltos innecesarios.

Lista de verificación de validación final

• El nombre de host de Collabora se resuelve en el proxy inverso.
• El puerto 443 presenta un certificado de confianza para ese nombre de host.
• El código no está expuesto innecesariamente a Internet pública en el puerto 9980.
• ssl.enable=falsey ssl.termination=truese aplican al diseño del backend HTTP.
• Nginx puede acceder a CODE en su dirección privada.
• /hosting/discoveryResponde a través de la URL HTTPS pública.
• La /cool/.../wsactualización de WebSocket se realizó correctamente.
• Un documento real se abre, se edita, se guarda y se vuelve a abrir.
• Has fijado y probado la versión exacta de la imagen de CODE que planeas implementar.

Si todas estas comprobaciones se superan, la terminación SSL funciona correctamente: el tráfico externo está protegido por HTTPS, Collabora reconoce la conexión pública como segura y la ruta de edición sigue funcionando. Si falla alguna comprobación, solucione el problema en esa capa en lugar de modificar varias partes de la pila a la vez.