# Сервер совместимости A4 с API ONLYOFFICE: установка

Версия сборки 2026.4.0.6.

## Что нового в 2026.4.0.6

1. **Moodle открывает и сохраняет документы.** Если в модуле ONLYOFFICE Moodle адрес «для запросов сервера документов»
   отличается от адреса самого Moodle (в Docker и за обратным прокси так почти всегда), Moodle отвечает переадресацией.
   Раньше подпись запроса на ней терялась: файл не открывался, а сохранение уходило
   пустым запросом. Теперь сервер проходит переадресации сам, подписывая каждый шаг, и сохранение доходит тем же `POST`.
2. **ownCloud получает правку при закрытии.** Если окно редактора открывалось, но не подключалось (оборванная загрузка,
   повторное открытие), такой «висящий» вход держал документ до 20 минут, и всё это время в ownCloud лежал файл без
   правки. Теперь при уходе последнего участника неподключившиеся входы отбрасываются, и файл сохраняется сразу.
3. **Образы редакторов — из комплекта Сервера A4 2026-10-17** (A4 2026.4.0.38487392181, F1 2026.4.0.20261017,
   P2 2026.4.0.29), с исправлением безопасности F1.
4. **`docker-compose.yml` запускается на ARM64.** У сервера совместимости больше не прибита платформа `linux/amd64`:
   загруженный архив `-arm64` теперь поднимается, а не отвергается Docker'ом.
5. **Проверено вживую 21.10.2026** на этой версии: Nextcloud 32, ownCloud 10.15 и 11, Seafile CE 14, Moodle 4.5 —
   `.docx`, `.xlsx`, `.pptx` и `.xlsm` (макросы байт в байт); у Moodle `.xlsm` модуль открывает только для просмотра.
   Протоколы — в `protocols/`.

Обновление с 2026.4.0.5: загрузить архив этого комплекта (`docker load`), в `docker-compose.yml` указать образ
`a4-compat:2026.4.0.6` и выполнить `docker compose up -d`. Настройки прежние; образы редакторов обновить по разделу
«Что нужно».

Сервер совместимости говорит на API ONLYOFFICE Document Server. Системы, у которых уже есть коннектор «ONLYOFFICE Docs»
(Nextcloud, ownCloud, Seafile, Alfresco, Moodle, Битрикс24, Confluence, Jira, Mattermost, Redmine и другие), указывают
на этот сервер, и их документы открываются в редакторах A4: `.docx` — в A4, `.xlsx`, `.xlsm`, `.xlsb` —
в F1, `.pptx` — в P2. Файлы и учётные записи остаются в вашей системе: сервер скачивает документ, когда его
открывают, держит в памяти, пока его правят, и каждое сохранение отдаёт обратно по адресу колбэка системы.

## Что нужно

- Машина с Linux и Docker: x86_64 (архив `-amd64`) или ARM64 (архив `-arm64`). Образы редакторов — только x86_64.
- Образы серверов редакторов A4, F1 и P2 — из комплекта Сервера A4 2026-10-17: https://dl.plantype.ru/a4-server/release/2026-10-17/
  (`A4-2026.4.0.38487392181-webhost-docker.tar.gz`, `F1-2026.4.0.20261017-webhost-docker.tar.gz`, `P2-2026.4.0.29-server-docker.tar.gz`;
  самый свежий комплект всегда лежит в https://dl.plantype.ru/a4-server/release/current/).
  `docker-compose.yml` этого комплекта ждёт метки `:latest`, поэтому после загрузки поставьте их:
  `docker tag a4-webhost:2026.4.0.38487392181 a4-webhost:latest`, `docker tag f1-webhost:2026.4.0.20261017 f1-webhost:latest`,
  `docker tag p2-server:2026.4.0.29 p2-server:latest`. Один `docker-compose.yml` поднимает все четыре контейнера.
- Обратный прокси с HTTPS (nginx, Caddy) на единственный наружный порт. Система, браузер и этот сервер должны
  достигать друг друга по имени.

## Установка

```bash
gunzip -c A4-2026.4.0.6-compat-docker-amd64.tar.gz | docker load          # этот сервер: образ a4-compat:2026.4.0.6
# архивы редакторов загружаются той же командой
cp docker-compose.yml /srv/a4-compat/docker-compose.yml
```

В `docker-compose.yml` заполнить:

- `JWT_SECRET` — общий секрет; то же значение вводится в системе в поле «секретный ключ»;
- `--public-url` — адрес, по которому система будет звать этот сервер, с https;
- образы трёх редакторов, если их метки отличаются от комплекта.

Затем:

```bash
cd /srv/a4-compat && docker compose up -d
```

## Проверка

```bash
curl -s http://127.0.0.1:8080/healthcheck    # печатает: true
curl -s http://127.0.0.1:8080/health         # JSON: "status": "ok", форматы, редакторы
```

Та же проверка, что делают системы, по шагам:

```bash
docker compose exec compat node /app/compat-doctor.mjs --server http://127.0.0.1:8080 --secret "<JWT_SECRET>"
```

Печатает `✓`/`✗` по шагам: `healthcheck`, команда `version` с подписью, отказ команде без подписи, пробная конвертация с
выкачиванием результата. Код выхода 1 — есть красный шаг.

Список систем и их состояние — `SISTEMY.md` этого комплекта; у «работает» — ссылка на протокол живого круга в
`protocols/`.

В настройках ONLYOFFICE вашей системы ввести публичный адрес (например `https://office.example.ru/`) и секрет. Проверка
соединения у системы зовёт `/healthcheck`, команду `version` и пробную конвертацию — всё три отвечают. Открыть документ
из системы: он открывается в редакторе; сохранить; в системе появляется новая версия.

## Обратный прокси (nginx)

Одна локация. Правка идёт по WebSocket, поэтому заголовки апгрейда обязательны:

```nginx
location / {
  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_set_header X-Forwarded-Proto $scheme;
  proxy_read_timeout 3600s;
  client_max_body_size 200m;
}
```

## Доводы

| довод | что делает |
|---|---|
| `--word`, `--cell`, `--slide` | адреса серверов редакторов по роду документа; хотя бы один |
| `--public-url` | публичный адрес этого сервера (ставится в ссылки, которые уходят системе) |
| `--jwt-secret` или `JWT_SECRET` | общий секрет; без него сервером воспользуется любая система |
| `--jwt-header` | имя заголовка с токеном, если система использует не стандартное (`AuthorizationJWT`) |
| `--idle-min` | через сколько минут без единого запроса документ закрывается и об этом сообщается системе (по умолчанию 20) |
| `COMPAT_LOG=requests` (окружение) | журнал каждого запроса с кодом, скачиваний и колбэков — ответ на «ошибка службы документов» у системы |

Значение довода — после ПРОБЕЛА: `--word http://word:8090`, а не `--word=...`.

## Как ложится API

| что зовёт система | что отвечает сервер |
|---|---|
| `web-apps/apps/api/documents/api.js` | `DocsAPI.DocEditor` открывает редактор в кадре |
| `/healthcheck` | `true` |
| `/coauthoring/CommandService.ashx`, `/command` | `version`, `info`, `drop`, `forcesave`, `meta`, `license` |
| `/ConvertService.ashx`, `/converter` | «тот же формат в тот же» и `txt` → `docx` (так коннекторы проверяют соединение) |
| колбэк (`editorConfig.callbackUrl`) | статус 1 при открытии, 6 при каждом сохранении, 2 или 4 когда уходит последний |

Просмотр (`mode: "view"`, `permissions.edit: false` или без `callbackUrl`): файл открывается, запись отвергается словами.

Чего нет: конвертации между форматами, двоичных изменений каждой правки внутри архива истории, шрифтов и плагинов
ONLYOFFICE, правки форматов вне перечисленных. Статус 2 содержит `changesurl`: архив с `changes.json` (кто и когда
сохранял). Сохранения уходят статусом 6 по мере дела и статусом 2 при закрытии документа; системы, которые действуют
только по статусу 2, получают итоговый файл, когда уходит последний редактирующий.

## Системы на WOPI

FileCloud, OpenCloud и Case.one подключают редактор по WOPI, а не по API ONLYOFFICE. Им указывают
`https://<этот сервер>/hosting/discovery`. Есть два режима:

- сервер склеивает WOPI-обнаружение редакторов в один ответ; редакторы запускаются в WOPI-режиме с публичным адресом
  `https://<этот сервер>/<род>` — см. их инструкции по установке;
- с `--wopi-hosts https://<разрешённый-хост>` сервер объявляет совместимый с Collabora вход, сам выполняет
  `CheckFileInfo`, `GetFile`, замки и `PutFile` и открывает все три рода документов через тот же адрес.

В первом режиме редактор презентаций пока не подписывает WOPI-запросы: строгий хост с обязательной proof-подписью
его отвергнет. Второй режим использует `access_token` хоста и не выдаёт его браузеру или журналу.

## Браузеры и куки

Редакторы узнают человека по куке, выставленной на адресе этого сервера, пока редактор открыт внутри страницы системы.
Браузеры, блокирующие сторонние куки (Safari по умолчанию, строгие настройки Chrome и Firefox), пропускают это только
когда система и сервер живут на одном сайте, например `cloud.example.ru` и `office.example.ru`. Ставьте сервер
совместимости под тот же домен, что и систему.

Документация и свежие сборки: https://tech.plantype.ru/