Файлы и Диск — Решение проблем¶

Аудитория: ТП 1-й линии (без доступа к БД)

Как пользоваться этим документом¶

Секции организованы по типам проблем. Для каждой: 1. Симптом — что описывает клиент 2. Что проверить — шаги диагностики 3. Решение — что сделать 4. Эскалация — когда передавать на 2-ю линию

Секции [2L] — заглушки для будущей SQL-диагностики.

1. Загрузка файлов¶

Самая частая тема — ~25% обращений. Ошибки при загрузке, ограничения размера и расширений.

1.1 Ошибка при загрузке файла¶

Симптом: при попытке приложить файл к задаче или комментарию — ошибка. Может быть 500, таймаут, или «невозможно загрузить».

Что проверить: - Размер файла — не превышает ли лимит (настройка MaxFileSize в общих настройках) - Расширение файла — не попадает ли в список запрещённых расширений (настройка категории) - ДП «Файл» — если загрузка в ДП, проверить настройку «Ограничения» (только изображения, допустимые расширения, макс. размер) - Мультифайл — если ДП без мультифайла, повторная загрузка заменяет существующий файл - Файловый провайдер — доступен ли активный провайдер

Решение: - Проверить настройку максимального размера: Общие настройки → Файлы - Проверить запрещённые расширения: Категория → Настройки → Запрещённые расширения - Если ошибка 500 — проверить журнал ошибок, скорее всего проблема провайдера

1.2 Максимальный размер файла — где настроить¶

Симптом: «где регулируется максимальный размер файла?», «увеличить допустимый размер файла для загрузки».

Решение: - Общий лимит: Общие настройки приложения → Файлы → MaxFileSize - На уровне ДП: настройка ДП «Файл» → Ограничения → Макс. размер - На уровне веб-сервера: лимит в nginx/IIS (requestFiltering → maxAllowedContentLength) - Для комментариев: отдельная настройка ограничения размера вложений

1.3 Запрещённые расширения не работают для встреч¶

Симптом: настройка «Запрещённые расширения» не отслеживает вложения во встречах.

Решение: известное ограничение — запрещённые расширения применяются только к задачам, а не к мероприятиям/встречам. Пока обходного решения нет.

1.4 Не добавляет расширения png/jpg для ДП «Файл»¶

Симптом: при настройке ДП «Файл» в режиме «Только изображения» — не принимает файлы png/jpg.

Что проверить: - Настройку ДП → Ограничения → «Только изображения» и/или «Допустимые расширения» - Не конфликтуют ли настройки между собой

1.5 Ошибка загрузки больших файлов (PG)¶

Симптом: при загрузке больших файлов на PostgreSQL — «invalid memory alloc request size».

Что проверить: - Тип провайдера — PostgreSQL использует bytea с лимитом 1 ГБ (для обычной загрузки в БД). При включённом TUS файлы загружаются через resumable upload в S3/MinIO, минуя bytea-ограничение (см. backend.md § 7, формат tempfile:tus:{id}) - Размер файла - Включён ли TUS (resumable upload) — если да, bytea-лимит не применяется

Эскалация: если файл меньше 1 ГБ и ошибка воспроизводится.

1.6 Загрузка данных из CSV / импорт¶

Симптом: при загрузке задач из CSV-файла — данные добавляются некорректно, или загрузка не работает.

Что проверить: - Формат CSV — кодировка (UTF-8), разделитель (;) - Маппинг колонок — соответствуют ли заголовки ожидаемым полям - После обновления — не изменился ли формат импорта

2. Скачивание файлов¶

2.1 Ошибка при скачивании файла¶

Симптом: при скачивании файла — ошибка, файл не загружается.

Что проверить: - Доступ пользователя к файлу / задаче / ДП - Файловый провайдер — доступен ли (не переключён ли) - Не удалён ли файл

2.2 Скачивается не та версия файла¶

Симптом: «в блоке Файлы скачивается первая версия файла, в ДП — последняя», «в онлайн-просмотре открывается последняя версия».

Что проверить: - Где именно скачивается — из блока «Файлы» или из ДП - Логика версионирования: блок «Файлы» может показывать оригинал, ДП — последнюю версию

Решение: это ожидаемое поведение — блок «Файлы» и ДП работают по разной логике. Из ДП всегда скачивается последняя версия. Из блока «Файлы» — зависит от контекста.

2.3 Не логируется скачивание файла¶

Симптом: в журнале действий с файлами нет записей о скачивании.

Что проверить: - Включён ли флаг «Логировать действия с файлами» в настройках ДП - Тип ДП — логирование работает для ДП «Файл» и колонок типа «Файл» в ДП «Таблица»

Решение: включить логирование в настройках ДП.

3. Диск¶

~15% обращений. Операции с Диском: права, перемещение, удаление.

3.1 Нет доступа к файлу/папке на Диске¶

Симптом: «не работает доступ к файлам через Поделиться», «доступ к файлу с диска».

Что проверить: - Раздел Диска — «Мои файлы» (только владелец и руководители), «Общие файлы» (все), «Обмен файлами» (только по явному доступу) - Права на папку — наследуются ли от родительской - Для «Обмен файлами» — выдал ли владелец доступ

Решение: - Проверить права через контекстное меню папки → «Доступ» - Для «Мои файлы» — доступ только владельцу и прямым руководителям

3.2 Как переименовать / переместить файл на Диске¶

Симптом: «как переименовать файл на диске?», «добавить возможность переносить файлы».

Решение: - Переименование: контекстное меню файла → «Переименовать» - Перемещение: на текущий момент drag-and-drop не поддерживается; нужно скачать и загрузить заново (или использовать API v1.2)

3.3 Ошибка при переходе в папку на Диске¶

Симптом: ошибка при открытии раздела «Файлы автоматизации» или другой папки.

Что проверить: - Версия системы — известные ошибки в некоторых версиях - Права на раздел

3.4 API Диска — права не применяются к дочерним объектам¶

Симптом: при использовании API v1.2 методов «Добавить/обновить права» и «Удалить разрешение» параметр propagate не работает.

Эскалация: это баг API.

4. OnlyOffice / R7 / WebApps¶

~10% обращений. Онлайн-просмотр и редактирование документов.

4.1 Не открываются файлы docx/xlsx в OnlyOffice¶

Симптом: файлы форматов docx и xlsx не открываются в онлайн-просмотре/редактировании.

Что проверить: - Настроен ли офисный пакет (R7/OnlyOffice) — ключ OfficeOnlineEditor в пользовательских настройках - Доступен ли сервер R7 — проверить URL из конфигурации - Список разрешённых подсетей (allowedIPs) — входит ли IP сервера 1Ф - Не истёк ли сертификат сервера R7

Решение: - Проверить appsettings.json → секция R7 → секретный ключ - Проверить пользовательский ключ OfficeOnlineEditor - Проверить доступность сервера R7 с веб-сервера 1Ф

4.2 OnlyOffice и PDF¶

Симптом: PDF не открывается в OnlyOffice, или открывается с ошибками.

Что проверить: - Поддерживает ли версия R7/OnlyOffice формат PDF - Размер файла

4.3 Как редактировать печатные формы без скачивания¶

Симптом: «как редактировать печатные формы через OnlyOffice?»

Решение: печатные формы (Word-шаблоны) после генерации можно открыть в R7/OnlyOffice для редактирования, если настроено действие при клике — «Открыть для просмотра в WebApps». Настраивается на уровне пользователя.

4.4 Ошибка doc/docx вложений из .eml через OnlyOffice¶

Симптом: при открытии вложений из eml-файла через OnlyOffice — ошибка.

Эскалация: вложения из eml требуют предварительного извлечения; прямое открытие может не поддерживаться.

4.5 Не открывается office-файл из email-вложения в Р7-Офис¶

Симптом: «не могу открыть Word из письма в Р7-Офис», «ошибка при открытии Excel-вложения из .eml», «ArgumentException при попытке просмотра документа».

Версии: - ❌ Версии до v2.266.554 — известная проблема - ✅ Версии v2.266.554+ — исправлено

Что проверить¶

Версия системы (критично!):
Если < 2.266.554 → рекомендовать обновление
Если ≥ 2.266.554 → искать другие причины
Формат файла:
Р7-Офис поддерживает: .docx, .xlsx, .pptx (новые форматы)
Старые форматы (.doc, .xls, .ppt) могут открываться с ограничениями
Конфигурация Р7-Офис:
Ключ OfficeOnlineEditor в Custom Settings
R7 secret в appsettings.json
Доступность сервера Р7-Офис с веб-сервера 1Ф
Тип ошибки в логах:
ArgumentException: Invalid key (tus:...) — версия < 2.266.554
NotFoundException: Preuploaded file not found — файл не найден
UnauthorizedException — нет прав на файл

Известные проблемы (до v2.266.554)¶

Причина: Код не поддерживал TUS-ключи при работе с email-вложениями.

Техническое объяснение: - Файлы загружались через TUS Protocol (формат: tempfile:tus:abc-def-123) - Р7-Офис интеграция ожидала только числовой формат (tempfile:12345) - При попытке открыть файл: ArgumentException: Invalid key (tus:abc-def-123)

Затронутые сценарии: - Открытие office-файлов из вложений .eml писем - Работа с большими файлами (> 50 MB), загруженными через TUS - Email-вложения из Exchange (EWS)

Решение¶

Для версий < 2.266.554: 1. Обновить систему до версии 2.266.554+ (критичное исправление) 2. Временное решение: скачать файл и открыть локально в десктопном приложении 3. Альтернатива: использовать OnlyOffice вместо Р7-Офис (если настроен)

Для версий ≥ 2.266.554: 1. Проверить настройки браузера (блокировка iframe, CORS) 2. Проверить доступность Р7-Офис сервера из браузера пользователя 3. Проверить права пользователя на файл 4. Проверить логи: logs/uniform-api.log и logs/tcclasslib.log

Как протестировать¶

Проверка версии системы:

Нижний левый угол SPA → О системе → Версия: 2.266.554+

Проверка работы Р7-Офис: 1. Открыть любой обычный файл (не из email) в Р7-Офис 2. Если работает → проблема специфична для email-вложений → проверить версию 3. Если не работает → проблема конфигурации Р7-Офис

Проверка TUS: - Администратор → Общие настройки → Файлы → TUS enabled - Если TUS включён и версия < 2.266.554 → обновление обязательно

Эскалация¶

Когда эскалировать на 2-ю линию: - Версия < 2.266.554 и нельзя обновить — критичный баг, нужно workaround - Версия ≥ 2.266.554, но email-вложения всё равно не открываются - Ошибки в логах, отличающиеся от описанных выше

Что приложить: - Версия системы - Скриншот ошибки - Логи: logs/uniform-api.log (последние 100 строк с меткой времени ошибки) - Формат файла и размер - Способ получения файла (Exchange, IMAP, .eml загрузка)

5. Файловые провайдеры¶

~8% обращений. Настройка и переключение провайдеров.

5.1 Создание / переключение файлового провайдера¶

Симптом: «создание новой БД для файлов», «изменить файловые провайдеры на тесте».

Что проверить: - Тип провайдера (MS SQL, PostgreSQL, S3) - Для MS SQL: создана ли таблица с нужной структурой (identity, varbinary(max), varchar) - Для S3: настроены ли endpoint, bucket, ключи доступа

Решение: - Для переключения: Общие настройки → «Вкладывать новые файлы через провайдер» - Старые файлы остаются в прежнем провайдере — переключение влияет только на новые

5.2 Tika не обрабатывает старые файлы¶

Симптом: «почему сервис Tika обрабатывает только новые файлы?»

Решение: TikaJob обрабатывает файлы, у которых ещё нет извлечённого текста. Для обработки старых файлов нужно очистить поле текстового содержимого в таблице провайдера.

[2L] SQL для очистки поля текстового содержимого.

5.3 Вопрос по хранению файлов в БД¶

Симптом: «как хранятся файлы?», «рекомендации по разбивке».

Решение: - Рекомендация: разбивать файловые БД на части по 100–200 ГБ - Файловые БД не требуют быстрых дисков - Провайдеры, используемые в категориях, нельзя удалить - Для PG: bytea (лимит 1 ГБ), компрессию включать не нужно (TOAST)

6. Файлы в ДП «Таблица»¶

6.1 Изменение файла в таблице помечает его на удаление¶

Симптом: при изменении файла в колонке «Файл» ДП «Таблица» — старый файл помечается на удаление.

Решение: ожидаемое поведение — при замене файла старая версия помечается как неактуальная. Для истории файлов по ячейке — функционал в разработке.

6.2 Виртуальная колонка на ДП «Файл» отображается как ссылка¶

Симптом: в гриде множественного выбора виртуальная колонка на ДП «Файл» (с галкой «Изображение») показывается как текстовая ссылка вместо превью.

Решение: это ограничение грида — превью изображений работает не во всех режимах отображения.

6.3 Неверный перевод кнопки «вложить файл» в ДП «Таблица»¶

Симптом: кнопка «вложить файл» в ДП «Таблица» переведена некорректно.

Решение: проблема локализации — сообщить команде разработки.

7. Экспорт и печать¶

7.1 Файлы не экспортируются / экспортируются некорректно в Excel¶

Симптом: при экспорте задач в Excel файлы не отображаются или ссылки нерабочие.

Что проверить: - ДП «Файл» — значение экспортируется как гиперссылка - Вложенные файлы (не через ДП) — не экспортируются в Excel - Авторизация — при скачивании из Excel добавляется ?auth=true, нужна настройка AuthTokenLoginUrl

Решение: - Для вложенных файлов без ДП: создать скрытый ДП со ссылкой через смарт-автоматизацию - Проверить настройку AuthTokenLoginUrl в appsettings.json

7.2 Шаблоны печати — пропали / не работают¶

Симптом: «можно вернуть шаблоны, которые были?», «настройка шаблона печати задачи».

Что проверить: - Версия системы — шаблоны печати могут меняться при обновлении - Настройки печати в категории

7.3 Некорректное формирование PDF¶

Симптом: PDF генерируется с ошибками или с надписью о лицензии FastReport.

Что проверить: - Лицензия FastReport — активна ли - Шаблон отчёта — нет ли ошибок

8. Антивирус и безопасность¶

8.1 Антивирусная проверка вложений¶

Симптом: «есть ли возможность добавить антивирус для проверки вложений?»

Решение: начиная с версии 2.267.370 (февраль 2026) доступна встроенная интеграция с PT Sandbox (Positive Technologies). Проверка файлов выполняется автоматически при загрузке — до записи в хранилище. Настройка через AdminSPA → Сервисы → PT Sandbox.

Подробнее: docs/domains/integrations/pt-sandbox.md

Альтернативный вариант (для других антивирусов): интеграция через смарт-скрипт (Lua/JS) + HTTP-action к внешнему API.

8.2 Возможность скачать чужие файлы при аплоаде¶

Симптом: в старой ДП «Таблица» при сохранении можно скачать чужие файлы.

Эскалация: проблема безопасности — передать на 2-ю линию немедленно.

8.3 Защита от скачивания¶

Симптом: вопросы о настройке защиты файлов от скачивания.

Решение: в настройках ДП «Файл» есть флаг «Защита от скачивания» — файл открывается только для постраничного просмотра (для не-владельцев при readonly-доступе к ДП).

9. Вложения в комментарии и чат¶

9.1 Невозможность отправки сообщения при добавлении файла¶

Симптом: при добавлении файла к комментарию или сообщению — ошибка отправки.

Что проверить: - Размер файла — не превышает ли лимит для комментариев - Расширение — не в запрещённых

9.2 При удалении комментария — что происходит с вложением¶

Симптом: при удалении комментария с вложением файл остаётся / не удаляется.

Решение: на текущий момент при удалении комментария вложение не удаляется автоматически. Предложение добавить диалог выбора — в бэклоге.

10. Не вкладываются файлы во встречу¶

Симптом: «не вкладываются файлы во встречу».

Что проверить: - Права пользователя на встречу - Максимальный размер файла - Запрещённые расширения (не применяются к встречам — см. 1.3)

11. Генерация файлов по шаблону¶

11.1 Параметры шаблона не подставляются / null¶

Симптом: действие «Сгенерировать файл по шаблону» создаёт файл, но значения из smart-выражений или ДП не подтягиваются — в документе пустые поля или нулевые значения.

Что проверить: - Синтаксис smart-выражений в шаблоне — корректность ключей, скобок - Типы ДП — совместимы ли с шаблоном (например, число vs строка) - Есть ли значение в ДП на момент генерации — если ДП пустой, результат будет null - Порядок действий в автоматизации — заполняется ли ДП до генерации файла

Решение: - Проверить шаблон на тестовой задаче с заполненными ДП - Убедиться, что smart-выражения корректны через предпросмотр - Если значение null — проверить, что ДП заполнен до запуска действия

11.2 Смарт-действие «наложить изображение на документ» работает некорректно¶

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

Что проверить: - Параметры действия: координаты, размер, страница - Формат исходного документа (PDF vs DOCX) - Размер и формат изображения

Эскалация: если параметры корректны, но результат неверный — передать разработке с примером файлов (исходник + результат + ожидание).

12. Ссылки на файлы и блок «Используется»¶

12.1 Не открывается ссылка на файл в блоке «Используется»¶

Симптом: в задаче в блоке «Используется» ссылка на файл не работает — ошибка или пустая страница.

Что проверить: - Не удалён ли файл из исходной задачи - Права пользователя на исходную задачу с файлом - Версия системы — возможен баг в конкретной сборке

Эскалация: если файл существует и права есть — баг, передать на 2-ю линию со скриншотом и URL.

13. Файлы и автоматизации (смарт-скрипты)¶

13.1 Как в смарт-скрипте отправить email с вложениями из задачи¶

Симптом: «как приложить файлы из задачи к email через смарт-действие?», «вложить файл из ДП в письмо».

Решение: - Использовать действие «Отправить email» с параметром вложений - Файлы можно указать через ДП «Файл» или через ID файла из блока «Файлы» - Для ДП «Файл»: в параметре вложений указать ссылку на ДП

Эскалация: если стандартные параметры не позволяют прикрепить нужный файл — передать на 2-ю линию.

13.2 Смарт-процесс «Вложить файл» — уточнения по работе¶

Симптом: вопросы о работе смарт-процесса «Вложить файл» — когда срабатывает, какие файлы захватывает.

Что проверить: - Настройки смарт-процесса: триггер, условия, целевой ДП - Тип файла: ДП «Файл» vs вложение комментария vs блок «Файлы»

14. Файлы и API¶

14.1 Как импортировать файл в задачу через API¶

Симптом: «как загрузить файл в задачу через REST API?», «импорт файлов через интеграцию».

Решение: - Загрузка файла: POST /api/files/upload/ToPreUploadedFiles — получить ключ preupload - Привязка к задаче: через обновление ДП «Файл» (POST /api/extParams/update) или через добавление вложения - Документация: docs/reference/api/curl-examples.md — раздел Files

15. Файлы приложений и конфигурация¶

15.1 Файлы приложений перезатираются при обновлении¶

Симптом: «после обновления пропали кастомные файлы», «как не потерять файлы при обновлении».

Что проверить: - Какие именно файлы: логотипы, фоны авторизации, кастомные скрипты - Расположение файлов — в папке приложения (перезатираются) или в отдельном хранилище

Решение: - Кастомные файлы (логотипы, фоны) размещать через настройки системы, а не заменой файлов на диске - Фон экрана авторизации: Общие настройки → Авторизация → Фоновое изображение - Логотипы: Общие настройки → Внешний вид - Если файлы размещены вручную на диске — делать бэкап перед обновлением

15.2 Ошибка сохранения файлового провайдера¶

Симптом: при создании или редактировании файлового провайдера — ошибка сохранения.

Что проверить: - Корректность параметров подключения (строка подключения, endpoint S3, bucket) - Доступность целевого хранилища с веб-сервера - Права учётной записи на целевую БД или S3-бакет

Эскалация: если параметры корректны и хранилище доступно — передать на 2-ю линию с текстом ошибки из логов.

15.3 Отсутствует data.json при экспорте конфигурации¶

Симптом: при экспорте конфигурации файл data.json не создаётся или пустой.

Что проверить: - Версия системы - Наличие данных для экспорта — не пустая ли конфигурация - Логи экспорта — нет ли ошибок

Эскалация: передать на 2-ю линию с версией системы и логами.

16. Скачивание файлов из ДП «Таблица» (массовое)¶

16.1 Как скачать все файлы из колонок таблицы¶

Симптом: «как скачать все файлы из таблицы одним архивом?», «массовая выгрузка файлов из ДП Таблица».

Решение: - Штатная кнопка «Скачать все» доступна в контекстном меню ДП «Таблица» (зависит от версии) - Альтернатива: API — получить список файлов через task_files_get_ext_param_files_by_task_id, затем скачать каждый по URL - Для единичных строк: клик по файлу в ячейке → скачивание

Чеклист для первичной диагностики¶

Контекст — ДП «Файл», Диск, комментарий, встреча
Операция — загрузка, скачивание, просмотр, удаление
Размер и формат файла
Тип провайдера — MS SQL, PostgreSQL, S3
Версия системы
Один пользователь или все
Скриншот / текст ошибки

Когда эскалировать¶

Ошибки провайдера (500, таймаут при загрузке/скачивании)
Проблемы безопасности (доступ к чужим файлам)
Ошибки PostgreSQL (invalid memory alloc)
OnlyOffice/R7 не работает при корректных настройках
Баги API Диска
Генерация файлов по шаблону — smart-выражения не подставляются при корректных настройках
Смарт-действие «наложить изображение» — некорректный результат при верных параметрах
Экспорт конфигурации — отсутствует data.json