Coloca ONLYOFFICE Docs detrás de HAProxy sin interrumpir la edición.

Ejecute ONLYOFFICE Docs detrás de HAProxy finalizando HTTPS en el proxy, reenviando el host y el esquema originales y permitiendo conexiones WebSocket de larga duración. Comience con un servidor de documentos en buen estado; agregue más servidores backend solo cuando su implementación de ONLYOFFICE esté configurada para admitir el funcionamiento en varios nodos, no simplemente porque HAProxy pueda distribuir las solicitudes.

¿Puede HAProxy equilibrar la carga entre dos servidores de documentos independientes?

HAProxy puede distribuir las solicitudes HTTP entre nodos, pero esto no convierte dos instalaciones independientes de ONLYOFFICE en un clúster de edición coordinado. Una sesión de edición mantiene conexiones persistentes y un estado de aplicación constante. El ejemplo oficial de ONLYOFFICE en modo activo-activo utiliza comprobaciones de estado del servidor y una cookie de persistencia; estos son mecanismos de enrutamiento, no sustituyen los servicios compartidos ni la arquitectura a nivel de aplicación que requiere su edición.

Para una instalación convencional de un solo servidor, utilice únicamente docs1el backend que se describe a continuación. Para dos nodos, primero confirme la arquitectura del clúster, la edición compatible, las dependencias compartidas, la compatibilidad de versiones y la configuración JWT con la documentación de implementación de ONLYOFFICE o el soporte del proveedor. Las direcciones de ejemplo — 10.0.10.21y 10.0.10.22— son direcciones IP privadas ilustrativas, no hosts detectados.

¿Qué debe estar funcionando antes de editar HAProxy?

El nombre público docs.example.comdebe resolverse en el punto final de HAProxy. HAProxy necesita los puertos TCP 80 y 443 de entrada y acceso a la red privada de cada servidor de documentos en el puerto 80. Su aplicación de gestión documental también debe poder acceder a la dirección pública de Docs, mientras que ONLYOFFICE debe poder recuperar documentos y enviar devoluciones de llamada a la aplicación. Mantenga la conexión HTTP del backend privada; cifre el salto del backend por separado si atraviesa una red no confiable.

1. Compruebe cada servidor de documentos desde el host proxy. Ejecute curl -i http://10.0.10.21/healthchecky, si está presente, curl -i http://10.0.10.22/healthcheck. Un punto final de estado operativo normalmente devuelve HTTP 200 con un cuerpo de true. Investigue el enrutamiento, los firewalls o el estado del servidor antes de configurar el balanceo si alguno falla.
2. Confirme un secreto JWT fijo. El servidor de documentos y su conector deben coincidir en el secreto del token. Para instalaciones de Docker, ONLYOFFICE documenta la JWT_SECRETvariable de entorno; desde Docs 7.2, depender de un secreto generado automáticamente puede provocar fallos de integración tras su recreación o reinicio. En implementaciones multinodo compatibles, alinee los secretos entre los nodos según la arquitectura del proveedor.

Estas comprobaciones siguen las instrucciones de instalación de Docker y de configuración de JWT del proveedor . No desactive JWT simplemente para solucionar un error de proxy.

¿Cómo se configura HTTPS y se reenvían las cabeceras correctas?

Paso 1: Preparar el certificado

Obtenga un certificado de confianza que cubra docs.example.com. En este ejemplo de Linux, HAProxy lee un archivo PEM que contiene la cadena de certificados seguida de la clave privada. Si ya existen certificados en otro lugar, sustituya esas rutas. Restrinja el acceso al archivo PEM combinado y configure su reconstrucción cuando se renueve el certificado.

sudo install -d -m 700 /etc/haproxy/certs
sudo sh -c 'umask 077; cat /etc/letsencrypt/live/docs.example.com/fullchain.pem /etc/letsencrypt/live/docs.example.com/privkey.pem > /etc/haproxy/certs/docs.example.com.pem'

Paso 2: Añadir el frontend y el backend

Realice una copia de seguridad de su configuración actual /etc/haproxy/haproxy.cfgy adapte las siguientes secciones en lugar de reemplazar sin más la configuración de registro o de servicio específica de la distribución. Esta es una configuración ilustrativa para las versiones modernas de HAProxy. Solo acepta HTTP para la redirección, finaliza HTTPS en el puerto 443, reenvía el host público y el esquema, y ​​supervisa el punto final de estado de la aplicación.

global
    log /dev/log local0

defaults
    mode http
    log global
    option httplog
    option forwardfor
    timeout connect 5s
    timeout client 60s
    timeout server 60s
    timeout tunnel 1h

frontend docs_http
    bind :80
    http-request redirect scheme https code 301

frontend docs_https
    bind :443 ssl crt /etc/haproxy/certs/docs.example.com.pem
    http-request set-header X-Forwarded-Proto https
    http-request set-header X-Forwarded-Host %[req.hdr(Host)]
    default_backend docs_nodes

backend docs_nodes
    option http-server-close
    balance roundrobin
    cookie SERVERID insert indirect nocache
    option httpchk GET /healthcheck
    http-check expect string true
    server docs1 10.0.10.21:80 check cookie docs1
    server docs2 10.0.10.22:80 check cookie docs2

Elimine la docs2línea a menos que el segundo nodo esté realmente listo. La cookie de persistencia ayuda a que las solicitudes HTTP posteriores regresen al nodo seleccionado. HAProxy gestiona una actualización de HTTP WebSocket sin una reescritura de URL especial; timeout tunnel 1hpermite que las conexiones actualizadas inactivas permanezcan abiertas durante más tiempo que las solicitudes normales. La documentación de HAProxy WebSocket explica este comportamiento.

X-Forwarded-ProtoLa configuración httpses correcta aquí porque este frontend termina HTTPS público. No confíe en un esquema de reenvío arbitrario proporcionado por el cliente ni en un host en el borde de la red con acceso a Internet. La documentación del proxy ONLYOFFICE exige específicamente que X-Forwarded-Protose X-Forwarded-Hostconserve el contexto de la URL externa.

¿Cómo se debe recargar y probar el balanceador de carga?

Paso 3: Validar antes de cambiar el tráfico

Compruebe la sintaxis antes de recargar. Un código de salida distinto de cero significa que debe resolver el error de configuración o certificado notificado antes de continuar:

sudo haproxy -c -f /etc/haproxy/haproxy.cfg
sudo systemctl reload haproxy
curl -i https://docs.example.com/healthcheck

La respuesta pública de la comprobación de estado debería mostrar HTTP 200 truecuando un servidor backend esté en buen estado. HAProxy utiliza las directivas option httpchky http-check expectpara eliminar los nodos con fallos de la rotación de nuevas solicitudes; consulte su referencia de comprobación de estado . Una comprobación superada no demuestra que la edición de documentos o la entrega de devoluciones de llamada funcionen correctamente.

Paso 4: Confirmar la edición, WebSockets y guardar.

Abra un documento a través de su aplicación integrada, como un sistema de gestión documental conectado a ONLYOFFICE Docs. En las herramientas para desarrolladores del navegador, utilice el panel Red para inspeccionar la conexión WebSocket: el protocolo de enlace de actualización debería completarse correctamente, generalmente con el estado HTTP 101 Switching Protocols. Realice una pequeña edición, cierre el editor, vuelva a abrir el documento y confirme que el cambio se guardó. Para una implementación de dos nodos compatible, pruebe también un segundo colaborador y un vaciado planificado de un solo nodo durante una ventana de mantenimiento.

Si la comprobación de salud pública funciona, pero el editor se bloquea o se desconecta, revise las advertencias de contenido mixto, los fallos de WebSocket, las discrepancias de JWT y si la aplicación de documentos puede acceder a la URL de Docs anunciada. Si un documento se abre pero no se guarda, investigue la accesibilidad de la devolución de llamada desde el servidor de documentos a la aplicación de origen en lugar de cambiar la política de round-robin de HAProxy. Una sesión activa de WebSocket interrumpida aún puede requerir la reconexión del cliente; las comprobaciones de salud del servidor no garantizan una conmutación por error de edición sin interrupciones.

Verificación final: tanto el punto final de salud pública como una prueba real de edición y reapertura deben ser satisfactorios. Mantenga solo nodos verificados y compatibles en rotación, confirme que la renovación del certificado recarga el PEM correcto y supervise los registros de HAProxy para detectar respuestas repetidas 502/503 o desconexiones inesperadas de WebSocket.