Если картинка появилась до отправки формы, это может быть локальный `blob:` preview: сервер её ещё не видел. Обновите страницу и посмотрите Network. Нужны два подтверждения — успешный upload-запрос и последующий GET по новому постоянному URL.

Разбирайте путь файла слева направо. Так ответ «200 OK» не спрячет ошибку фоновой обработки, запись абсолютного временного пути в базу или сохранение внутри удаляемого слоя контейнера.

Семь контрольных точек одного изображения

ЭтапЧто зафиксироватьТипичный сбой
Формаmultipart/form-data и имя поляJSON вместо файла
Приёмразмер, upload error, request idлимит proxy/PHP
Проверкареальный тип и декодированиедоверие расширению
Преобразованиеформат, размеры, результат encoderисключение после response
Storageустойчивый key и подтверждение записивременный каталог
Базаkey/version пользователястарое поле не обновилось
Выдачаstatus, Content-Type, cacheстарый URL из кеша

Backend возвращает объект, который можно снова прочитать

POST /api/profile/avatar
Content-Type: multipart/form-data; boundary=...

HTTP/1.1 201 Created
Content-Type: application/json

{
  "avatar_key": "avatars/u-1842/01J...webp",
  "avatar_url": "/media/avatars/u-1842/01J...webp"
}

Формат условный. Клиент сохраняет полученный URL, а не продолжает показывать локальный blob. Перед успешным ответом приложение должно знать, что объект действительно записан; если преобразование выполняется асинхронно, API явно возвращает статус обработки и UI умеет показать ошибку.

Изображение проверяют по содержимому

  • Разрешайте только необходимые форматы и ограничивайте размер до декодирования.
  • Не доверяйте присланному Content-Type: его выбирает клиент.
  • Проверяйте сигнатуру и способность безопасной библиотеки декодировать файл.
  • Генерируйте собственное имя, не используйте путь из имени пользователя.
  • Ограничивайте ширину, высоту и общее число пикселей.
  • Храните объект вне исполняемого каталога и выдавайте как данные.

OWASP рекомендует сочетать allowlist расширений, проверку типа и сигнатуры, лимиты, сгенерированное имя и авторизацию. Ни одна отдельная проверка не является полной защитой. Повторное кодирование изображения полезно для нормализации, но всё равно требует актуальной библиотеки и обработки ошибок.

В контейнере нужен постоянный слой

Файл, записанный в `/tmp` или writable layer контейнера, исчезнет после очистки или пересоздания. Для одного сервера это может быть volume или отдельный shared-каталог; для нескольких экземпляров — общее object storage. В базе храните key относительно выбранного storage, а не путь конкретного контейнера.

Значение в базеПочему хрупкоУстойчивее
/tmp/php8F3aВременный uploadstorage key
/app/public/u/a.pngЗависит от releaseshared media key
http://container-7/a.pngИмя экземплярапубличный media URL
avatar.pngКоллизииgenerated unique key

Старая картинка может быть только кешем

Если объект сохранён, но браузер показывает прежний, сравните фактический URL и response headers. Проще создавать новый versioned key при каждой замене, чем пытаться немедленно очистить все слои кеша. Удаление старого объекта делайте после успешной записи нового и обновления базы, иначе частичный сбой оставит профиль без аватара.

Тест отличает upload от preview

  1. Загрузить небольшой валидный PNG и дождаться ответа API.
  2. Скопировать возвращённый key и открыть URL в приватном окне.
  3. Перечитать профиль через API и сравнить сохранённое значение.
  4. Перезапустить один экземпляр приложения и повторить GET.
  5. Попробовать файл с неверной сигнатурой и слишком большими размерами.
  6. Заменить аватар дважды и проверить, что профиль указывает на последнюю версию.

Готовая реализация переживает обновление страницы и перезапуск приложения, не принимает произвольный файл и не оставляет базу указывать на отсутствующий объект. Для разбора принесите обезличенный request id, ответ API, storage key и логи этапа записи — само изображение пользователя обычно не требуется.

Проверенные источники