Cómo depurar los registros de conexión en línea de Collabora con el nivel de registro coolwsd

La plantilla de configuración pública actual de Collabora Online aún expone logging.levelen coolwsd.xml, con valores admitidos que van desde warninghasta debugy trace. Para un fallo de conexión, aumente brevemente el nivel, reproduzca una conexión fallida, inspeccione el destino real del registro del servicio y restaure el nivel normal cuando termine. El valor que se muestra en el XML no siempre es el valor efectivo: un comando de inicio o una configuración del contenedor pueden anularlo, y las áreas de alta verbosidad, como el registro de WebSocket, pueden deshabilitarse por separado.

Esta guía se centra en el diagnóstico de fallos de conexión entre el navegador y Collabora o al abrir documentos. Utiliza la coolwsd.xml.inplantilla de código fuente pública actual y material oficial de Collabora revisado el 6 de octubre de 2026. Los valores predeterminados de los paquetes y los nombres de los servicios pueden variar según la versión y la implementación, por lo que le recomendamos que confirme la instancia en ejecución antes de copiar rutas o ejecutar comandos de reinicio.

¿Qué cambios se producen en el nivel de registro de coolwsd?

coolwsdes el demonio WebSocket de Collabora Online, el proceso del servidor que gestiona las sesiones del navegador y la actividad de los documentos. Su nivel de registro determina la cantidad de detalles que emite el proceso. La plantilla de origen actual enumera niveles con nombre, incluidos fatal, critical, error, warning, notice, information, debug, y trace, así como niveles numéricos del 0 al 8. Los valores numéricos van de menos a más detallados. Para una primera pasada de diagnóstico, debuges un paso adelante razonable; utilice tracesolo cuando necesite detalles de conexión más precisos.

La level_startupconfiguración independiente controla el registro durante el inicio inicial; luego, el registro vuelve al nivel de level. La plantilla actual establece el registro de inicio en trace; esto no significa que el funcionamiento normal permanezca en el nivel de rastreo. Evite realizar cambios level_startupcuando el problema se produzca después de que el servicio ya esté en funcionamiento.

Una salida más detallada puede aumentar el volumen de registros e incluir URL, direcciones, identificadores de sesión u otros detalles operativos. Trate los registros como información confidencial; recopile solo el período de tiempo necesario y oculte la información secreta antes de compartirla.

Paso 1: Identificar cómo se ejecuta esta instancia de Collabora

Primero, determine si Collabora Online se ejecuta como un servicio del sistema, en Docker o Podman, o en Kubernetes. Esto es importante porque los cambios realizados en un archivo dentro de un contenedor en ejecución podrían no persistir, y los registros del contenedor podrían enviarse a la salida estándar en lugar de a un archivo.

• Paquete del sistema: compruebe el servicio en ejecución y su nombre de unidad, normalmente coolwsd. La configuración suele ser /etc/coolwsd/coolwsd.xml. Las versiones anteriores pueden usar una loolwsdruta heredada.
• Docker o Podman: identifique el nombre del contenedor y cómo se proporciona su configuración. Un archivo montado mediante enlace o una variable de despliegue suele ser la fuente persistente de la configuración.
• Kubernetes: inspeccione los valores de Helm, ConfigMap o el manifiesto de despliegue que proporciona coolwsd.xml. Editar un pod directamente es temporal.

Antes de editar, haga una copia de seguridad del archivo de configuración o guarde una copia de los valores de implementación. Si no está seguro de qué archivo lee el proceso en ejecución, revise primero su definición de servicio o comando de inicio. Una causa común de un aparente error es editar un archivo de ejemplo en lugar de la configuración activa.

Paso 2: Aumentar temporalmente el nivel de actividad

En el activo coolwsd.xml, localice la <logging>sección y cambie solo el valor dentro de <level>. Comience con debug. Si el intento de conexión aún no produce suficiente detalle, use brevemente tracepara una reproducción. Mantenga sin cambios la configuración existente de level_startup, la configuración de archivos y la configuración no relacionada.

<config>
  <logging>
    <level>trace</level>
    <level_startup>trace</level_startup>
  </logging>
</config>

Este es un ejemplo abreviado de la estructura XML relevante, no un reemplazo del archivo de configuración completo. Para implementaciones en contenedores, configure la opción mediante el mecanismo persistente compatible con esa imagen o gráfico. El código fuente oficial de Collabora incluye anulaciones de configuración de línea de comandos, por lo que si el valor parece ignorarse, revise los argumentos de inicio o los parámetros de implementación para encontrar un segundo logging.levelvalor.

Si los registros se guardan en un archivo, la plantilla de origen actual documenta la ruta del archivo en logging.file, generalmente /var/log/coolwsd.log. Sin embargo, el registro en archivo puede estar deshabilitado en una compilación de producción. Si habilita la salida de archivo o utiliza una ruta personalizada, confirme que la coolcuenta de servicio tiene permisos de escritura y que systemd permite que el servicio escriba en esa ubicación. No haga que el registro sea legible para todos los usuarios para solucionar un problema de permisos.

Paso 3: Reinicie o vuelva a implementar, luego reproduzca el problema una vez.

La mayoría de las configuraciones empaquetadas surten efecto después de reiniciar el servicio. Reinicie durante una ventana de mantenimiento adecuada o una instancia de prueba, ya que las sesiones de edición activas pueden interrumpirse. Para un servicio systemd, un comando típico es:

sudo systemctl restart coolwsd
sudo systemctl status coolwsd --no-pager

Utilice el nombre de servicio real en su host. Para un contenedor, actualice la configuración persistente y reinicie o vuelva a implementar dicho contenedor. Para Kubernetes, aplique el manifiesto o el cambio de Helm mediante su proceso de lanzamiento habitual. Confirme que el proceso se inicia correctamente antes de reproducir el problema.

Registre la hora exacta, el usuario afectado o la cuenta de prueba, el paso de apertura del documento y el error visible en el navegador. Reproduzca el fallo una vez y, a continuación, deje de generar solicitudes. Un único intento con marca de tiempo es más fácil de correlacionar entre Collabora, el proxy inverso y el servidor de almacenamiento o WOPI que una larga secuencia de sesiones no relacionadas.

Paso 4: Lea el origen del registro de su implementación.

Para un servicio systemd, siga el registro mientras reproduce el problema:

sudo journalctl -u coolwsd -f

Para inspeccionar una ventana reciente delimitada, use sudo journalctl -u coolwsd --since "10 minutes ago". Si su unidad tiene otro nombre, sustitúyalo. Para Docker, use docker logs --since 10m --follow CONTAINER_NAMEy reemplace CONTAINER_NAMEcon el nombre o ID real del contenedor. Podman y Kubernetes tienen sus propios comandos de registro; consulte la documentación de tiempo de ejecución de la implementación en lugar de asumir que existe un archivo de host.

Si el registro de archivos está habilitado, inspeccione la ruta configurada, por ejemplo sudo tail -F /var/log/coolwsd.log. La ruta en su archivo puede ser diferente. La ausencia de un archivo no significa necesariamente que el servicio no haya generado registros; es posible que esté escribiendo en el registro de transacciones o en la salida del contenedor.

Paso 5: Correlacionar la secuencia de conexión

Comience con las entradas en la marca de tiempo registrada. Busque marcadores de advertencia y error y términos relacionados con la conexión, como WOPI, WebSocket, Socket, o la ruta de solicitud relevante. En un archivo, un primer filtro específico puede ser:

grep -Ei 'ERR|WRN|WOPI|WebSocket' /var/log/coolwsd.log

A continuación, siga la secuencia: ¿el navegador accedió a la URL pública?, ¿el proxy inverso reenvió la solicitud?, ¿se completó la actualización de WebSocket?, ¿Collabora se comunicó con el servidor del documento? Los registros de acceso y errores del proxy pueden responder preguntas que el registro de coolwsd no puede, como si la solicitud llegó al servicio. Si el navegador informa de un fallo en la conexión WebSocket, pero coolwsd no registra ninguna solicitud coincidente, investigue el DNS, la terminación TLS, las reglas del firewall y el enrutamiento del proxy inverso antes de modificar los permisos del documento.

La plantilla de configuración actual incluye Socket, WebSocket, Admin, y Pixelentre las opciones predeterminadas disabled_areaspara una salida de alta verbosidad. Si el registro de seguimiento está activo pero faltan detalles del socket, revise esta configuración. Para un diagnóstico rápido, elimine solo el área relevante Socketde WebSocketla lista deshabilitada separada por comas, manteniendo intactas las exclusiones no relacionadas. Reinicie o vuelva a implementar y repita la misma prueba controlada. Restaure la lista original después de recopilar la evidencia.

Paso 6: Restablecer el registro normal y proteger la evidencia.

Regrese <level>al valor de producción anterior, generalmente warningen la plantilla de código fuente pública, y restaure cualquier cambio disabled_areas. Reinicie o vuelva a implementar si su empaquetado lo requiere. Confirme que el servicio funciona correctamente y que los mensajes de depuración o seguimiento han cesado. Conserve únicamente el fragmento de diagnóstico con límite de tiempo en una ubicación restringida.

Antes de enviar un extracto del registro al soporte de Collabora o a un administrador, elimine los tokens de acceso, los encabezados de autorización, las URL firmadas, los nombres de usuario, los nombres de host privados y los nombres de los documentos, siempre que sea posible. Conserve las marcas de tiempo y el contexto de error no confidencial necesario para reproducir la secuencia.

Errores comunes de depuración

• Cambiar solo level_startup: esta configuración se aplica a la fase de inicio inicial y luego vuelve a level. Para un fallo después del inicio, cambie level.
• Suponiendo que tracetodas las categorías estén habilitadas: las áreas deshabilitadas pueden suprimir mensajes de socket o WebSocket con gran cantidad de detalles. Consulte la lista de filtros.
• Buscar en el lugar equivocado: el registro, la salida del contenedor y un archivo son destinos de registro diferentes. Determine cuál está activo antes de solucionar un problema con un archivo vacío.
• Mantener el registro de actividad habilitado: el registro de alto volumen puede crecer rápidamente y expone más detalles operativos. Restaure el valor anterior tan pronto como finalice la prueba.
• Modificar varios ajustes a la vez dificulta identificar cuál influyó en el resultado. Ajuste un valor, reproduzca un fallo y registre el resultado.

Fuentes

• Fuente de Collabora Online: opciones de registro de coolwsd.xml.in
• Fuente de Collabora Online: configuración predeterminada de registro de producción
• Manual del SDK en línea de Collabora, 24.04
• Valores de Helm de Collabora Online para la configuración de despliegue