Быстрый старт с объектным хранилищем Garage - совместимым с S3

Запустите Garage в Docker за несколько минут

Содержимое страницы

Гараж — это открытое, саморазмещаемое, совместимое с S3 объектное хранилище, предназначенное для небольших и средних развертываний с акцентом на устойчивость и геораспределение.

Это руководство проведет вас от простого копирования/вставки одноузловой настройки до производственных шаблонов: компоновка кластера, репликация, TLS через обратный прокси, многодисковые хранилища, мониторинг, восстановление и резервное копирование.

Для более широкого обзора — объектное хранилище, PostgreSQL, Elasticsearch и AI-ориентированные слои данных — см. статью Инфраструктура данных для систем ИИ.

Гаражные ящики

Что такое Гараж

Гараж — это распределенное объектное хранилище, совместимое с S3, предназначенное для саморазмещения, стремящееся оставаться легковесным и простым в эксплуатации, при этом поддерживая мультисайтовые/геораспределенные кластеры. Он распространяется под лицензией AGPL v3.

Основные идеи, формирующие его работу:

Гараж измеряет емкость узлов и их физическое расположение («зоны») для размещения реплик; изменения топологии кластера (добавление/удаление узлов) обрабатываются через версионированные компоновки и перебалансировку. Объекты разбиваются на блоки фиксированного размера (block_size), что позволяет выполнять дедупликацию и необязательное сжатие Zstandard; хеши блоков используются для размещения и дедупликации. Гараж не завершает TLS на своих S3 API/веб-эндпоинтах: ожидается, что вы развернете обратный прокси для HTTPS в реальных развертываниях.

Архитектура и поток данных

На высоком уровне вы взаимодействуете с Гаражем через клиенты, совместимые с S3; трафик обычно поступает через обратный прокси (TLS), достигает одного или нескольких эндпоинтов API Гаража (часто «шлюзовых» узлов), а затем обслуживается узлами хранения, содержащими реплицированные блоки данных.

Поток данных кластера garage

Узлы имеют роли: узлы хранения с емкостью против шлюзовых узлов, которые предоставляют эндпоинты без хранения данных; шлюзы снижают задержку, избегая дополнительных сетевых переходов и «зная», какие узлы хранения запрашивать. Репликация контролируется через replication_factor (например, 3-кратная репликация по зонам), с четкими компромиссами между доступностью и устойчивостью к сбоям, описанными в справочнике конфигурации.

Быстрый старт копирования/вставки

Это намеренно минимальное одноузловое развертывание для изучения рабочих процессов: конфигурация → запуск сервера → определение компоновки → создание корзины + ключа → загрузка объекта.

Предварительные требования

Вам нужны docker, openssl и (опционально) клиент S3, такой как awscli. CLI Гаража — это тот же бинарный файл, который используется для администрирования кластера.

Пошаговая инструкция

# 0) Рабочая область
mkdir -p ~/garage-quickstart/{config,meta,data}
cd ~/garage-quickstart

# 1) Создать стартовую конфигурацию (постоянные пути внутри контейнера)
cat > ./config/garage.toml <<EOF
metadata_dir = "/var/lib/garage/meta"
data_dir     = "/var/lib/garage/data"
db_engine = "sqlite"

# Одноузловое обучающее развертывание (НЕТ отказоустойчивости). Для производства см. далее.
replication_factor = 1

rpc_bind_addr   = "[::]:3901"
rpc_public_addr = "127.0.0.1:3901"
rpc_secret      = "$(openssl rand -hex 32)"

[s3_api]
s3_region = "garage"
api_bind_addr = "[::]:3900"
# Опциональный стиль виртуального хоста. Стиль пути всегда включен.
root_domain = ".s3.garage.localhost"

[s3_web]
bind_addr = "[::]:3902"
root_domain = ".web.garage.localhost"
index = "index.html"

[admin]
api_bind_addr = "[::]:3903"
admin_token   = "$(openssl rand -base64 32)"
metrics_token = "$(openssl rand -base64 32)"
EOF

# 2) Выбрать тег изображения (заполнитель). Примеры тегов появляются в документации Garage.
GARAGE_IMAGE="dxflrs/garage:TAG_PLACEHOLDER"

# 3) Запуск Garage (Docker)
docker run -d --name garaged \
  -p 3900:3900 -p 3901:3901 -p 3902:3902 -p 3903:3903 \
  -v "$PWD/config/garage.toml:/etc/garage.toml:ro" \
  -v "$PWD/meta:/var/lib/garage/meta" \
  -v "$PWD/data:/var/lib/garage/data" \
  "$GARAGE_IMAGE"

# 4) Использовать CLI garage внутри контейнера
alias garage='docker exec -ti garaged /garage'

# 5) Проверить статус узла (вероятно, увидите "НЕ НАЗНАЧЕНА РОЛЬ")
garage status

# 6) Назначить компоновку (один узел) и применить ее
NODE_ID="$(garage status | awk '/НЕ НАЗНАЧЕНА РОЛЬ/{print $1; exit}')"
garage layout assign -z dc1 -c 1G "$NODE_ID"
garage layout apply --version 1

# 7) Создать корзину + ключ и предоставить минимально необходимые разрешения
garage bucket create example-bucket
garage key create example-app-key
garage bucket allow --read --write --owner example-bucket --key example-app-key

# 8) Показать ключевые материалы (сохраните их в безопасном месте)
garage key info example-app-key

Шаблон конфигурации (S3 API на 3900, RPC на 3901, веб-эндпоинт на 3902, админ API на 3903) и рабочий процесс «требуется компоновка» взяты напрямую из быстрого старта в исходниках.

Проверка с AWS CLI

Гараж требует от клиентов использовать настроенный s3_region (часто «garage»); если ваш клиент использует us-east-1, вы можете получить перенаправления AuthorizationHeaderMalformed.

# Установка (один из вариантов)
python -m pip install --user awscli

# Настройка окружения (пример)
export AWS_ACCESS_KEY_ID="ВАШ_ИДЕНТИФИКАТОР_КЛЮЧА_GARAGE"
export AWS_SECRET_ACCESS_KEY="ВАШ_СЕКРЕТНЫЙ_КЛЮЧ_GARAGE"
export AWS_DEFAULT_REGION="garage"
export AWS_ENDPOINT_URL="http://localhost:3900"

aws s3 ls
aws s3 cp /etc/hosts s3://example-bucket/hosts.txt
aws s3 ls s3://example-bucket/
aws s3 cp s3://example-bucket/hosts.txt /tmp/hosts.txt

Быстрый старт в исходниках рекомендует использовать файл ~/.awsrc для переключения между эндпоинтами/ключами и указывает минимальные версии AWS CLI для удобного управления эндпоинтами.

Варианты установки и развертывания

Установка бинарных файлов и пакетов

Документация Garage явно поддерживает: загрузку бинарных файлов со страницы загрузки Garage, использование пакетов дистрибутива (например, apk add garage на Alpine) или сборку из исходников при необходимости.

Docker и Docker Compose

Garage предоставляет образы контейнеров и документирует минимальный метод docker run для быстрого старта. Для производства вы обычно будете использовать compose (или оркестратор) для управления постоянным хранилищем, обратным прокси и обновлениями (постепенные перезапуски). Руководство Garage «развертывание на кластере» предполагает Docker на каждом узле и указывает на общие пути хостов и рекомендацию по использованию SSD для метаданных.

systemd

Garage документирует устойчивое развертывание systemd, включая предупреждения о DynamicUser= systemd и о том, где постоянное состояние оказывается на диске. Минимальный пример юнита (адаптируйте пути к своей среде):

# /etc/systemd/system/garage.service
[Unit]
Description=S3-совместимое объектное хранилище Garage
After=network.target

[Service]
ExecStart=/usr/local/bin/garage -c /etc/garage.toml server
Restart=on-failure
Environment=RUST_LOG=garage=info

[Install]
WantedBy=multi-user.target

Kubernetes и Helm

Garage поставляется с Helm-чартом в репозитории и имеет официальные страницы документации для развертывания в Kubernetes. Обычная ошибка заключается в том, что вам все равно нужно загрузить/применить компоновку кластера после установки (вы можете автоматизировать это с помощью Kubernetes Job).

Конфигурация, безопасность и TLS

Хранилища и компоновка дисков

Garage разделяет хранилище на metadata_dir и data_dir. Справочник конфигурации рекомендует размещать metadata_dir на быстром SSD для улучшения времени отклика, в то время как data_dir может находиться на более крупном HDD. Для узлов с несколькими дисками данных Garage поддерживает конфигурацию data_dir с несколькими дисками, с емкостями по путям и автоматической балансировкой.

# Пример: несколько HDD для блоков данных
metadata_dir = "/mnt/ssd/garage-meta"
data_dir = [
  { path = "/mnt/hdd1/garage-data", capacity = "8T" },
  { path = "/mnt/hdd2/garage-data", capacity = "8T" },
]

Модель управления доступом против политик корзин S3

Garage не реализует стиль ACL и политик корзин AWS; он использует свою собственную систему разрешений «ключ доступа на корзину», управляемую через CLI Garage / админ API. Это означает, что «политика», которую вы обычно переводите в Garage, заключается в следующем: какой ключ доступа получает чтение/запись/владение на каких корзинах(ах).

# Ключ только для чтения для корзины:
garage key create ro-key
garage bucket allow --read example-bucket --key ro-key

# Удаление доступа:
garage bucket deny example-bucket --key ro-key

Адресация корзин в стиле DNS против стиля пути

Garage может поддерживать доступ к корзинам в стиле виртуального хоста (DNS), если вы настроили [s3_api].root_domain; стиль пути всегда включен. Если вы не настроили стиль виртуального хоста (дикий DNS + возможно дикий TLS), многие клиенты могут быть заставлены работать, принудительно включая стиль пути, и документация Garage показывает примеры клиентов с force_path_style = true.

TLS

S3 API и веб-эндпоинты Garage не поддерживают TLS напрямую; официальное руководство заключается в размещении обратного прокси перед ними, обычно Nginx, для обслуживания HTTPS и мультиплексирования сервисов на порту 443.

Минимальная «форма» Nginx (см. официальный кулинарный рецепт обратного прокси для полного примера):

# /etc/nginx/sites-available/garage.conf (отрывок)
upstream garage_s3 { server 127.0.0.1:3900; }

server {
  listen 443 ssl;
  server_name garage.example.com;

  ssl_certificate     /etc/letsencrypt/live/garage.example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/garage.example.com/privkey.pem;

  location / {
    proxy_pass http://garage_s3;
    proxy_set_header Host $host;
  }
}

Шифрование на стороне сервера

Garage поддерживает S3 SSE-C («шифрование на стороне сервера с ключами, предоставленными клиентом»: клиент отправляет ключи шифрования в заголовках по запросу; Garage шифрует при хранении и удаляет ключ после запроса. Таблица совместимости S3 Garage также отмечает, что эндпоинты конфигурации шифрования на уровне корзины не реализованы, поэтому обращайтесь с SSE-C как с поведением на уровне объекта/запроса, а не как с настройками по умолчанию для корзины.

Эксплуатация Garage в производственной среде

Мониторинг и ведение журналов

Garage предоставляет метрики в формате Prometheus и поддерживает экспорт трассировок в формате OpenTelemetry. Административные и метрические конечные точки могут быть защищены токенами (admin_token, metrics_token и metrics_require_token), а трассировки могут экспортироваться через trace_sink (OTLP). Для ведения журналов Garage можно настроить с помощью RUST_LOG, а справочник по конфигурации документирует переменные окружения для отправки журналов в syslog/journald вместо stderr.

Надежность, ремонт и обычные задачи по обслуживанию

Garage включает фоновые инструменты «сканирования» (проверки целостности) и ремонта; сканирования могут быть запущены вручную и отслеживаться через команды worker/task, но они интенсивно используют диск и могут замедлять кластер. Изменения топологии и настройки емкости обрабатываются через управление компоновкой; операции применяются как новые версии компоновки.

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

Как минимум, создавайте резервные копии метаданных, так как они содержат конфигурацию кластера, состояние корзины/ключа и индексы. Garage поддерживает периодические снимки метаданных (metadata_auto_snapshot_interval) и ручные снимки (garage meta snapshot --all). Руководство по миграции Garage явно рекомендует создавать резервные копии определенных файлов/папок из metadata_dir каждого узла (включая снимки и файлы компоновки).

Для данных объектов обращайтесь с Garage как с любым конечным пунктом S3: используйте совместимые с S3 инструменты резервного копирования (например, restic, duplicity), нацеленные на корзину Garage, как описано на странице интеграций Garage «Резервные копии».

Устранение распространенных ошибок

NO ROLE ASSIGNED в garage status обычно означает, что вы еще не создали/применили компоновку. Исправление: garage layout assign …, затем garage layout apply. AuthorizationHeaderMalformed часто указывает на то, что клиент использует неправильный регион; установите AWS_DEFAULT_REGION (или эквивалент) в соответствии с [s3_api].s3_region. Ошибки подписи/запроса могут быть вызваны несоответствием стиля пути и стиля виртуального хоста; настройте [s3_api].root_domain для стиля виртуального хоста или принудительно используйте стиль пути в клиентах (например, force_path_style=true в rclone). Ошибки разрешения часто просто означают «ключ не разрешен в корзине»; проверьте с помощью garage bucket info <bucket> и убедитесь, что garage bucket allow имеет правильные флаги.

Основные заметки по настройке производительности

Размещайте metadata_dir на SSD, когда это возможно; документация Garage отмечает улучшенное время отклика и «значительно сниженную» потенциальную задержку. Настройте block_size и сжатие осторожно: значения по умолчанию Garage предназначены для разумного использования, но справочник по конфигурации объясняет компромисс и отмечает, что изменения применяются только к вновь загруженным данным. Если у вас есть NVMe, увеличение параллелизма записи блоков может повысить пропускную способность, но увеличивает использование памяти; Garage предоставляет рекомендации по block_max_concurrent_writes_per_request. Собственные бенчмарки Garage подчеркивают затраты на внутрикластерную задержку в геораспределенных настройках и выделяют выборы проектирования (например, избегание лидеров консенсуса), которые могут снизить влияние геозадержки.

Краткое сравнение с MinIO и AWS S3

Garage оптимизирован для самоуправляемых, геораспределенных кластеров и операционной простоты, с некоторыми намеренными пробелами в функциях S3 (например, нет политик корзин S3/ACL; ограниченная поддержка версионирования). MinIO делает упор на широту API S3 и высокопроизводительные корпоративные развертывания (например, собственные материалы MinIO описывают функции, такие как блокировка объектов, репликация и уведомления о событиях). AWS S3 — это управляемая эталонная реализация с сильной согласованностью, 11 девятками надежности и целями доступности 99,99%, а также широкой экосистемой функций (классы хранения, жизненный цикл, событие, IAM).

Больше о Minio:

Полезные ссылки