Отслеживание сбоев подключения к Collabora с помощью журналов coolwsd

Для контейнера Collabora Online Development Edition (CODE) увеличьте coolwsdуровень логирования до debug, убедитесь, что области Socketи WebSocketне отключены, затем воспроизведите ошибку открытия документа, отслеживая логи контейнера. В Docker Compose передайте настройки через extra_paramsпеременную среды образа CODE и пересоздайте службу. Используйте traceтолько в том случае, если отладочный вывод не показывает, где прерывается соединение, и вернитесь к предыдущему уровню после завершения.

Этот метод подходит для развертывания в Docker или Compose, где можно обновлять конфигурацию контейнера. При установке нативного пакета используется /etc/coolwsd/coolwsd.xmlменеджер служб. Параметр добавляет диагностическую информацию; сам по себе он не устраняет проблемы с прокси-сервером, хостом WOPI, сертификатом или сетью.

1. Начните с одного контролируемого размножения.

Выберите один документ и запишите время попытки его открытия, общедоступный URL-адрес Collabora и имя контейнера или службы Compose. Избегайте многократного обновления нескольких файлов: одной попытки будет проще сопоставить симптомы браузера, журнал прокси, журнал интеграционного сервера и записи coolwsd.

Убедитесь, что контейнер запущен, и определите его имя:

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

Замените collaboraприведенное ниже имя на имя контейнера, отображаемое на вашем хосте. Незадолго до воспроизведения проблемы начните получать следующий вывод:

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

--followЭта опция позволяет передавать новые данные потоком, --sinceограничивать начальную историю и --timestampsдобавлять метки времени Docker. Docker описывает эти параметры в своем справочнике по журналам контейнеров . В Compose можно использовать docker compose logs --since=2m --follow collabora, где collabora— это ключ службы.

2. Для тестирования переведите coolwsd в режим отладки.

Схема конфигурации Collabora поддерживает именованные уровни, включая warning, notice, information, debug, и trace. Она также определяет disabled_areas; документированное значение по умолчанию отключает подробный вывод из Socketи WebSocket, среди прочих областей. Это важно для устранения неполадок с подключением: изменение только уровня может привести к тому, что наиболее полезные сведения о рукопожатии останутся скрытыми. Эти параметры описаны в шаблоне конфигурации Collabora coolwsd и руководстве по Collabora Online SDK (раздел конфигурации Docker; проверено в октябре 2026 г.).

Для официального collabora/codeобраза добавьте эти два параметра к существующему значению службы extra_params. Сохраните все параметры, уже необходимые для вашей установки, такие как завершение SSL-соединения или имя сервера:

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

Второй вариант оставляет доступными Socketобласти WebSocketдля подробного логирования, сохраняя при этом Adminобласти Pixelотключенными. Не добавляйте эти две области обратно в список отключенных во время этого теста. В документации к образу CODE описан extra_paramsспособ передачи параметров командной строки в coolwsd. Если в вашем развертывании используется смонтированный файл конфигурации или образ, управляемый поставщиком, используйте вместо этого метод конфигурации этого развертывания.

Примените изменения, внесенные при создании сервиса, путем его повторного создания:

docker compose up -d --force-recreate collabora

Используйте фактическое имя вашей службы Compose. Для кратковременного контейнера, запущенного с помощью команды `compose` docker run, обновите его конфигурацию запуска и создайте его заново с теми же томами, сетями, портами и другими параметрами. В руководстве CODE указано, что образ принимает `compose` extra_paramsпри запуске; не следует предполагать, что изменение среды уже созданного контейнера повлияет на работающий процесс coolwsd.

3. Прочитайте информацию о соединении по порядку.

Воспроизведите ошибку один раз и проанализируйте только этот интервал. Найдите в выводе такие термины, как WebSocket, WOPI, ERR, и WRN, затем сравните временные метки. Точная формулировка и области журнала различаются в зависимости от версии Collabora, поэтому рассматривайте их как категории для проверки, а не как гарантированные текстовые сообщения.

• На момент тестирования новых записей coolwsd не обнаружено: возможно, запрос не доходит до этого контейнера. Проверьте настроенный публичный URL-адрес, DNS, балансировщик нагрузки, журналы доступа/ошибок обратного прокси-сервера и убедитесь, что вы отслеживаете нужную реплику.
• Браузер подключается к сервису, но WebSocket не остается открытым: проверьте обработку прокси-сервером обновления WebSocket, переадресованный хост и схему, завершение TLS, маршрутизацию пути и тайм-ауты простоя. Сравните с консолью разработчика браузера и журналами прокси-сервера; coolwsd не может объяснить запрос, который прокси-сервер так и не переадресовал.
• Появляется WOPI-запрос, который завершается с ошибкой: проверьте WOPI-URL сервера интеграции, список разрешенных хостов или конфигурацию псевдонимов, доступность из контейнера Collabora и ответ сервера интеграции. Ошибка WOPI — это отдельный этап от соединения WebSocket между браузером и Collabora.
• WOPI работает, но браузер по-прежнему отключается: далее сосредоточьтесь на маршруте WebSocket и ошибках подключения на стороне браузера. Эта последовательность действий сужает область поиска; она не доказывает, какой именно прокси-сервер или сетевые настройки неверны.

Если Docker не выводит никакой информации, даже если служба активна, проверьте конфигурацию логирования внутри контейнера. Команда log в Docker считывает стандартный вывод и потоки ошибок контейнера; в установке, настроенной на запись в файл, вместо этого может использоваться путь, например /var/log/coolwsd.log, , определенный в конфигурации. Проверьте сам файл, а не предполагайте этот путь:

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

Если ведение журнала файлов включено, используйте указанный путь, например:

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

4. Проверьте результат и восстановите нормальный режим ведения журнала.

После проверки выполните ограниченное чтение, чтобы убедиться, что запланированная попытка привела к появлению новых записей:

docker logs --since 5m --timestamps collabora

Вы получите полезный результат, если сможете сопоставить неудачное открытие с событием coolwsd или установить, что запрос так и не достиг этого контейнера, а затем определить, на каком этапе подключения требуется дальнейшая обработка. Если вам нужно отфильтровать вывод, сначала используйте короткий временной интервал:

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

Восстановите предыдущие значения logging.level, disabled_areasа затем создайте службу заново. Уровни отладки и трассировки могут выдавать гораздо больше информации и включать конфиденциальные сведения об эксплуатации. Перед тем как делиться журналами, удалите токены доступа, имена документов, идентификаторы пользователей, имена хостов и внутренние адреса. Если служба не является официальным образом CODE, подтвердите путь к ее конфигурации и поддерживаемые параметры у разработчика этого образа.