Если картинка появилась до отправки формы, это может быть локальный `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 | Временный upload | storage key |
| /app/public/u/a.png | Зависит от release | shared media key |
| http://container-7/a.png | Имя экземпляра | публичный media URL |
| avatar.png | Коллизии | generated unique key |
Старая картинка может быть только кешем
Если объект сохранён, но браузер показывает прежний, сравните фактический URL и response headers. Проще создавать новый versioned key при каждой замене, чем пытаться немедленно очистить все слои кеша. Удаление старого объекта делайте после успешной записи нового и обновления базы, иначе частичный сбой оставит профиль без аватара.
Тест отличает upload от preview
- Загрузить небольшой валидный PNG и дождаться ответа API.
- Скопировать возвращённый key и открыть URL в приватном окне.
- Перечитать профиль через API и сравнить сохранённое значение.
- Перезапустить один экземпляр приложения и повторить GET.
- Попробовать файл с неверной сигнатурой и слишком большими размерами.
- Заменить аватар дважды и проверить, что профиль указывает на последнюю версию.
Готовая реализация переживает обновление страницы и перезапуск приложения, не принимает произвольный файл и не оставляет базу указывать на отсутствующий объект. Для разбора принесите обезличенный request id, ответ API, storage key и логи этапа записи — само изображение пользователя обычно не требуется.