Cómo configurar un clúster en línea de Collabora con varios nodos

Un clúster de Collabora Online no se limita a varios coolwsdservidores en buen estado conectados mediante un balanceador de carga round-robin. La edición colaborativa depende del envío de solicitudes del mismo documento al mismo nodo de Collabora. WOPISrcPor este motivo, el gráfico de Kubernetes de Collabora documenta el enrutamiento mediante el identificador de documento WOPI. Esta guía utiliza el gráfico Helm de Collabora en Kubernetes como configuración concreta de varios nodos e indica qué cambios son necesarios para un controlador de entrada diferente o una implementación que no sea en Kubernetes.

Verificado: El gráfico de Collabora admite múltiples réplicas y describe la afinidad por documento WOPISrc. Depende de la implementación: anotaciones de entrada, terminación TLS, solicitudes de recursos y si es apropiado un controlador de sesión. No es seguro asumir que cualquier balanceador de carga o cualquier configuración de "sesión persistente" preservará la afinidad de los documentos. Confirme el comportamiento específico del controlador y pruébelo antes de migrar usuarios al clúster.

Qué hace el clúster y qué no hace.

En una implementación estándar con múltiples réplicas, cada nodo de Collabora puede servir documentos, mientras que un proxy envía las solicitudes de cada documento a un único nodo. Esto distribuye los documentos de forma independiente entre los nodos del grupo. Sin embargo, esto no significa que todos los nodos compartan el mismo proceso de edición en tiempo real ni que un documento en ejecución pueda moverse sin problemas si su nodo se detiene.

Collabora también documenta un controlador COOL para Kubernetes que incorpora un enfoque diferente para la gestión de sesiones. Su enrutamiento y configuración difieren de los de un grupo de réplicas independiente. Este artículo configura el modelo de afinidad de origen WOPI más sencillo; no lo combine con la configuración de tokens de ruta específicos del controlador a menos que haya implementado y configurado el controlador para su versión.

Acción: decida si necesita un servicio básico replicado de Collabora para redundancia de capacidad y nodos, o una configuración administrada por el controlador con comportamiento sensible a la sesión. Esta última tiene componentes adicionales y configuración específica de la versión. Consulte la descripción general del controlador en línea de Collabora si está evaluando esta opción.

Antes de implementar

• Un clúster de Kubernetes en funcionamiento, Helm, DNS para un nombre de host público de Collabora y un servidor de entrada o proxy inverso compatible con TLS.
• Una integración WOPI, como Nextcloud, configurada para usar el nombre de host público único de Collabora en lugar de direcciones de pods individuales.
• El host o los hosts WOPI que Collabora tiene permitido aceptar, introducidos en la collabora.aliasgroupsconfiguración del gráfico.
• Suficiente CPU y memoria para la carga de trabajo de los documentos, además de una forma de inspeccionar el estado de los pods, los registros de entrada y el uso de recursos.
• Una ventana de mantenimiento para el lanzamiento inicial y un documento de prueba con dos cuentas de usuario independientes.

Un servicio dedicado de Collabora Online es diferente del servidor CODE integrado de Nextcloud. Nextcloud describe su opción integrada como orientada al uso personal o a equipos pequeños, y sin las funciones avanzadas de escalabilidad de un servidor dedicado. Acción: si necesita un grupo de Collabora con varios nodos, planifique el servicio dedicado y confirme el modelo de licencia y soporte adecuado para su implementación. Consulte la guía de instalación de Nextcloud Office .

Paso 1: Elija el modelo de enrutamiento

El modelo independiente documentado utiliza hashes WOPISrcque identifican el documento en las solicitudes WOPI. Las solicitudes de un mismo documento deben llegar al mismo pod; las solicitudes de documentos diferentes pueden distribuirse entre pods. Una regla de round-robin genérica no cumple con este requisito.

Acción: utilice una implementación de entrada compatible con la documentación del gráfico, como los ejemplos de entrada de NGINX o HAProxy documentados, o utilice el proxy inverso del gráfico en el espacio de nombres si el clúster no permite un controlador de entrada adecuado. Si utiliza otro proxy, verifique que pueda enrutar de forma consistente las solicitudes de la fuente WOPI tanto para las solicitudes HTTP ordinarias como para las conexiones WebSocket de larga duración.

Paso 2: Inspeccione el gráfico y seleccione una versión.

El gráfico y sus valores cambian con el tiempo. Antes de instalarlo, consulte el archivo README y los valores oficiales del gráfico actual, en lugar de copiar una configuración de una versión anterior. Los ejemplos que se muestran a continuación siguen la documentación actualizada del gráfico de Collabora, revisada el 6 de octubre de 2026; considere las notas de la versión y los valores actuales del repositorio como la referencia principal para la fecha de instalación.

helm repo add collabora https://collaboraonline.github.io/online/
helm repo update
helm search repo collabora/collabora-online --versions
helm show values collabora/collabora-online

Acción: seleccione una versión del gráfico que se ajuste a su política de control de cambios y registre la versión de la imagen de Collabora que implementa. Fije la versión del gráfico para actualizaciones repetibles; evite depender de una versión flotante no revisada en producción. La guía de configuración del gráfico se encuentra en el archivo README de Collabora Online para Kubernetes .

Paso 3: Preparar los valores para tres réplicas

Este ejemplo asume el controlador de entrada NGINX, terminación TLS en la entrada y un host WOPI externo en cloud.example.com. Reemplace ambos nombres de host con los suyos. Si la terminación TLS se realiza en otro lugar o utiliza HAProxy, utilice la configuración documentada correspondiente de ese controlador.

replicaCount: 3

autoscaling:
  enabled: false

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/upstream-hash-by: "$arg_WOPISrc"
    nginx.ingress.kubernetes.io/proxy-body-size: "0"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
  hosts:
    - host: office.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific

collabora:
  aliasgroups:
    - host: "https://cloud.example.com:443"
  extra_params: --o:ssl.enable=false --o:ssl.termination=true

La anotación hash y los valores de tiempo de espera se muestran en el ejemplo de NGINX del gráfico. Esta extra_paramslínea solo es apropiada cuando el proxy inverso finaliza TLS y se conecta a Collabora mediante HTTP. No la aplique sin cambios si su topología TLS es diferente. Configure el secreto TLS de entrada y el host según su administrador de certificados y los valores del gráfico local; el extracto omite la configuración específica del proveedor.

Acción: guarde esto como my_values.yaml, agregue la configuración TLS requerida por su entrada y compare cada clave con la de la versión del gráfico seleccionada values.yaml. Mantenga el nombre de host público de Collabora consistente en DNS, TLS, la URL de Collabora de la integración y el enrutamiento del proxy.

Paso 4: Instalar la versión de Collabora

Instálelo en un espacio de nombres dedicado. Reemplace <chart-version>con la versión seleccionada en el paso 2; los corchetes angulares aquí son marcadores de posición explicativos y no deben escribirse literalmente.

helm install --create-namespace   --namespace collabora   collabora-online collabora/collabora-online   --version <chart-version>   -f my_values.yaml

Para una versión existente, utilice una actualización planificada de Helm tras revisar las notas de migración y los cambios realizados en dicha versión. Evite implementar una actualización importante de imagen o gráfico al mismo tiempo que su primer cambio de escalado; modificar una variable a la vez facilita el aislamiento de fallos.

Acción: inspeccionar la liberación y esperar a que todas las réplicas estén listas:

helm status collabora-online -n collabora
kubectl get pods,svc,ingress -n collabora
kubectl get events -n collabora --sort-by=.lastTimestamp

La existencia de tres réplicas deseadas no garantiza que tres nodos en buen estado estén gestionando el tráfico. Verifique la disponibilidad, los reinicios recientes, la programación y los puntos de acceso. Si quedan pods pendientes, inspeccione la capacidad disponible del clúster y las solicitudes y límites de recursos en los valores del gráfico.

Paso 5: Conecte la aplicación WOPI

En la configuración de integración de Office de la plataforma de archivos, establezca la URL del servidor Collabora al punto final público, por ejemplo https://office.example.com, . No dirija la aplicación a una IP de pod ni a un nombre de servicio exclusivo de Kubernetes, a menos que la integración se ejecute dentro del clúster y que el enrutamiento privado sea compatible explícitamente con su diseño.

El nombre de host aliasgroupsdebe identificar al host WOPI que almacena y sirve los documentos; no es el nombre de host de Collabora. Una discrepancia puede provocar fallos en la validación del host WOPI, incluso cuando los pods y el ingress de Collabora funcionan correctamente.

Acción: introduzca la misma URL pública de Collabora en la configuración de la integración, guárdela y verifique que la comprobación de conectividad o detección se realice correctamente. Si falla, revise la lista de permisos WOPI de la aplicación, los grupos de alias de Collabora, el DNS, el TLS y los encabezados de proxy antes de modificar el número de réplicas.

Paso 6: Probar la afinidad y la colaboración de los documentos.

Abra un documento de prueba e inspeccione los registros de entrada o proxy para confirmar qué servidor lo sirve. Luego, abra el mismo documento desde una segunda sesión de usuario y verifique que ambos usuarios puedan editar y ver los cambios del otro. Abra un documento diferente y confirme que el balanceador de carga pueda enviarlo a otro pod en buen estado. La prueba se centra en el enrutamiento y la colaboración, no solo en si la página de destino devuelve un código HTTP 200.

Acción: verifique que el hash de origen WOPI esté presente y se aplique de forma consistente a las solicitudes generadas para el mismo documento, incluida la actualización de WebSocket. Si los usuarios no ven las ediciones de los demás, compare la selección del servidor para el mismo documento antes de investigar el host WOPI o la caché del navegador.

Paso 7: Prueba del manejo del estado y la pérdida de nodos.

Las comprobaciones de disponibilidad deben mantener fuera de servicio un pod en mal estado o en fase de inicio. El gráfico incluye configuraciones de inicio, disponibilidad y sondeo de actividad, pero el comportamiento y la sincronización exactos dependen de la versión del gráfico y del clúster seleccionados. Si un pod deja de estar disponible, puede interrumpir los documentos que se estén ejecutando en él; un grupo de afinidad básico no debe describirse como una replicación de sesión en vivo.

Acción: en un entorno de prueba, retire un pod del servicio durante una sesión de edición activa, observe el comportamiento del cliente y el enrutamiento del proxy, luego vuelva a abrir el documento y confirme que llega a un pod en buen estado. No realice esta prueba en documentos de producción activos sin un plan de mantenimiento aprobado. Para una continuidad de sesión más estricta, evalúe el controlador COOL y su configuración de token de ruta específica de la versión.

Paso 8: Monitorear, ajustar y actualizar de forma deliberada.

Realiza un seguimiento de los reinicios de pods, el uso de CPU y memoria, los errores de solicitudes y WebSocket, la latencia de entrada y los informes de los usuarios sobre la carga o reconexión de documentos. La documentación de gráficos de Collabora incluye directrices para la monitorización de Kubernetes. Configura los recursos a partir de la carga de trabajo observada en lugar de copiar ejemplos numéricos: el tamaño del documento, las sesiones concurrentes, las fuentes y los patrones de edición afectan a la capacidad.

Collabora recomienda ejecutar la misma versión en todos los nodos con balanceo de carga para que los clientes reciban recursos web consistentes y específicos de la versión. Durante las actualizaciones, utilice la estrategia de implementación compatible con el gráfico, supervise la disponibilidad y los registros, y pruebe un documento abierto por varios usuarios antes de declarar que el cambio se ha completado.

Acción: mantenga la versión del gráfico, la versión de la imagen, el archivo de valores y los resultados de las pruebas juntos en su registro de cambios. Programe las actualizaciones, confirme que todas las réplicas convergen en la versión prevista y conserve un plan de reversión compatible con el comportamiento de reversión admitido por el gráfico.

Conceptos erróneos comunes que conviene revisar

• “Tres réplicas crean automáticamente un clúster funcional”. Las réplicas por sí solas no configuran la afinidad de documentos. Confirme que los hashes de entrada se encuentran en la fuente WOPI o que su controlador proporciona el enrutamiento de sesión previsto.
• «Las sesiones persistentes basadas en la IP del usuario son suficientes». Esta no es la regla que describe el gráfico de Collabora para su grupo de Kubernetes independiente. Los usuarios que colaboran en un documento deben conectarse al mismo nodo, incluso si acceden desde diferentes dispositivos o redes. Configure la afinidad basada en documentos y realice una prueba con dos usuarios.
• «Una página de inicio en buen estado demuestra que el clúster está listo». Esto solo demuestra que una solicitud HTTP se ha completado correctamente. Prueba la apertura y edición colaborativa de un documento, las actualizaciones de WebSocket y el comportamiento cuando un pod deja de estar disponible.
• Agregar un nodo garantiza que las sesiones activas sobrevivan a la pérdida del nodo. Un grupo básico de afinidad de origen WOPI enruta un documento a un nodo; esto no garantiza que su proceso de edición en memoria se replique. Confirme el comportamiento de recuperación esperado en una prueba controlada o evalúe las funciones de administración de sesiones independientes del controlador.

Para instalaciones que no utilizan Kubernetes, el principio arquitectónico es el mismo, pero no se aplican los comandos de gráficos de Kubernetes ni las anotaciones de entrada. Utilice la configuración de proxy correspondiente a su versión de Collabora y balanceador de carga, asegúrese de que se admitan las conexiones WebSocket de larga duración e implemente el enrutamiento por documento mediante la fuente WOPI. El manual del SDK de Collabora Online describe el balanceo de carga y el WOPISrcrequisito de afinidad; consulte la sección equivalente en el manual para la versión que utiliza.