Uppy: загрузка файлов — мастерская, PHP и продолжение через Tus
Собираем понятную загрузку вложений: девять задач Uppy, ограничения, подписи, частичные ошибки, локальные черновики и Tus. Мастерская, PHP/Node.js и исходники.

Uppy: загрузка файлов как понятный процесс
Вложение к заявке кажется простой задачей: выбрать файл и нажать кнопку. Но в рабочем интерфейсе сразу возникают вопросы. Как показать несколько документов? Что делать, если один из них слишком большой? Нужно ли начинать заново после обрыва сети? Может ли менеджер закрыть страницу и вернуться к выбранным материалам? Как отличить передачу байтов от успешного сохранения заявки?
Uppy помогает собрать клиентскую часть этого процесса: список файлов, превью, метаданные, ограничения, события и плагины передачи. Его можно встроить в личный кабинет, CRM, редактор материалов, сервис согласования документов или внутренний портал. Пользователь видит состояние каждого вложения и понимает, какое действие доступно дальше.
В статье разберём девять связанных задач, собственный PHP-обработчик и продолжение передачи через Tus. На странице работает настоящая библиотека Uppy; публичный транспорт намеренно учебный и никуда не отправляет файлы. Реальные HTTP-загрузки воспроизводятся в скачиваемом проекте, а их проверенные результаты доступны в мастерской. Исходники, команды Windows и Linux, тесты и ограничения включены в материал.
Где применять: заявки, каталог, кабинет и согласование
В сервисном бизнесе клиент прикладывает фотографии неисправности, сотрудник добавляет акт, менеджер подписывает документ понятным названием. Хороший интерфейс связывает файл с конкретной заявкой, показывает размер и позволяет удалить случайный выбор до отправки. Оператору не приходится угадывать, что скрывается за именем IMG_0048.
В каталоге товаров полезна пакетная загрузка: несколько изображений отправляются независимо, а ошибка одного не стирает результат остальных. Во внутреннем кабинете важны приватность и срок жизни временных вложений. В редакторе длинных видеоматериалов на первый план выходит продолжение передачи после пропавшей сети: пользователь уже потратил время и трафик, их желательно сохранить.
Начинайте с конкретного сценария продукта. Для одного маленького аватара достаточно более простой формы. Uppy становится особенно полезен, когда появляются очередь, несколько состояний и разные источники. При этом библиотека не решает за вас, кто имеет право читать документ, сколько хранить черновик и когда вложение становится частью опубликованной сущности.
Uppy, обычный input и FilePond: как выбрать
Стандартный input type=file остаётся хорошим решением для простой формы. Браузер открывает системный выбор, а приложение отправляет FormData. Если нужны превью, индивидуальный прогресс, отмена и повтор, эту обвязку придётся написать и проверить самостоятельно. Стоимость здесь определяется количеством состояний, а не длиной первого примера.
Uppy удобно рассматривать как основу управляемой очереди. Dashboard даёт готовую оболочку, а transport-плагин определяет способ доставки. В этой статье основной акцент — связь списка, частичных ошибок и возобновления. Материал про FilePond и PHP-загрузку на сайте полезен для сравнения оформления поля и другого подхода к интеграции.
Выбирайте по требованиям и поведению в реальном интерфейсе. Проверьте мобильный выбор, русские сообщения, размер сборки, формат серверного ответа и способ восстановления. Наличие красивого Dashboard ещё не означает, что приложение корректно обрабатывает ответ 413 или удаляет временные файлы. Эти обязанности остаются частью вашего сервиса.
| Задача | Практический выбор |
|---|---|
| Один небольшой файл | input и FormData часто достаточны |
| Список, подписи, отдельные состояния | Uppy Core + Dashboard |
| Обычный PHP upload | XHRUpload и multipart-контроллер |
| Продолжение с сохранённого смещения | Tus-клиент и совместимый сервер |
Что работает прямо на странице: границы мини-мастерской
Откройте мастерскую и добавьте учебный набор. Выбор, ограничения, метаданные, состояния Uppy и сохранение небольшого черновика работают в браузере. Кнопки ошибки, повтора и паузы запускают наш локальный TeachingTransport: он моделирует продвижение внутри вкладки. Эти проценты не измеряют сеть, а завершение не означает появления файла на сервере.
Такой режим позволяет безопасно изучить интерфейс, не превращая публичную статью в открытое файловое хранилище. В блоке PHP/Tus лежат отдельные записи настоящих HTTP-проверок Windows и Linux. Они не зависят от ваших выбранных файлов. Для собственных реальных загрузок распакуйте ZIP и включите локальный transport по инструкции ниже.
Все девять задач доступны из списка и кнопок перехода. Смена задачи очищает текущий набор; сохранённый по отдельной кнопке черновик остаётся. Ниже находятся просмотрщик исходников, скачивание отдельного файла и полный архив. Большую мастерскую удобно открыть в отдельной вкладке: там больше места для Dashboard, журнала и ответа сервера.
Версии и структура: Core, Dashboard, transport
В проекте закреплены @uppy/core 6.3.1, Dashboard 6.0.3, Tus и XHRUpload 6.0.1, русская локализация 5.3.2. Номера пакетов различаются: у них собственные выпуски и требования к Core. Нельзя автоматически подставить одинаковую версию во все зависимости. Согласованный набор вместе с транзитивными пакетами сохранён в package-lock.json.
Оболочка написана на HTML5 и Bootstrap 5.3.9. JavaScript собирается esbuild; Uppy, стили и локализация лежат в public, внешнего CDN при открытии мастерской нет. Сервер Tus использует @tus/server 2.4.7 и FileStore 2.1.2. Для повторения выбран Node 24 LTS и PHP 8.3 с fileinfo.
Каталог src содержит интерфейс и модель правил, server — настоящие локальные обработчики, tests — проверки жизненного цикла Uppy, tools — сборку и HTTP-опыты. public является готовой публикацией. Изменяйте исходники, затем запускайте build: ручная правка минифицированного файла приведёт к расхождению с просмотрщиком и скачиваемым проектом.
{
"name":"aen-uppy-workshop","version":"1.0.0","private":true,"type":"module","license":"MIT",
"engines":{"node":">=22"},
"scripts":{"build":"node tools/build.mjs","test":"node --test tests/*.test.mjs","serve":"node tools/serve.mjs","tus":"node server/tus.mjs","record":"node tools/record.mjs"},
"dependencies":{"@uppy/core":"6.3.1","@uppy/dashboard":"6.0.3","@uppy/tus":"6.0.1","@uppy/xhr-upload":"6.0.1","@uppy/locales":"5.3.2","@tus/server":"2.4.7","@tus/file-store":"2.1.2","bootstrap":"5.3.9"},
"devDependencies":{"esbuild":"0.28.2"}
}
Windows: запустить мастерскую и настоящий PHP
Распакуйте проект, откройте PowerShell в его каталоге и проверьте Node и PHP. В PATH должен находиться php.exe с расширением fileinfo. Если PHP установлен отдельно, задайте PHP_BIN полным путём. Команда npm ci устанавливает именно версии lock-файла, а не случайно выбранный новый набор библиотек.
После сборки запустите serve и откройте http://127.0.0.1:8568/. В интерфейсе появится блок локального транспорта. Выберите PHP: страница создаст сессию и получит CSRF-токен. Добавьте учебный набор и начните передачу. Теперь XHRUpload делает настоящий multipart-запрос, а результат содержит серверный ID и контрольную сумму.
Остановка выполняется Ctrl+C в консоли этого проекта. Не запускайте PHP development server на общедоступном адресе. Наш router специально проверяет loopback и Host; это лаборатория для изучения запросов. Для просмотра статических файлов PHP не принципиален, но он нужен для воспроизведения реального обработчика и его ошибок.
node --version
php --version
php -m
npm ci --ignore-scripts
npm test
npm run record
npm run build
npm run serve
# При необходимости:
# $env:PHP_BIN = 'C:\php\php.exe'
Linux: тот же проект и проверка на VPS через SSH
В Linux используются тот же package-lock и те же исходники. Установите поддерживаемый Node 24 LTS и PHP CLI с fileinfo. Не переносите node_modules из Windows: установите зависимости на целевой платформе. Затем выполните тесты, запись HTTP-опытов и сборку. Это проверит не только синтаксис, но и фактическое сохранение байтов.
Для первого опыта на VPS оставьте оба сервера привязанными к 127.0.0.1. SSH-туннель перенесёт локальные порты вашего компьютера к процессам удалённого Linux. Интерфейс останется доступен по привычному адресу, а файлы будут проходить через настоящий сервер. Порты 8568 и 8569 не требуется открывать в firewall.
Такой режим полезен для диагностики окружения, дисковых прав и серверных ограничений до публичного развёртывания. Он не заменяет систему пользователей. Если порт на вашем компьютере уже занят, завершите собственный предыдущий стенд либо согласованно измените адреса, origin и port проекта. Проверка доступа к production API выполняется отдельно.
npm ci --ignore-scripts
npm test
npm run record
npm run build
npm run serve
# На своём компьютере, отдельная консоль:
ssh -N -L 8568:127.0.0.1:8568 -L 8569:127.0.0.1:8569 user@server
Создание Uppy: интерфейс отделён от передачи
Экземпляр Uppy хранит набор файлов и их состояния. Dashboard подключается к конкретному элементу страницы и отображает этот набор. Transport подписывается на запуск и сообщает о результате. Такое разделение позволяет оставить привычную оболочку и изменить серверный способ доставки без переписывания всей формы.
В мастерской отключена автоматическая отправка: сначала человек проверяет набор и подписи, затем явно запускает действие. Это удобно для карточки заявки. При переходе к другой задаче предыдущий экземпляр уничтожается, чтобы старые обработчики и таймеры не продолжали работать с уже заменённым интерфейсом.
Размещайте правила рядом с состоянием приложения, а не прячьте их в подписи кнопок. Ограничение количества относится к конфигурации Uppy, формат номера заявки — к контракту формы, права пользователя — к серверному контроллеру. Описание API Core находится в официальной документации Uppy. В полном app.mjs показано, как эти части связаны в нашем проекте.
const uppy = new Uppy({
autoProceed: false,
restrictions: { maxNumberOfFiles: 4, maxFileSize: 2 * 1024 * 1024 }
});
uppy.use(Dashboard, { inline: true, target: '#dashboard' });
// Дальше подключается ровно один transport: учебный, XHR или Tus.
Пример 1. Вложения к заявке: список и осознанный выбор
Первая задача воспроизводит обычную карточку обращения. Нажмите «Добавить учебный набор»: появятся текстовая заметка и маленькое PNG. Можно выбрать собственные файлы через Dashboard. Посмотрите имя, размер, превью, удалите лишнее и убедитесь, что счётчик отражает оставшийся набор. До запуска нет даже учебного завершения.
В продукте рядом со списком полезно показывать назначение вложений: фотографии объекта, документы договора или подтверждение выполненной работы. Если сервер принимает несколько разных категорий, лучше дать явное поле категории, чем пытаться определять смысл по расширению. Имя файла остаётся пользовательскими данными и не должно напрямую превращаться в путь хранения.
Оставляйте возможность исправить выбор до отправки. Человек может случайно выбрать соседний документ, особенно на телефоне. Удаление из списка на этом этапе просто исключает объект из очереди. После отправки такая же визуальная кнопка уже не обязана означать удаление серверных байтов: эту разницу разберём отдельно.
uppy.addFile({ name: 'notes.txt', type: 'text/plain',
data: new Blob(['Комментарий к заявке'], { type: 'text/plain' }),
meta: { caption: 'Комментарий клиента' }
});
Пример 2. Тип, размер и количество до отправки
Выберите задачу ограничений. Она разрешает один PNG не больше 100 KiB. Кнопки неправильного типа и слишком большого файла дают воспроизводимые отрицательные случаи без поиска подходящих файлов на диске. Добавьте учебный PNG повторно, чтобы проверить ограничение количества. Ошибка должна появиться сразу и объяснить, что именно исправить.
В остальных задачах действует другой контракт: до четырёх PNG, JPEG или TXT, до 2 MiB на файл и до 4 MiB на набор. Эти значения намеренно небольшие. В интерфейсе реального сервиса лимит следует показывать до выбора, иначе пользователь узнает о нём после потраченного времени.
Клиентская проверка экономит действия и трафик, но не защищает сервер. Запрос можно отправить другим клиентом, а Content-Type назначить произвольно. Поэтому PHP повторно проверяет размер и фактический тип. Когда правила расходятся, человек видит противоречивое поведение; полезно хранить прикладные лимиты в одном согласованном контракте и тестировать обе стороны.
export function restrictions(id) { return id==='limits' ? {maxNumberOfFiles:1,maxFileSize:100*1024,allowedFileTypes:['image/png']} : {maxNumberOfFiles:4,maxFileSize:2*MiB,maxTotalFileSize:4*MiB,allowedFileTypes:['image/png','image/jpeg','text/plain']}; }
Пример 3. Метаданные: подпись и номер заявки
В третьей задаче одной загрузки недостаточно: каждому файлу нужна подпись от четырёх символов. Попробуйте запустить пустые подписи, затем исправьте их кнопкой или редактором метаданных Dashboard. Номер заявки должен иметь вид REQ-1042. Ошибка останавливает запуск до появления прогресса и остаётся рядом с действием.
Подпись помогает человеку понять содержимое, а requestId связывает набор с будущей операцией. При настоящем multipart-запросе мы отправляем только разрешённые поля caption и requestId. Случайные свойства внутреннего состояния Uppy не должны автоматически становиться параметрами бизнес-API.
На сервере формат идентификатора не доказывает доступ к заявке. После аутентификации контроллер обязан проверить, что текущий пользователь может добавлять вложения именно в эту сущность. В локальной лаборатории реальной базы заявок нет, поэтому номер является учебным контрактом. Это полезная граница: пример показывает передачу метаданных и ошибки, но не изображает готовую CRM-авторизацию.
export function validateBeforeUpload(files,id,requestId) {
if(!/^REQ-\d{3,6}$/.test(requestId))throw Error('Номер заявки: REQ- и от 3 до 6 цифр.');
if(!files.length)throw Error('Сначала добавьте хотя бы один файл.');
if(id==='meta'&&files.some(f=>String(f.meta.caption||'').trim().length<4))throw Error('Добавьте каждому файлу подпись от 4 символов.');
return true;
}
Пример 4. Частичная ошибка и повтор только неудачных
Выберите сценарий частичной ошибки, добавьте набор и начните передачу. Один файл завершится, второй один раз получит учебный отказ примерно на середине. Нажмите «Повторить ошибки». Успешный файл останется успешным, а повтор запустится для неудачного. Журнал событий позволяет увидеть, что именно произошло с каждым вложением.
Это поведение важно для пакетной загрузки. Если из десяти фотографий одна не прошла, повтор всего набора расходует время и может создавать дубликаты на сервере. Сохраняйте отдельный статус и объясняйте, сколько объектов уже принято. Общая кнопка продолжения должна учитывать незавершённые и ошибочные элементы.
Повтор запроса и продолжение с offset — разные механизмы. В учебном transport неудачный файл начинает свой локальный цикл заново. Обычный multipart часто тоже требует новой передачи целиком. Tus позволяет договориться о подтверждённой части. В рабочем API дополнительно продумайте идемпотентность: таймаут ответа не доказывает, что сервер не сохранил объект.
uppy.on('upload-error', (file, error) => showError(file.id, error.message));
uppy.on('complete', result => {
showCounts(result.successful.length, result.failed.length);
});
// По отдельной кнопке, если есть ошибки:
await uppy.retryAll();
Пример 5. Пауза, продолжение и отмена
В пятой задаче начните передачу и нажмите «Пауза». Учебный счётчик остановится; «Продолжить» вернёт обработку оставшихся шагов. «Очистить список» отменяет локальный опыт. Эти действия позволяют оценить подписи и состояния без искусственно медленного интернет-соединения. На странице прямо указано, что это модель передачи, а не сетевой замер.
В настоящем upload возможности паузы зависят от транспорта. Клиент может прервать запрос, но серверу нужно понимать, какой объём уже принят и как продолжить. Поэтому нельзя обещать одинаковое поведение для любого endpoint только потому, что в панели есть кнопка. В нашем локальном режиме Tus отвечает за возобновление, PHP использует обычный multipart.
После успешного сохранения удаление элемента из Dashboard меняет клиентское состояние. Для удаления объекта сервера требуется отдельная авторизованная операция. В статье есть такой PHP endpoint и проверка владельца. Продумайте также поведение уже привязанного документа: отмена нового черновика и удаление подписанного акта — разные бизнес-действия.
uppy.pauseAll();
uppy.resumeAll();
uppy.cancelAll(); // Очищает очередь; не является DELETE вашего хранилища.
Пример 6. Настоящий XHRUpload и multipart в PHP
На публичной странице выберите запись PHP и платформу Windows или Linux. Вы увидите запрос без сессии, неправильный CSRF, подменённый MIME, неверный номер заявки, слишком большой файл и успешное сохранение PNG. Затем тест читает байты владельцем, проверяет отказ другой сессии и удаляет объект. Это запись реальных HTTP-действий, а не ответ на текущий выбор Dashboard.
В локальном проекте переключатель PHP подключает настоящий XHRUpload. endpoint относится к текущему origin, файл передаётся в поле file, а caption и requestId входят в multipart. Cookies связывают запрос с созданной сессией. При успехе JSON содержит ID, размер, MIME и SHA: клиент получает понятный серверный результат.
Параметры конкретного плагина описаны в документации XHRUpload. Показанная конфигурация соответствует нашему обработчику; для другого API нужно согласовать поля, credentials, коды ошибок и формат ответа. Не копируйте URL чужого демонстрационного сервера для пользовательских документов.
uppy.use(XHRUpload, {
endpoint: '/api/upload', fieldName: 'file', formData: true,
allowedMetaFields: ['caption', 'requestId'],
headers: { 'X-CSRF-Token': csrf },
withCredentials: true, limit: 2
});
PHP-обработчик: проверки, случайный ID и приватное хранение
server/upload.php принимает один успешно загруженный файл, проверяет размер и метаданные, определяет MIME через fileinfo. Для PNG/JPEG дополнительно проверяется структура и размер изображения, для текста — UTF-8, отсутствие нулевого байта и меньший лимит. Ошибка возвращает осмысленный HTTP-статус до сохранения объекта.
Сервер сам назначает случайный ID и хранит файл в runtime/php-files вне public. Исходное имя не участвует в пути. В текущей сессии остаётся список принадлежащих ей ID. Поэтому случайный адрес сам по себе не даёт права прочитать документ: отдельный GET проверяет владельца и выдаёт байты как attachment с нейтральным MIME.
Локальные квоты ограничивают опыт, но встроенный однопроцессный PHP-сервер не является готовой архитектурой многопользовательского хранения. Для PHP-FPM нужны атомарные квоты, база владельцев и статусов, устойчивое хранение сессий и политика очистки. Основы PHP можно повторить в нашем большом PHP-мануале, а устройство $_FILES — в официальном разделе загрузок PHP.
$mime = (new finfo(FILEINFO_MIME_TYPE))->file($f['tmp_name']);
$id = bin2hex(random_bytes(16));
$destination = $directory . '/' . $id . '.bin';
if (!move_uploaded_file($f['tmp_name'], $destination)) {
reply(500, ['error' => 'Cannot store file']);
}
// До этого выполнены проверки. Полный обработчик находится в ZIP.
Пример 7. Tus: продолжить с подтверждённого смещения
Представьте передачу большого отчёта через нестабильную сеть. Клиент успел отправить часть, соединение исчезло, затем приложение вернулось. Нужно узнать состояние сервера, а не полагаться на последнюю цифру прогресса в интерфейсе. Tus описывает HTTP-протокол возобновляемой передачи; для работы нужны совместимые клиент и сервер.
В нашей записи POST создаёт ресурс, первый PATCH передаёт 65 536 байт. Затем сервер останавливается и запускается с тем же FileStore. HEAD подтверждает сохранённое смещение, ошибочный PATCH с нулевым offset получает 409, а правильный PATCH дописывает остаток. Итоговая SHA совпадает с исходными данными на Windows и Linux.
Это проверяет важную практическую гарантию стенда: уже принятые байты переживают перезапуск процесса. Объём теста небольшой, чтобы опыт быстро повторялся. Он не является нагрузочным тестом гигабайтных файлов. Правила offset и заголовков описаны в спецификации Tus.
POST /files → 201 Location: /files/<id>
PATCH /files/<id> → 204 Upload-Offset: 65536
# Перезапуск сервера с тем же каталогом FileStore
HEAD /files/<id> → 200 Upload-Offset: 65536
PATCH offset=0 → 409, принятые байты не меняются
PATCH offset=65536 → 204, файл завершён
SHA256(на диске) == SHA256(исходных байтов)
Локальный Tus: токен, FileStore и подключение Uppy
Для настоящей передачи запустите npm run tus во второй консоли. Перед этим создайте случайный UPPY_TUS_TOKEN и вставьте его в локальное поле мастерской. Сервер слушает только 127.0.0.1:8569, принимает ограниченные файлы и не раздаёт их через публичный GET. Токен относится к вашей учебной копии; в опубликованной странице его нет.
Uppy Tus подключается к этому endpoint и ведёт сетевую передачу. В примере размер части 64 KiB выбран, чтобы последовательность было проще изучать. Для production это не универсальная рекомендация: частые мелкие запросы создают накладные расходы. Настройку нужно согласовать с сервером, proxy и реальными размерами файлов.
Loopback очень быстрый, поэтому ручная пауза маленького файла может не успеть сработать. Для наблюдения используйте ограничение скорости в DevTools или запись HTTP-опыта. Плагин и его параметры описаны в документации Uppy Tus. Без совместимого серверного endpoint одна клиентская настройка не создаст возобновление.
# PowerShell: собственный временный токен лаборатории
$env:UPPY_TUS_TOKEN = node -e "console.log(require('node:crypto').randomBytes(24).toString('hex'))"
Write-Output $env:UPPY_TUS_TOKEN
npm run tus
uppy.use(Tus, {
endpoint: 'http://127.0.0.1:8569/files',
headers: { Authorization: 'Bearer ' + token },
retryDelays: [0, 500, 1500], limit: 2,
chunkSize: 65536, // Только для наблюдения в лаборатории
removeFingerprintOnSuccess: true
});
Пример 8. Черновик в IndexedDB после обновления страницы
Выберите задачу восстановления, добавьте файлы и подписи, нажмите «Сохранить черновик». После очистки списка или обновления страницы «Восстановить» вернёт Blob и метаданные. Хранение выполняется только по явному действию; общий размер ограничен 2 MiB, количество — четырьмя, срок — 24 часами.
Это собственный небольшой механизм IndexedDB. Он восстанавливает выбранные данные, но не обещает автоматически продолжить серверную загрузку. Связь с Tus-ресурсом, срок его хранения и актуальность авторизации — отдельные вопросы. В экосистеме Uppy есть Golden Retriever; в данном проекте этот плагин не подключён, чтобы граница нашего сценария была видна в коротком исходнике.
Локальное хранилище может быть недоступно или очищено браузером. Поэтому интерфейс сообщает ошибку сохранения, а не рисует ложный успех. Черновик на одном устройстве не является серверной резервной копией и не появляется автоматически на другом. Для чувствительных документов заранее определите, допустимо ли вообще сохранять их в браузере.
await saveDraft(uppy.getFiles());
const draft = await loadDraft();
uppy.cancelAll();
for (const file of draft.files) uppy.addFile(file);
// Отдельное действие пользователя:
await deleteDraft();
Пример 9. Манифест: когда можно завершать заявку
Последняя задача связывает файлы с прикладным действием. Попробуйте подготовить заявку до окончания передачи: контракт отклонит незавершённый набор. Завершите все файлы и повторите. В результате появится JSON с requestId, идентификаторами, именами, размерами, подписями и признаком submitted:false. Его можно скачать и изучить.
Учебный манифест никуда не отправляется. Он показывает границу между upload и сохранением сущности. Пользователь может успешно передать два документа, но ещё не нажать «Создать заявку». На сервере такие объекты удобно считать временными, пока отдельная транзакция не проверит владельца, статус и разрешённую связь с заявкой.
После добавления, удаления файла или изменения номера подготовленный результат сбрасывается. Это защищает от скачивания очевидно устаревшего снимка интерфейса. В реальном API нужна более сильная проверка: клиентские ID недоверенные, а состояние могло измениться параллельно. Кнопка завершения должна отражать подтверждённый результат сервера, а не только локальное отсутствие ошибок.
export function manifest(files,requestId) {
validateBeforeUpload(files,'commit',requestId);
if(files.some(f=>f.error||!f.progress.uploadComplete||!f.response?.body?.id))throw Error('Сначала успешно завершите каждый файл.');
return {requestId,attachments:files.map(f=>({id:f.response.body.id,name:f.name,size:f.size,caption:f.meta.caption||'',transport:f.response.body.transport})),submitted:false};
}
Прогресс передачи и готовность документа — разные состояния
Проценты полезны, когда точно известно, что они измеряют. XHR сообщает о передаче запроса, Tus работает с подтверждёнными смещениями, а наш TeachingTransport показывает только локальный учебный цикл. Не называйте все три значения одинаковым «документ готов», если за передачей следуют проверка, преобразование и привязка к сущности.
В рабочем сервисе файл может пройти состояния selected, uploading, uploaded, checking и ready. К примеру, изображение после приёма перекодируется, PDF проверяется, а антивирусный этап занимает дополнительное время. Пользователю лучше показать «Файл принят, выполняется проверка», чем замереть на ста процентах без объяснения.
Обработка изображений разобрана в материале про Intervention Image. В нашем Tus-стенде произвольные байты сохраняются в приватной лаборатории и не становятся доступным документом. Проверка MIME и готовности после завершения специально обозначена как задача интеграции. Этот шаг нельзя заменить расширением имени, присланным браузером.
Ошибки сети и API: какое действие предложить человеку
Разделяйте ошибки, которые пользователь может исправить, и временные сбои. Неверный тип требует другого файла, превышение размера — уменьшения или изменения лимита сервиса, отказ авторизации — восстановления входа. Повторять неизменённый запрос при каждом ответе 413 бессмысленно. Временную недоступность можно повторить с ограниченной задержкой.
В PHP-записи видно несколько уровней отказа: 401 без сессии, 403 при неправильном CSRF, 415 для недопустимого содержимого, 422 для метаданных, 413 для размера. В реальной инфраструктуре 413 может вернуть Nginx до запуска PHP. Поэтому обработчик ошибок клиента должен выдерживать и не-JSON ответ, не оставляя форму в бесконечной загрузке.
Сохраняйте связь сообщения с конкретным файлом, предлагайте понятное исправление и не удаляйте уже успешные элементы. Для поддержки полезны request ID и серверный журнал. Токены, cookies и содержимое частных документов в такой журнал не нужны. Результат отмены также следует объяснить отдельно от ошибки сети.
Безопасность и квоты: чему не равен красивый uploader
Наши обработчики намеренно ограничены loopback. PHP использует сессию и CSRF, но не систему пользователей; Tus — общий локальный bearer, но не разграничение по владельцам. Поэтому архив нельзя просто выставить наружу и назвать приватным файловым сервисом. Он даёт проверяемую основу передачи и показывает места для прикладных решений.
Перед публичной интеграцией определите владельца ресурса, срок хранения, доступ к исходному документу и политику удаления. Квота должна учитывать параллельные запросы атомарно: подсчёт файлов в каталоге одного учебного процесса не заменяет транзакцию нескольких PHP-FPM workers. Случайный ID уменьшает угадываемость, но права проверяются отдельно.
Файлы держите вне исполняемого web-root. Не доверяйте имени и заявленному MIME. Для изображений дополнительно ограничивайте размеры и ресурсы декодирования; для документов выбирайте необходимые проверки по их назначению. Не подключайте облачные источники и OAuth просто ради наличия кнопок: каждый новый источник расширяет реальные обязанности вашего приложения.
Linux/VPS: раздать мастерскую и подключить свой API
Для публикации этой мастерской достаточно статического каталога public. Nginx или Caddy раздают HTML, CSS, JavaScript и записи проверок; PHP-обработчики остаются в исходном архиве. Так устроена и версия статьи: читатель может работать с интерфейсом, а сайт не принимает его документы.
Если вы внедряете реальную загрузку в свой сервис, нужен отдельный контроллер с аутентификацией и правами. Для PHP согласуйте client_max_body_size у proxy, post_max_size и upload_max_filesize в PHP и прикладной лимит. Для Tus настройте разрешённые методы, streaming, таймауты и корректные Location; затем проверьте прерывание и продолжение через именно ваш proxy.
Файл deploy/VPS.md разделяет статическую публикацию и приватную лабораторию через SSH. Практику инфраструктуры дополняют статьи про Nginx, Caddy и Docker Compose. TLS, резервирование, очистка и наблюдение за диском относятся к работающему серверу, а не возникают автоматически после npm run build.
server {
listen 80;
server_name uploads.example.com;
root /srv/uppy/public;
index index.html;
add_header X-Content-Type-Options nosniff always;
location / { try_files $uri $uri/ =404; }
location ~ \.php$ { return 404; }
}
# Для реального домена настройте HTTPS вашим ACME-клиентом.
# Проверка конфигурации перед reload:
# sudo nginx -t
Очистка временных файлов и завершение лаборатории
Временные вложения появляются, когда человек выбрал файл, передал его и ушёл, не завершив заявку. Если сохранять их бесконечно, квота заканчивается даже без активных пользователей. В продукте полезна явная модель временного объекта: владелец, размер, время создания, срок удаления, статус проверки и ссылка на итоговую сущность.
В нашем PHP-примере владелец может удалить объект отдельным DELETE с CSRF. Tus поддерживает авторизованное завершение ресурса через DELETE. Запись проверок использует эти действия и подтверждает результат. Удаление элемента списка Uppy само по себе не вызывает прикладной DELETE и не гарантирует освобождения диска.
В FileStore задан срок для незавершённых передач, однако регулярный запуск cleanup и политика завершённых объектов остаются отдельной задачей. Не обещайте автоматическую очистку только из-за наличия expiration-настройки. После опытов остановите собственные процессы и удаляйте только данные конкретной учебной копии, сверив путь. Пользовательские проекты и другие контейнеры для этого не нужны.
// PHP: cookie текущей сессии отправляется same-origin автоматически.
await fetch('/api/files/' + id, {
method: 'DELETE', credentials: 'same-origin',
headers: { 'X-CSRF-Token': csrf }
});
Мобильный интерфейс и доступность действий
На узком экране человек чаще выбирает файл через системный диалог, чем перетаскивает его мышью. Поэтому основное действие должно оставаться явной кнопкой, а drag-and-drop — дополнительным удобством. В мастерской колонки складываются, действия переносятся, а длинный JSON прокручивается внутри блока, не расширяя всю страницу.
Сообщение состояния находится рядом с кнопками и объявляется через aria-live. Ошибка описывается текстом, а не одним цветом. Поля номера заявки, transport и токена имеют подписи. При работе с клавиатурой важно проверить доступность выбора, удаления, повторения и просмотра исходников, не требуя точного попадания в маленькую иконку.
При переносе в продукт проверяйте полный путь: добавить файл, исправить подпись, дождаться результата, восстановить ошибку, завершить заявку. Эмуляция узкой ширины помогает найти переполнение, но не подтверждает поведение файлового диалога на каждом физическом телефоне. Для камеры и специальных мобильных сценариев потребуется отдельная проверка на целевых устройствах.
Что проверено: Uppy, HTTP, Windows и Linux
В проект включены четыре содержательных теста реального Uppy Core: ограничения, контракт метаданных, частичный отказ с повтором только ошибочного файла, пауза и отмена активных задач. Они запускаются в Node и проверяют состояние библиотеки; это не подстановка собственного объекта вместо Uppy.
Скрипт record выполняет ещё два HTTP-сценария по десять шагов: PHP и Tus. PHP проверяет реальные multipart-байты, сессию, CSRF, тип, размер, владельца, чтение и удаление. Tus проверяет авторизацию, лимит, запись части, рестарт FileStore, подтверждённый offset, отказ 409 и совпадение итоговой SHA. Токены и случайные сессионные данные не попадают в публичную запись.
Эти проверки выполнены в Windows с Node 24.19.0 и в отдельном Linux-контейнере с Node 24.22.3 и PHP 8.3.36. Записи доступны в мастерской. Они подтверждают описанные операции, но не заменяют браузерную приёмку страницы или нагрузочные испытания вашего production-сервера. После изменения исходников повторяйте тесты и пересобирайте публичные файлы.
npm test
npm run record
npm run build
# Изолированная Linux-проверка:
docker build -t aen-uppy-lab .
docker run --rm --name aen-uppy-verify aen-uppy-lab
Исходники и маршрут внедрения в рабочий сервис
Скачиваемый архив содержит весь проект, lock-файл, локальные серверы, тесты, инструкции и готовый public. Авторский код распространяется по MIT; лицензии зависимостей собраны в LICENSES.txt. Просмотрщик на странице показывает те же исходные файлы, что использованы при сборке. Сначала повторите учебный набор, затем меняйте один контракт за раз.
Практичный первый шаг — вложения одной сущности с небольшими лимитами и понятным серверным ID. После этого добавьте обработку частичных ошибок, приватное чтение и удаление. Tus имеет смысл подключать, когда продолжение действительно экономит пользователю время; вместе с ним нужно проверить хранение ресурсов и права после восстановления соединения.
Для расширения ориентируйтесь на Dashboard API, Uppy Core, XHRUpload и Tus plugin. Хорошая интеграция заканчивается не движущейся полосой, а понятным ответом на три вопроса: что принято, где это сохранено и какое действие пользователь может выполнить дальше.


