Перейти к содержимому
Поиск
Разработка

Garage: собственное S3-хранилище — мастерская, PHP, Node.js и 9 опытов

Храним файлы приложения через S3 API: девять реальных опытов, права, временные ссылки, multipart, PHP и Node.js. Мастерская, исходники и Linux/VPS.

Александр Некрасов
Garage: собственное S3-хранилище — мастерская, PHP, Node.js и 9 опытов — обложка

Garage: файлы приложения через S3 API

Приложение принимает фотографии, формирует PDF, хранит вложения обращений и выгружает большие отчёты. Сначала всё лежит рядом с PHP-кодом в uploads. Затем появляются второй сервер, фоновые задачи, отдельный кабинет и необходимость выдавать файл по временной ссылке. В этот момент полезно отделить хранение объектов от конкретного экземпляра приложения. Garage предоставляет собственный S3-совместимый сервер: клиент обращается к bucket и ключу объекта через HTTP, а приложение перестаёт зависеть от локального каталога одного веб-процесса.

В этом материале соберём рабочую лабораторию с девятью опытами. Загрузим текстовый отчёт, проверим байты, прочитаем метаданные, обойдём каталог страницами, запросим диапазон, скопируем и удалим объект, ограничим доступ и создадим временные ссылки. Для больших файлов разберём multipart. Будут Node.js, PHP, Windows, Linux, настройки HTTPS и понятные границы одноузлового стенда.

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

Где использовать: CRM, отчёты, медиа и внутренние сервисы

В CRM объектное хранилище подходит для файлов обращения, актов, фотографий результата работы и выгрузок. В базе приложения остаются владелец, статус, назначение и ключ объекта; сами байты передаются в Garage. Когда пользователь открывает карточку, приложение проверяет его права и выдаёт короткую ссылку либо проксирует файл. Разные роли могут видеть одну карточку, но иметь разные разрешения на её вложения.

В сервисе отчётов генератор PDF работает в очереди и сохраняет результат по новому ключу. Веб-приложение показывает статус «готов» и размер документа, не удерживая большой файл в памяти после ответа. Такой сценарий удобно связать с BullMQ. Для интерфейса загрузки подойдёт Uppy, но права и подтверждение сохранения всё равно определяет сервер приложения.

Garage также можно рассматривать как место для копий и артефактов, если выбранная программа действительно поддерживает нужный набор S3-операций. Перед переносом проверьте сценарий целиком: создание, чтение, удаление, восстановление и работу при отказе. Совпадение названия протокола не заменяет такую проверку.

Bucket, key, metadata: как устроен адрес файла

Bucket объединяет объекты и служит границей назначения и доступа. Key — полное имя объекта внутри bucket, например reports/2026-11/weekly.pdf. Слеши создают привычное представление каталога для клиента, но объект остаётся значением по одному ключу. Изменение «папки» обычно означает новый ключ и, при необходимости, отдельное удаление старого.

В учебном проекте bucket называется aen-workshop. Node-проверки каждой платформы работают в собственном префиксе reports/windows/ или reports/linux/. Это делает результаты понятными и позволяет повторять тест, не затрагивая произвольные объекты. Основной файл weekly.txt содержит русскоязычный отчёт. Мы считаем SHA-256 исходного текста и сравниваем его с полученным содержимым.

Metadata хранит небольшие дополнительные атрибуты, а Content-Type помогает клиенту понять формат. Не складывайте туда полноценную карточку клиента, секреты и сложную модель доступа. Деловые данные удобнее держать в БД приложения, где доступны транзакции, индексы и проверки прав. Связь с файлом создавайте через устойчивый идентификатор и ключ объекта.

const reference = {
  bucket: 'aen-workshop',
  key: 'reports/windows/weekly.txt',
  contentType: 'text/plain; charset=utf-8'
};

S3-совместимость: что проверить до выбора инструмента

S3-совместимый сервер предоставляет знакомые операции и подпись запросов, но не обязан повторять весь набор сервисов AWS. В нашей лаборатории проверены конкретные действия: PutObject, GetObject, HeadObject, ListObjectsV2, CopyObject, DeleteObject, временные ссылки и multipart. Для них важны не только HTTP-коды, но и точные байты, права, параметры и ошибки.

Сверяйте требования с таблицей совместимости Garage. Например, встроенное версионирование bucket не заявлено как реализованная функция. Поэтому перезапись одного ключа не нужно подавать пользователю как гарантированное сохранение всех прежних версий. Если история нужна, создавайте собственные уникальные ключи и храните связь версий в БД, а независимое резервирование планируйте отдельно.

Для оценки выпишите операции вашей системы: потоковая загрузка, диапазоны, метаданные, очистка незавершённых загрузок, CORS, выдача ссылок. Затем прогоните их своим клиентом. Не переносите автоматически в конфигурацию Garage политики IAM или параметры, предназначенные для другого S3-провайдера: одинаковое назначение не означает одинаковую административную модель.

Мини-мастерская: девять реальных опытов и конструктор запроса

На странице находится интерактивный просмотрщик записей. Выберите задачу, затем платформу Windows или Linux и нажмите «Показать результат». Входные параметры, статус, хеши и детали получены реальными Node.js-клиентами против Garage 2.5.0 в отдельном Linux-контейнере. Переключатель платформ выбирает запись; он не запускает новый серверный запрос на хостинге сайта.

Ниже можно подготовить GetObject, HeadObject или PutObject: указать bucket, ключ внутри reports/ и срок временной ссылки. Конструктор проверяет форму значений и выдаёт JSON. Он не подписывает URL, не обращается к вашему серверу и не запрашивает secret key. Это удобная заготовка для чтения примеров, а не форма управления чужим хранилищем.

Изменение параметров сбрасывает готовый результат и отключает его скачивание до повторной сборки. Исходники можно выбрать в списке файлов, раскрыть, скопировать либо сохранить. Полный проект содержит исполняемые тесты, PHP-клиент, Compose и инструкции для собственного сервера.

Версии, состав проекта и воспроизводимость

Проект закрепляет Garage 2.5.0 не только тегом, но и digest Docker-образа. AWS SDK для JavaScript используется в версии 3.1171.0; зависимости записаны в package-lock.json. Проверки выполнены Node.js 24 на Windows и Linux. PHP-пример рассчитан на PHP 8.3 с ext-curl и поддержкой CURLOPT_AWS_SIGV4 в cURL.

Lock-файл помогает повторить набор пакетов, а закреплённый образ — конкретный сервер. Это не обещание, что такой набор нужно сохранять навсегда: перед обновлением проверяйте изменения API, совместимость и миграции. После обновления сначала прогоняйте тесты на отдельном стенде, затем планируйте перенос данных и возврат при ошибке.

В архив не входят node_modules, рабочие ключи, метаданные Garage и содержимое его диска. Случайные секреты создаются при первом lab:up внутри .runtime. Статическая мастерская получает только очищенные записи и исходный код. Полные подписанные URL в записи специально не сохраняются: это временные возможности доступа, а не безопасные диагностические строки.

{
  "name": "aen-garage-workshop",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT",
  "scripts": {
    "lab:up": "node tools/lab.mjs up",
    "lab:down": "node tools/lab.mjs down",
    "lab:restart": "node tools/lab.mjs restart",
    "test": "node tests/integration.mjs",
    "build": "node tools/build.mjs",
    "start": "node tools/server.mjs"
  },
  "dependencies": {
    "@aws-sdk/client-s3": "3.1171.0",
    "@aws-sdk/s3-request-presigner": "3.1171.0",
    "bootstrap": "5.3.9"
  }
}

Windows: поднять лабораторию и выполнить первые запросы

На Windows нужен Docker Desktop в режиме Linux containers и установленный Node.js 24. Распакуйте архив в отдельный каталог и откройте там PowerShell. Команда npm ci устанавливает зависимости по lock-файлу, а lab:up создаёт собственное состояние и запускает только Compose-проект aen-b25-garage. Сервис доступен по loopback, поэтому лаборатория не открывает S3 для всей локальной сети.

После npm test появится актуальная запись Windows. PHP-команда выполняет отдельный PUT и GET, сравнивает хеш и печатает короткий результат без ключей. Если PHP не видит ext-curl, сначала проверьте свой php.ini и используемый исполняемый файл. Наличие PHP в другой программе не означает, что именно он доступен из текущего терминала.

Команды restart и persistence разделены специально: после перезапуска мы действительно читаем контрольные объекты, а не считаем успешный старт доказательством сохранности. Браузерная мастерская открывается на 8594. Завершение lab:down сохраняет данные, чтобы следующий запуск продолжился с теми же учебными ключами.

npm ci --ignore-scripts
npm run lab:up
npm test
php src/upload.php
npm run lab:restart
node tools/persistence.mjs
npm run build
npm start

Linux: тот же проект и проверка из контейнера

В Linux используйте Docker Engine с Compose plugin и Node.js 24. Команды проекта совпадают с Windows; это снижает различия между компьютером разработчика и серверной платформой. Установка Docker и права на сокет зависят от дистрибутива и вашей политики доступа. Не решайте проблему разрешений выдачей всему каталогу произвольных прав на запись.

Отдельный пример ниже запускает Node-клиент внутри сети лаборатории. Там Garage доступен по имени сервиса garage и порту 3900; с хоста используется 127.0.0.1:8591. Эти адреса не взаимозаменяемы в уже подписанной ссылке, поскольку имя хоста участвует в подписи. Для теста клиент подписывает запрос сразу для своего endpoint.

В публикации Linux-проверки выполнены в локальных контейнерах, а не на боевом VPS. Это подтверждает исполняемый код и интеграцию с реальным сервером в данной среде. Настройка DNS, сертификата, дисков и внешних клиентов рассматривается отдельно и требует проверки на вашей инфраструктуре.

npm ci --ignore-scripts
npm run lab:up

docker run --rm --network aen-b25-garage_default \
  -e GARAGE_ENDPOINT=http://garage:3900 \
  -v "$PWD:/app" -w /app node:24.22.3-bookworm-slim \
  node tests/integration.mjs

Compose: закрытый учебный сервер и постоянные каталоги

Compose публикует только один порт S3 и только на 127.0.0.1. RPC и admin API не выведены на хост. Это полезная исходная схема для разработки: тестовый сервер не становится непреднамеренно общедоступным. Для HTTPS на VPS перед loopback-портом будет отдельный reverse proxy с вашим доменом.

Garage хранит метаданные и блоки объектов в разных каталогах. В проекте оба находятся внутри .runtime и подключены постоянными bind mounts. Остановка или пересоздание контейнера не должна удалять их. При этом сохранность каталога на одном диске не равна отказоустойчивости: потеря диска уничтожит и объекты, и локальные метаданные.

Секреты передаются через локальный env-файл, который генерирует инструмент запуска. Файл исключён из исходного архива и публичного просмотра. В реальном развёртывании ограничьте доступ к нему и к Docker: пользователь, имеющий полный доступ к Docker, может читать конфигурацию контейнеров. Не воспринимайте переменную окружения как автоматическое шифрование.

services:
  garage:
    image: dxflrs/garage:v2.5.0@sha256:677e5b758e4425a325b811c425c026bf35a4bf42f7ddbaa773de3f4fd779a5a5
    command: [/garage, server, --single-node, --default-bucket]
    env_file: .runtime/garage.env
    environment:
      RUST_LOG: garage=warn
      NO_COLOR: "1"
    ports: ["127.0.0.1:8591:3900"]
    volumes:
      - ./garage.toml:/etc/garage.toml:ro
      - ./.runtime/meta:/var/lib/garage/meta
      - ./.runtime/data:/var/lib/garage/data
    restart: unless-stopped

Конфигурация Garage: region, endpoint и один узел

В нашем garage.toml выбран SQLite для метаданных, replication_factor=1 и локальный RPC-адрес. Флаги запуска автоматически настраивают один узел и начальный bucket. Такой режим удобно изучать: не нужно сначала осваивать весь процесс изменения layout. Но он не создаёт вторую копию данных и не должен незаметно превратиться в единственное хранилище важных оригиналов.

S3 region здесь равен garage. Это значение должно совпадать у сервера и подписывающего клиента. public_endpoint описывает адрес, под которым сервис доступен потребителям. В лаборатории это HTTP на loopback; после настройки домена его заменяют на HTTPS-адрес. Path-style позволяет обращаться по пути /bucket/key без отдельных DNS-имён для каждого bucket.

Начальные ключи создаёт lab:up. Отдельный read-only ключ нужен для проверки минимальных прав. Инструмент сохраняет секрет локально, но выводит только сообщение о готовности; ключи не попадают в обычный stdout. Подробности параметров сверяйте со справочником конфигурации выбранной версии.

metadata_dir = "/var/lib/garage/meta"
data_dir = "/var/lib/garage/data"
db_engine = "sqlite"
replication_factor = 1
rpc_bind_addr = "127.0.0.1:3901"
rpc_public_addr = "127.0.0.1:3901"

[s3_api]
s3_region = "garage"
api_bind_addr = "0.0.0.0:3900"
public_endpoint = "http://127.0.0.1:8591"
public_endpoint_path_style = true

[admin]
api_bind_addr = "127.0.0.1:3903"

Node.js: клиент с явными endpoint и path-style

S3Client получает четыре важные части: endpoint, region, credentials и forcePathStyle. По умолчанию наш endpoint локальный; в Linux-контейнере он передаётся через GARAGE_ENDPOINT. Количество попыток ограничено, чтобы временная ошибка не превращала учебный запрос в бесконечное ожидание. Политику повторов для рабочего приложения нужно выбирать по операции и требованиям к задержке.

SDK умеет добавлять контрольные суммы автоматически. В этой интеграции параметры requestChecksumCalculation и responseChecksumValidation выставлены в WHEN_REQUIRED, чтобы согласовать запросы с используемым S3-сервером. Это не отменяет прикладную проверку целостности: в опытах отдельно вычисляется SHA-256 полученных байтов. Не используйте ETag как универсальную замену собственному хешу для всех способов загрузки.

Конфигурацию credentials в примерах читает серверный код. Браузеру её передавать нельзя. Для фронтенда выдаётся короткая подписанная операция после авторизации пользователя либо используется собственный защищённый endpoint приложения. Данные формы посетителя не должны свободно определять адрес серверного S3-клиента.

import {S3Client,PutObjectCommand,GetObjectCommand} from '@aws-sdk/client-s3';
import {getSignedUrl} from '@aws-sdk/s3-request-presigner';
export function client(credentials,endpoint=process.env.GARAGE_ENDPOINT||'http://127.0.0.1:8591'){
 return new S3Client({endpoint,region:'garage',forcePathStyle:true,credentials,maxAttempts:2,requestChecksumCalculation:'WHEN_REQUIRED',responseChecksumValidation:'WHEN_REQUIRED'});
}
export function objectKey(value){if(typeof value!=='string'||!/^reports\/[a-zA-Z0-9][a-zA-Z0-9._/-]{0,180}$/.test(value)||value.includes('..')||value.endsWith('/'))throw Error('Key must be a file inside reports/, without ..');return value;}
export async function uploadReport(s3,bucket,key,text){objectKey(key);if(typeof text!=='string'||Buffer.byteLength(text)>1024*1024)throw Error('Report must be text up to 1 MiB');return s3.send(new PutObjectCommand({Bucket:bucket,Key:key,Body:text,ContentType:'text/plain; charset=utf-8',Metadata:{purpose:'aen-workshop'}}));}
export async function signedRead(s3,bucket,key,expiresIn=60){objectKey(key);if(!Number.isInteger(expiresIn)||expiresIn<1||expiresIn>300)throw Error('Expiry must be 1..300 seconds');return getSignedUrl(s3,new GetObjectCommand({Bucket:bucket,Key:key}),{expiresIn});}

Пример 1. Сохранить отчёт и проверить возвращённые байты

Первый опыт загружает короткий текст UTF-8 в weekly.txt, затем читает объект. Мы проверяем успешный PUT, размер тела и SHA-256. Такая последовательность полезнее одного сообщения «загружено»: неверная кодировка, преобразование перевода строки или чтение другого ключа сразу проявится в результате.

В реальном приложении сначала сформируйте устойчивый идентификатор отчёта. Для новой версии документа лучше создавать новый ключ, а не одновременно перезаписывать один путь разными заданиями. После успешной загрузки сохраните в БД bucket, key, размер, хеш и связь с владельцем. Если запись в БД не удалась, вам понадобится понятная процедура очистки осиротевшего объекта.

Учебная функция uploadReport принимает только текст до 1 MiB и ключ внутри reports/. Это проверка клиента, а не защита всего хранилища. Другой клиент с теми же правами может выполнить иной запрос. Ограничения пользовательской загрузки должны проверяться в авторизованном сценарии приложения и подтверждаться после фактического сохранения.

const put = await uploadReport(s3, Bucket, Key, reportText);
const object = await s3.send(new GetObjectCommand({Bucket, Key}));
const bytes = await object.Body.transformToByteArray();
const digest = createHash('sha256').update(bytes).digest('hex');
assert.equal(digest, expectedDigest);

Пример 2. HEAD: показать карточку файла без полного скачивания

Чтобы показать в кабинете имя, размер и формат, не обязательно загружать весь объект. HeadObject возвращает сведения о нём без тела. В опыте проверяются ContentLength, ContentType и metadata purpose. Это удобно для карточки отчёта, подтверждения готовности результата или сверки ожидаемого размера после внешней загрузки.

Часть пользовательских атрибутов может быть недостоверной, если их задавал сам клиент. Content-Type не доказывает, что внутри действительно PDF или изображение. Для важных загрузок анализируйте фактическое содержимое и применяйте свои правила допустимых файлов. Аналогично, поле owner в metadata само по себе не является авторизацией.

Старайтесь не строить экран списка на сотнях отдельных HEAD-запросов подряд. Основные сведения для каталога можно хранить в БД приложения при завершении загрузки, а HEAD использовать для точечной сверки. При необходимости пакетной проверки ограничивайте параллельность и показывайте пользователю прогресс, чтобы интерфейс не зависал на одном долгом ответе.

const info = await s3.send(new HeadObjectCommand({Bucket, Key}));
console.log({
  bytes: info.ContentLength,
  type: info.ContentType,
  purpose: info.Metadata?.purpose
});

Пример 3. Каталог: Prefix и ContinuationToken

В хранилище может быть больше объектов, чем помещается в один ответ. ListObjectsV2 возвращает страницу и, если нужно, токен продолжения. В опыте создаются пять собственных файлов, а MaxKeys=2 заставляет получить три страницы. Проверяем итоговое число, отсутствие дублей и принадлежность всех ключей выбранному префиксу.

ContinuationToken нужно считать непрозрачным значением. Не превращайте его в номер страницы и не конструируйте самостоятельно. Передавайте токен следующему запросу вместе с теми же фильтрами. Если пользователь сменил префикс, старый токен должен быть сброшен. Иначе экран будет смешивать состояние разных каталогов.

Обход изменяющегося хранилища не следует автоматически считать снимком на один момент времени. Для бизнес-отчёта, где важен точный состав, используйте свой реестр объектов или заранее зафиксированный набор ключей. В интерфейсе полезно различать пустой каталог, ещё не загруженную страницу, ошибку сети и окончание списка.

let token;
do {
  const page = await s3.send(new ListObjectsV2Command({
    Bucket, Prefix: 'reports/windows/page/', MaxKeys: 2,
    ContinuationToken: token
  }));
  console.log((page.Contents ?? []).map(item => item.Key));
  token = page.NextContinuationToken;
} while (token);

Пример 4. Range: получить нужный участок

Range позволяет прочитать часть объекта. Это нужно медиаплееру, просмотрщику большого файла и собственной докачке. Мы запрашиваем bytes=0-11, проверяем статус 206, Content-Range и ровно двенадцать полученных байтов. Их SHA сравнивается с тем же участком исходного буфера.

Диапазоны измеряются в байтах. Русская буква в UTF-8 занимает несколько байтов, поэтому произвольный диапазон может закончиться внутри символа. Нельзя считать результат Range готовой строкой для отображения без понимания кодировки и границ. Для бинарного файла это обычный буфер; для текстового просмотра нужен дополнительный слой разбора.

В собственной докачке сохраняйте идентичность исходного объекта. Если файл под тем же ключом изменился между частями, простое соединение диапазонов может дать неверный результат. Практичный подход — неизменяемые ключи версий и итоговая проверка полного хеша. Поведение прокси для Range тоже включайте в проверку на VPS.

const fragment = await s3.send(new GetObjectCommand({
  Bucket, Key, Range: 'bytes=0-11'
}));
const bytes = await fragment.Body.transformToByteArray();
assert.equal(fragment.$metadata.httpStatusCode, 206);
assert.equal(bytes.length, 12);

Пример 5. CopyObject: копия без промежуточного скачивания

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

CopySource указывает bucket и исходный key. Для имён с пробелами и другими специальными символами понадобится корректное кодирование, соответствующее SDK и API. В лаборатории используются предсказуемые ASCII-ключи, чтобы сосредоточиться на поведении операции, а не скрывать ошибки сложного URL за удачным примером.

Копия не равна атомарному переименованию в файловой системе. Если дальше предполагается удаление исходника, это второй шаг с собственными ошибками. Сначала подтвердите, что новая версия существует и доступна нужному получателю; затем обновите ссылку в БД и только после этого применяйте согласованную политику удаления.

await s3.send(new CopyObjectCommand({
  Bucket, Key: 'reports/windows/copy.txt',
  CopySource: Bucket + '/reports/windows/weekly.txt'
}));

Пример 6. Удаление: отдельная операция с понятным результатом

Опыт удаляет только copy.txt, который был создан предыдущим шагом. Затем GET должен вернуть 404. Это принципиальная граница учебного теста: он не получает все bucket и не очищает чужие префиксы. Даже в личной лаборатории безопаснее заранее перечислить, какие собственные объекты скрипт вправе изменить.

В интерфейсе приложения удаление обычно начинается с проверки прав и ясного подтверждения пользователем. Полезно сначала пометить запись как удалённую в собственном реестре, если вашим требованиям нужен период восстановления. Физическая очистка объекта может выполняться позже фоновой задачей с журналом результата.

Не рассчитывайте, что репликация вернёт объект после корректно авторизованного удаления: изменение распространяется как нормальная операция. История версий и резервная копия решают другую задачу. Сроки хранения, юридические требования и доступ сотрудников определяйте отдельно от кнопки DeleteObject. В лаборатории этих бизнес-правил нет, и пример не выдаёт их за готовый сервис.

await s3.send(new DeleteObjectCommand({Bucket, Key: copyKey}));
try {
  await s3.send(new GetObjectCommand({Bucket, Key: copyKey}));
} catch (error) {
  if (error.$metadata?.httpStatusCode === 404) {
    console.log('Объект отсутствует');
  } else throw error;
}

Пример 7. Read-only ключ и запрет анонимного чтения

Отдельному сервису, который только показывает отчёты, не нужно право записи. Лаборатория создаёт ключ aen-reader и выдаёт ему read на учебный bucket. Мы действительно читаем объект этим ключом, пробуем записать новый и выполняем неподписанный GET. Чтение разрешено, две последние операции получают отказ.

Права Garage и права пользователя приложения относятся к разным уровням. Один серверный ключ может читать весь bucket, а конкретному клиенту CRM доступно только одно обращение. Поэтому приложение сначала проверяет владельца и назначение файла, а уже затем выполняет S3-операцию либо выпускает временную ссылку.

Не используйте имя bucket как секрет. Не сохраняйте постоянный secret key в HTML, публичном JavaScript или localStorage посетителя. Разделяйте ключи интеграций, чтобы можно было отключить одну систему, не меняя доступ всех остальных. Команда ниже выдаёт только чтение; owner и write здесь не нужны.

docker compose -p aen-b25-garage -f compose.yaml exec -T garage \
  /garage bucket allow --read --key aen-reader aen-workshop

Пример 8. Временная ссылка GET или PUT

Подписанная ссылка позволяет клиенту выполнить конкретный запрос без передачи ему постоянного ключа. Например, пользователь прошёл авторизацию в кабинете, приложение проверило доступ к отчёту и создало GET-ссылку на шестьдесят секунд. Сам файл затем приходит из S3, не занимая поток вашего PHP-процесса на всю передачу.

В опыте проверены GET и PUT, изменение пути после подписи и истечение срока. Испорченный путь отклонён. Просроченная ссылка в Garage 2.5.0 возвращает 400 InvalidRequest с сообщением Date is too old. Поэтому клиент должен понимать категории ошибок, а не ожидать единственный код 403 для любой проблемы авторизации.

Ссылка не становится одноразовой только из-за TTL. Её можно использовать в пределах разрешённого времени и операции. Не выводите полный URL в логи, аналитику и публичные примеры. Для загрузки выберите сервером допустимый key, затем проверьте фактический объект и связь с заявкой. При подписании используйте адрес, доступный получателю: менять Host после создания подписи нельзя.

const url = await signedRead(s3, Bucket, Key, 60);
// Возвращайте URL только после проверки прав пользователя.
// Не записывайте его целиком в application log.

const putURL = await getSignedUrl(s3, new PutObjectCommand({
  Bucket, Key: 'reports/windows/presigned.txt',
  ContentType: 'text/plain'
}), {expiresIn: 60});

Пример 9. Multipart: части, завершение и отмена

Большой файл удобнее передавать частями. Сначала создаётся multipart upload, затем каждая часть получает номер, а клиент сохраняет её ETag. После успешной передачи всех частей CompleteMultipartUpload собирает объект. В нашем опыте первая часть содержит 5 MiB, вторая — 64 KiB; после завершения проверяется хеш общего содержимого.

Для пользовательского интерфейса это основа прогресса и повторной передачи отдельной части. Но сохранённый UploadId ещё не означает, что операция завершена. Клиент должен различать отправленные части, подтверждённое завершение и объект, готовый к использованию приложением. Если финальный запрос получил сетевой тайм-аут, сначала выясните результат, а не создавайте бесконечно новые загрузки.

Незавершённую загрузку нужно отменять. Поэтому второй опыт создаёт отдельную сессию, вызывает AbortMultipartUpload и проверяет, что её нет в списке. В рабочем сервисе добавьте уборку брошенных сессий по своей политике. Кнопка отмены в интерфейсе должна завершать и локальную передачу, и предусмотренную серверную очистку.

const started = await s3.send(new CreateMultipartUploadCommand({Bucket, Key}));
const part = await s3.send(new UploadPartCommand({
  Bucket, Key, UploadId: started.UploadId, PartNumber: 1, Body: bytes
}));
// Сохраните номер и ETag; после всех частей вызовите CompleteMultipartUpload.
// Если пользователь отменил операцию:
await s3.send(new AbortMultipartUploadCommand({
  Bucket, Key, UploadId: started.UploadId
}));

PHP: подписанный PUT/GET штатным cURL

Для небольшой PHP-интеграции не обязательно вручную реализовывать SigV4. Современный cURL умеет выполнять эту подпись через CURLOPT_AWS_SIGV4. Пример задаёт region/service, пару ключей, SHA тела, тайм-ауты и явный HTTP-метод. После PUT выполняется GET того же объекта; хеши сравниваются через hash_equals.

Это самостоятельный CLI-пример, который можно перенести в обработчик готового отчёта. Он читает локальную конфигурацию только на серверной стороне. В реальном приложении используйте принятый механизм секретов и собственную обработку исключений. Не печатайте ответ с диагностическими заголовками в публичную страницу при любой ошибке.

Для большого набора S3-операций удобнее полноценный SDK. Его можно подключить через Composer, а затем повторить те же проверки на вашей версии Garage. В этой лаборатории оба простых запроса действительно выполнены PHP на Windows и Linux; наличие такого примера не является проверкой всех методов AWS SDK for PHP.

<?php
declare(strict_types=1);
if (!extension_loaded('curl') || !defined('CURLOPT_AWS_SIGV4')) throw new RuntimeException('PHP ext-curl with AWS SigV4 support required');
$config=json_decode(file_get_contents(__DIR__.'/../.runtime/credentials.json'),true,512,JSON_THROW_ON_ERROR);
$base=getenv('GARAGE_ENDPOINT')?:'http://127.0.0.1:8591';
$key='reports/php-'.(PHP_OS_FAMILY==='Windows'?'windows':'linux').'.txt';
$body="Учебный отчёт PHP: UTF-8 и подпись SigV4.\n";
$url=rtrim($base,'/').'/'.$config['bucket'].'/'.implode('/',array_map('rawurlencode',explode('/',$key)));
function callS3(string $url,array $config,string $method,?string $body=null): array {
 $ch=curl_init($url);curl_setopt_array($ch,[CURLOPT_RETURNTRANSFER=>true,CURLOPT_CUSTOMREQUEST=>$method,CURLOPT_USERPWD=>$config['accessKeyId'].':'.$config['secretAccessKey'],CURLOPT_AWS_SIGV4=>'aws:amz:garage:s3',CURLOPT_CONNECTTIMEOUT=>3,CURLOPT_TIMEOUT=>10,CURLOPT_FOLLOWLOCATION=>false,CURLOPT_HTTPHEADER=>['Content-Type: text/plain; charset=utf-8','x-amz-content-sha256: '.hash('sha256',$body??'')]]);
 if($body!==null)curl_setopt($ch,CURLOPT_POSTFIELDS,$body);
 $result=curl_exec($ch);$status=curl_getinfo($ch,CURLINFO_RESPONSE_CODE);if($result===false)throw new RuntimeException(curl_error($ch));curl_close($ch);
 if($status<200||$status>=300)throw new RuntimeException('S3 HTTP '.$status);return ['status'=>$status,'body'=>$result];
}
$put=callS3($url,$config,'PUT',$body);$get=callS3($url,$config,'GET');
if(!hash_equals(hash('sha256',$body),hash('sha256',$get['body'])))throw new RuntimeException('Downloaded SHA mismatch');
echo json_encode(['platform'=>PHP_OS_FAMILY,'php'=>PHP_VERSION,'key'=>$key,'putStatus'=>$put['status'],'getStatus'=>$get['status'],'bytes'=>strlen($body),'sha256'=>hash('sha256',$body),'roundTrip'=>true],JSON_PRETTY_PRINT|JSON_UNESCAPED_UNICODE).PHP_EOL;

Как связать загрузку с записью в базе приложения

S3-объект и строка вашей БД не находятся в одной общей транзакции. Если сначала сохранить объект, а затем не записать его карточку, появится лишний файл. Если сначала объявить файл готовым в БД, а загрузка сорвётся, пользователь получит неработающую ссылку. Поэтому нужен явный жизненный цикл: создана заявка, передаются данные, объект подтверждён, результат доступен.

Удобный вариант — сервер выдаёт uploadId приложения и заранее выбранный key. После загрузки клиент сообщает о завершении, а сервер проверяет объект: допустимый размер, ожидаемый тип, контрольные сведения и принадлежность операции текущему пользователю. Только после проверки статус меняется на ready. Отдельная задача удаляет старые незавершённые заявки и их собственные объекты.

Повтор команды завершения должен быть осмысленным: если тот же объект уже принят, возвращайте прежний результат либо ясный конфликт. Не создавайте новую запись при каждом сетевом повторе. Эти решения относятся к вашему приложению; Garage хранит объекты и не знает, какой клиент оплатил отчёт или кто подписал акт.

const attachment = {
  id: 'att-2026-001',
  ownerId: 42,
  bucket: 'customer-files',
  key: 'reports/att-2026-001.pdf',
  status: 'uploading',
  expectedBytes: 125600
};

Linux/VPS: постоянный каталог и эксплуатационный минимум

Для пилота на Linux подготовьте отдельный каталог, например /opt/aen-garage, и разверните туда проект под своим пользователем обслуживания. Не копируйте ключи из публичной инструкции: lab:up создаст новые. После запуска ограничьте доступ к .runtime, проверьте свободное место и сохранность каталогов после перезапуска. Полные команды и порядок находятся в VPS.md внутри архива.

Важные данные не должны зависеть от случайного рабочего каталога пользователя или очистки /tmp. Заранее определите, где лежат metadata и data, кто имеет к ним доступ, какой диск используется и как проверяется его заполнение. Разделение каталогов помогает организовать обслуживание, но само по себе не создаёт дополнительной копии.

Для запуска после перезагрузки проверьте состояние службы Docker и политику restart контейнера. Не добавляйте одновременно несколько механизмов, которые будут независимо перезапускать один и тот же процесс. Для обновления закрепляйте новый образ, читайте миграционные замечания и проверяйте восстановление до изменения рабочего сервера.

cd /opt/aen-garage
npm ci --ignore-scripts
npm run lab:up
chmod 700 .runtime
chmod 600 .runtime/credentials.json .runtime/reader.json .runtime/garage.env
systemctl is-enabled docker
docker compose -p aen-b25-garage -f compose.yaml ps

Caddy: один HTTPS-домен перед S3

В path-style режиме достаточно домена s3.example.com, который вы замените своим. DNS должен вести на сервер, а Caddy должен иметь возможность получить сертификат. Garage остаётся на loopback8591; наружу открывается reverse proxy с HTTPS. В garage.toml нужно указать соответствующий public_endpoint и перезапустить собственный сервис.

Блок ниже задаёт лимит тела одного запроса 64MB. Это эксплуатационное решение примера, а не ограничение самого Garage на размер объекта. Для multipart общий объект может быть больше одной части; лимит нужно согласовать с размером частей, сетью и требованиями приложения. Не копируйте произвольный большой лимит без понимания доступных ресурсов.

После изменения конфигурации выполните caddy validate и затем reload принятой службы. Проверьте через внешний домен успешный подписанный запрос и ожидаемый отказ без подписи. Не пытайтесь исправить неверный сертификат отключением TLS-проверки SDK. Более подробно работа прокси разобрана в материале о Caddy.

s3.example.com {
    request_body {
        max_size 64MB
    }
    reverse_proxy 127.0.0.1:8591
}

Nginx: сохранить Host, путь и query подписи

Для Nginx важна аккуратная передача исходного запроса. SigV4 зависит от метода, адреса и подписанных параметров. Если прокси перепишет путь, заменит Host или потеряет X-Amz-параметры query, сервер увидит другую операцию и отклонит подпись. Поэтому в примере S3 расположен на отдельном домене и proxy_pass не добавляет новый префикс пути.

Конфигурация требует уже установленного действующего TLS-сертификата. Пути в примере нужно заменить на реальные. Перед применением выполните nginx -t; только успешная проверка позволяет переходить к reload. Caddy и Nginx показаны как два варианта, а не как обязательная цепочка из двух прокси.

Отключение буферизации подходит для передачи тела и уменьшает зависимость от временного файла прокси. Тайм-аут и размер запроса выбраны явно. На своём сервере проверьте медленную загрузку, Range, multipart и крупный объект через весь внешний маршрут. Дополнительные повседневные настройки есть в статье о Nginx.

# Include within http {}; install your valid TLS certificate first.
server {
    listen 443 ssl;
    server_name s3.example.com;
    ssl_certificate /etc/letsencrypt/live/s3.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/s3.example.com/privkey.pem;
    client_max_body_size 64m;
    location / {
        proxy_pass http://127.0.0.1:8591;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_request_buffering off;
        proxy_buffering off;
        proxy_read_timeout 120s;
    }
}

Прямая загрузка из браузера и CORS

Подписанная PUT-ссылка может убрать большой файл из пути через ваше приложение. Сервер авторизует операцию и выбирает key, браузер отправляет байты непосредственно в S3, а затем приложение подтверждает результат. У такого подхода есть отдельная настройка CORS: браузер должен получить разрешение на нужный origin, методы и заголовки.

CORS не выдаёт пользователю права на объекты и не заменяет подпись. Он определяет, разрешено ли браузерному коду читать ответ в данной междоменной ситуации. Настраивайте конкретный origin своего интерфейса и только необходимые методы. Если запрос работает из curl, но блокируется в браузере, проверяйте preflight и заголовки ответа, а не сразу расширяйте права bucket.

Наша публичная мастерская не отправляет файлы на S3 и не включает демонстрационный CORS для всех посетителей. Рабочий presigned PUT проверен HTTP-клиентом в тестах. Реальное соединение вашего фронтенда с отдельным доменом, его preflight и интерфейс прогресса нужно проверить самостоятельно после настройки доменов. В исходниках нет постоянного секретного ключа для браузера.

Один узел, три зоны и границы надёжности

Один Docker-контейнер хорош для изучения API, но его нельзя называть отказоустойчивым кластером. Перезапуск подтверждает сохранение данных в тех же каталогах; он не моделирует потерю диска, недоступность площадки или конфликт нескольких узлов. Эти границы подписаны и в статье, и в исходном проекте.

Для реального распределённого развёртывания официальный рецепт кластера Garage рекомендует минимум три узла. Потребуются план зон отказа, объёмов, закрытого RPC-соединения и layout. Три контейнера на одном физическом диске не становятся тремя независимыми копиями. В многосерверной конфигурации не сохраняют автоматический флаг single-node из этой лаборатории.

Даже репликация не является историей всех изменений. Разрешённое удаление или ошибка приложения могут распространиться штатно. Поэтому отдельно определите независимую копию, срок её хранения, допустимую потерю последних изменений и порядок восстановления. Эти требования появляются из задачи сервиса, а не из количества зелёных строк в docker compose ps.

Резервная копия и проверка восстановления

Для небольшой одноузловой лаборатории самый понятный согласованный снимок получается после остановки только собственного Garage. В архив включают всё его состояние, конфигурацию и необходимые секреты, затем сервер запускают обратно. Такая копия содержит чувствительные данные: храните её закрыто и зашифрованно, отдельно от исходного диска. В VPS.md приведён конкретный порядок с tar и SHA-256.

Команда garage meta snapshot сохраняет метаданные, но не заменяет сохранение самих блоков объектов. Не называйте один такой файл полным резервным комплектом. Аналогично, успешное вычисление SHA архива доказывает его целостность относительно контрольной суммы, но не подтверждает, что сервер восстановится и вернёт нужные файлы.

Проверяйте восстановление на отдельном стенде без рабочих клиентов. Сохраните исходную версию образа, восстановите права на каталоги, прочитайте контрольные объекты и сравните их хеши. Не запускайте одновременно скопированный node identity в связанном рабочем кластере. Для организации независимых снимков пригодится restic, но конкретную процедуру восстановления всё равно нужно отработать.

docker compose -p aen-b25-garage -f compose.yaml stop garage
# Сохраните .runtime, garage.toml и compose.yaml в закрытый архив.
# Для рабочего скрипта обеспечьте start также при ошибке архивирования.
docker compose -p aen-b25-garage -f compose.yaml start garage
node tools/persistence.mjs

Диагностика: доступ, подпись, время и поддержка API

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

При проблеме временной ссылки посмотрите категорию ответа. Наш опыт с истёкшим TTL вернул Date is too old; изменение пути дало отказ подписи. Полную ссылку при этом не нужно сохранять в публичный журнал. Достаточно operationId приложения, имени операции, разрешённого идентификатора объекта, HTTP-кода и безопасного сообщения.

Ошибку 501 следует сопоставить с поддержкой конкретного S3-метода. При сетевых сбоях отдельно проверяйте локальный сервер, прокси, DNS и TLS. После смены версии SDK повторяйте лабораторию: автоматические заголовки и контрольные суммы могут измениться. Журналируйте ровно то, что помогает восстановить событие, не превращая диагностический файл в хранилище ключей.

docker compose -p aen-b25-garage -f compose.yaml exec -T garage /garage status
docker compose -p aen-b25-garage -f compose.yaml exec -T garage /garage stats
docker compose -p aen-b25-garage -f compose.yaml logs --tail=100 garage

Что проверено в проекте и что остаётся за его пределами

Node.js-проверки выполнены на Windows и Linux против настоящего Garage. На каждой платформе подтверждены девять сценариев и девятнадцать проверок: коды ответа, байты, SHA, каталог без дублей, права, действующие и испорченные ссылки, multipart и отмена. PHP отдельно выполнил PUT/GET с русским текстом и подтвердил хеш на обеих платформах.

После перезапуска читаются контрольные объекты Windows и Linux из прежнего состояния. Это проверка сохранности при штатном рестарте. Она не выдаётся за испытание аварии диска или полноценное восстановление резервной копии. Одноузловой стенд не доказывает работу репликации в распределённой системе, а локальный HTTP не подтверждает ваш внешний HTTPS-маршрут.

Мастерская показывает происхождение каждой записи, платформу и время запуска. Кнопка «Показать результат» не выполняет новый запрос. В скачиваемом проекте npm test запускает настоящие операции; их исходники открыты для проверки. Такой формат позволяет сразу исследовать инструмент на странице и затем воспроизвести опыт на своём компьютере или тестовом сервере.

npm test
php src/upload.php
npm run lab:restart
node tools/persistence.mjs
npm run build

Исходники и первый шаг внедрения

Начните с одного ограниченного сценария: готовый отчёт, который уже умеет создавать ваше приложение. Выберите отдельный bucket, выдайте серверному клиенту только необходимые права, загрузите файл по уникальному ключу и свяжите его с владельцем в БД. Затем добавьте авторизованную выдачу короткой GET-ссылки и проверку отсутствующего результата.

После успешного пути проверьте отказы: неверный ключ, закончившийся TTL, недоступный сервер, повтор завершения и попытку прочитать чужое вложение. Продумайте очистку незавершённых операций, контроль диска и резервную копию. Только после этого переносите большой каталог существующих файлов. Массовую миграцию удобно выполнять постепенно с журналом и проверкой хешей.

В архиве находятся клиент Node.js, PHP-пример, интеграционные тесты, Compose, закреплённые зависимости, записи, мастерская и VPS.md. Используйте документацию Garage, справочник AWS SDK для JavaScript и константы PHP cURL для дальнейших изменений. Авторский код можно брать за основу; эксплуатационные требования нужно привязать к ценности ваших данных.