Строка `Отчёт + 10%.pdf` проходит минимум через форму, приложение, SDK, подпись URL, объектное хранилище и HTTP-ответ браузеру. Если один слой декодирует её второй раз, `%` станет началом escape-последовательности, `+` превратится в пробел или кириллица распадётся. Лечить это заменой символов в конце слишком поздно.

В S3 object key — Unicode-последовательность в UTF-8 размером до 1024 байт. Слеш является частью key и создаёт видимость папок, хотя модель хранилища плоская. Пользовательское имя файла не обязано становиться key: чаще безопаснее генерировать UUID/key, а исходную строку хранить отдельно.

Три значения не смешиваются

ЗначениеПримерНазначение
object keytenant/42/01J….binстабильный адрес объекта
original filenameОтчёт + 10%.pdfотображение и аудит
download filenameочищенная версияContent-Disposition браузеру
URL-encoded keytenant/42/01J%E2%80%A6.binпуть HTTP/подпись

Не восстанавливайте имя из последнего сегмента key, если оно важно бизнесу. Храните его в своей БД рядом с MIME type, размером и владельцем; пользовательские metadata объекта могут быть дополнительной копией, но не единственным индексом.

Загрузка фиксирует исходную Unicode-строку

  • Принять имя как Unicode и ограничить длину в байтах и символах.
  • Удалить NUL, управляющие символы и разделители путей для download name.
  • Не доверять расширению при определении MIME и безопасности файла.
  • При необходимости выбрать одну форму нормализации Unicode и записать её явно.
  • Создать независимый object key, не раскрывающий tenant или персональные данные.

NFC и NFD могут выглядеть одинаково, но состоять из разных code points. Это особенно заметно после загрузки с разных ОС. Не нормализуйте молча уже существующие keys: в S3 это разные объекты. Нормализацию лучше ввести на границе новой загрузки и сохранить исходное значение для отображения.

Key кодируется ровно один раз

raw key: tenant/42/Фото #1+.jpg
path segments: [tenant, 42, Фото #1+.jpg]
encode each segment as UTF-8 percent-encoding
keep intentional '/' separators
never encode the already encoded URL again

SDK обычно сам формирует канонический запрос и подпись. Если передать ему уже percent-encoded key вместо исходной строки, знак `%` может закодироваться как `%25`, и запрос уйдёт к другому объекту. Зафиксируйте контракт функции: она принимает raw key или URL, но не угадывает по наличию процента.

Браузеру имя задаёт Content-Disposition

RFC 6266 разрешает одновременно передать совместимый ASCII `filename` и расширенный UTF-8 `filename*`; получатель, который понимает оба, должен предпочесть `filename*`. ASCII fallback не обязан побайтно повторять кириллицу — он нужен старым клиентам и должен оставаться безопасным.

Content-Disposition: attachment;
 filename="report-10-percent.pdf";
 filename*=UTF-8''%D0%9E%D1%82%D1%87%D1%91%D1%82%20%2B%2010%25.pdf

Экранируйте каждый параметр по его синтаксису, а не общей HTML-функцией. Уберите CR/LF, кавычки обрабатывайте корректно, разделители пути не допускайте. Не позволяйте имени изменить заголовки ответа или сохранить файл за пределами выбранной пользователем папки.

Presigned URL подписывает итоговый заголовок

S3 GetObject позволяет переопределить `Content-Disposition` через query-параметр `response-content-disposition`. Для presigned URL этот параметр добавляют до вычисления подписи и кодируют так, как ожидает SDK. Если изменить его после подписания, canonical request уже не совпадёт и хранилище отклонит запрос.

  1. Взять raw object key из БД.
  2. Сформировать безопасные filename и filename* из original filename.
  3. Передать response-content-disposition в параметры SDK GetObject.
  4. Получить presigned URL с коротким сроком.
  5. Проверить заголовок фактического ответа и имя в браузере.

Матрица символов находит первый сломанный слой

ИмяЧто проверяетЧастая ошибка
Фото 1.jpgUTF-8 и пробелпробел стал +
a+b.txtliteral plus+ превратился в пробел
10%.pdfliteral percentошибка decode
a#b?.txtfragment/querykey обрезан в URL
ё/ё.txtNFD/NFC и slashразные keys/путь
"name".csvquoted filenameсломанный заголовок

Для каждого случая сравните исходную строку, UTF-8 bytes, key в SDK, canonical request при необходимости, сохранённый key из list/head, заголовок ответа и имя на диске. Не ограничивайтесь тем, что объект «открылся»: неверное имя может проявиться только при скачивании.

Миграция не переименовывает objects вслепую

Переименование в объектном хранилище обычно означает copy в новый key и удаление старого. До массовой операции составьте таблицу old key → new key, проверьте ссылки и версии, сохраните rollback и исключите коллизии Unicode. Если проблема только в download filename, менять object key вообще не нужно.

Для разбора подготовьте один raw key, original filename в JSON-escaped виде, итоговый URL без подписи/секретных параметров, Content-Disposition ответа, используемый SDK и результат матрицы символов. Access key и полный presigned URL передавать нельзя.

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