# Подключение редакторов A4 к коробочному Битрикс24

Краткая версия руководства по установке. Полное руководство со схемой, снимками экрана и
листом планирования:

- открыть в браузере (в редакторе A4): https://tech.plantype.ru/demo/a4-rukovodstvo/
- Word: https://tech.plantype.ru/media/Rukovodstvo-A4-Bitrix24-2026-10-14.docx
- PDF: https://tech.plantype.ru/media/Rukovodstvo-A4-Bitrix24-2026-10-14.pdf

Что получится: в Диске портала у файлов .docx, .xlsx, .xlsm и .pptx появится команда
«Редактировать → A4». Файл откроется в браузере, а правка сохранится новой версией того же
файла. Несколько сотрудников смогут править один файл одновременно. Файлы остаются в Диске.
Время — около часа, если сервер, имя в DNS и сертификат уже есть.

## 1. Как это работает

1. Сотрудник открывает файл в Диске и выбирает «Редактировать → A4».
2. Портал узнаёт у сервера A4, какой редактор открывает этот тип файла (адрес discovery).
3. Браузер открывает окно редактора на сервере A4 по HTTPS (правка идёт через WebSocket).
4. Редактор берёт файл у портала и сохраняет правку новой версией (протокол WOPI, каждый запрос
   подписан ключом сервера A4).

Все соединения — HTTPS, порт 443. Документы не уходят в облако разработчика.

## 2. Подготовка

| Параметр | Минимум | Рекомендуем |
|---|---|---|
| ОС сервера A4 | Linux x86-64 | Ubuntu 22.04/24.04, Debian 12, Astra Linux, РЕД ОС |
| Docker | Docker Engine 24, docker compose v2 | последняя стабильная |
| Процессор | 2 ядра | 4 ядра для 10+ открытых файлов |
| Память | 4 ГБ | 2 ГБ + 250 МБ на открытый файл; 8 ГБ ≈ 20 файлов |
| Диск | 10 ГБ | 20 ГБ (образы 1,3 ГБ, архивы 0,5 ГБ) |
| Портал | коробочный Битрикс24 с модулем «Диск», PHP 8.2+, HTTPS | |

Сеть: браузеры → портал и сервер A4 (443); сервер портала → сервер A4 (443, discovery);
сервер A4 → портал (443, WOPI). Сервер A4 должен открывать портал по тому же адресу, что и
браузер. Контейнеры слушают только 127.0.0.1 (8090, 8092, 8094, 8096); наружу — только nginx.

Подготовьте: имя сервера A4 в DNS (например `office.example.ru`) и сертификат TLS, которому
доверяют браузеры и сервер портала. Если сертификат внутренний — корневой сертификат центра
должен быть в доверенных на сервере портала.

Лист планирования:

| Параметр | Пример | Ваше значение |
|---|---|---|
| Адрес портала (PORTAL_URL) | https://portal.example.ru | |
| Адрес сервера A4 (EDITORS_URL) | https://office.example.ru | |
| Каталог комплекта | /opt/a4-server | |
| Сертификат и ключ | /etc/ssl/certs/office.example.ru.crt, /etc/ssl/private/office.example.ru.key | |
| discovery таблиц и документов | https://office.example.ru/hosting/discovery | |
| discovery презентаций P2 | https://office.example.ru/p2/hosting/discovery | |

## 3. Установка «Сервера A4»

**Шаг 1. Каталог.**

```sh
sudo mkdir -p /opt/a4-server && sudo chown $USER /opt/a4-server && cd /opt/a4-server
```

**Шаг 2. Скачайте комплект** (15 файлов, около 515 МБ):

```sh
U=https://dl.plantype.ru/a4-server/release/current
curl -fsSO $U/SHA256SUMS
for f in $(awk '{print $2}' SHA256SUMS); do curl -fsSO "$U/$f"; done
ls | wc -l                       # 15
```

**Шаг 3. Проверьте суммы:**

```sh
sha256sum -c SHA256SUMS | grep -c ': OK'   # 14
```

**Шаг 4. Загрузите образы:**

```sh
docker load -i F1-*-webhost-docker.tar.gz
docker load -i A4-*-webhost-docker.tar.gz
docker load -i P2-*-server-docker.tar.gz
```

Ожидается три строки `Loaded image: …` (f1-webhost, a4-webhost, p2-server).

**Шаг 5. Файл .env** (со схемой https://, без косой черты в конце):

```sh
cat > .env <<'EOF'
PORTAL_URL=https://portal.example.ru
EDITORS_URL=https://office.example.ru
EOF
```

`PORTAL_URL` — адрес портала, как его видит браузер; только ему редакторы отдают и сохраняют
файлы. `EDITORS_URL` — адрес сервера A4 за nginx.

**Шаг 6. Запустите:**

```sh
docker compose -f docker-compose-wopi.yml up -d
docker compose -f docker-compose-wopi.yml ps   # 4 контейнера Up, p2 — (healthy)
```

**Шаг 7. Проверьте на самом сервере:**

```sh
curl -s http://127.0.0.1:8096/hosting/discovery | grep -o 'ext="[a-z]*"' | sort -u
# ext=""  ext="docx"  ext="xlsb"  ext="xlsm"  ext="xlsx"
curl -s http://127.0.0.1:8094/p2/hosting/discovery | grep -c pptx   # 1 или больше
```

Ответ «разные proof-ключи» — F1 и A4 запущены не этим файлом, повторите шаг 6.

**Шаг 8. nginx и сертификат:**

```sh
sudo cp nginx-wopi.conf /etc/nginx/conf.d/a4-server.conf
sudo nano /etc/nginx/conf.d/a4-server.conf     # server_name, ssl_certificate, ssl_certificate_key
sudo nginx -t && sudo systemctl reload nginx
```

Не удаляйте строки Upgrade, Connection и Cookie — без них окно редактора будет пустым.

**Шаг 9. Проверьте с сервера портала** (без -k):

```sh
curl -s https://office.example.ru/hosting/discovery | head -c 200
curl -s https://office.example.ru/p2/hosting/discovery | head -c 200
```

Ожидается начало XML `<wopi-discovery>`. «SSL certificate problem» — добавьте корневой
сертификат (`update-ca-certificates` или `update-ca-trust`) и перезапустите PHP-FPM.

## 4. Модуль в Битрикс24

1. Marketplace → Каталог решений → найдите **A4** → «A4: документы, таблицы и презентации в
   Диске» → **Установить**. Или https://marketplace.1c-bitrix.ru/solutions/a4office.wopi/.
2. Настройки → Настройки продукта → Настройки модулей → «A4: документы, таблицы и презентации в
   Диске»:

| Поле | Значение |
|---|---|
| Адрес описания редакторов (discovery) | https://office.example.ru/hosting/discovery |
| Адрес сервера презентаций P2 (discovery) | https://office.example.ru/p2/hosting/discovery |
| Проверять подписи запросов редактора | отмечено |
| Публичный адрес портала | https://portal.example.ru (= PORTAL_URL) |

3. **Сохранить**.

Без доступа к Маркетплейсу: архив модуля с https://dl.plantype.ru/a4-bitrix24/release/ —
распакуйте в `local/modules/`, установите на странице «Модули».

## 5. Проверка

- Откройте файл в Диске → «…» → «Редактировать» → **A4**, внесите правку, дождитесь надписи о
  сохранении. В истории появилась новая версия, после повторного открытия правка на месте.
- Таблицы (.xlsx, .xlsm, .xlsb) открываются в F1, презентации (.pptx) — в P2.
- Совместная работа: два сотрудника видят курсоры и правки друг друга (правьте разные абзацы).
- Новый файл: Диск → «Добавить» → «A4» → «Документ», «Таблица» или «Презентация» (модуль 0.3.9
  и новее).

## 6. Обслуживание

```sh
docker compose -f docker-compose-wopi.yml stop | start | restart | ps
docker compose -f docker-compose-wopi.yml logs --tail 100 a4     # f1, p2, discovery
```

Обновление: новый выпуск — в отдельный каталог, суммы, `docker load`, перенесите `.env`,
`docker compose -f docker-compose-wopi.yml up -d`, проверка (шаг 7). Тома `proof` и `p2-data`
не удаляйте (в них ключи подписи), не запускайте `down -v`.

Резервное копирование: `.env`, конфигурация nginx, сертификат и тома с ключами:

```sh
for v in proof p2-data; do
  docker run --rm --entrypoint tar -v a4-server-wopi_$v:/v -v $PWD:/b \
    $(docker images --format '{{.Repository}}:{{.Tag}}' | grep -m1 f1-webhost) czf /b/backup-$v.tgz -C /v .
done
```

Откат: в каталоге прежнего выпуска `docker compose -f docker-compose-wopi.yml up -d`.

## 7. Неполадки

| Признак | Что сделать |
|---|---|
| В меню нет A4 | модуль установлен? адрес discovery заполнен? |
| «Редактор не открылся» | шаг 9 с сервера портала: DNS, порт 443, сертификат |
| Пустая страница вместо редактора | в nginx нет Upgrade/Connection (шаг 8) |
| Редактор открылся без файла | сервер A4 → портал недоступен или PORTAL_URL ≠ публичный адрес портала |
| Пустой экран у презентаций | адрес P2 должен заканчиваться на /p2/hosting/discovery |
| «Файл изменили в другом месте», 409 | закройте старые вкладки, подождите до 30 минут |
| 401 после переустановки | повторите через минуту; не помогло — удалите `bitrix/cache/a4office.wopi` на портале |
| «Добавить → A4» не создаёт файл | обновите решение до 0.3.9 и новее |

## Поддержка

partner@a4-office.ru — рабочие дни 9:00–18:00 МСК. Приложите выпуск комплекта, версию модуля,
вывод `docker compose -f docker-compose-wopi.yml ps` и журналы за время ошибки.