Garage - szybki start magazynu obiektów kompatybilnego z S3
Uruchom Garage w Dockerze w ciągu minut
Garage to open-source, samowystarczalny, S3-zgodny system magazynowania obiektów zaprojektowany do małych i średnich wdrożeń, z silnym naciskiem na odporność i georozproszenie.
Ten przewodnik krok po kroku prowadzi Cię od prostego jednowęzłowego ustawienia do wzorców produkcyjnych: układ klastra, replikacja, TLS przez odwrotny proxy, wielodyskowe magazyny, monitorowanie, naprawy i backup/restore.
Aby poznać szerszy obraz – magazyn obiektów, PostgreSQL, Elasticsearch i warstwy danych natywnych dla AI – zobacz artykuł Infrastruktura danych dla systemów AI.
Co to jest Garage
Garage to rozproszony magazyn obiektów S3-zgodny przeznaczony do samowystarczalnego hostowania, który ma na celu utrzymanie lekkiego i prostego w eksploatacji działania, jednocześnie wspierając klastry wielowęzłowe/geo-rozproszone.
Jest wypuszczany pod licencją AGPL v3.
Główne idee, które kształtują sposób jego działania:
Garage mierzy pojemność węzła i lokalizację fizyczną (“strefy”) w celu rozmieszczenia replik; zmiany topologii klastra (dodawanie/usuwanie węzłów) są obsługiwane przez wersjonowane układy i balansowanie obciążenia.
Obiekty są dzielone na bloki o stałym rozmiarze (block_size), co umożliwia deduplikację i opcjonalne kompresowanie Zstandard; hashe bloków są wykorzystywane do rozmieszczenia i deduplikacji.
Garage nie kończy TLS na swoich punktach końcowych API S3/strony internetowej: w rzeczywistych wdrożeniach oczekuje się wdrożenia odwrotnego proxy dla HTTPS.
Architektura i przepływ danych
Na wysokim poziomie interakcja z Garage odbywa się poprzez klientów S3-zgodnych; ruch zwykle wchodzi przez odwrotny proxy (TLS), dochodzi do jednego lub wielu punktów końcowych API Garage (często węzłów „bramowych”), a następnie jest obsługiwany przez węzły magazynowe, które przechowują zreplikowane bloki danych.
Węzły mają role: węzły magazynowe z pojemnością vs węzły bramowe, które udostępniają punkty końcowe bez przechowywania danych; bramy zmniejszają opóźnienia, unikając dodatkowych skoków sieciowych i „wiedząc”, które węzły magazynowe należy zapytać.
Replikacja jest kontrolowana przez replication_factor (np. replikacja 3-warstwowa w strefach), z jasnymi opisami kompromisów dostępności/odporności na awarie w dokumentacji konfiguracji.
Szybki start – kopiuj i wklej
To celowo bardzo minimalne wdrożenie jednowęzłowe do nauki przepływów pracy: konfiguracja → uruchomienie serwera → zdefiniowanie układu → utworzenie bazy + klucza → przesłanie obiektu.
Wymagania wstępne
Potrzebujesz docker, openssl oraz (opcjonalnie) klienta S3, np. awscli. CLI Garage to ten sam binarny plik używany do zarządzania klastrzem.
Krok po kroku
# 0) Przestrzeń robocza
mkdir -p ~/garage-quickstart/{config,meta,data}
cd ~/garage-quickstart
# 1) Utwórz bazową konfigurację (trajne ścieżki wewnątrz kontenera)
cat > ./config/garage.toml <<EOF
metadata_dir = "/var/lib/garage/meta"
data_dir = "/var/lib/garage/data"
db_engine = "sqlite"
# Jednowęzłowe wdrożenie do nauki (BEZ redundancji). Dla produkcji patrz dalej.
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"
# Opcjonalny styl vhost. Styl ścieżki jest zawsze włączony.
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) Wybierz tag obrazu (zastępczy). Przykładowe tagi pojawiają się w dokumentacji Garage.
GARAGE_IMAGE="dxflrs/garage:TAG_PLACEHOLDER"
# 3) Uruchom 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) Użyj CLI Garage wewnątrz kontenera
alias garage='docker exec -ti garaged /garage'
# 5) Sprawdź status węzła (prawdopodobnie zobaczysz "NO ROLE ASSIGNED")
garage status
# 6) Przypisz układ (jednowęzłowy) i zastosuj
NODE_ID="$(garage status | awk '/NO ROLE ASSIGNED/{print $1; exit}')"
garage layout assign -z dc1 -c 1G "$NODE_ID"
garage layout apply --version 1
# 7) Utwórz bazę + klucz i nadaj prawa minimalne
garage bucket create example-bucket
garage key create example-app-key
garage bucket allow --read --write --owner example-bucket --key example-app-key
# 8) Pokaż materiał klucza (zapisz go bezpiecznie)
garage key info example-app-key
Wzorzec konfiguracji (API S3 na porcie 3900, RPC na porcie 3901, punkt końcowy sieciowy na porcie 3902, API administratora na porcie 3903) oraz „przepływ pracy wymagający układu” pochodzą bezpośrednio z oryginalnego przewodnika szybkiego startu.
Walidacja za pomocą AWS CLI
Garage wymaga, aby klienci korzystali z skonfigurowanej s3_region (często „garage”); jeśli Twój klient używa us-east-1, możesz natknąć się na przekierowania AuthorizationHeaderMalformed.
# Instalacja (jedna opcja)
python -m pip install --user awscli
# Konfiguracja środowiska (przykład)
export AWS_ACCESS_KEY_ID="YOUR_GARAGE_KEY_ID"
export AWS_SECRET_ACCESS_KEY="YOUR_GARAGE_SECRET_KEY"
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
W oryginalnym przewodniku szybkiego startu zaleca się użycie pliku ~/.awsrc do przełączania między punktami końcowymi/kluczami i zauważa minimalne wersje AWS CLI dla wygody w obsłudze punktów końcowych.
Opcje instalacji i wdrażania
Instalacje binarne i pakiety
Dokumentacja Garage jawnie wspiera: pobieranie binarnych plików z strony pobierania Garage, korzystanie z pakietów dystrybucji (np. apk add garage w Alpine), lub budowanie z źródeł, jeśli to konieczne.
Docker i Docker Compose
Garage udostępnia obrazy kontenerów i dokumentuje minimalny sposób użycia docker run do szybkiego startu.
W produkcji zwykle używasz compose (lub orchestratora) do zarządzania magazynem danych, odwrotnym proxy i aktualizacjami (restarty w trybie rolowym). Przewodnik Garage „wdrożenie w klastrze” zakłada użycie Docker na każdym węźle i wskazuje typowe ścieżki hosta i zalecanie SSD dla metadanych.
systemd
Dokumentacja Garage zawiera opis wzmocnionej instalacji systemd, w tym ostrzeżenia dotyczące DynamicUser= w systemd i miejsca, w którym kończy się stan trwały na dysku.
Przykład minimalnego pliku jednostki (przystosuj ścieżki do swojego środowiska):
# /etc/systemd/system/garage.service
[Unit]
Opis=Magazyn obiektów S3-zgodny 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 i Helm
Garage dostarcza chart Helm w repozytorium i ma oficjalne strony dokumentacji dla wdrożeń w Kubernetes.
Typowym pułapką jest fakt, że nadal musisz uruchomić i zastosować układ klastra po zainstalowaniu (możesz to automatyzować za pomocą zadania Kubernetes).
Konfiguracja, zabezpieczenia i TLS
Magazyny i układ dysków
Garage dzieli magazyn na metadata_dir i data_dir. W referencji do konfiguracji zaleca się umieszczenie metadata_dir na szybkim SSD w celu poprawy czasu odpowiedzi, podczas gdy data_dir może znajdować się na większym HDD.
Dla węzłów z wieloma dyskami danych, Garage wspiera konfigurację wielodyskowego data_dir z pojemnością na każdej ścieżce i automatycznym balansowaniem.
# Przykład: wiele HDD do bloków danych
metadata_dir = "/mnt/ssd/garage-meta"
data_dir = [
{ path = "/mnt/hdd1/garage-data", capacity = "8T" },
{ path = "/mnt/hdd2/garage-data", capacity = "8T" },
]
Model kontroli dostępu vs polityki S3
Garage nie implementuje ACLi typu AWS ani polityk S3; używa własnego systemu kontroli dostępu „na poziomie klucza dostępu i bazy danych”, zarządzanego przez CLI Garage / API administratora.
To oznacza, że „polityka”, którą zwykle przetłumaczyłeś na Garage, to: który klucz dostępu ma uprawnienia do odczytu/zapisu/posiadania w jakich bazach danych.
# Klucz do odczytu z bazy:
garage key create ro-key
garage bucket allow --read example-bucket --key ro-key
# Usuń dostęp:
garage bucket deny example-bucket --key ro-key
Adresowanie typu DNS vs ścieżki dla baz
Garage może wspierać wirtualne hosty (styl DNS), jeśli skonfigurujesz [s3_api].root_domain; styl ścieżek jest zawsze włączony.
Jeśli nie skonfigurujesz stylu vhost (DNS z wieloma zapisami + możliwe TLS z wieloma zapisami), wiele klientów może działać, jeśli zmusisz je do stylu ścieżek, a dokumentacja Garage pokazuje przykłady klientów z force_path_style = true.
TLS
API S3 i punkty końcowe sieciowe Garage nie obsługują bezpośrednio TLS; oficjalna wskazówka to umieszczenie odwrotnego proxy przed nimi, najczęściej Nginx, który obsłuży HTTPS i zintegruje usługi na porcie 443.
Minimalny kształt Nginx (patrz pełny przykład w oficjalnym przewodniku odwrotnego proxy):
# /etc/nginx/sites-available/garage.conf (fragment)
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;
}
}
Szyfrowanie po stronie serwera
Garage obsługuje S3 SSE-C („szyfrowanie po stronie serwera z kluczami dostarczonymi przez klienta”): klient wysyła klucze szyfrowania w nagłówkach każdego żądania; Garage szyfruje dane w spoczynku i usuwa klucz po zakończeniu żądania.
Tabela zgodności S3 Garage również zauważa, że punkty końcowe konfiguracji szyfrowania na poziomie bazy danych nie są implementowane, więc traktuj SSE-C jako zachowanie na poziomie obiektu/żądania, a nie domyślne zachowanie bazy danych.
Operowanie Garage w produkcji
Monitorowanie i logowanie
Garage udostępnia metryki w formacie Prometheus i wspiera eksportowanie śladów w formacie OpenTelemetry.
Punkty końcowe administratora i metryki mogą być chronione tokenami (admin_token, metrics_token i metrics_require_token), a ślad może być eksportowany przez trace_sink (OTLP).
Dla logowania Garage może być dostosowany przez RUST_LOG, a dokumentacja konfiguracji opisuje zmienne środowiskowe, które umożliwiają wysyłanie logów do syslog/journald zamiast stderr.
Trwałość, naprawy i typowe zadania utrzymaniowe
Garage zawiera tło „sprawdzania” (weryfikacja integralności) i narzędzia do naprawy; sprawdzanie można ręcznie uruchomić i monitorować za pomocą poleceń pracownika/zadania, ale jest intensywnie obciążające dyski i może spowolnić klastrze.
Zmiany topologii i dostosowania pojemności są obsługiwane przez zarządzanie układem; operacje są stosowane jako nowe wersje układu.
Strategia backupu i przywracania
Minimum backupuj metadane, ponieważ zawierają one konfigurację klastra, stan baz/kluczy i indeksy. Garage obsługuje okresowe kopie zapasowe metadanych (metadata_auto_snapshot_interval) i kopie zapasowe ręczne (garage meta snapshot --all).
Wskazówki migracji Garage jawnie zalecają backupowanie określonych plików/katalogów z każdego węzła metadata_dir (w tym kopie zapasowe i pliki układu).
Dla danych obiektowych traktuj Garage jak każdy punkt końcowy S3: użyj narzędzi do kopii zapasowych S3-zgodnych (np. restic, duplicity), skierowanych do bazy Garage, jak opisano na stronie integracji „Backups” w dokumentacji Garage.
Rozwiązywanie typowych błędów
NO ROLE ASSIGNED w garage status zwykle oznacza, że nie utworzyłeś jeszcze ani nie zastosowałeś układu. Rozwiązanie: garage layout assign … a następnie garage layout apply.
AuthorizationHeaderMalformed często wskazuje, że klient używa niewłaściwej strefy; ustaw AWS_DEFAULT_REGION (lub odpowiednik) tak, aby odpowiadał [s3_api].s3_region.
Błędy podpisu/żądania mogą wynikać z niezgodności stylu ścieżki vs stylu vhost; skonfiguruj [s3_api].root_domain dla stylu vhost, lub włącz styl ścieżki w klientach (np. force_path_style=true w rclone).
Błędy dostępu są często po prostu „klucz nie jest dozwolony na bazie danych”; sprawdź za pomocą garage bucket info <bucket> i upewnij się, że garage bucket allow ma odpowiednie flagi.
Uwagi dotyczące regulacji wydajności, które są najważniejsze
Umieść metadata_dir na SSD, jeśli to możliwe; dokumentacja Garage wskazuje poprawę czasu odpowiedzi i „drastyczne zmniejszenie” potencjalnego opóźnienia.
Dostosuj block_size i kompresję ostrożnie: domyślne ustawienia Garage są zaprojektowane, aby być rozsądne, ale dokumentacja konfiguracji wyjaśnia kompromis i zauważa, że zmiany mają zastosowanie tylko do nowo przesłanych danych.
Jeśli masz NVMe, zwiększenie liczby równoległych zapisów bloków może poprawić przepustowość, ale zwiększa zużycie pamięci; Garage dostarcza wskazówek dla block_max_concurrent_writes_per_request.
Własne testy Garage podkreślają koszty opóźnień wewnątrz klastra w konfiguracjach georozproszonych i wskazują na decyzje projektowe (np. unikanie liderów konsensusu), które mogą zmniejszyć wpływ opóźnień geograficznych.
Krótkie porównanie z MinIO i AWS S3
Garage jest zoptymalizowany pod kątem samowystarczalnych, georozproszonych klastrów i prostoty wdrażania, z pewnymi celowymi lukami w funkcjach S3 (np. brak polityk i ACLi S3, ograniczona obsługa wersji).
MinIO skupia się na szerokości API S3 i wysokiej wydajności wdrożeń w środowisku przedsiębiorstwowym (np. własne materiały MinIO opisują funkcje takie jak blokada obiektów, replikacja i powiadomienia o zdarzeniach).
AWS S3 to zarządzana implementacja referencyjna z silną spójnością, 11 dziewiątkami trwałości i 99,99% dostępności, oraz szerokim ekosystemem funkcji (klasy magazynowania, cykl życia, zdarzenia, IAM).
Aby poznać więcej szczegółów, zobacz Porównanie Garage, MinIO i AWS S3.
Więcej o MinIO:
- MinIO jako alternatywa dla AWS S3. Omówienie i instalacja MinIO
- Przykładowe parametry wiersza poleceń MinIO
