Rastrea los fallos de conexión de Collabora con los registros de coolwsd.

Para un contenedor de Collabora Online Development Edition (CODE), aumente coolwsdel nivel de registro a debug, asegúrese de que las áreas Sockety no estén deshabilitadas, luego reproduzca un error al abrir un documento mientras sigue los registros del contenedor. En Docker Compose, pase la configuración a través de la variable de entorno de la imagen CODE y vuelva a crear el servicio. Use solo si la salida de depuración no muestra dónde se detiene la conexión, y regrese al nivel anterior cuando termine.WebSocketextra_paramstrace

Este método es adecuado para implementaciones con Docker o Compose, donde se puede actualizar la configuración del contenedor. Una instalación de paquete nativa utiliza /etc/coolwsd/coolwsd.xmlsu administrador de servicios. La configuración agrega detalles de diagnóstico; no repara por sí sola un problema de proxy, host WOPI, certificado o red.

1. Comience con una reproducción controlada.

Seleccione un documento y anote la hora en que intenta abrirlo, la URL pública de Collabora y el nombre del contenedor o del servicio Compose. Evite actualizar varios archivos repetidamente: un solo intento facilita la identificación del problema en el navegador, el registro del proxy, el registro del servidor de integración y las entradas de coolwsd.

Comprueba que el contenedor esté en funcionamiento e identifica su nombre:

docker ps --format 'table {.Names}	{.Status}	{.Ports}'

Reemplace collaboralo siguiente con el nombre del contenedor que se muestra en su host. Comience a seguir la salida poco antes de reproducir el problema:

docker logs --since 2m --follow --timestamps collabora

--followtransmite nueva salida, --sincelimita el historial inicial y --timestampsagrega marcas de tiempo de Docker. Docker documenta esas opciones en su referencia de registros de contenedores . En Compose, puede usar docker compose logs --since=2m --follow collabora, donde collaboraes la clave del servicio.

2. Elevar coolwsd al nivel de depuración para la prueba.

El esquema de configuración de Collabora admite niveles con nombre, incluidos warning, notice, information, debug, y trace. También define disabled_areas; el valor predeterminado documentado desactiva la salida de alta verbosidad de Sockety WebSocket, entre otras áreas. Esto es importante para la resolución de problemas de conexión: cambiar el nivel por sí solo puede dejar los detalles de handshake más útiles suprimidos. Estas opciones están documentadas en la plantilla de configuración coolwsd de Collabora y en el manual del SDK de Collabora Online (sección de configuración de Docker; revisado en octubre de 2026).

Para la collabora/codeimagen oficial, agregue las dos opciones al extra_paramsvalor existente del servicio. Conserve cualquier opción que ya requiera su instalación, como la terminación SSL o el nombre del servidor:

services:
  collabora:
    environment:
      extra_params: "--o:logging.level=debug --o:logging.disabled_areas=Admin,Pixel"

La segunda opción deja Sockety WebSocketdisponible para el registro detallado mientras mantiene Adminy Pixeldeshabilitados. No vuelva a agregar esas dos áreas a la lista de deshabilitados durante esta prueba. La documentación de la imagen CODE describe extra_paramscomo una forma de pasar opciones de línea de comandos a coolwsd. Si su implementación utiliza un archivo de configuración montado o una imagen administrada por el proveedor, siga el método de configuración de esa implementación.

Aplique la edición de Compose recreando el servicio:

docker compose up -d --force-recreate collabora

Utilice el nombre real de su servicio Compose. Para un contenedor de corta duración iniciado con docker run, actualice su configuración de ejecución y recréelo con los mismos volúmenes, redes, puertos y otras opciones. El manual de CODE indica que la imagen acepta extra_paramsal inicio; no asuma que cambiar el entorno de un contenedor ya creado modifica el proceso coolwsd en ejecución.

3. Lea la conexión en orden

Reproduzca el fallo una vez y revise únicamente ese intervalo. Busque en la salida términos como WebSocket, WOPI, ERR, y WRN, y luego compare las marcas de tiempo. La redacción exacta y las áreas de registro varían según la versión de Collabora, así que considérelas como categorías para inspeccionar en lugar de mensajes literales garantizados.

• No se encontraron nuevas entradas de coolwsd durante la prueba: es posible que la solicitud no esté llegando a este contenedor. Verifique la URL pública configurada, el DNS, el balanceador de carga, los registros de acceso/error del proxy inverso y si está monitorizando la réplica correcta.
• El navegador accede al servicio, pero el WebSocket no permanece abierto: inspeccione la gestión del proxy para la actualización del WebSocket, el host y el esquema reenviados, la terminación TLS, el enrutamiento de rutas y los tiempos de espera por inactividad. Compare con la consola del desarrollador del navegador y los registros del proxy; coolwsd no puede explicar una solicitud que el proxy nunca reenvía.
• Aparece una solicitud WOPI que falla: compruebe la URL WOPI del servidor de integración, la lista de permisos del host o la configuración del alias, la accesibilidad desde el contenedor de Collabora y la respuesta del servidor de integración. Un error WOPI es una etapa independiente de la conexión WebSocket entre el navegador y Collabora.
• WOPI funciona correctamente, pero el navegador sigue desconectándose: a continuación, nos centraremos en la ruta WebSocket y los errores de conexión del navegador. Esta secuencia reduce las posibilidades de búsqueda, pero no demuestra qué configuración de proxy o de red es incorrecta.

Si Docker no muestra ninguna salida aunque el servicio esté activo, compruebe la configuración de registro dentro del contenedor. El comando `log` de Docker lee la salida estándar y los flujos de error del contenedor; una instalación configurada para escribir en un archivo puede usar una ruta como `// /var/log/coolwsd.logarchivo/ruta/archivo

docker exec collabora sh -c 'grep -n -A25 "<logging>" /etc/coolwsd/coolwsd.xml'

Si el registro de archivos está habilitado, utilice la ruta configurada, por ejemplo:

docker exec collabora sh -c 'tail -n 200 /var/log/coolwsd.log'

4. Verifique el resultado y restablezca el registro normal.

Después de la prueba, ejecute una lectura limitada para confirmar que el intento previsto produjo nuevas entradas:

docker logs --since 5m --timestamps collabora

Obtendrá un resultado útil si puede alinear el error de apertura con un evento coolwsd o establecer que la solicitud nunca llegó a este contenedor, y luego identificar qué etapa de la conexión requiere seguimiento. Si necesita filtrar la salida, utilice primero una ventana de tiempo corta:

docker logs --since 5m collabora | grep -Ei 'coolwsd|WOPI|WebSocket|ERR|WRN'

Restaure los valores anteriores logging.levely disabled_areasvuelva a crear el servicio. Los niveles de depuración y rastreo pueden generar mucha más información, incluyendo detalles operativos confidenciales. Antes de compartir los registros, oculte los tokens de acceso, los nombres de los documentos, los identificadores de usuario, los nombres de host y las direcciones internas. Si el servicio no es la imagen oficial de CODE, confirme su ruta de configuración y los parámetros compatibles con el responsable de dicha imagen.