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

MAATRIX

OnlyOffice Document Server разворачивают за один docker run, и первые полчаса всё работает идеально — документ открылся, курсор мигает. А потом приходит коллега, начинает редактировать тот же файл, и редактор виснет с крутящимся индикатором, либо вместо документа выскакивает «Token is not correct». Дальше начинается угадывание: то ли дело в JWT, то ли в сети, то ли контейнеру не хватает памяти. Разберём самые частые поломки OnlyOffice на сервере — с чёткой причиной и командой, которая её подтверждает.

С чего начинать диагностику

OnlyOffice Document Server — это не один процесс, а связка: nginx спереди, за ним несколько node.js-сервисов (DocService отвечает за редактирование, ConvertService — за конвертацию форматов, SpellChecker — за проверку орфографии), и, если вы используете официальный all-in-one образ, внутри того же контейнера крутятся ещё RabbitMQ, Redis и PostgreSQL. Все они управляются через supervisor, и первое, что стоит проверить при любой странности — их статус:

docker exec -it onlyoffice-documentserver supervisorctl status

Если какой-то из процессов в состоянии FATAL или постоянно перезапускается — это и есть источник проблемы, а не то, на что жалуется браузер. Второй быстрый чек — health-эндпоинт самого Document Server:

curl http://localhost/healthcheck

Ответ true означает, что сервис в принципе жив и может принимать запросы. Логи лежат внутри контейнера в /var/log/onlyoffice/documentserver/ — отдельные папки под каждый сервис (docservice/, converter/, nginx/). Если у вас смонтирован volume под этот путь, логи переживут пересоздание контейнера, и вы сможете смотреть историю ошибок, а не только текущий момент:

docker exec -it onlyoffice-documentserver tail -f /var/log/onlyoffice/documentserver/docservice/out.log

Держите это правило перед собой: браузер показывает симптом («не удалось скачать файл», «token is not correct»), а причина почти всегда видна в одном из этих логов за секунду до того, как ошибка всплыла на экране.

Ошибка «Token is not correct» и проблемы с JWT

Начиная с шестой ветки OnlyOffice включает проверку JWT-токена по умолчанию — это защита от того, чтобы кто угодно мог дёргать API вашего Document Server. Токен должен совпадать в двух местах: на самом сервере документов и в конфиге коннектора (плагина Nextcloud, вашего кастомного интеграционного скрипта и так далее). Если они разошлись, редактор либо вовсе не открывает документ, либо падает с явной ошибкой прямо в интерфейсе.

Проверьте, что секрет одинаковый с обеих сторон. В docker-compose файле Document Server это переменные окружения:

environment:
  - JWT_ENABLED=true
  - JWT_SECRET=your-long-random-secret
  - JWT_HEADER=Authorization

А в настройках коннектора (например, в приложении OnlyOffice для Nextcloud: Настройки → Управление → ONLYOFFICE) — поле «Секретный ключ» должно содержать точно такую же строку, без лишних пробелов в конце. Частая ошибка — поменять JWT_SECRET в .env, но не пересоздать контейнер: docker restart подхватывает старое окружение, если переменная зашита в уже созданный контейнер, нужен именно пересоздание:

docker compose up -d --force-recreate documentserver

Второй источник похожих ошибок — рассинхронизация времени между сервером документов и сервером приложения. JWT токены завязаны на время жизни, и если часы на серверах разъехались на несколько минут, проверка токена будет проваливаться при абсолютно верном секрете. Проверьте синхронизацию:

timedatectl status

Если NTP synchronized: no — включите синхронизацию (timedatectl set-ntp true) и подождите, пока время выровняется, прежде чем снова тестировать редактор.

«Не удалось скачать файл, который вы редактируете»

Эта ошибка — про сеть, а не про сам файл. Схема работы OnlyOffice такая: приложение (условно, ваша CRM или Nextcloud) отдаёт Document Server ссылку, откуда скачать документ для открытия, а Document Server, в свою очередь, зовёт callback-URL приложения, чтобы сохранить изменения. Оба этих запроса идут не из браузера пользователя, а напрямую с контейнера Document Server — и если он физически не может достучаться до вашего приложения, вы получите именно эту ошибку.

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

docker exec -it onlyoffice-documentserver curl -v "https://ваш-домен/path/to/file.docx"

Типичные причины провала:

• Document Server и приложение в разных docker-сетях — если оба сервиса в контейнерах на одном хосте, проще всего положить их в общую сеть и обращаться по имени сервиса, а не через внешний домен и интернет.
• Firewall блокирует запрос — если приложение доступно только с определённых IP, добавьте в разрешённый список адрес сервера с Document Server.
• Самоподписанный SSL-сертификат — Document Server по умолчанию проверяет валидность сертификата на другой стороне и обрывает соединение при self-signed. Правильное решение — выпустить нормальный сертификат через Let's Encrypt, это разобрано в статье про ошибки Let's Encrypt на сервере. Отключать проверку через REJECT_UNAUTHORIZED=false — рабочий костыль для теста, но не для продакшена: вы теряете защиту от подмены сертификата на пути запроса.
• Внутренний DNS не резолвит имя — если приложение обращается к Document Server по внутреннему хостнейму, а не по IP, убедитесь, что этот хостнейм резолвится именно из контейнера, а не только с хост-машины.

Совместное редактирование не запускается или обрывается

Если документ открывается, но при попытке редактировать вдвоём курсор второго пользователя не появляется, а изменения не долетают — почти всегда дело в WebSocket-соединении. Совместное редактирование в OnlyOffice работает через постоянное соединение на путь /doc/, и если между браузером и Document Server стоит reverse proxy, он обязан явно пробрасывать заголовки апгрейда протокола.

Для nginx это выглядит так:

location /doc/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 3600s;
}

Обратите внимание на proxy_read_timeout — WebSocket-соединение держится открытым долго, и стандартный таймаут в 60 секунд будет обрывать сессию редактирования каждую минуту простоя. Общие принципы настройки reverse proxy с вебсокетами и другими типовыми граблями разобраны в статье про Nginx как реверс-прокси на сервере.

Отдельно проверьте, не стоит ли перед сервером CDN или защитный прокси (например, Cloudflare в оранжевом режиме), который не пропускает WebSocket на этом поддомене — для таких сервисов обычно нужно явно включать поддержку WebSocket или переводить поддомен с Document Server в режим DNS-only.

Высокая нагрузка на CPU и RAM, контейнер падает

All-in-one образ Document Server — это не лёгкий сервис. Внутри одновременно работают nginx, несколько node.js-процессов, RabbitMQ, Redis и PostgreSQL, и каждое открытое совместное редактирование держит активное соединение и потребляет память на стороне DocService. На слабом VPS с 1-2 ГБ RAM сервис либо не стартует вовсе, либо падает при первой же попытке одновременного редактирования — процесс просто убивает OOM killer:

dmesg | grep -i "out of memory"
docker inspect onlyoffice-documentserver --format='{{.State.OOMKilled}}'

Если видите true — контейнеру не хватило памяти, и вопрос решается либо ресурсами сервера, либо распределением нагрузки. Точную формулу «сколько RAM на одного одновременного редактора» приводить не буду — это ориентир, который сильно зависит от размера документов и версии Document Server, а не константа. На практике комфортный запас для небольшой команды начинается от нескольких гигабайт свободной памяти сверх того, что нужно самому приложению-коннектору; если пользователей и документов становится много, разумнее вынести PostgreSQL, Redis и RabbitMQ в отдельные контейнеры или на отдельный сервер, как это описано в официальной схеме масштабирования OnlyOffice, а не пытаться выжать всё из одного all-in-one образа.

Как временную страховку от внезапного всплеска нагрузки стоит настроить своп — это не заменит нехватку физической памяти, но даёт системе шанс не убить процесс мгновенно, пока вы разбираетесь с причиной. Как правильно посчитать размер и настроить его, написано в статье про настройку swap на VPS.

Отдельно — не забывайте про постоянные volume для данных. Без них при каждом пересоздании контейнера вы теряете шрифты, настройки и базу PostgreSQL внутри, что выглядит как «сервис снова просит первоначальную настройку»:

volumes:
  - ./data:/var/www/onlyoffice/Data
  - ./logs:/var/log/onlyoffice
  - ./lib:/var/lib/onlyoffice
  - ./db:/var/lib/postgresql

Проблемы со шрифтами и конвертацией документов

Если PDF или картинки, сгенерированные из документов, показывают квадратики вместо кириллицы — Document Server не увидел нужные шрифты. Загрузите файлы шрифтов (например, из пакета ttf-mscorefonts или собственные корпоративные .ttf) в /usr/share/fonts внутри контейнера, затем пересоберите кэш шрифтов и перезапустите сервисы редактирования:

docker exec -it onlyoffice-documentserver documentserver-generate-allfonts.sh
docker exec -it onlyoffice-documentserver supervisorctl restart all

Вторая типичная жалоба — конвертация больших файлов (например, .docx на сотни страниц или сложную .xlsx с макросами) обрывается по таймауту, и вместо результата пользователь видит ошибку конвертации. Здесь помогает не бесконечное увеличение лимитов, а разумная проверка: действительно ли документ должен быть таким тяжёлым, или его стоит разбить. Если конвертация тяжёлых, но легитимных файлов — обычная практика в вашей команде, увеличьте лимиты в конфигурации ConvertService и дайте серверу больше ресурсов на этот процесс отдельно от DocService, чтобы долгая конвертация не отжирала память у активных сессий редактирования.

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