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

Кратко

Этот гид показывает, как установить и настроить скрипт onlyoffice-alfresco, чтобы пользователи могли совместно редактировать документы из Alfresco Share в ONLYOFFICE Online Editors. Приведены требования, пошаговая инструкция, проверочные сценарии и рекомендации по безопасности.

TL;DR

Установите ONLYOFFICE Document Server и нужную версию Java, соберите плагин через Gradle, установите onlyoffice-alfresco и добавьте параметр onlyoffice.url в alfresco-global.properties. Проверьте, что в библиотеке документов появилась команда «Edit in Onlyoffice» и что доступ к Document Server защищён HTTPS.

Что описано в статье

Быстрая установка и сборка onlyoffice-alfresco
Проверки работоспособности и тесты приёмки
Варианты для продакшена: Docker и обратный прокси
Безопасность, GDPR и рекомендации по развертыванию

Требования

ONLYOFFICE Document Server (локально или в защищённой сети)
Java 7 SDK или новее (рекомендовано Oracle Java 8)
Gradle
Права администратора на сервере Alfresco

Подготовка среды и полезные проверки

Проверьте версию Java: java -version.
Проверьте Gradle: gradle -v.
Убедитесь, что Документный сервер ONLYOFFICE доступен по сети и прослушивает нужный порт (обычно 80/443 или кастомный).
Рекомендуется использовать HTTPS и действительные сертификаты для Document Server.

Шаг 1. Установка ONLYOFFICE Document Server

Следуйте официальной инструкции ONLYOFFICE для установки Document Server или используйте официальный Docker-образ, чтобы избежать конфликтов с зависимостями. Docker-образ часто проще для тестовой среды и CI.

Важно: в продакшене задействуйте HTTPS и настройте обратный прокси (Nginx / Apache) перед Document Server.

Шаг 2. Установка Gradle

Добавьте репозиторий Gradle и установите его командой:

sudo add-apt-repository ppa:cwchien/gradle

Обновите списки пакетов:

sudo apt-get update

Установите Gradle:

sudo apt-get install gradle

Если Gradle уже установлен и требуется переустановка, удалите старую версию:

sudo apt-get remove gradle

Проверка: gradle -v.

Шаг 3. Установка Oracle Java 8

Рекомендуется Oracle Java 8 для совместимости с плагинами Alfresco (в средах, где это допустимо). Команды для установки:

sudo add-apt-repository ppa:webupd8team/java
sudo apt-get update
sudo apt-get install oracle-java8-installer

Проверка: java -version должна показывать Oracle Java 1.8.x.

Примечание: при ограничениях лицензирования используйте OpenJDK 8, но заранее протестируйте совместимость.

Шаг 4. Переключение альтернатив Java

Убедитесь, что система использует нужную версию Java:

sudo update-alternatives --config java
sudo update-alternatives --config javac
sudo update-alternatives --config javaws

Выберите путь к Oracle Java, если он установлен.

Шаг 5. Сборка зависимостей плагина Alfresco

Склонируйте репозиторий плагина Alfresco и соберите артефакты:

git clone https://github.com/yeyan/alfresco-amp-plugin.git

cd amp-plugin
gradle publish

Цель: создать AMP/Share AMP-пакеты в каталоге сборки, которые затем понадобятся для установки в Alfresco.

Шаг 6. Копирование onlyoffice-alfresco плагина

Склонируйте плагин onlyoffice-alfresco:

cd ..
git clone https://github.com/cetra3/onlyoffice-alfresco.git

Шаг 7. Сборка AMP-пакетов для share и repo

Выполните gradle amp в директориях share и repo плагина (если структура плагина предполагает отдельные подпроекты):

# Пример: в корне плагина
gradle amp

Проверьте, что сборка создала пакеты в ./build/amp.

Шаг 8. Добавьте onlyoffice.url в alfresco-global.properties

Откройте файл alfresco-global.properties и добавьте строку с URL Document Server. Пример:

onlyoffice.url=https://onlyoffice.example.com

Совет: используйте FQDN и HTTPS. Если Document Server за обратным прокси, укажите адрес прокси.

Шаг 9. Скопируйте пакеты в каталоги Alfresco

Скопируйте созданные AMP-пакеты из ./build/amp в каталоги установки Alfresco:

amps/ — для репозитория (repo)
amps_share/ — для Share

После копирования убедитесь, что файлы имеют корректные права доступа.

Шаг 10. Примените AMP-пакеты

Запустите скрипт применения AMP-пакетов:

bin/apply_amps.sh

Вы увидите два модуля, которые будут установлены. Нажмите Enter для завершения установки. Затем перезапустите Tomcat/службы Alfresco.

После перезапуска в библиотеке документов должна появиться новая команда “Edit in Onlyoffice” для офисных документов.

Проверки и критерии приёмки

В интерфейсе Alfresco Share появилась кнопка/действие «Edit in Onlyoffice».
Документ открывается в ONLYOFFICE Editor без ошибок.
Изменения сохраняются обратно в Alfresco и видны другим пользователям.
Трафик к Document Server проходит по HTTPS и видим в логах прокси/Document Server.

Тестовые сценарии (мини-набор)

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

Отладка и распространённые ошибки

Ошибка подключения к Document Server: проверьте onlyoffice.url, DNS и доступность порта.
Ошибки сборки Gradle: проверьте версии Gradle/Java и зависимости репозитория.
Ошибки при применении AMP: проверьте права доступа и корректность путей в Alfresco.
Если после перезапуска Alfresco действие не появилось — очистите кэш браузера и перезапустите Alfresco ещё раз.

Совет: просмотрите логи Alfresco (alfresco.log, share.log) и логи Document Server для подробностей.

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

Docker Compose: используйте официальный образ ONLYOFFICE Document Server и контейнер Alfresco для тестовых сред.
Обратный прокси: размещайте Document Server за Nginx/Apache для TLS-терминации и статического кеширования.
Облачные решения: если не хотите управлять Document Server, рассмотрите хостинг ONLYOFFICE или интеграцию через API (при условии совместимости).

Роли и чек-листы

Администратор Alfresco:
- Установить Java/Gradle и собрать AMP
- Добавить толькоURL в конфиг
- Перезапустить сервисы
Сетевой инженер:
- Настроить DNS и HTTPS
- Открыть нужные порты и настроить обратный прокси
Тестировщик:
- Прогнать тестовые сценарии и регистрировать баги

Безопасность и соответствие (GDPR)

Передавайте данные между Alfresco и Document Server только по HTTPS.
По возможности размещайте Document Server внутри защищённой сети или VPC.
Логи могут содержать метаданные документов — настройте ротацию и доступ к логам.
При необходимости ограничьте доступ к Document Server сетевыми ACL и firewall.

Совместимость и советы по миграции

Тестируйте плагин на тестовом стенде, идентичном продакшну по версиям Java и Alfresco.
Проверяйте совместимость с текущими версиями Alfresco Share и установленными модулями.
При переходе с одной инсталляции Document Server на другую обновите onlyoffice.url и протестируйте.

Краткое руководство по восстановлению (rollback)

Верните прежние AMP-пакеты из резервной копии и примените их.
Восстановите alfresco-global.properties из резервной копии.
Перезапустите Alfresco и проверьте работоспособность.

Часто задаваемые вопросы

Q: Можно ли использовать OpenJDK вместо Oracle Java? A: Да, но заранее протестируйте совместимость. Некоторые среды лучше работают с Oracle Java 8.

Q: Нужно ли ставить Document Server на тот же хост, что и Alfresco? A: Нет. Обычно Document Server размещают отдельно и защищают через обратный прокси.

Q: Как обеспечить одновременное редактирование? A: ONLYOFFICE обеспечивает коллаборативное редактирование через Document Server; убедитесь, что порты и настройки WebSocket/HTTP доступны.

Заключение

Интеграция Alfresco и ONLYOFFICE даёт пользователям возможность совместно редактировать документы прямо из интерфейса Share. Ключевые моменты — корректная установка Document Server, правильная версия Java/Gradle, сборка AMP и безопасная конфигурация onlyoffice.url. Тестируйте изменения в тестовой среде перед выкатыванием в продакшн.

Важно: всегда используйте HTTPS и контролируйте доступ к Document Server.

Ресурсы

Alfresco: https://www.alfresco.com/
ONLYOFFICE: http://www.onlyoffice.com/
onlyoffice-alfresco на GitHub: https://github.com/cetra3/onlyoffice-alfresco

Интеграция Alfresco с ONLYOFFICE Online Editors