ONLYOFFICE + Redmine: интеграция и настройка

Краткое описание

Интерфейс ONLYOFFICE Docs

ONLYOFFICE Docs — это open-source офисный пакет под лицензией GNU AGPL v3.0. Он включает веб‑просмотрщики и совместные редакторы для текстов, таблиц и презентаций с высокой совместимостью форматов OOXML (DOCX/XLSX/PPTX). Документный сервер можно интегрировать с различными облачными системами и встроить в собственное решение. В связке с Redmine редакторы позволяют редактировать и совместно править документы прямо в интерфейсе Redmine.

Важно: ONLYOFFICE совместим с Redmine версии 4.0.0 и выше.

Что потребуется перед началом

Рабочая инстанция Redmine с доступом администратора.
Сервер/контейнер ONLYOFFICE Document Server, доступный по сети и из Redmine.
Возможность установить плагин в папку redmine/plugins и выполнить команды bundle/rake.
(Рекомендовано) HTTPS и возможность настроить JWT для защиты обмена данными.

Примечание: если Redmine размещён за прокси или в Kubernetes, убедитесь, что DNS/маршрутизация и заголовки X‑Forwarded корректны.

Шаг 1: Установка ONLYOFFICE Docs

Чтобы редактировать документы из Redmine, нужен отдельно работающий ONLYOFFICE Document Server. Убедитесь, что он доступен как из Redmine, так и из браузеров пользователей. Самый простой способ — Docker:

sudo docker run -i -t -d -p 80:80 --restart=always onlyoffice/documentserver

Важно: если вы используете HTTPS на фронтенде, настройте обратный прокси (nginx, traefik и т. п.) перед Document Server, либо разверните контейнер с поддержкой TLS.

Дополнительная документация и подробные инструкции доступны в HowtoForge и официальной документации ONLYOFFICE.

Шаг 2: Установка плагина интеграции для Redmine

Скачайте коннектор ONLYOFFICE для Redmine. Можно клонировать репозиторий с GitHub:

git clone https://github.com/ONLYOFFICE/onlyoffice-redmine

Или загрузить архив релиза и распаковать:

wget https://github.com/ONLYOFFICE/onlyoffice-redmine/archive/refs/tags/v1.0.0.tar.gz

tar -xvzf v1.0.0.tar.gz

Папка плагина в redmine/plugins должна называться onlyoffice_redmine. Переименуйте скачанную папку, если это необходимо:

mv onlyoffice-redmine onlyoffice_redmine
mv onlyoffice-redmine-1.0.0 onlyoffice_redmine

Остановите Redmine, затем поместите каталог onlyoffice_redmine в redmine/plugins и выполните установку зависимостей:

cd redmine
bundle install

Инициализация/обновление базы данных и миграция плагина (пример для production):

RAILS_ENV=production bundle exec rake db:migrate
RAILS_ENV=production bundle exec rake redmine:plugins:migrate NAME=onlyoffice_redmine

После этого перезапустите Redmine.

Важно: делайте бэкап базы и файлов Redmine перед установкой плагинов.

Шаг 3: Настройка плагина в Redmine

После установки откройте в Redmine: Администрирование -> Плагины -> ONLYOFFICE Redmine plugin -> Configure. Укажите:

URL и порт ONLYOFFICE Document Server (например, https://docs.example.com).
Секретный ключ для JWT — тот же, что нужно указать на Document Server, чтобы включить проверку подписи.
Дополнительные параметры: кастомизация редактора, формат по умолчанию и т. п.

Экран настроек плагина ONLYOFFICE в Redmine

Важно: если Document Server недоступен по указанному URL для браузера пользователя (например, внутри сети), редактирование не заработает.

Шаг 4: Использование ONLYOFFICE Docs в Redmine

Настройка прав доступа для файлов в Redmine

После настройки вы сможете просматривать, редактировать и совместно править документы, загруженные в модули Issues, Files, Documents, Wiki и News. Доступ к просмотру и редактированию контролируется правами ролей внутри Redmine.

Поддерживаемые для редактирования форматы: DOCX, XLSX, PPTX.

Доступные для просмотра форматы: DOC, DOCX, DOCM, DOT, DOTX, DOTM, ODT, FODT, OTT, RTF, TXT, HTML, HTM, MHT, XML, PDF, DJVU, FB2, EPUB, XPS, XLS, XLSX, XLSM, XLT, XLTX, XLTM, ODS, FODS, OTS, CSV, PPS, PPSX, PPSM, PPT, PPTX, PPTM, POT, POTX, POTM, ODP, FODP, OTP.

Редактирование документа в Redmine через ONLYOFFICE

Коллаборативные функции: режимы совместного редактирования в реальном времени и блочной (paragraph-locking), «Отслеживание изменений», комментирование и встроенный чат.

Безопасность и JWT

JWT (JSON Web Token) используется для проверки подлинности запросов между Redmine и Document Server. Порядок действий:

Сгенерируйте надёжный секрет на стороне сервера (длинная случайная строка).
Введите его в настройках плагина Redmine и в конфигурации ONLYOFFICE Document Server.
Включите HTTPS для всех внешних подключений.

Важно: не используйте один и тот же секрет в публичных тестовых окружениях. Регулярно меняйте ключи и храните их в защищённых хранилищах (Vault, KMS).

Критерии приёмки

Пользователь с ролью «Разработчик» открывает .docx из задачи и может сохранить правки без ошибок.
Несанкционированный доступ блокируется (JWT проверяется, Document Server отвечает 401/403 на некорректный токен).
Совместное редактирование: как минимум два пользователя в реальном времени видят изменения и могут оставлять комментарии.
Просмотр форматов (PDF, ODT) работает без загрузки файла.

Чек-листы по ролям

Администратор Redmine:

Проверить доступность ONLYOFFICE по URL из браузера.
Установить и мигрировать плагин.
Настроить JWT и HTTPS.

Разработчик / Менеджер проекта:

Убедиться, что роль имеет права «Просмотр файлов» и/или «Редактирование файлов».
Протестировать открытие и сохранение DOCX/XLSX/PPTX.

Сотрудник поддержки:

Проверить логи Redmine и Document Server при ошибках.
Спросить об окружении пользователя (прокси, VPN, браузер).

Устранение неполадок (troubleshooting)

Симптом: «Документ не открывается» — возможные причины:

Неправильный URL Document Server в настройках плагина.
Document Server недоступен извне (firewall, сеть).
JWT не совпадает на стороне Redmine и Document Server — ошибка аутентификации.
Браузер блокирует смешанный контент (HTTP/HTTPS).

Проверочные шаги:

Откройте URL Document Server напрямую в браузере.
Проверьте логи Redmine (production.log) и логи Document Server на предмет ошибок JWT или 502/504.
Попробуйте временно отключить JWT, чтобы локализовать проблему (только на тестовом окружении).

Важно: отключать JWT в продакшене нельзя — это снизит безопасность.

Когда интеграция может не подойти

Если ваша инфраструктура не позволяет открыть Document Server пользователям извне и вы не можете настроить прокси.
Если нужен только просмотр специфичных проприетарных форматов с расширенными сценариями — возможны ограничения.
Если ваша политика безопасности запрещает передачу файлов на отдельный сервер.

Альтернативы:

Использовать встроенные плагины для конвертации в PDF и редактировать локально.
Рассмотреть другие облачные редакторы с поддержкой интеграции (в зависимости от требований безопасности и лицензирования).

Мини‑методология внедрения (быстрая дорожная карта)

Тестовая среда: разверните Redmine и Document Server в изолированной сети.
Установите плагин и выполните миграции.
Настройте JWT и HTTPS; протестируйте функциональность ролей.
Проведите нагрузочное тестирование совместного редактирования (несколько пользователей).
Перенесите на продакшн по плану с бэкапом и откатом.

Риски и их смягчение

Риск: утечка документов при неправильной конфигурации сети.
Смягчение: шифрование TLS, firewall, ограничение доступа по IP.
Риск: уязвимость в плагине.
Смягчение: следить за обновлениями плагина и проводить регулярные обновления.
Риск: несовместимость версий Redmine/плагина.
Смягчение: проверять совместимость и проводить тесты в staging.

Короткий глоссарий

Document Server: сервер ONLYOFFICE, обрабатывающий редакторы и просмотрщики.
JWT: JSON Web Token для подписи запросов между Redmine и Document Server.
OOXML: набор форматов Microsoft Office (DOCX, XLSX, PPTX).

Примечания и советы по локализации

В корпоративной сети используйте внутренние DNS-имена и доверенные сертификаты.
Для внешнего доступа предпочтителен прокси с WAF (web application firewall).

Итог

Вы успешно интегрируете ONLYOFFICE Docs с Redmine, если настроите Document Server, установите плагин onlyoffice_redmine, укажете корректный URL и общий JWT‑секрет, а также проверите права доступа. После этого пользователи смогут совместно редактировать DOCX, XLSX и PPTX прямо в Redmine.

Ключевые действия: развернуть Document Server, установить плагин, настроить JWT/HTTPS, протестировать права и совместное редактирование.

Важно: периодически проверяйте обновления плагина и Document Server, а также сохраняйте бэкапы перед миграциями.