Исправлена ​​ошибка подключения Collabora Online «Ну, это неловко».

Сообщение Collabora Online «Что ж, это неприятно, мы не можем подключиться к вашему документу» — это симптом, а не диагноз. Оно появляется после загрузки оболочки редактора, но сеанс работы с документом не может завершиться. В современных системах самый быстрый способ исправить это — определить, какое именно соединение в пути WOPI не работает, вместо того чтобы менять случайные настройки Collabora.

В данном руководстве в качестве ориентиров используются текущая документация по администрированию Nextcloud 35 и рекомендации по SDK Collabora Online 25.04. Та же логика устранения неполадок применима ко многим интеграциям ownCloud и пользовательским интеграциям WOPI, но точные названия параметров могут различаться в зависимости от платформы и версии.

Что обычно вызывает эту ошибку подключения к Collabora?

Для корректной работы браузерной сессии необходимо несколько отдельных путей. Браузер пользователя должен иметь доступ как к серверу хранения, так и к Collabora; сервер хранения должен иметь доступ к Collabora; Collabora должна иметь доступ к серверу хранения; протоколы и сертификаты должны быть совместимы; и обратный прокси-сервер должен корректно перенаправлять HTTP- и WebSocket-маршруты Collabora. На официальной странице устранения неполадок Nextcloud эти требования к двусторонней доступности явно перечислены.

Это означает, что не существует единого универсально правильного решения. Выбирайте путь восстановления, исходя из первого неудачного теста:

1. Проверьте конечные точки обнаружения и возможностей Collabora.

Начните с общедоступного URL-адреса Collabora, который фактически используется вашей интеграцией. Откройте эти конечные точки в браузере и на сервере хранения:

https://office.example.com/hosting/discovery
https://office.example.com/hosting/capabilities

В текущей документации Nextcloud по устранению неполадок рекомендуется использовать оба теста. Конечная точка обнаружения должна возвращать XML, а параметры возможностей — данные о возможностях Collabora. Тайм-аут, предупреждение о сертификате, ошибка 404, страница ошибки, отображаемая прокси-сервером, или зацикливание перенаправления означают, что перед изменением настроек WOPI следует исправить сеть или обратный прокси-сервер.

Сначала проверьте общедоступные URL-адреса обнаружения и возможностей Collabora; оба должны быть доступны по одному и тому же имени хоста, используемому для интеграции.

Для получения исчерпывающих рекомендаций по настройке конечных точек см. раздел « Устранение неполадок Nextcloud Office» и руководство по SDK Collabora Online 25.04 .

2. Проверьте все четыре направления сети, а не только браузер.

Распространенная ошибка — предположение, что раз office.example.comCollabora открывается в браузере на компьютере, то она также может получать файлы с сервера хранения. Это не гарантировано. Проверьте работу на реальных хостах или в контейнерах:

# From the Nextcloud/storage server
curl -fsS https://office.example.com/hosting/discovery >/dev/null && echo OK

# From the Collabora host/container
curl -fsS https://cloud.example.com/status.php

# Then inspect Collabora logs
docker logs --tail 100 collabora

Если публичное имя хоста разрешается по-разному внутри Docker, Kubernetes или частной сети, решите, следует ли исправить внутреннюю DNS-запись, добавить соответствующее сопоставление хостов или перенаправить трафик через публичную конечную точку. Внутренняя DNS-запись обычно удобнее в масштабе; запись в файле hosts быстро работает для небольшой статической установки, но становится сложнее в обслуживании.

Проведите тесты доступности непосредственно на серверах, а затем используйте журнал Collabora, чтобы отличить сбой сети от сбоя доверия WOPI.

3. Исправьте работу обратного прокси, если отсутствуют маршруты WebSockets или Collabora.

Collabora — это не обычное статическое веб-приложение. Его обратный прокси-сервер нуждается в маршрутах для ресурсов браузера, обнаружения/возможностей, трафика документов и WebSocket. В руководстве по SDK Collabora пример с Nginx перенаправляет /browser, /hosting/discovery, /hosting/capabilities, /cool/.../wsпуть WebSocket и связанный с /coolним /loolтрафик.

Для маршрута WebSocket прокси-сервер должен сохранять хост и передавать HTTP-запрос на обновление. Упрощенная схема Nginx выглядит следующим образом:

location ~ ^/cool/(.*)/ws$ {
    proxy_pass http://127.0.0.1:9980;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 36000s;
}

Не копируйте это вслепую, если вы используете другой способ завершения TLS. Collabora описывает отдельные шаблоны для завершения TLS и SSL на всем протяжении соединения. Если TLS завершается на Nginx, а соединение с бэкэндом осуществляется по протоколу HTTP, внутренние настройки SSL в Collabora должны соответствовать этой схеме. Использование HTTPS повсюду проще с точки зрения логики, в то время как завершение TLS на прокси-сервере уменьшает обработку сертификатов внутри контейнеров, но вводит еще одно ограничение конфигурации.

Правильно настроенный обратный прокси-сервер должен перенаправлять HTTP-маршруты Collabora и сохранять обновление WebSocket для сеанса работы с документом.

4. Проверьте согласованность протокола, сертификата и имени хоста.

В текущей документации Nextcloud по настройке Office указано, что сервер Collabora Online должен использовать тот же протокол, что и установка Nextcloud, при этом рекомендуется использовать HTTPS. На практике смешанные общедоступные конфигурации HTTP/HTTPS могут привести к блокировке контента, неправильным целям перенаправления или ошибкам проверки сертификатов на стороне сервера.

Проверьте эти пункты одновременно:

• Сохраненный в вашей платформе хранения URL-адрес Collabora — это точный общедоступный URL-адрес, к которому имеют доступ пользователи.
• Предоставленный сертификат, связанный с этим именем хоста, действителен для данного имени хоста и пользуется доверием сервера хранения.
• Collabora может проверить HTTPS-сертификат сервера хранения данных.
• Ваш обратный прокси-сервер корректно перенаправляет запросы на исходный хост и по исходной схеме.
• Перенаправление с настроенного имени хоста Collabora на другое имя хоста, которое не ожидается WOPI, отсутствует.

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

5. Исправляйте списки разрешенных сайтов WOPI вместо их отключения.

Если обнаружение работает, а в журналах Collabora отображаются сообщения типа « Unauthorized WOPI hostнет подходящего хоста WOPI, соответствующего целевому объекту», проблема переместилась с базового подключения на конфигурацию доверия. В официальной документации Nextcloud по устранению неполадок администраторам специально рекомендуется обращаться к журналам контейнера в этом случае.

Что касается хранилища, Nextcloud рекомендует ограничивать запросы WOPI IP-адресами серверов Collabora, используя параметр «Разрешить список запросов WOPI» . На стороне Collabora разрешенные хосты хранилища WOPI должны совпадать с URL-адресами хранилища, которые фактически получает Collabora. Для нескольких доменов хранилища в текущем SDK Collabora описаны группы псевдонимов WOPI.

Следите за тем, чтобы URL-адрес сервера Collabora и список разрешенных серверов WOPI соответствовали реальной конфигурации развертывания; используйте узкоспециализированные доверенные записи вместо отключения проверки.

См. раздел «Конфигурация Nextcloud Office» для получения информации о текущем URL-адресе сервера и списке разрешенных WOPI. Если вы используете ownCloud Infinite Scale, служба совместной работы использует COLLABORATION_APP_ADDRURL-адрес офисного приложения и COLLABORATION_WOPI_SRCвнешний источник WOPI; см. документацию по службе совместной работы ownCloud .

В каких случаях следует использовать встроенный код вместо отдельного сервера Collabora?

Для небольшой установки Nextcloud встроенный сервер CODE уменьшает количество компонентов, управляемых извне. Компромисс заключается в том, что он по-прежнему зависит от возможности доступа экземпляра Nextcloud к самому себе через имя хоста, используемое в браузере. В документации Nextcloud по устранению неполадок это прямо указано, и предлагается корректно разрешать это имя хоста, если встроенный CODE не может подключиться.

Отдельный сервер Collabora обычно лучше подходит, когда требуется независимое масштабирование, централизованное обслуживание нескольких экземпляров хранилища или производственная архитектура с более четкими границами ресурсов. Он добавляет конфигурацию DNS, прокси, сертификатов, брандмауэра и доверия WOPI, поэтому операционная нагрузка возрастает.

Чего не следует делать

• Не следует отключать проверку WOPI в качестве первого решения. Она может скрыть фактическое несоответствие имен хостов и ослабить барьер безопасности.
• Не следует напрямую открывать порт 9980 только потому, что прокси-сервер не работает. Необходимо исправить прокси-сервер, если только прямое открытие порта не является преднамеренным и безопасным решением.
• Не следует предполагать, что ответ 200 с главной страницы Collabora доказывает работоспособность редактирования документов. Обнаружение, возможности, доступ к файлам WOPI и WebSockets — это разные процессы.
• Не вносите изменения сразу в несколько уровней. После каждого изменения проводите тестирование, чтобы определить, что именно стало причиной проблемы: DNS, TLS, проксирование или доверие WOPI.

Контрольный список для окончательной проверки

После внесения изменений проверьте систему в следующем порядке:

1. Откройте /hosting/discoveryи /hosting/capabilitiesиспользуйте браузер.
2. Получите те же самые конечные точки с сервера хранения.
3. С сервера Collabora получите URL-адрес состояния сервера хранения.
4. Откройте документ, одновременно просматривая журналы Collabora и хранилища.
5. Убедитесь, что браузер устанавливает соединение WebSocket с Collabora без повторных разрывов.
6. Убедитесь, что второй пользователь может открыть и отредактировать тестовый документ, если требуется совместное редактирование.

Если все шесть проверок пройдут успешно, стандартное сообщение «Ну, это неловко» больше не должно маскировать сбой подключения. Если сообщение остаётся, сохраните точные строки журнала Collabora и информацию о сбое сети в браузере для одной попытки открытия документа; эти два доказательства будут полезнее, чем само стандартное сообщение пользовательского интерфейса.