Интеграция ONLYOFFICE Docs с Redmine

Внешний вид только что установленного сервера документов ONLYOFFICE

В этой статье описаны шаги по установке и настройке интеграции ONLYOFFICE Docs (Document Server) и Redmine с использованием официального коннектора. Приведены рекомендации по безопасности, типичные проблемы и чек-листы для администратора и пользователя.

Цель и совместимость

Цель: дать пошаговое руководство для быстрой настройки редактирования офисных файлов внутри Redmine с помощью ONLYOFFICE Docs. Подходит для Redmine версии 4.0.0 и выше.

Ключевые возможности после интеграции:

Редактирование и совместная работа в реальном времени над DOCX, XLSX, PPTX.
Просмотр множества форматов (PDF, ODT, HTML и др.).
Защита доступа через JWT.

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

Чтобы редактировать документы через Redmine, вам нужен развёрнутый ONLYOFFICE Document Server. Сервер должен быть доступен по URL и порту как для Redmine, так и для конечных клиентов. Кроме того, Document Server должен уметь отправлять HTTP-запросы в Redmine.

Проще всего установить последнюю версию через Docker. Выполните на сервере эту команду:

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

После этого Document Server будет доступен по порту 80 на хосте, где выполняется контейнер. Для подробной инструкции можно обратиться к руководствам по Docker и к HowtoForge.

Важно: если ваш Redmine работает по HTTPS, убедитесь, что и Document Server доступен по HTTPS или что прокси/балансировщик корректно настроен и передаёт заголовки протокола.

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

Скачайте коннектор 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

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

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

Затем остановите Redmine и поместите каталог onlyoffice_redmine в папку redmine/plugins.

Перейдите в корневой каталог Redmine и установите зависимости:

cd redmine
bundle install

Инициализируйте/обновите базу данных и миграции плагинов:

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

После завершения перезапустите Redmine.

Шаг 3: Настройте плагин интеграции

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

URL и порт установленного ONLYOFFICE Document Server.
Секретный ключ для включения JWT, который защищает документы от неавторизованного доступа. Тот же ключ нужно прописать в конфигурации Document Server для проверки подписи.
При необходимости настройте параметры интерфейса редакторов.

Скриншот страницы настроек плагина ONLYOFFICE в Redmine

Примечание: храните секретный ключ в защищённом месте и используйте длинную случайную строку. Если ключ скомпрометирован, смените его и в Document Server, и в плагине Redmine одновременно.

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

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

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

На текущий момент доступны совместное редактирование и соавторство для форматов DOCX, XLSX и PPTX.

Интерфейс интеграции ONLYOFFICE и Redmine при редактировании документа

Поддерживаемые для просмотра форматы включают: 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.

Доступные функции совместной работы:

Режимы реального времени и блокировки абзацев.
Отслеживание изменений (Track Changes).
Комментарии.
Встроенный чат.

Когда интеграция может не сработать

Document Server недоступен по сети из Redmine (firewall, NAT, неправильный URL/порт).
Неправильно указан секретный ключ JWT в одном из сервисов.
Проблемы с CORS или SSL (неподписанные сертификаты, некорректный прокси).
Версия Redmine ниже 4.0.0.

Как проверить: curl или браузер к URL Document Server, посмотреть логи Redmine и Docker-контейнера, убедиться, что в логах нет ошибок валидации JWT.

Альтернативные подходы

Встроенный просмотрщик/редактор других продуктов (например, OnlyOffice Desktop Editors не интегрируются напрямую с Redmine).
Использовать внешний файловый менеджер или WebDAV-сервер для хранения и редактирования файлов вне Redmine.
Развернуть прокси с TLS-терминацией перед Document Server, если требуется корпоративный сертификат.

Руководство по безопасности

Всегда включайте JWT и храните ключ в секрете.
Используйте HTTPS между клиентом, Redmine и Document Server.
Ограничьте доступ к Document Server через сетевые правила (firewall, security groups).
Регулярно обновляйте контейнер onlyoffice/documentserver и Redmine с плагинами.

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

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

Установить Docker и развернуть Document Server.
Поместить onlyoffice_redmine в redmine/plugins.
Выполнить bundle install и миграции.
Настроить JWT и HTTPS.
Проверить доступность из браузера и логов.

Разработчик/интегратор:

Проверить совместимость версий.
Настроить прокси и CORS при необходимости.
Автоматизировать развёртывание через Ansible/CI.

Пользователь:

Убедиться, что имеет права на просмотр/редактирование в проекте.
Загружать поддерживаемые форматы (DOCX/XLSX/PPTX) для совместного редактирования.

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

Документ формата DOCX можно открыть и редактировать внутри Redmine.
Несколько пользователей могут одновременно вносить правки и видеть изменения в реальном времени.
JWT успешно защищает запросы к Document Server (проверяется логами и отсутствием 401/403).

Краткий словарь

ONLYOFFICE Document Server: сервер, предоставляющий веб-редакторы для документов.
JWT: JSON Web Token, механизм подписи и проверки целостности запросов.
Плагин onlyoffice_redmine: компонент для интеграции Document Server с Redmine.

Краткая методология установки

Разверните Document Server (Docker).
Установите плагин в redmine/plugins.
Выполните миграции и перезапустите Redmine.
Настройте URL и JWT в плагине.
Протестируйте открытие и совместное редактирование.

Итог

Интеграция ONLYOFFICE Docs с Redmine позволяет добавить полноценные веб-редакторы и функции совместной работы в систему управления проектами. Важно корректно настроить сетевой доступ и JWT, чтобы обеспечить безопасность и стабильность работы. После установки администратор и пользователи получают удобный инструмент для создания и редактирования DOCX, XLSX и PPTX прямо в интерфейсе Redmine.

Сводка действий: установить Document Server, установить и настроить плагин, задать секретный ключ и протестировать совместную работу.