ONLYOFFICE Docs¶

Первая Форма поддерживает онлайн-совместную работу с документами (текстами, таблицами, презентациями). В качестве редактора используется ONLYOFFICE Docs.

Режимы распространения ONLYOFFICE:

Коммерческая версия;
CommunityEdition под GNUAGPLv3.

Архитектура решения¶

Роль компонентов:

Первая Форма:

Реализует REST-API в соответствии со спецификацией ONLYOFFICE API;
Принимает HTTP-запросы от ONLYOFFICE Docs для операций.

ONLYOFFICE Docs:

Отправляет запросы к API "Первой Формы";
Отображает интерфейс редактора на фронтенде.

Безопасность¶

Используются JWT-токены:

Генерируются на стороне хоста ("Первая Форма");
Передаются только валидным сессиям;
Проверка подписи осуществляется на уровне Docs (симметричный секретный ключ).

Системные требования¶

Минимальные рекомендации в зависимости от числа одновременно активных пользователей:

Размер инсталляции	vCPU	RAM	Storage
<100 пользователей	2	4GB	40GB
>100 пользователей	≥4	4–8GB	≥160GB

Поддерживаемые ОС:

Любой современный Linux x64 - Debian, Ubuntu, CentOS, RHEL и т.п.

Ограничения использования ONLYOFFICE Document Server Community Edition¶

ONLYOFFICE CE не поддерживает кластеризацию. Отказоустойчивость и масштабирование должны обеспечиваться средствами оркестратора или путём запуска нескольких независимых реплик. При втором варианте, если несколько пользователей одновременно редактируют один и тот же документ, возможна рассинхронизация.

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

Для сценариев, где требуется кластеризация, отказоустойчивость с высокой нагрузкой или значительно большее число одновременных редактирующих пользователей/сессий, необходимо рассмотреть коммерческий вариант лицензирования — Enterprise-версию. Или рассмотреть использование отечественного продукта — Р7‑Офис, который является вариантом импортозамещения офисного пакета.

Docker-развертывание¶

Для удобства развертывания, масштабирования и обновлений рекомендуется поднять ONLYOFFICE через Docker. Вы можете скачать образ из репозитория Docker HUB или из репозитория Первая Форма:

Официальный образ: onlyoffice/documentserver ;
Образ от Первой Формы: docker.1forma.ru/onlyoffice/documentserver .

Образы включают в себя:

ONLYOFFICE Docs;
Nginx;
Вспомогательные сервисы (в составе образа или как зависимые контейнеры):

oRedis — кэширование, сессии;

oRabbitMQ — очереди задач (например, фоновые конвертации);

oPostgreSQL — база данных.

Запуск в Docker Compose¶

Для удобного, воспроизводимого и расширяемого развёртывания ONLYOFFICE Docs используем Docker Compose с внешним .env -файлом.

Вы можете скачать готовые файлы конфигурации Docker Compose из репозитория Первая Форма. Архив содержит преднастроенные конфигурации для различных сценариев развертывания ONLYOFFICE.

Cоздайте каталог, где будут храниться все файлы конфигурации и данные:

mkdir -p /opt/onlyoffice

cd /opt/onlyoffice

Создайте файл docker-compose.yml.

Пример docker-compose.yml (содержание может отличаться в зависимости от требуемой конфигурации).

services:

documentserver:

image: docker-public.1forma.ru/onlyoffice/documentserver:latest

container_name: documentserver

ports:

- '80:80

- '443:443'

volumes:

- ./documentserver/logs:/var/log/onlyoffice:Z

- ./documentserver/data:/var/www/onlyoffice/Data:Z

- ./documentserver/lib:/var/lib/onlyoffice:Z

- ./documentserver/db:/var/lib/postgresql:Z

environment:

- ALLOW_META_IP_ADDRESS

- ALLOW_PRIVATE_IP_ADDRESS

- AMQP_URI

- DB_HOST

- DB_NAME

- DB_PORT

- DB_PWD

- DB_TYPE

- DB_USER

- JWT_ENABLED

- JWT_HEADER

- JWT_IN_BODY

- JWT_SECRET

- LETS_ENCRYPT_DOMAIN

- LETS_ENCRYPT_MAIL

- ONLYOFFICE_HTTPS_HSTS_ENABLED

- ONLYOFFICE_HTTPS_HSTS_MAXAGE

- REDIS_SERVER_HOST

- REDIS_SERVER_PASS

- REDIS_SERVER_PORT

- SSL_CERTIFICATE_PATH

- SSL_DHPARAM_PATH

- SSL_KEY_PATH

- SSL_VERIFY_CLIENT

- TZ

- USE_UNAUTHORIZED_STORAGE

- WOPI_ENABLED

healthcheck:

test: ["CMD-SHELL", "curl -f http://localhost/healthcheck || exit 1"]

interval: 30s

timeout: 10s

retries: 3

start_period: 60s

stdin_open: true

restart: unless-stopped

networks:

onlyoffice:

networks:

onlyoffice:

Пояснения к параметрам:

, image: используется образ docker-public.1forma.ru/onlyoffice/documentserver:latest

, healthcheck: проверяется доступность /healthcheck , возвращающей HTTP 200

Рядом создайте .env:

# JWT Settings

JWT_ENABLED=true

JWT_SECRET=JWT_SECRET

JWT_HEADER=Authorization

JWT_IN_BODY=true

# WOPI Settings

WOPI_ENABLED=true

ALLOW_META_IP_ADDRESS=true

ALLOW_PRIVATE_IP_ADDRESS=true

USE_UNAUTHORIZED_STORAGE=true

# Timezone

TZ=Europe/Moscow

Пояснения к параметрам:

JWT_ENABLED — включение проверки JWT-токенов.
JWT_SECRET — секретный симметричный ключ для подписи JWT. Должен содержать не менее 32 символов. Размер ключа должен быть больше 256 бит.
JWT_HEADER — заголовок и включение передачи токена в теле запроса.
WOPI_ENABLED — включение поддержки WOPI-интеграции.
ALLOW_META_IP_ADDRESS, ALLOW_PRIVATE_IP_ADDRESS- — разрешают доступ к мета- и приватным IP адресам.
USE_UNAUTHORIZED_STORAGE — разрешает подключение к хранилищам с самоподписанными сертификатами.
TZ — устанавливает часовой пояс контейнера.

Запустите сервис:

docker compose up -d

Хранение данных вне контейнеров¶

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

/var/log/onlyoffice — для журналов (логов) ONLYOFFICE Docs.
/var/www/onlyoffice/Data — для сертификатов.
/var/lib/onlyoffice — для кэша файлов.

Мы настоятельно рекомендуем хранить данные вне Docker-контейнеров — на хост-машине. Это позволит вам легко обновлять ONLYOFFICE Docs при выходе новой версии без потери данных. Чтобы получить доступ к данным, расположенным вне контейнера, необходимо смонтировать тома. Это можно сделать с помощью volumes:

volumes:

- ./documentserver/logs:/var/log/onlyoffice:Z # для логов ONLYOFFICE Docs

- ./documentserver/data:/var/www/onlyoffice/Data:Z # для сертификатов

- ./documentserver/lib:/var/lib/onlyoffice:Z # для кэша файлов

- ./documentserver/db:/var/lib/postgresql:Z # для базы данных (если не используется внешний

сервис)

ℹ️ Обратите внимание: если вы монтируете папки, которые еще не существуют, они будут созданы автоматически, но права доступа к ним будут ограничены. Вам нужно будет вручную изменить права доступа на соответствующие

Обычно нет необходимости сохранять данные контейнера, так как его работа не зависит от состояния. Однако сохранение данных будет полезно:

для удобного доступа к данным контейнера, например, логам;
чтобы снять ограничения на объём данных внутри контейнера;
при использовании сервисов, запускаемых вне контейнера, таких как PostgreSQL, Redis, RabbitMQ.

Использование внешнего сервиса Redis¶

Docker-образ onlyoffice/documentserver содержит встроенный сервер Redis. Однако, если в вашей инфраструктуре уже работает выделенный Redis-сервер, использование встроенного может быть избыточным.

Преимущества подключения внешнего Redis:

Централизованная работа с кэшем и сессиями для всей инфраструктуры.
Независимость обновлений от отделенного сервиса.

Определите следующие переменные окружения:

REDIS_SERVER_HOST=REDIS_HOST

REDIS_SERVER_PORT=6379

REDIS_SERVER_PASS=REDIS_PASSWORD

Пояснения к параметрам:

REDIS_SERVER_HOST — IP или DNS вашего Redis-сервера.
REDIS_SERVER_PORT — порт (обычно 6379).
REDIS_SERVER_PASS — пароль (если Redis защищен).

После этого onlyoffice/documentserver отключит встроенный Redis и подключится к указанному.

Использование внешнего сервиса RabbitMQ¶

Образ также включает встроенный RabbitMQ. Использование внешнего брокера позволяет:

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

Для подключения внешнего сервиса RabbitMQ настройте строку подключения через переменную окружения:

AMQP_URI=amqp://guest:guest@rabbitmq

Пояснения к параметрам:

AMQP_URI — URI для подключения к RabbitMQ.

После этого Docs не будет запускать RabbitMQ внутри контейнера, а подключится к внешнему.

Использование внешнего SQL сервера¶

Внутренний образ содержит встроенный PostgreSQL, но для стабильности, резерва и масштабирования можно использовать внешний SQL-сервер (PostgreSQL, MSSQL, MariaDB и др).

Определите переменные окружения:

DB_TYPE=postgres

DB_HOST=DB_SERVER

DB_PORT=5432

DB_NAME=onlyoffice

DB_USER=onlyoffice

DB_PWD=DB_PASSWORD

Пояснения к параметрам:

DB_TYPE — тип СУБД: PostgreSQL, MSSQL, MariaDB, MySQL, oracle.
Остальные — подключение к внешней базе

Убедитесь, что база и пользователь созданы перед запуском.

Пример команд создания базы данных и пользователя PostgreSQL

-- Create OnlyOfice User

create user onlyoffice with inherit login password 'DB_PASSWORD';

-- Create OnlyOfice DB

create database onlyoffice

template template0

owner onlyoffice

encoding 'utf8'

lc_collate 'ru_RU.utf8'

lc_ctype 'ru_RU.utf8';

Пример команд создания базы данных и пользователя MSSQL

create database onlyoffice;

-- Создайте пользователя и назначьте права:
CREATE LOGIN onlyoffice WITH PASSWORD = '<надёжный_пароль>';
CREATE USER onlyoffice FOR LOGIN onlyoffice;
ALTER ROLE db_owner ADD MEMBER onlyoffice;

Запуск с использованием HTTPS¶

Доступ к ONLYOFFICE можно обезопасить с помощью SSL, чтобы предотвратить несанкционированный доступ. Сертификат SSL, выданный удостоверяющим центром (CA), обеспечивает доверие через подтверждённого поставщика. Вы можете автоматически получить сертификаты от Let's Encrypt или использовать собственные.

Переключение ONLYOFFICE Docs на HTTPS с использованием certbot

Самый простой способ — автоматическое получение сертификатов SSL от Let's Encrypt с помощью certbot.

Определите переменные окружения:

LETS_ENCRYPT_DOMAIN=yourdomain.com

LETS_ENCRYPT_MAIL=email@example.com

Пояснения к параметрам:

LETS_ENCRYPT_DOMAIN — доменное имя для сертификата.
LETS_ENCRYPT_MAIL — email-адрес для регистрации и восстановления.

Сертификат от Let's Encrypt будет автоматически сгенерирован и установлен. После этого ONLYOFFICE Docs будет доступен по адресу https://yourdomain.com

Подключение собственных сертификатов

Для обеспечения защищённого HTTPS-доступа к ONLYOFFICE Docs с собственными сертификатами необходимо предоставить SSL-сертификаты и задать соответствующие переменные окружения.

Настройте проброс сертификатов в контейнер в docker-compose.yml:

volumes:

- ./ssl/cert.crt:/ssl/cert.crt:ro

- ./ssl/private.key:/ssl/private.key:ro

- ./ssl/dhparam.pem:/ssl/dhparam.pem:r

Настройте переменные окружения в .env:

SSL_CERTIFICATE_PATH=/ssl/cert.crt

SSL_KEY_PATH=/ssl/private.key

SSL_DHPARAM_PATH=/ssl/dhparam.pem

Пояснения к параметрам:

ONLYOFFICE_HTTPS_HSTS_ENABLED — включение HSTS: по умолчанию true.
ONLYOFFICE_HTTPS_HSTS_MAXAGE — максимальный срок HSTS: 31536000.
SSL_VERIFY_CLIENT — проверка клиентских сертификатов: false.
SSL_CERTIFICATE_PATH — путь к SSL-сертификату.
SSL_KEY_PATH — путь к приватному ключу.
SSL_DHPARAM_PATH — путь к параметрам DH.

Использование ONLYOFFICE Docs за прокси-сервером¶

ONLYOFFICE Docs — это онлайн-приложение, которое часто интегрируется во внутренние сети. Во многих сетях используются веб-серверы-прокси, такие как NGINX, HAProxy и Træfik, для маршрутизации и балансировки трафика. Эти прокси обеспечивают безопасность, масштабируемость и контроль над подключениями.

Чтобы ONLYOFFICE Docs корректно работал за прокси, необходимо правильно настроить пересылаемые HTTP-заголовки. При использовании прокси важно передавать информацию о клиентском запросе серверу через специальные заголовки:

X-Forwarded-Proto — определяет исходный протокол, использованный клиентом (HTTP или HTTPS).
X-Forwarded-Host — указывает исходный хост, запрошенный клиентом.

В зависимости от инфраструктуры и целей, есть несколько основных сценариев настройки:

1. Обычный сценарий (прокси на локальный сервер)

2. HTTPS-прокси → HTTP-сервер

3. Виртуальный путь (виртуальный префикс)

4. Проксирование через Frontend Первая Форма

Обычный сценарий (прокси на локальный сервер)

Используется, если необходимо просто перенаправить входящий трафик на локальный сервер с ONLYOFFICE Docs.

Пример готовой конфигурации Nginx

upstream docservice {

server backendserver-address;

}

map $http_host $this_host {

"" $host;

default $http_host;

}

map $http_x_forwarded_proto $the_scheme {

default $http_x_forwarded_proto;

"" $scheme;

}

map $http_x_forwarded_host $the_host {

default $http_x_forwarded_host;

"" $this_host;

}

map $http_upgrade $proxy_connection {

default upgrade;

"" close;

}

proxy_set_header Upgrade $http_upgrade;

proxy_set_header Connection $proxy_connection;

proxy_set_header X-Forwarded-Host $the_host;

proxy_set_header X-Forwarded-Proto $the_scheme;

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

server {

listen 0.0.0.0:80;

listen [::]:80 default_server;

server_tokens off;

location / {

proxy_pass http://docservice;

proxy_http_version 1.1;

}

HTTPS-прокси → HTTP-сервер

Используется, когда необходимо обеспечить безопасное соединение с клиентом, но сам ONLYOFFICE Docs работает по HTTP. Все входящие соединения автоматически перенаправляются на HTTPS.

Пример готовой конфигурации Nginx

upstream docservice {

server backendserver-address;

}

map $http_host $this_host {

"" $host;

default $http_host;

}

map $http_x_forwarded_proto $the_scheme {

default $http_x_forwarded_proto;

"" $scheme;

}

map $http_x_forwarded_host $the_host {

default $http_x_forwarded_host;

"" $this_host;

}

map $http_upgrade $proxy_connection {

default upgrade;

"" close;

}

proxy_set_header Upgrade $http_upgrade;

proxy_set_header Connection $proxy_connection;

proxy_set_header X-Forwarded-Host $the_host;

proxy_set_header X-Forwarded-Proto $the_scheme;

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

server {

listen 0.0.0.0:80;

listen [::]:80 default_server;

server_name _;

server_tokens off;

return 301 https://$server_name:443$request_uri;

}

server {

listen 0.0.0.0:443 ssl;

listen [::]:443 ssl default_server;

server_tokens off;

root /usr/share/nginx/html;

ssl_certificate {{SSL_CERTIFICATE_PATH}};

ssl_certificate_key {{SSL_KEY_PATH}};

ssl_verify_client off;

ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";

ssl_protocols TLSv1.2 TLSv1.3; # TLSv1 и TLSv1.1 устарели и отключены (RFC 8996). Используйте только TLSv1.2 и TLSv1.3.

ssl_session_cache builtin:1000 shared:SSL:10m;

ssl_prefer_server_ciphers on;

add_header X-Content-Type-Options nosniff;

location / {

proxy_pass http://docservice;

proxy_http_version 1.1;

}

Виртуальный путь (виртуальный префикс)

Подходит в ситуациях, когда нужно разместить ONLYOFFICE Docs по определённому URL-префиксу (например, /office/ ) в рамках существующего веб-приложения.

Пример готовой конфигурации Nginx

upstream docservice {

server backendserver-address;

}

map $http_x_forwarded_proto $the_scheme {

default $http_x_forwarded_proto;

"" $scheme;

}

map $http_x_forwarded_host $the_host {

default $http_x_forwarded_host;

"" $host;

}

map $http_upgrade $proxy_connection {

default upgrade;

"" close;

}

proxy_set_header Upgrade $http_upgrade;

proxy_set_header Connection $proxy_connection;

proxy_set_header X-Forwarded-Host $the_host/office;

proxy_set_header X-Forwarded-Proto $the_scheme;

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

server {

listen 0.0.0.0:80;

listen [::]:80 default_server;

server_tokens off;

location /office/ {

proxy_pass http://docservice/;

proxy_http_version 1.1;

}

Проксирование ONLYOFFICE через Frontend «Первая Форма»

Frontend-сервис приложения Первая Форма может работать в режиме reverse proxy, если в тракте запроса не используется другое проксирующее решение.

Вы можете настроить проксирование запросов к ONLYOFFICE через виртуальный путь /office например: https://1f.domain/office

Для этого необходимо задать переменную окружения в конфигурации сервиса 1forma frontend:

PROXY_ONLYOFFICE_URL=http://onlyoffice.service

ℹ️ В конфигурации 1F-SPA эта переменная называется SPA_PROXY_ONLYOFFICE_URL. Убедитесь что используете правильное имя для вашего способа развёртывания.

Пояснения к параметрам:

http://onlyoffice.service — адрес сервиса ONLYOFFICE во внутренней сети (например, внутри Docker Compose).
PROXY_ONLYOFFICE_URL — сообщает фронтенду, куда перенаправлять запросы с пути /office.

Настройка ONLYOFFICE в приложении Первая Форма¶

Для корректной работы ONLYOFFICE в приложении Первая Форма необходимо выполнить два этапа настройки:

1. Настроить симметричный ключ для генерации и проверки JWT-токена.

2. Указать параметры OfficeOnlineEditor в Кастомных настройках приложения.

Настройка секрета для симметричного ключа JWT

JWT (JSON Web Token) используется для обеспечения безопасности взаимодействия между компонентами. Токен подписывается симметричным секретом, который должен быть одинаково известен как отправителю, так и получателю.

Требования к секрету:

Должен содержать не менее 32 символов.
Должен быть достаточно сложным (рекомендуется использовать случайно сгенерированную строку).

Способы настройки секрета:

1. Через файл конфигурации appsettings.json:

"R7": {

"SecretKey": "JWT_SECRET"

}

2. Через переменные окружения:

R7_SECRET_KEY=JWT_SECRET

Настройка параметров OfficeOnlineEditor

Для настройки ONLYOFFICE в приложении Первая Форма небходимо указать нужное в значение ключа OfficeOnlineEditor в разделе Кастомных настройках приложения.

Ключ имеет вид Json — объекта:

{"editor": "OnlyOffice", "settings": {"serverAddress":"https://ru.1forma.ru/office", "allowedIPs": \[\]}}

В атрибут settings можно задать адрес сервера и список разрешенных подсетей.

Пояснения к параметрам:

"editor": "OnlyOffice" — указывает использование редактора.

ℹ️ Обратите внимание: для корректной работы с онлайн-редакторами необходимо учитывать версию платформы. В версиях 2.264 Кассиопея и ниже в параметре "editor" для работы с OnlyOffice необходимо указывать значение "r7". Начиная с версии 2.265 Цефей и выше для одноименного редактора доступно значение "OnlyOffice", использование "r7" остается только для редактора Р7-Офис

"serverAddress" — адрес сервера ONLYOFFICE (например, https://1f.domain/office/).
"allowedIPs" — список разрешенных IP-адресов или подсетей. Может быть пустым.

После внесения всех настроек перезапустите приложение, чтобы изменения вступили в силу.

Полезные ссылки

Исходники Docker-образа (GitHub) — Готовый контейнер для запуска ONLYOFFICE Docs с инструкциями и переменными окружения

Примеры настройки Reverse Proxy (GitHub) — Готовые конфигурации для NGINX, Apache, HAProxy и Træfik для работы через прокси.