Cómo configurar Collabora Online detrás de Nginx

Lo que debería hacer un proxy inverso funcional

Una implementación correcta de Collabora Online detrás de Nginx proporciona a los usuarios una dirección HTTPS pública para el editor, manteniendo el servicio de Collabora en una red privada. El editor debe cargar sus recursos del navegador, detectar las funcionalidades de Office, abrir un documento a través de la plataforma de almacenamiento conectada y mantener activa su conexión WebSocket durante la edición. Una comprobación de sintaxis válida de Nginx por sí sola no garantiza que estas rutas funcionen.

Este ejemplo asume que un servidor Collabora independiente o un contenedor CODE escucha en el puerto 9980, Nginx sirve office.example.comy TLS termina en Nginx. Reemplace el nombre de host y las rutas del certificado con los suyos. La dirección de backend 127.0.0.1:9980solo se aplica cuando Nginx y Collabora comparten un host y el servicio está vinculado a la interfaz loopback. Para contenedores separados, use el nombre del servicio Collabora en una red Docker privada, como http://collabora:9980.

Antes de cambiar Nginx

Confirme que el nombre DNS público se resuelve al proxy, que el certificado TLS cubre ese nombre exacto y que Nginx puede acceder a Collabora a través de su dirección interna. Si utiliza Docker, conecte ambos servicios a una red definida por el usuario y no publique el puerto de Collabora públicamente. Si Nginx se ejecuta en el host, asigne el puerto del contenedor a la interfaz de bucle invertido (loopback), por ejemplo 127.0.0.1:9980:9980. Su firewall debe exponer los puertos web públicos que desea servir, no el puerto del backend de Collabora.

Elija una configuración TLS. La configuración que se muestra a continuación utiliza TLS desde el navegador a Nginx y HTTP simple en un salto privado de confianza a Collabora. Esta es la terminación TLS. Si la política también requiere cifrado entre el proxy y Collabora, utilice HTTPS para el enlace ascendente y configure Nginx para que confíe en el certificado del backend. No cambie solo el proxy_passesquema: la configuración TLS del servidor debe coincidir con la del oyente de Collabora. Collabora documenta ambas configuraciones de proxy en su guía de proxy inverso de Nginx y en el manual del SDK 25.04 .

Configura las opciones TLS compatibles con proxy de Collabora

Para la terminación TLS, configure coolwsdel servicio de Collabora con ssl.enable=falsey ssl.termination=true. La forma de establecer estos valores depende de cómo se instaló Collabora: edite la coolwsd.xmlconfiguración compatible o utilice las opciones documentadas para su paquete o contenedor. Con la imagen Docker CODE, las implementaciones suelen pasar las opciones como extra_params; consulte la documentación de la imagen para su versión y cite correctamente los argumentos en Compose. Reinicie o vuelva a crear el servicio de Collabora después de cambiar su configuración.

Estas configuraciones le indican a Collabora que la conexión externa está protegida por el proxy, aunque el salto del proxy al servidor backend utilice HTTP. No instalan un certificado público, no configuran el DNS ni autorizan a un servidor de almacenamiento a usar Collabora. Configure la lista de hosts permitidos de WOPI o los ajustes de integración por separado, según su plataforma de almacenamiento.

Configura Nginx para reenviar las rutas del editor.

Nginx debe pasar los recursos de descubrimiento y del navegador y conservar la actualización de WebSocket utilizada por la edición interactiva. El siguiente es un ejemplo de un solo servidor. Defina mapen el contexto de Nginx http, como el principal nginx.conf, no dentro del host virtual:

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

Coloque el bloque del servidor en la configuración del sitio incluida por Nginx. Esto supone que los certificados TLS ya están instalados y que la conexión del proxy a Collabora es HTTP:

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;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    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 $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 36000s;
        proxy_buffering off;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 36000s;
    }
}

Las rutas que comienzan con /cooltransportan las solicitudes principales de WebSocket y del editor; el patrón también incluye /loolrutas heredadas para compatibilidad. El proxy de WebSocket de Nginx requiere los encabezados de actualización HTTP/1.1 porque Upgradey Connectionson encabezados salto a salto. El tiempo de espera de lectura largo ayuda a evitar el cierre de una conexión de edición activa debido a un tiempo de espera de proxy corto normal. Consulte la documentación del proxy de WebSocket de Nginx y la referencia del módulo de proxy .

Para HTTPS en el servidor ascendente, cambie las URL del servidor de backend https://y configure adecuadamente la verificación del certificado ascendente y la cadena de certificados de confianza de Nginx. Evite deshabilitar la verificación del certificado como solución permanente. Si Nginx se encuentra en otro contenedor, reemplace la dirección de bucle invertido con el nombre del servicio de Collabora; 127.0.0.1dentro del contenedor proxy, apunta a ese contenedor proxy.

Cuando se utiliza un prefijo URI en /collabora/lugar de un nombre de host dedicado, la configuración y las URL de descubrimiento generadas por Collabora requieren un manejo de ruta adicional. Comience con un nombre de host dedicado a menos que su plataforma admita explícitamente una implementación de subruta. Un bloque de servidor que reenvía las solicitudes en la raíz no hace que las URL generadas por el descubrimiento funcionen automáticamente con un prefijo.

Recargar y verificar cada capa

Valide la configuración de Nginx antes de aplicarla y, a continuación, reinicie el servicio:

sudo nginx -t
sudo systemctl reload nginx

Si la comprobación de sintaxis falla, corrija primero el archivo y la línea indicados. Una recarga exitosa confirma que Nginx aceptó la configuración, no que el backend, el certificado o la ruta de WebSocket funcionen. Compruebe la validez del DNS y del certificado por separado y, a continuación, solicite los dos puntos finales de Collabora a través del nombre de host público:

curl -fsS https://office.example.com/hosting/discovery | head
curl -fsS https://office.example.com/hosting/capabilities

El punto final de descubrimiento debe devolver XML en lugar de una página de error 404 de Nginx o una página de inicio de sesión; las capacidades deben devolver una respuesta de Collabora. Inspeccione las URL del editor del XML de descubrimiento: deben usar el nombre de host HTTPS público y las rutas accesibles, no un nombre de contenedor ni una dirección interna. La imagen de ejemplo a continuación muestra los tipos de respuestas que se deben buscar; los valores mostrados son ilustrativos y no corresponden a la salida de un servidor en funcionamiento.

Finalmente, configure su plataforma de documentos para que la utilice https://office.example.comcomo servidor Collabora y abra un documento de prueba. Una señal de éxito útil es que el editor se cargue y siga respondiendo mientras escribe, guarda y vuelve a abrir el documento. En las herramientas para desarrolladores del navegador, la solicitud WebSocket /cool/debería actualizarse correctamente; el estado HTTP 101 Switching Protocolses el resultado esperado del protocolo de enlace WebSocket. No considere el estado de un ejemplo dibujado como prueba de que su propio servidor superó esta verificación.

Analiza los fallos por sus síntomas.

• 502 Bad Gateway: Nginx no puede conectarse al servidor ascendente. Compruebe el nombre del servicio, el puerto, la red del contenedor, el listener y los registros. Si los contenedores están separados, no utilice la dirección de bucle invertido del contenedor proxy.
• Error 404 al descubrir o acceder a los recursos del navegador: Confirme que la solicitud llega al host virtual correcto y que la ubicación reenvía la ruta sin una reescritura de URI no deseada. Pruebe la URL pública, no solo la URL del servidor.
• El editor se carga pero se bloquea o se desconecta: Inspeccione la /cool/.../wssolicitud. La falta de encabezados de actualización, una conexión HTTP/1.0, un tiempo de espera corto o un proxy que almacena la conexión en búfer pueden interrumpir la edición. Confirme que la solicitud se actualiza y permanece abierta mientras el documento está activo.
• Host WOPI no autorizado: El proxy puede funcionar correctamente, aunque Collabora rechace la plataforma de almacenamiento. Verifique el nombre de host WOPI con la lista de permitidos de Collabora y la configuración del conector de la plataforma. No solucione este problema exponiendo el backend a internet.
• Advertencia sobre contenido mixto o certificado: asegúrese de que la URL del editor público y las URL de detección utilicen HTTPS y que el certificado coincida con el nombre de host. Si finaliza TLS en Nginx, verifique también la configuración de finalización de Collabora.

Una vez superadas estas comprobaciones, mantenga el backend de Collabora en modo privado y supervise los registros de Nginx y Collabora al actualizar cualquiera de los componentes. Este ejemplo de un único servidor ascendente no configura la alta disponibilidad, el balanceo de carga ni la afinidad de sesión por documento. Para múltiples réplicas de Collabora, siga las instrucciones de implementación del controlador o balanceador de carga de Collabora correspondiente y pruebe la afinidad de documentos antes de enrutar el tráfico de producción.

Fuentes y notas de versión

El 6 de octubre de 2026, se verificaron los detalles de configuración con la documentación del proxy de Collabora y el manual del SDK 25.04, así como con las referencias de WebSocket y el módulo proxy de Nginx. Las opciones de paquetes y contenedores pueden variar según la versión de Collabora; confirme los nombres de las configuraciones para la versión que utilice antes de aplicarlas. Este artículo no presupone una plataforma de almacenamiento específica ni demuestra una implementación en producción.