Фрагментарная загрузка файлов¶

ℹ️ Доступно, начиная с версии 2.264 Кассиопея

В .NET приложении реализован функционал предварительной загрузки файлов (Preupload) через протокол TUS с сохранением файлов в S3 (MinIO). Распространяется на загрузку файлов в ленту, карточку задачи, в ДП, при создании и обновлении календарных встреч.

Технология фрагментарной загрузки файлов использует метод chunk ("частями") — это способ разбивать большие файлы на маленькие кусочки и отправлять каждый кусочек отдельно. Что позволяет продолжать загрузку файла даже после сбоя связи, если ваше интернет-соединение прервано, вы сможете легко восстановить процесс загрузки и продолжить с места остановки. Если во время загрузки возникает ошибка, система автоматически перезапустит процесс, позволяя вам продолжать загрузку немедленно или спустя некоторое время. Благодаря возможности делить файлы на небольшие фрагменты, вы можете загружать большие объемы данных размером до 1--3 ГБ (в зависимости от настроек системы).

Технология конфигурируется с помощью ключа Tus в системном файле приложения appsettings.json. Для удаления временных файлов из tus-хранилища предназначено задание по таймеру CleanExpiredFilesFromPreuploadedTusStoreJob.

ℹ️ Если на основном сервере приложения в appsettings.json включен Tus, то для корректной работы задания по таймеру его необходимо включить и на джоб-сервере.

Время жизни загруженных файлов в часах устанавливается в параметре FileExpirationInHours ключа Tus. Если в параметре ключа задано NULL, файлы удаляться не будут.

Конфигурация appsettings.json¶

Параметры секции `Tus`¶

Параметр	Тип	По умолчанию	Описание
`PreuploadEnabled`	bool	false	Включить TUS preupload
`PreuploadEndpoint`	string	`/files/tus/preupload`	URL endpoint для TUS-загрузки
`FileExpirationInHours`	int?	null	Время жизни загруженных файлов в часах. `null` — не удалять
`StoreType`	string	—	Тип хранилища: `S3` или `Local`
`S3`	object	—	Настройки S3 (заполнять при `StoreType: S3`)
`Local`	object	—	Настройки локального хранилища (заполнять при `StoreType: Local`)

Параметры `S3`¶

Параметр	Тип	По умолчанию	Описание
`Endpoint`	string	—	URL S3-сервера, например `https://s3.1forma.net`
`BucketName`	string	—	Имя бакета для временных TUS-файлов
`AccessKey`	string	—	Access Key ID
`SecretKey`	string	—	Secret Access Key
`Region`	string	null	Регион (для MinIO можно оставить пустым)
`ForcePathStyle`	bool	true	Path-style доступ к бакетам (`{endpoint}/{bucket}/...`). Для MinIO — `true`
`PreferredPartSizeInBytes`	int?	null	Размер части при multipart-загрузке. `null` — значение по умолчанию

Параметры `Local`¶

Параметр	Тип	Описание
`Path`	string	Путь к директории на диске для хранения временных файлов

Пример конфигурации — S3 (MinIO)¶

"Tus": {
  "PreuploadEnabled": true,
  "PreuploadEndpoint": "/files/tus/preupload",
  "FileExpirationInHours": 24,
  "StoreType": "S3",
  "S3": {
    "Endpoint": "https://s3.1forma.net",
    "BucketName": "tusd-dev",
    "AccessKey": "<access-key>",
    "SecretKey": "<secret-key>",
    "Region": "",
    "ForcePathStyle": true
  }
}

Пример конфигурации — Local¶

"Tus": {
  "PreuploadEnabled": true,
  "FileExpirationInHours": 24,
  "StoreType": "Local",
  "Local": {
    "Path": "/opt/1f/tus-store"
  }
}

ℹ️ TUS считается включённым (Enabled = true) только при одновременном выполнении условий: PreuploadEnabled: true и для S3 — указан Endpoint, для Local — указан Path.

Бакеты TUS по средам¶

Среда	Бакет
DEV	`tusd-dev`
HD	`tusd-hd`
Release-кластеры	`tusd-{cluster}` (например, `tusd-dragon`)

На бакетах TUS необходимо настроить lifecycle-политику на 24 часа — см. object-storage.md.

Использование TUS в Р7-Офис¶

Добавлено: 2026-02-13 (задача 2031736)

С версии 2.266.554 TUS-загрузки поддерживаются при открытии документов в Р7-Офис (российский офисный редактор).

Формат ключей¶

TUS-файлы в PreUploadedFiles имеют формат ключа: tempfile:tus:{tus-id}

Где {tus-id} — строковый идентификатор TUS-загрузки в S3/MinIO.

Примеры: - Старый формат: tempfile:12345 (числовой ID, хранится в БД) - Новый TUS формат: tempfile:tus:abc-def-123 (строковый ID, хранится в S3/MinIO)

Сценарии использования¶

1. Открытие office-файлов из email-вложений (.eml)¶

До версии 2.266.554: - ❌ Файлы из .eml вложений не открывались в Р7-Офис - ❌ Ошибка: ArgumentException: Invalid key (tus:abc-def-123)

После версии 2.266.554: - ✅ Файлы из .eml вложений открываются корректно - ✅ Поддержка TUS-ключей в OfficeOnlineEditorsService и R7Controller

2. Открытие больших файлов (> 50 MB)¶

Для файлов, загруженных через TUS: - Поддержка resumable upload (возобновляемая загрузка) - Эффективная работа с большими файлами - Снижение нагрузки на БД

Совместимость форматов¶

Система поддерживает оба формата одновременно для обратной совместимости:

Формат	Версия	Хранилище	API
`tempfile:12345`	Все версии	`PreUploadedOnPostTaskFiles` (БД)	`GetPreUploadedForPostTaskFile()`
`tempfile:tus:abc-def-123`	2.264+	S3/MinIO (TUS)	`GetPreuploadedFile()`

Ограничения TUS в Р7-Офис¶

Версионность: - Версии < 2.266.554: TUS-ключи НЕ поддерживаются в Р7-Офис - Версии ≥ 2.266.554: TUS-ключи поддерживаются полностью

Форматы файлов: - Поддерживаются: .docx, .xlsx, .pptx (новые форматы Office) - Ограниченная поддержка: .doc, .xls, .ppt (старые форматы)

Размер файлов: - Максимальный размер определяется настройкой MaxRequestLength - Рекомендуемый максимум для редактирования в браузере: 100 MB

Очистка TUS-файлов¶

Job: CleanExpiredFilesFromPreuploadedTusStoreJob

Параметры: - FileExpirationInHours — время жизни файлов в часах (по умолчанию: 24) - Удаляются файлы старше указанного срока из S3/MinIO

Проверка работы job:

-- Логи выполнения job
SELECT TOP 10 *
FROM JobExecutionHistory
WHERE JobName = 'CleanExpiredFilesFromPreuploadedTusStoreJob'
ORDER BY StartTime DESC;

Troubleshooting¶

Проблема: Не открывается office-файл из email-вложения

Диагностика: 1. Проверить версию системы (должна быть ≥ 2.266.554) 2. Проверить логи: logs/uniform-api.log и logs/tcclasslib.log 3. Проверить конфигурацию TUS в appsettings.json

Решение: - Версия < 2.266.554: обновить систему - Версия ≥ 2.266.554: проверить настройки S3/MinIO и job очистки

Связанные документы¶

Форматы файловых ключей — все форматы ключей