Collabora Online на сервере: частые ошибки и решения

MAATRIX

Собственный Collabora Online — это редактирование Word, Excel и Impress прямо в браузере, без Google и Microsoft 365, с документами на вашем сервере. Звучит просто, но на практике связка nginx + WebSocket + WOPI-протокол ломается в паре мест почти у каждого, кто разворачивает её впервые. Ниже — типовые ошибки, с которыми сталкиваются при установке Collabora Online (CODE, Collabora Online Development Edition) на собственном VPS, и рабочие способы их закрыть.

Как устроено Collabora Online и почему оно капризное

Collabora Online — это не просто «LibreOffice в браузере». Это отдельный сервис coolwsd (в старых версиях — loolwsd), который:

• принимает документ по протоколу WOPI от хост-приложения (Nextcloud, ownCloud, кастомный WOPI-сервер или прямая интеграция через iframe);
• рендерит его через движок LibreOffice внутри своего контейнера;
• передаёт изменения в браузер через WebSocket-соединение в реальном времени.

Именно последний пункт — источник большинства проблем. Обычный HTTP реверс-прокси прекрасно проксирует статику и REST-запросы, но WebSocket требует отдельного Upgrade-заголовка и корректных таймаутов — если прокси об этом не знает, соединение рвётся, и пользователь видит либо бесконечную загрузку, либо документ, который открывается, но не реагирует на ввод.

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

«This document could not be loaded» и WOPI host not allowed

Самая частая ошибка при первом запуске. В логах coolwsd (docker logs collabora) видно что-то вроде:

wsd-00007 kit-src Error: Domain 'https://cloud.example.com' is not on the list of allowed WOPI hosts

Причина: Collabora по умолчанию разрешает подключаться только серверам, чей домен явно прописан в --o:storage.wopi.host (или через переменную окружения aliasgroup1 в Docker-образе). Если CODE-контейнер работает как отдельный сервис для Nextcloud, домен облака должен быть в списке разрешённых явно, регулярным выражением:

docker run -d \
  --name collabora \
  -p 127.0.0.1:9980:9980 \
  -e 'aliasgroup1=https://cloud\.example\.com:443' \
  -e 'extra_params=--o:ssl.enable=false --o:ssl.termination=true' \
  --restart unless-stopped \
  collabora/code:latest

Ключевые моменты:

• точки в домене экранируются как \. — это часть regex, а не опечатка;
• порт указывается явно, обычно :443, даже если снаружи трафик идёт через 80/443 на nginx, а не напрямую в контейнер;
• если WOPI-хостов несколько (например, staging и prod), добавляются aliasgroup2, aliasgroup3 и так далее — единой переменной со списком через запятую в старых образах не будет работать надёжно, используйте отдельные переменные.

После правки переменных окружения контейнер нужно пересоздать (docker compose up -d --force-recreate), просто рестарта недостаточно — переменные окружения читаются при старте процесса coolwsd внутри образа.

nginx как обратный прокси: рабочий конфиг с WebSocket

Ошибка №2 по частоте — редактор либо не открывается вовсе, либо открывается, но зависает при попытке набрать текст: Failed to load Collabora Online — cannot connect. В консоли браузера при этом видно обрыв WebSocket (WebSocket connection to 'wss://...' failed).

Если Collabora стоит за nginx (что почти всегда так — контейнер слушает 127.0.0.1:9980, наружу торчит только nginx с SSL), конфиг должен явно поддерживать апгрейд соединения и увеличенные таймауты:

# Collabora Online - static assets
location ^~ /browser {
    proxy_pass https://127.0.0.1:9980;
    proxy_set_header Host $http_host;
}

# Collabora Online - WOPI discovery
location ^~ /hosting/discovery {
    proxy_pass https://127.0.0.1:9980;
    proxy_set_header Host $http_host;
}

location ^~ /hosting/capabilities {
    proxy_pass https://127.0.0.1:9980;
    proxy_set_header Host $http_host;
}

# main websocket
location ~ ^/cool/(.*)/ws$ {
    proxy_pass https://127.0.0.1:9980;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $http_host;
    proxy_read_timeout 36000s;
    proxy_send_timeout 36000s;
}

# download, presentation, admin
location ~ ^/cool {
    proxy_pass https://127.0.0.1:9980;
    proxy_set_header Host $http_host;
}

В версиях CODE после переименования путей (/lool/ → /cool/) регулярки нужно проверять по фактической версии образа — старые гайды в сети до сих пор ссылаются на /lool/, и со свежим collabora/code такой конфиг просто не сработает: браузер получит 404 на WebSocket-эндпоинт. Проверить актуальный путь проще всего через curl -k https://127.0.0.1:9980/hosting/discovery — в XML-ответе перечислены реальные URL-шаблоны для текущей версии.

Второй нюанс — proxy_read_timeout. Значение по умолчанию в nginx (60 секунд) обрывает WebSocket при простое: пользователь открыл документ, отошёл на пять минут — соединение уже разорвано, документ «завис». 36000 секунд (10 часов) — разумный запас для рабочей сессии.

Если у вас уже настроен reverse-proxy для других сервисов, общие принципы прокси под WebSocket разобраны в статье nginx как реверс-прокси на сервере: частые ошибки и решения — сюда стоит заглянуть, если проблема не только с Collabora, а с прокси в целом.

Бесконечная загрузка редактора и mixed content

Симптом: страница Nextcloud открывается, документ пытается загрузиться, крутится спиннер — и всё, ошибки в интерфейсе нет вообще. Открываем консоль разработчика в браузере (F12 → Network/Console) и обычно видим один из двух вариантов.

Mixed content. Если Nextcloud открыт по https://, а Collabora проксируется через http:// (или iframe пытается загрузить ресурс не с того протокола), браузер молча блокирует часть запросов. Решение — единообразный HTTPS на обоих доменах, и обязательно настоящий сертификат (Let's Encrypt), не самоподписанный: самоподписанные сертификаты внутри iframe обычно не проходят проверку без явного разрешения пользователя, а дать его для iframe, скрытого внутри Nextcloud, обычному пользователю негде.

X-Frame-Options / CSP. Collabora по умолчанию выставляет заголовки, разрешающие встраивание в iframe только для доверенных источников. Если nginx перед Collabora сам добавляет X-Frame-Options: SAMEORIGIN или Content-Security-Policy: frame-ancestors 'self' глобально (унаследовано из общего конфига безопасности сервера), эти заголовки перебивают то, что выставляет coolwsd, и браузер отказывается рисовать iframe. Проверяется через вкладку Network — смотрим заголовки ответа на путь /browser/.../cool.html. Если там виден чужой X-Frame-Options, убирайте его из общего location-блока и оставляйте управление заголовками за Collabora.

Интеграция с Nextcloud: приложение Collabora Online / Nextcloud Office

Отдельный класс проблем — не в coolwsd, а в связке с Nextcloud через приложение Nextcloud Office (бывшее Collabora Online для Nextcloud, движок richdocuments). Настройки — Nextcloud → Параметры → Nextcloud Office.

Частая ошибка при сохранении URL сервера Collabora:

Error connecting to the WOPI server. Please retry now, or contact your administrator.

Проверочный список:

1. URL сервера в настройках указывается без завершающего слэша и обязательно с https:// — https://office.example.com, не https://office.example.com/.
2. Сам сервер Nextcloud должен физически достучаться до Collabora по этому URL — если оба контейнера в одной docker-сети, а в настройках указан внешний домен, проверьте, что DNS-запросы с сервера резолвят домен в правильный IP.
3. Если Nextcloud и Collabora на разных серверах, между ними должен быть открыт порт 443 в обе стороны.
4. После смены домена или сертификата иногда нужно очистить кеш WOPI-дискавери — надёжнее всего отключить и заново включить приложение Nextcloud Office.

Если у вас ещё не поднят сам Nextcloud, пошаговая установка описана в статье как установить и настроить Nextcloud на VPS, а типовые проблемы уже работающего облака — в Nextcloud на сервере: частые ошибки и решения.

Стоит помнить и об альтернативе: если Collabora упорно не заводится из-за конфликтов версий или дефицита ресурсов, для интеграции с Nextcloud есть ONLYOFFICE — с другой архитектурой и другим набором проблем. Процесс установки описан в статье как установить и настроить ONLYOFFICE на VPS.

Производительность: сколько ресурсов реально нужно

Collabora Online — не лёгкий сервис. Каждый открытый документ запускает отдельный процесс LibreOffice внутри контейнера (kit-процесс), и по умолчанию образ держит пул предзапущенных процессов для быстрого отклика.

Ориентировочно (это именно ориентир, а не гарантированные цифры — реальное потребление зависит от размера документов и версии образа):

Если контейнер падает или зависает под нагрузкой, а docker stats показывает упирание в лимит памяти, помогают параметры в extra_params:

--o:per_document.max_concurrency=2
--o:num_prespawn_children=1

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

Общие практики распределения ресурсов между контейнерами разобраны в статье Docker: лучшие практики безопасности.

Обновления и совместимость версий

Отдельная категория ошибок возникает не при первой установке, а после обновления. Образ collabora/code:latest подтягивает новую версию при пересоздании контейнера, и если её WOPI-протокол изменился сильнее, чем ожидает установленная версия приложения Nextcloud Office, редактор перестаёт открываться с общей ошибкой без деталей.

Практика, которая экономит нервы:

• фиксируйте тег образа явно (collabora/code:24.04.13.2, а не latest) в docker-compose.yml, чтобы обновление было осознанным шагом, а не побочным эффектом docker compose pull;
• перед обновлением проверяйте матрицу совместимости в документации Nextcloud Office — версия приложения и версия coolwsd должны быть согласованы;
• держите под рукой предыдущий рабочий тег образа, чтобы откат занимал одну команду, а не восстановление из бэкапа.

Общие приёмы отладки Docker-контейнеров, которые не запускаются после изменений, собраны в статье Docker-контейнер не запускается: причины и решение.

Частые вопросы