# Онлайн-просмотр файлов — Решение проблем

Руководство по диагностике проблем с онлайн-просмотром и редактированием файлов в 1Форме. Охватывает ONLYOFFICE, Р7-Офис и встроенный просмотрщик.

> **Если площадка собрана как 1F Certificate Edition (ФСТЭК):** онлайн-просмотр и редактирование документов (ONLYOFFICE / Р7-Офис / Office WebApps) в этой сборке отсутствуют по дизайну — подсистема исключена из сборки целиком. Отсутствие действия «Открыть в редакторе» и маршрутов `api/r7/*` — штатное поведение, а не ошибка настройки. Дальнейшая диагностика в этом руководстве — для полной сборки.

---

## 1. Настройка по умолчанию: Скачать vs Просмотр

**Проблема.**

При клике на файл MS Office происходит скачивание вместо онлайн-просмотра.

### Причина

Действие при клике управляется настройкой `FileOnClickActionMode` на двух уровнях:

| Уровень | Где настраивается | Приоритет |
|---------|-------------------|-----------|
| **Пользователь** | Личные настройки пользователя → «Действие с файлами MS Office при клике» | Высший (если не «По умолчанию») |
| **Общие настройки** | Кастомные настройки приложения (`sys_user`) | Применяется, когда у пользователя стоит «По умолчанию» |

Значения `FileOnClickActionMode` (колонка `Users.FileOnClickActionMode`, тип `int`):

| Значение | Код | Описание |
|----------|-----|----------|
| 0 | `Download` | Скачать файл |
| 1 | `ShowInOfficeOnlineEditor` | Открыть для просмотра в веб-интерфейсе |
| 2 | `EditInWebDav` | Открыть для редактирования в десктопном приложении (WebDav) |
| 3 | `Default` | По умолчанию (берётся из общих настроек) |

**Типичный сценарий.**

У пользователя стоит `Default` (3) → система берёт значение из общих настроек → там стоит `Download` (0) → файл скачивается.

**Диагностика.**

```sql
-- Проверить настройку конкретного пользователя
SELECT UserID, Login, FileOnClickActionMode
FROM Users
WHERE UserID = {userId};

-- Массовая проверка: сколько пользователей на каком режиме
SELECT FileOnClickActionMode, COUNT(*) AS Cnt
FROM Users
GROUP BY FileOnClickActionMode;
```

**Решение.**

1. Изменить настройку конкретного пользователя через интерфейс: Настройки пользователя → «Действие с файлами MS Office при клике» → «Открыть для просмотра в веб-интерфейсе».
2. Изменить общую настройку для всех пользователей с режимом «По умолчанию»: Администрирование → Кастомные настройки приложения.

---

## 2. ONLYOFFICE / Р7-Офис не отвечает

### 2.1 DNS resolution в Docker

**Симптом:** «онлайн просмотр периодически не работает — падает ошибка резолва DNS». Ошибка появляется нестабильно, может проходить и возвращаться.

**Причина:** сервер приложения 1Ф обращается к ONLYOFFICE по внутреннему hostname. Если ONLYOFFICE запущен в Docker, контейнер 1Ф (или хост) может не резолвить hostname ONLYOFFICE-сервера через стандартный DNS.

**Диагностика:**

1. Проверить, какой `serverAddress` указан в настройке `OfficeOnlineEditor`:
```sql
SELECT [Key], [Value]
FROM SettingsCustom
WHERE [Key] = 'OfficeOnlineEditor';
```

2. С сервера приложения 1Ф проверить доступность ONLYOFFICE:
```bash
# Проверка DNS resolution
nslookup <hostname-из-serverAddress>

# Проверка доступности
curl -I <serverAddress>
```

3. Если ONLYOFFICE в Docker — проверить сетевую конфигурацию контейнера:
```bash
docker inspect <container_name> | grep -A 20 "Networks"
```

**Решение:**

Добавить `extra_hosts` в `docker-compose.yml` контейнера, который обращается к ONLYOFFICE (или наоборот):

```yaml
services:
  app:
    extra_hosts:
      - "onlyoffice.local:192.168.1.100"
```

Либо указать IP-адрес вместо hostname в `serverAddress`:

```json
{"editor": "OnlyOffice", "settings": {"serverAddress": "https://192.168.1.100/office"}}
```

Альтернативы:

- Использовать Docker bridge network для обоих контейнеров (если оба в Docker)
- Настроить DNS-сервер внутренней сети для резолва hostname

### 2.2 Сервер ONLYOFFICE недоступен

**Симптом:** документы не открываются в онлайн-редакторе, ошибка в консоли браузера при загрузке iframe.

**Диагностика:**

1. Проверить `serverAddress` (см. SQL выше).
2. С сервера 1Ф — `curl -I <serverAddress>`.
3. Проверить, запущен ли контейнер/сервис ONLYOFFICE:
```bash
docker ps | grep -i office
systemctl status onlyoffice
```

4. Проверить логи ONLYOFFICE:
```bash
docker logs <onlyoffice-container> --tail 100
```

**Решение:** перезапустить контейнер/сервис, проверить сертификаты, проверить firewall.

### 2.3 Неверная конфигурация OfficeOnlineEditor

**Симптом:** редактор не открывается или открывается в неожиданном режиме.

**Что проверить:**

| Параметр | Что проверить |
|----------|--------------|
| `editor` | Версия <= 2.264: `"r7"` для OnlyOffice. Версия >= 2.265: `"onlyOffice"` для OnlyOffice, `"r7"` только для Р7-Офис. Значение `"webApps"` ранее использовалось для Office Web Apps Server — в актуальной сборке не работает (OWA удалён после миграции на .NET Core). |
| `serverAddress` | URL доступен с сервера 1Ф |
| `allowedIPs` | IP сервера 1Ф входит в список (или список пуст) |
| Secret в `appsettings.json` | Секция `R7` → `SecretKey` задан (не короче 32 символов) и совпадает с `JWT_SECRET` сервиса документов |

```sql
-- Проверка текущей конфигурации
SELECT [Key], [Value]
FROM SettingsCustom
WHERE [Key] = 'OfficeOnlineEditor';
```

Корректный формат ключа:
```json
{"editor": "onlyOffice", "settings": {"serverAddress": "https://domain/office", "allowedIPs": [], "internalKeyLifetimeHours": 12}}
```

### 2.4 Документ открывается, но сохранение не проходит

**Симптом:** после обновления площадки документ в Р7-Офис или ONLYOFFICE открывается, а сохранение из редактора не создаёт новую версию; в журнале приложения есть строка отказа на маршруте редактора.

**Причина:** платформа принимает сохранение только с подписанным обратным вызовом и только с адреса сервиса документов, указанного в `serverAddress`. Отказ возможен, если не задан общий секрет `R7:SecretKey`, у сервиса документов не включена подпись, адрес содержимого не совпал с `serverAddress` или часы серверов разошлись больше чем на 5 минут.

**Решение:** расшифровка по коду ответа и строкам журнала — в [решении проблем с файлами](https://help.1forma.ru/domains/files/support-guide.md), раздел 4.7, и в руководстве [ONLYOFFICE Docs](https://help.1forma.ru/maintenance_guide/office/onlyofficedocs.md). Признак настройки, а не сбоя: сохранение поверх версии, загруженной другим пользователем, отклоняется ответом 410 — чужая версия при этом не затирается.

---

## 3. Ошибки при открытии конкретных форматов

### 3.1 Ограничения форматов: старые Office и PDF

**Симптом:** файлы старых форматов Office не открываются или открываются с ошибками.

**Причина:** ONLYOFFICE / Р7-Офис поддерживает преимущественно новые форматы (`.docx`, `.xlsx`, `.pptx`). Старые форматы (`.doc`, `.xls`, `.ppt`) могут открываться с ограничениями.

**Решение:**

- Конвертировать файлы в новые форматы
- Скачать и открыть локально

**PDF не открывается в ONLYOFFICE.**

**Симптом:** PDF не открывается или открывается с ошибками в онлайн-редакторе.

**Что проверить:**

- Поддерживает ли установленная версия ONLYOFFICE / Р7-Офис формат PDF
- PDF-файлы открываются встроенным просмотрщиком 1Ф (без ONLYOFFICE). Если встроенный просмотрщик не работает — проблема на стороне браузера

### 3.2 Файлы из .eml — ArgumentNullException: fileKey

**Симптом:** `System.ArgumentNullException: fileKey` или `ArgumentException: Invalid key (tus:...)` при открытии office-документа из вложения .eml файла.

**Причина:** До версии **2.266.554** система не поддерживала TUS-ключи (`tempfile:tus:...`) при работе с email-вложениями.

**Диагностика:**

1. Проверить версию системы.
2. Проверить логи:
```bash
grep -i "Invalid key" logs/uniform-api.log
grep -i "ArgumentException\|ArgumentNullException" logs/tcclasslib.log
```

**Решение:**

- Версия < 2.266.554 → **обновить систему**. Это критичное исправление.
- Версия >= 2.266.554 → проверить настройки TUS в `appsettings.json` и работу job `CleanExpiredFilesFromPreuploadedTusStoreJob`.

**Временное решение** (для версий < 2.266.554): скачать файл и открыть локально.

### 3.3 Ограничение CE: 20 одновременных сессий

**Симптом:** документ открывается только в режиме просмотра, хотя у пользователя есть права на редактирование. Проблема проявляется при большом числе одновременных пользователей.

**Причина:** ONLYOFFICE Community Edition ограничивает число одновременных сессий редактирования — максимум **20 вкладок**. При превышении все последующие подключения переходят в режим только для чтения.

**Диагностика:**

- Проверить нагрузку на ONLYOFFICE: сколько пользователей одновременно работают.
- Логи ONLYOFFICE: ограничение фиксируется в логах сервера.

**Решение:**

- Для > 20 одновременных редакторов: перейти на Enterprise-версию ONLYOFFICE или Р7-Офис
- Кластеризация CE не поддерживается. Можно запустить несколько независимых реплик, но при совместном редактировании одного документа возможна рассинхронизация

---

### 3.4 Неподдерживаемый формат: понятный отказ вместо ошибки

**Симптом:** при открытии файла в Р7-Офис приходит сообщение о неподдерживаемом формате, документ не открывается; в интерфейсе это может выглядеть как сбой открытия.

**Причина:** расширение файла не входит в список поддерживаемых редактором, поэтому конфигурация редактора (`/api/r7/config`) не собирается. Система отдаёт отказ — сообщение «Один или более файлов имеет неподдерживаемый формат(расширение).» — и **не пишет** запись в журнал ошибок: отказ по формату не считается ошибкой сервера.

**Версии:** в сборке 2.268 «Скульптор» запрос `/api/r7/config` для файла `.dotx` завершался необработанным `System.ArgumentException: File with extension 'DOTX' is not supported` с кадром `Valhalla.Utils/DocumentTypeHelper.cs`, и в лог попадала запись. После исправления шаблоны Word `.dotx` открываются в редакторе как документы Word, документы поддерживаемых форматов (`.docx`, `.xlsx`, `.pptx`) отдаются как раньше, а для прочих расширений приходит только сообщение об отказе.

**Что проверить:**

- расширение файла — поддерживает ли его редактор (для шаблонов Word поддерживается `.dotx`);
- версию сборки: до исправления такой запрос попадает в журнал ошибок как `System.ArgumentException: File with extension ... is not supported`, после — нет;
- получил ли пользователь сообщение или HTTP 400 — это штатный отказ, а не ошибка конфигурации редактора.

**Решение:** открыть документ локальным приложением или сохранить его в поддерживаемом формате. Искать ошибку в настройках редактора в этом случае не нужно.

## 4. Диагностика

### 4.1 Логи

Где искать ошибки онлайн-просмотра:

| Лог | Что содержит |
|-----|-------------|
| `logs/uniform-api.log` | Ошибки API онлайн-редактора и работы с файлами |
| `logs/tcclasslib.log` | Ошибки онлайн-редактора: формат ключей, доступ к файлам |
| Консоль браузера | Ошибки загрузки iframe, CORS, сетевые ошибки |
| Docker-логи ONLYOFFICE | Внутренние ошибки сервера документов |

**Типичные ошибки в логах:**

| Ошибка | Причина | Решение |
|--------|---------|---------|
| `ArgumentException: Invalid key (tus:...)` | Версия < 2.266.554, TUS-ключи не поддерживаются | Обновление системы |
| `ArgumentNullException: fileKey` | fileKey не передан (null/empty) | Проверить источник файла, логи |
| `NotFoundException: Preuploaded file not found` | Файл в PreUploadedFiles отсутствует или истёк | Проверить TTL, job очистки |
| `UnauthorizedException: Access denied` | Нет прав на файл | Проверить права пользователя |
| DNS resolution error | Hostname ONLYOFFICE не резолвится | См. секцию 2.1 |

### 4.2 Проверка конфигурации

SQL-запросы для проверки конфигурации редактора:

```sql
-- 1. Настройки редактора
SELECT [Key], [Value]
FROM SettingsCustom
WHERE [Key] = 'OfficeOnlineEditor';

-- 2. Тип редактора
SELECT JSON_VALUE([Value], '$.editor') AS Editor,
       JSON_VALUE([Value], '$.settings.serverAddress') AS ServerAddress
FROM SettingsCustom
WHERE [Key] = 'OfficeOnlineEditor';

-- 3. Настройка действия при клике на файл (конкретный пользователь)
SELECT UserID, Login, FileOnClickActionMode
FROM Users
WHERE Login = '{login}';

-- 4. Preupload-файлы (диагностика проблем с eml)
SELECT ID, FileName, DateUploaded, UserID, DATALENGTH(FileContent) AS SizeBytes
FROM PreUploadedOnPostTaskFiles
WHERE ID = {id};

-- 5. Просроченные preupload-файлы (> 24 часа)
SELECT COUNT(*) AS ExpiredFiles
FROM PreUploadedOnPostTaskFiles
WHERE DateUploaded < DATEADD(HOUR, -24, GETDATE());
```

### 4.3 Доступность сервера и чеклист обращения в поддержку

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

```bash
# С сервера 1Ф:
curl -I <serverAddress-из-OfficeOnlineEditor>

# Проверка конфигурации через API 1Ф:
curl -s -H "1F-Pat: <token>" "https://<instance>/api/r7/config"

# Если ONLYOFFICE в Docker:
docker ps | grep -i office
docker logs <container> --tail 50
```

**Чеклист перед обращением в поддержку 1Ф.**

Что приложить при обращении:

1. Версия платформы
2. Значение `OfficeOnlineEditor` из CustomSettings (**без секретов**)
3. Результат `curl -I <serverAddress>` с сервера 1Ф
4. Логи `uniform-api.log` и `tcclasslib.log` в момент ошибки
5. Скриншот ошибки из консоли браузера
6. Формат и источник файла (ДП, комментарий, Диск, eml-вложение)