Развертывание Garage S3 в Docker Compose: легковесное распределенное объектное хранилище на Rust для бэкапов и медиафайлов

Организация объектного хранилища на собственном сервере долгое время упиралась в безальтернативный выбор: либо MinIO, который по умолчанию преаллоцирует от 1 GiB оперативной памяти на одиночный узел (снижается только флагом CI_CD=true до 256 MiB) и перешел на жесткую коммерческую модель с платными Enterprise-подписками, либо распределенные монстры вроде Ceph, администрирование которых требует сложной инфраструктуры. Garage S3 — это современное открытое распределенное объектное хранилище (лицензия AGPLv3, разработчик Deuxfleurs), написанное на языке Rust. Garage потребляет всего 50–80 МБ оперативной памяти, мгновенно стартует, сохраняет метаданные во встроенном движке LMDB с автоматическими снапшотами и изначально спроектировано для работы на недорогих VDS и географически распределенных узлах. В этой практической инструкции мы развернем свежий стабильный релиз Garage S3 v2.5 в Docker Compose, настроим топологию кластера, подключим защищенный Nginx с SSL и потоковой передачей без буферизации, выпустим S3-ключи и настроим интеграцию с Rclone, Restic и AWS CLI.

1. Архитектура Garage S3: чем Rust-хранилище превосходит MinIO и Ceph

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

Ключевые архитектурные особенности Garage S3 v2.5:

• Экстремально низкое потребление ресурсов. Благодаря компиляции в нативный машинный код на Rust, демон Garage потребляет от 50 до 80 МБ RAM в режиме ожидания и не более 150–250 МБ при непрерывной потоковой записи данных. Здесь нет сборщика мусора (GC) и принудительной преаллокации гигабайтов памяти.
• Движок метаданных LMDB с автоснапшотами. Все списки бакетов, ключи, блоки и индексы версий хранятся во встроенной базе данных LMDB (Lightning Memory-Mapped Database) с отображением в память. Демон умеет автоматически создавать консистентные снапшоты метаданных без остановки сервиса.
• Чанкование объектов и встроенная дедупликация. При загрузке файлы нарезаются на блоки фиксированного размера (по умолчанию block_size = "1M"), сжимаются алгоритмом Zstandard (Zstd) и хэшируются. Одинаковые блоки данных дедуплицируются, экономя дисковое пространство.
• Бессерверное согласование CRDT и устойчивость к задержкам. В многоузловой конфигурации Garage не использует классический консенсус Raft с выбором лидера. Вместо этого применяется протокол репликации на базе CRDT (Conflict-free Replicated Data Types) поверх легковесного протокола RPC. Кластер продолжает успешно обслуживать чтение и запись даже при сетевых сбоях между серверами в разных дата-центрах.
• Встроенный статический веб-сервер (S3 Website). Garage умеет раздавать содержимое любого бакета как обычный веб-сайт через выделенный порт 3902 (поддерживаются индексные документы index.html и страницы ошибок).

2. Системные требования и выбор конфигурации VDS

Благодаря компактности Garage, порог входа в организацию собственного S3-хранилища снижен до минимума. Вы можете запустить его как на минимальном сервере для личных бэкапов, так и на высоконагруженном накопителе:

3. Подготовка окружения, сетевая безопасность и генерация секретов

Перед запуском контейнеров необходимо подготовить структуру каталогов на сервере и сгенерировать криптографические ключи авторизации.

Создайте рабочую директорию проекта /opt/garage с подкаталогами для метаданных, блоков данных, снапшотов и конфигурационных файлов:

sudo mkdir -p /opt/garage/{config,data/meta,data/data,data/snapshots}
cd /opt/garage

Garage использует несколько сетевых портов, каждый из которых выполняет строгую задачу:

• 3900 — S3 API (основной порт для клиентов: AWS CLI, Rclone, Restic, SDK);
• 3901 — RPC межкластерная синхронизация (обмен блоками и согласование топологии между нодами Garage);
• 3902 — S3 Web (опциональный статический веб-сервер для раздачи сайтов из бакетов);
• 3903 — Admin & Metrics API (управление кластером и выгрузка метрик Prometheus).

Для защищенного взаимодействия внутри кластера и доступа к эндпоинтам мониторинга сгенерируйте криптостойкие токены с помощью утилиты генератора надежных паролей или стандартной утилиты openssl:

# 1. 32-байтный hex-ключ межкластерной авторизации RPC (обязателен для всех нод)
openssl rand -hex 32

# 2. Секретный токен для доступа к административному API
openssl rand -base64 32

# 3. Токен для сбора метрик Prometheus
openssl rand -base64 32

Сохраните полученные значения — они понадобятся нам при заполнении конфигурационного файла garage.toml.

4. Манифест Docker Compose: запуск сервиса Garage v2.5

Мы зафиксируем образ на актуальном стабильном релизе dxflrs/garage:v2.5.0. Использование конкретного тега вместо плавающего :latest гарантирует предсказуемость обновлений и защищает сервер от несовместимостей формата метаданных LMDB.

Создайте файл /opt/garage/docker-compose.yml:

services:
  garage:
    image: dxflrs/garage:v2.5.0
    container_name: garage_storage
    restart: unless-stopped
    ports:
      # S3 API: принимает клиентские вызовы (закрыт локально, трафик проксирует Nginx)
      - "127.0.0.1:3900:3900"
      # RPC порт: межкластерное взаимодействие (в standalone-режиме держим на localhost)
      - "127.0.0.1:3901:3901"
      # S3 Web: раздача статических сайтов из бакетов
      - "127.0.0.1:3902:3902"
      # Admin & Prometheus API: метрики и администрирование
      - "127.0.0.1:3903:3903"
    volumes:
      # Конфигурационный файл монтируется в режиме read-only
      - ./config/garage.toml:/etc/garage.toml:ro
      # Метаданные (LMDB) — рекомендуется размещать на скоростном NVMe
      - ./data/meta:/var/lib/garage/meta
      # Блоки данных (объекты S3)
      - ./data/data:/var/lib/garage/data
      # Директория автоматических снапшотов метаданных LMDB
      - ./data/snapshots:/var/lib/garage/snapshots
    environment:
      - RUST_LOG=garage=info
    # Ограничение ресурсов cgroups для защиты сервера от OOM Killer
    mem_limit: 512m
    cpus: 1.0
    healthcheck:
      test: ["CMD-SHELL", "/garage status > /dev/null 2>&1 || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 5s

networks:
  default:
    name: garage_net

Обратите внимание на ограничения ресурсов: лимит mem_limit: 512m с пятикратным запасом перекрывает штатные потребности Garage (50–80 МБ RAM) и исключает риск неконтролируемого захвата памяти.

Для генерации персональных конфигураций под другие сервисы инфраструктуры вы всегда можете использовать наш интерактивный генератор Docker Compose онлайн.

5. Конфигурация garage.toml: репликация, LMDB и параметры эндпоинтов

Все параметры демона Garage описываются в едином файле формата TOML. Создайте файл /opt/garage/config/garage.toml:

# Директории для метаданных и бинарных блоков
metadata_dir = "/var/lib/garage/meta"
data_dir = "/var/lib/garage/data"

# Каталог и интервал создания автоматических снапшотов метаданных LMDB
metadata_snapshots_dir = "/var/lib/garage/snapshots"
metadata_auto_snapshot_interval = "6h"

# Движок базы данных метаданных: скоростной LMDB (рекомендован разработчиками)
db_engine = "lmdb"

# Фактор репликации: 1 для автономного VDS (для отказоустойчивого кластера из 3 узлов задается 3)
replication_factor = 1
consistency_mode = "consistent"

# Размер блока для чанкования объектов и уровень сжатия Zstd (1 — оптимальный баланс CPU и сжатия)
block_size = "1M"
compression_level = 1

# Сетевой интерфейс и секрет для протокола RPC (межкластерная синхронизация)
rpc_bind_addr = "[::]:3901"
rpc_public_addr = "127.0.0.1:3901"
rpc_secret = "ВСТАВЬТЕ_СЮДА_HEX_КЛЮЧ_ОТ_OPENSSL_RAND_HEX_32"

[s3_api]
# Привязка API к порту 3900 и указание региона хранилища
api_bind_addr = "[::]:3900"
s3_region = "garage"
root_domain = ".s3.example.ru"

[s3_web]
# Эндпоинт статического хостинга сайтов из бакетов
bind_addr = "[::]:3902"
root_domain = ".web.example.ru"

[admin]
# Административный интерфейс и метрики Prometheus
api_bind_addr = "0.0.0.0:3903"
admin_token = "ВСТАВЬТЕ_СЮДА_ТОКЕН_ОТ_OPENSSL_RAND_BASE64_32"
metrics_token = "ВСТАВЬТЕ_СЮДА_ТОКЕН_METRICS_ОТ_OPENSSL_RAND_BASE64_32"

Замените значения rpc_secret, admin_token, metrics_token на сгенерированные вами секреты и укажите ваш рабочий домен вместо example.ru.

Задайте строгие права доступа к конфигурационному файлу, чтобы исключить чтение мастер-секретов посторонними процессами:

chmod 600 /opt/garage/config/garage.toml

6. Инициализация кластера и топологии (Layout assign и Layout apply)

В отличие от MinIO, где демон сразу после первого запуска готов принимать файлы в корневой каталог, Garage S3 использует концепцию топологии кластера (Cluster Layout). Даже при работе на одном изолированном сервере демон должен точно знать свою зону размещения (Zone) и выделенный объем накопителя (Capacity). Без настройки топологии статус ноды останется в состоянии NO ROLE ASSIGNED, а попытка создать бакет завершится ошибкой.

Запустите контейнер хранилища:

cd /opt/garage
docker compose up -d

Проверьте статус демона и определите уникальный идентификатор ноды (Node ID):

docker exec garage_storage /garage status

В выводе консоли появится таблица с обнаруженными узлами:

==== HEALTHY NODES ====
ID                 Hostname        Address         Tag                   Zone  Capacity
563e1ac825ee3323   garage_storage  127.0.0.1:3901  NO ROLE ASSIGNED

Скопируйте идентификатор ноды из первого столбца (в примере это 563e1ac825ee3323, достаточно даже первых 8 символов) и назначьте ей роль в топологии:

# Назначаем ноду в зону dc1 с лимитом емкости 100 ГБ (задайте фактический размер диска)
docker exec garage_storage /garage layout assign -z dc1 -c 100G 563e1ac825ee3323

Проверьте сформированный черновой план топологии:

docker exec garage_storage /garage layout show

Примените изменения топологии к кластеру, зафиксировав версию 1:

docker exec garage_storage /garage layout apply --version 1

Убедитесь, что статус изменился на активный:

docker exec garage_storage /garage status

Теперь в столбцах Zone и Capacity отображаются заданные значения (dc1 и 100 GB), а хранилище полностью готово к созданию бакетов и приему клиентских данных.

7. Создание бакетов, API-ключей и разграничение прав доступа

В архитектуре Garage S3 учетные записи (API-ключи) и бакеты полностью изолированы друг от друга: один ключ может иметь доступ к десяткам бакетов с разными правами, а бакет может разделяться между несколькими независимыми сервисами.

1. Создание бакета

Создайте бакет для хранения резервных копий серверов:

docker exec garage_storage /garage bucket create backups-vds

Проверьте метаданные созданного бакета:

docker exec garage_storage /garage bucket info backups-vds

2. Выпуск сервисного API-ключа

Создайте ключ доступа для агента бэкапов:

docker exec garage_storage /garage key create backup-agent-key

В консоли отобразится пара учетных данных S3:

Key name: backup-agent-key
Key ID: GK3515373e4c851ebaad366558
Secret key: 7d37d093435a41f2aab8f13c19ba067d9776c90215f56614adad6ece597dbb34
Authorized buckets: (none)

3. Назначение прав доступа ключа к бакету

По умолчанию вновь созданный ключ не имеет доступа ни к одному бакету. Предоставьте ключу полные права на чтение, запись и управление бакетом:

docker exec garage_storage /garage bucket allow \
  --read \
  --write \
  --owner \
  backups-vds \
  --key backup-agent-key

Убедитесь, что разрешения применились:

docker exec garage_storage /garage bucket info backups-vds

8. Настройка Nginx Reverse Proxy с поддержкой SSL и адресации Path-style

Для защищенной работы клиентов по протоколу HTTPS и корректной передачи многогигабайтных файлов настроим веб-сервер Nginx в качестве обратного прокси.

Создайте конфигурационный файл виртуального хоста /etc/nginx/sites-available/s3.example.ru.conf:

server {
    listen 80;
    server_name s3.example.ru;

    # 1. Снятие лимита на размер загружаемых объектов (бэкапы баз данных и образы дисков)
    client_max_body_size 0;

    # 2. Критически важно: отключение буферизации запросов и ответов
    # Без proxy_request_buffering off Nginx будет сохранять весь файл во временную папку диска
    proxy_request_buffering off;
    proxy_buffering off;

    # 3. Увеличенные таймауты для тяжелых операций чтения/записи
    proxy_connect_timeout 300s;
    proxy_send_timeout 300s;
    proxy_read_timeout 300s;

    location / {
        proxy_pass http://127.0.0.1:3900;
        proxy_http_version 1.1;

        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Отключение сжатия gzip в Nginx (Garage сжимает блоки нативно через Zstd)
        gzip off;
    }
}

Активируйте конфигурацию и перезагрузите веб-сервер:

sudo ln -s /etc/nginx/sites-available/s3.example.ru.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Выпустите бесплатный SSL-сертификат Let's Encrypt с автоматической перенастройкой HTTPS с помощью Certbot:

sudo certbot --nginx -d s3.example.ru --redirect --non-interactive --agree-tos -m admin@example.ru

Проверьте корректность цепочки шифрования через онлайн проверку SSL-сертификатов, а также убедитесь с помощью сканера открытых портов, что служебные порты 3900, 3901 и 3903 не торчат наружу. Если вам требуется собрать индивидуальный конфиг обратного прокси, воспользуйтесь нашим генератором Nginx Reverse Proxy онлайн.

9. Интеграция с клиентами: Rclone, Restic, AWS CLI и статические веб-сайты

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

1. Работа через AWS CLI

Для управления объектами через официальный CLI Amazon достаточно передать параметры авторизации и эндпоинт:

export AWS_ACCESS_KEY_ID="GK3515373e4c851ebaad366558"
export AWS_SECRET_ACCESS_KEY="7d37d093435a41f2aab8f13c19ba067d9776c90215f56614adad6ece597dbb34"
export AWS_DEFAULT_REGION="garage"
export AWS_ENDPOINT_URL="https://s3.example.ru"

# Просмотр списка доступных бакетов
aws s3 ls

# Загрузка тестового файла
aws s3 cp /var/log/syslog s3://backups-vds/syslog.txt

# Скачивание файла обратно
aws s3 cp s3://backups-vds/syslog.txt /tmp/syslog_restored.txt

2. Настройка синхронизации через Rclone

Добавьте секцию хранилища в файл конфигурации ~/.config/rclone/rclone.conf с явным указанием режима force_path_style = true:

[garage]
type = s3
provider = Other
env_auth = false
access_key_id = GK3515373e4c851ebaad366558
secret_access_key = 7d37d093435a41f2aab8f13c19ba067d9776c90215f56614adad6ece597dbb34
region = garage
endpoint = https://s3.example.ru
force_path_style = true
acl = private

Теперь синхронизировать локальные каталоги с S3 можно одной командой:

rclone sync /opt/backups/ garage:backups-vds/daily/ --progress

3. Шифрованные дедуплицированные бэкапы через Restic

В связке с утилитой Restic или Autorestic вы получаете полноценное решение корпоративного класса: клиентское шифрование, снепшоты и дедупликация перед отправкой:

export RESTIC_REPOSITORY="s3:https://s3.example.ru/backups-vds"
export AWS_ACCESS_KEY_ID="GK3515373e4c851ebaad366558"
export AWS_SECRET_ACCESS_KEY="7d37d093435a41f2aab8f13c19ba067d9776c90215f56614adad6ece597dbb34"
export RESTIC_PASSWORD="ВашСложныйПарольШифрованияБэкапа"

# Инициализация репозитория
restic init

# Создание моментального снимка каталога /var/www
restic backup /var/www

4. Раздача статического веб-сайта из бакета

Если вам нужно быстро опубликовать документацию или статический фронтенд, включите режим веб-хостинга:

docker exec garage_storage /garage bucket website --allow --index index.html backups-vds

Все файлы с расширением .html, загруженные в корень бакета, будут мгновенно доступны по протоколу HTTP через порт 3902.

10. Резервное копирование метаданных LMDB, мониторинг и обслуживание

Вся файловая структура и каталоги объектов Garage привязаны к базе данных метаданных LMDB. Если скопировать рабочий файл базы «на горячую» обычной командой cp, из-за параллельных транзакций записи результирующий файл может оказаться поврежден.

В релизах Garage v2 предусмотрен встроенный механизм создания консистентных снапшотов по расписанию: директива metadata_auto_snapshot_interval = "6h" автоматически сохраняет срезы базы в каталог /var/lib/garage/snapshots.

Для регулярного архивирования снапшотов на внешний носитель или бэкап-сервер создайте скрипт /opt/garage/backup_meta.sh:

#!/usr/bin/env bash
set -euo pipefail

BACKUP_DIR="/opt/garage/backups"
TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
mkdir -p "${BACKUP_DIR}"

# 1. Архивирование свежего снапшота метаданных LMDB и конфигурации
tar -czf "${BACKUP_DIR}/garage_meta_snapshot_${TIMESTAMP}.tar.gz" -C /opt/garage config data/snapshots

# 2. Удаление архивов старше 14 дней
find "${BACKUP_DIR}" -name "garage_meta_snapshot_*.tar.gz" -type f -mtime +14 -delete

echo "[$(date)] Резервная копия снапшота метаданных Garage S3 успешно создана: ${BACKUP_DIR}"

Сделайте скрипт исполняемым и добавьте его в планировщик crontab -e для выполнения раз в сутки:

chmod +x /opt/garage/backup_meta.sh
# 0 4 * * * /opt/garage/backup_meta.sh >> /var/log/garage_backup.log 2>&1

Для мониторинга здоровья хранилища настройте сбор метрик Prometheus по эндпоинту http://127.0.0.1:3903/metrics, передавая заголовок Authorization: Bearer <metrics_token>. Демон экспортирует ключевые показатели: количество прочитанных и записанных байтов, состояние семафоров и свободное дисковое пространство.

11. Чек-лист проверки готовности Garage S3 к production-эксплуатации