La regla más importante es la siguiente: implementar ONLYOFFICE Document Server detrás de HAProxy es sencillo para un único servidor backend, pero un clúster de editores con varios nodos requiere más que un simple round-robin. La documentación actual de la API de ONLYOFFICE indica que las solicitudes del mismo documento deben llegar al mismo nodo de Document Server durante la edición colaborativa. Para integraciones modernas, el mecanismo recomendado es el shardkeyparámetro de consulta, que el balanceador de carga puede usar para la afinidad con reconocimiento de documentos.
Si solo dispone de un servidor de documentos y desea utilizar HAProxy para la terminación HTTPS, un nombre de host público estable o comprobaciones de estado centralizadas, la configuración es más sencilla. Si dispone de dos o más nodos de servidor de documentos, utilice los mismos principios básicos de proxy, pero añada enrutamiento basado en shardkeyen lugar de asumir que el round-robin ordinario es suficiente.
Los ejemplos que aparecen a continuación se han comparado con la documentación actual del proxy de ONLYOFFICE , la documentación de la clave de fragmentación de ONLYOFFICE y la guía actual de HAProxy WebSocket .
HAProxy es una interfaz sensata cuando se requiere una URL pública https://docs.example.com, terminación TLS en el balanceador de carga, comprobaciones de estado activas o varios nodos de servidor de documentos detrás de un único punto final. También resulta útil cuando Nextcloud, ownCloud, DMS personalizado o aplicación no debe conectarse directamente a un nodo individual del servidor de documentos.
Esta guía parte de la base de:
No comience con el balanceador de carga. Primero, verifique que cada servidor backend esté en buen estado desde el host HAProxy. ONLYOFFICE documenta /healthcheckcomo el punto final para verificar la disponibilidad del editor. Un servidor en buen estado devuelve true; la verificación cubre dependencias principales como la base de datos, el agente de mensajes, la conexión a Redis y el almacenamiento.
curl -sS http://10.0.10.21/healthcheck
curl -sS http://10.0.10.22/healthcheckResultado esperado:
true
true
Si falla un servidor backend, solucione primero el problema en ese nodo. Las causas comunes incluyen reglas de firewall, un puerto interno incorrecto, servicios del servidor de documentos que no se están ejecutando o servicios de soporte no disponibles.
ONLYOFFICE es una aplicación HTTP que utiliza conexiones WebSocket de larga duración durante la edición. HAProxy puede gestionar automáticamente las conexiones WebSocket tras la actualización a HTTP, pero su política de tiempo de espera sigue siendo importante. La documentación de HAProxy recomienda un timeout tunnelvalor para las conexiones WebSocket actualizadas.
Un punto de partida práctico es:
global
log /dev/log local0
log /dev/log local1 notice
daemon
maxconn 4096
defaults
log global
mode http
option httplog
option dontlognull
timeout connect 5s
timeout client 60s
timeout server 60s
timeout tunnel 1h
Un tiempo de espera de túnel de una hora es solo un ejemplo, no un requisito universal. Elija un valor que se ajuste al comportamiento de edición, la política de seguridad y los límites de recursos de su organización. Si los editores se desconectan con mucha frecuencia, compare ese intervalo con los tiempos de espera por inactividad de HAProxy y de cualquier firewall o proxy inverso.
ONLYOFFICE requiere explícitamente el reenvío de encabezados cuando se ejecuta detrás de un proxy. En particular, X-Forwarded-Protole indica al servidor de documentos si el cliente original usó HTTP o HTTPS, mientras que X-Forwarded-Hostconserva el nombre de host solicitado por el cliente.
Una interfaz limpia de HAProxy puede tener este aspecto:
frontend onlyoffice_http
bind *:80
mode http
http-request redirect scheme https code 301
frontend onlyoffice_https
bind *:443 ssl crt /etc/haproxy/certs/docs.example.com.pem
mode http
option httplog
http-request set-header X-Forwarded-Proto https
http-request set-header X-Forwarded-Host %[req.hdr(Host)]
default_backend onlyoffice_docs
Normalmente, en el modo HTTP moderno de HAProxy, no es necesario recrear manualmente las reglas de encabezado Upgradey estilo NGINX Connection. HAProxy reconoce la actualización de HTTP a WebSocket y cambia la conexión a modo túnel. Lo importante es no insertar reglas que eliminen o interrumpan la solicitud de actualización.
Para que el cliente pueda ver su dirección IP, agréguelo option forwardforen el backend. Esto genera una X-Forwarded-Forcabecera a partir de la dirección de origen del cliente.
Si HAProxy actúa como servidor de documentos, el backend puede ser sencillo:
backend onlyoffice_docs
mode http
option forwardfor
option httpchk GET /healthcheck
http-check expect status 200
timeout tunnel 1h
server ds1 10.0.10.21:80 checkEn este diseño, HAProxy funciona principalmente como un proxy inverso, un punto final TLS y un control de estado.
Para una implementación real de varios nodos, no confíe en el simple algoritmo round-robin para la edición colaborativa. La documentación actual de ONLYOFFICE indica que todas las solicitudes pertenecientes al mismo documento deben llegar al mismo servidor. Las solicitudes del editor del navegador al servidor incluyen automáticamente una clave de fragmentación, y las aplicaciones deben agregarla ?shardkey=<document-key>a las solicitudes de comandos, conversión y del Generador de documentos donde esté documentado.
HAProxy admite el uso de hash en un parámetro de consulta de URL, por lo que un backend adecuado para la API estándar de ONLYOFFICE Docs es:
backend onlyoffice_docs
mode http
option forwardfor
option httpchk GET /healthcheck
http-check expect status 200
timeout tunnel 1h
balance url_param shardkey
server ds1 10.0.10.21:80 check
server ds2 10.0.10.22:80 check
shardkeyel enrutamiento basado en para la API estándar de Docs en lugar del simple round-robin.El algoritmo de HAProxy url_paramaplica un hash al parámetro de la cadena de consulta seleccionado. Si dicho parámetro no está presente, HAProxy recurre al comportamiento habitual de balanceo de carga. Por ello, es fundamental que su integración envíe la clave de fragmentación en las solicitudes donde ONLYOFFICE lo recomienda.
WOPI es diferente. ONLYOFFICE indica que las integraciones de WOPI utilizan el WOPISrcparámetro de consulta para el mismo propósito de enrutamiento. No copie la balance url_param shardkeylínea sin modificar en un diseño de WOPI y asuma que proporciona la afinidad requerida.
Antes de recargar el servicio, valide la configuración:
sudo haproxy -c -f /etc/haproxy/haproxy.cfgRecargue la aplicación solo después de que la validación de sintaxis sea exitosa:
sudo systemctl reload haproxy
sudo systemctl status haproxySi su distribución utiliza un gestor de servicios o una ruta de configuración diferente, adapte los comandos en consecuencia. Es preferible recargar la configuración a reiniciarla forzosamente si su paquete HAProxy admite recargas de configuración controladas.
Ahora, comprueba qué es lo que realmente alcanzarán los usuarios y tu plataforma de gestión documental:
curl -sS https://docs.example.com/healthcheckEl cuerpo esperado es:
trueA continuación, verifique el certificado TLS:
openssl s_client -connect docs.example.com:443 -servername docs.example.com </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -datesFinalmente, abra un documento real a través de la aplicación de integración. Una comprobación de estado solo demuestra que el punto final del servidor de documentos está listo; no demuestra que las URL de devolución de llamada, la configuración JWT, las descargas de documentos, las devoluciones de llamada para guardar o la afinidad entre varios nodos sean correctas.
| Síntoma | Capa probable a inspeccionar | Acción útil |
|---|---|---|
El público /healthcheckfracasa | Enrutamiento HAProxy, TLS o estado del backend | Pruebe cada backend directamente y, a continuación, inspeccione el estado y los registros de HAProxy. |
| El marco del editor se carga y luego se desconecta. | Ruta de WebSocket o tiempo de espera por inactividad | Verifique timeout tunnelsi existe algún firewall o proxy entre el navegador y HAProxy. |
| Las URL generadas utilizan HTTP en lugar de HTTPS. | Encabezados reenviados | Verificar X-Forwarded-Proto: httpsy X-Forwarded-Host. |
| La edición de múltiples nodos se comporta de forma inconsistente. | Afinidad de documentos | Confirme shardkeyque está presente y que HAProxy lo cifra de forma consistente. |
| La comprobación de estado funciona, pero el guardado falla. | Ruta de devolución de llamada/red de integración | Verifique que Document Server pueda acceder a la función de devolución de llamada de la aplicación de almacenamiento y a las URL de los documentos. |
| Algunos nodos abandonan la rotación repetidamente. | Verificación de dependencia o estado del backend | Realice una consulta /healthcheckdirectamente en el nodo afectado e inspeccione los registros de su servidor de documentos. |
La persistencia de IP de origen tradicional no es la mejor solución predeterminada para ONLYOFFICE. Varios usuarios que editan el mismo archivo pueden tener direcciones IP de cliente diferentes, y un mismo usuario puede abrir distintos documentos que no necesariamente residen en el mismo nodo. La afinidad basada en el documento y en la clave de fragmentación de ONLYOFFICE es más precisa, ya que la clave de enrutamiento representa el documento que se está editando, en lugar de la dirección de red del usuario.
La misma distinción explica por qué una sesión persistente basada en cookies no debe considerarse un sustituto del comportamiento de enrutamiento documentado por ONLYOFFICE. Utilice la clave de fragmentación documentada de la aplicación al crear una implementación de la API Docs en varios nodos.
truedesde /healthcheckantes de ser agregado a HAProxy.X-Forwarded-Protoy X-Forwarded-Hostse envían correctamente.shardkeyafinidad basada en , no solo round robin simple.WOPISrc.Para un servidor de documentos, HAProxy funciona principalmente como un proxy inverso limpio y una capa TLS. Para varios nodos de servidor de documentos, la diferencia crucial radica en el enrutamiento con reconocimiento de documentos. Primero, configure el proxy en función de este requisito y, a continuación, añada comprobaciones de estado, HTTPS y ajustes de tiempo de espera.
Solucione los problemas de copiar y pegar de Collabora Online con aplicaciones locales probando los atajos de teclado, los permisos del portapapeles del navegador, HTTPS, las políticas de iframe y los formatos de contenido.
Solucione el problema del texto borroso en los editores de escritorio de ONLYOFFICE en Linux comprobando el escalado de la pantalla, el escalado de la interfaz de la aplicación, la disponibilidad de la fuente y el ámbito de representación en un orden seguro.
Aprenda cómo bloquear la impresión y las descargas en las integraciones de ONLYOFFICE Workspace, DocSpace o Docs, y verifique qué controles se aplican a cada método de uso compartido.
Solucione los errores 502 del servidor de documentos ONLYOFFICE detrás de Nginx. Verifique el estado del servicio, los registros, los puertos ascendentes, los encabezados reenviados, los WebSockets y la red de Docker.
Solucione los problemas de tiempo de espera de ONLYOFFICE Documents en un servidor autohospedado comprobando la URL correcta del portal o WebDAV, el acceso a la red, HTTPS, las credenciales y el enrutamiento del servidor.
Establezca una plantilla personalizada de LibreOffice Writer como predeterminada, actualícela o restablézcala y verifique que los nuevos documentos utilicen sus estilos y diseño de página preferidos.
Solucione los problemas de exportación de PDF de ONLYOFFICE separando los problemas de conversión, descarga del navegador y servidor, y luego verifique que el PDF guardado se abra y conserve su diseño.
Elimine ONLYOFFICE Document Server de Linux de forma segura. Siga los pasos para la instalación del paquete, Docker, Snap y Kubernetes, conserve los datos y verifique los servicios restantes.
Configure la sincronización con LDAP o Active Directory en ONLYOFFICE Workspace con ajustes de conexión segura, filtros de usuarios y grupos, asignación de atributos, derechos de administrador, sincronización programada y comprobaciones de verificación prácticas.
Instale ONLYOFFICE Document Server detrás de HAProxy con terminación TLS, encabezados reenviados, comprobaciones de estado, tiempos de espera seguros para WebSocket y enrutamiento con reconocimiento de documentos para implementaciones de varios nodos.
