Garage - szybki start magazynu obiektowego kompatybilnego z S3
Uruchom Garage w Dockerze w ciągu kilku minut
Garage to open-source, samodzielnie hostowany, S3-kompatybilny system magazynowania obiektów zaprojektowany do wdrożeń od małych po średnie, 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 backendy magazynowania, monitorowanie, naprawy oraz backup/restore.
Aby zobaczyć większy obraz – magazyn obiektów, PostgreSQL, Elasticsearch i warstwy danych wstępnie przeznaczone do AI – zobacz artykuł Infrastruktura danych dla systemów AI.
Co to jest Garage
Garage to rozproszony magazyn obiektów kompatybilny z S3 przeznaczony do samodzielnej instalacji, mający na celu utrzymanie lekkiego i prostego działania, jednocześnie wspierając klastry wielowęzłowe/georozproszone.
Jest wydawany na licencji AGPL v3.
Kluczowe idee kształtujące sposób jego działania:
Garage mierzy pojemność węzła i lokalizację fizyczną („strefy”), aby umieszczać repliki; 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 ustalonej wielkości (block_size), co umożliwia deduplikację i opcjonalne kompresowanie Zstandard; hashe bloków są używane do umieszczania i deduplikacji.
Garage nie kończy TLS na swoich końcach 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ę przez klienta kompatybilnego z S3; ruch zwykle wchodzi przez odwrotny proxy (TLS), osiąga jeden lub więcej punktów końcowych API Garage (często węzły bramkowe), a następnie jest obsługiwany przez węzły magazynowe, które przechowują replikowane bloki danych.
Węzły mają role: węzły magazynowe z pojemnością vs. węzły bramkowe, które eksponują punkty końcowe bez przechowywania danych; bramki 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-wątkowa w strefach), z jasnymi opisami dostępności i kompromisów w tolerancji awarii w dokumentacji konfiguracji.
Szybki start kopiuj/wklej
To celowo minimalne wdrożenie jednowęzłowe do nauki przepływów pracy: konfiguracja → uruchomienie serwera → zdefiniowanie układu → utworzenie koszyka + klucza → przesłanie obiektu.
Wymagania wstępne
Potrzebujesz docker, openssl oraz (opcjonalnie) klienta S3 takiego jak awscli. CLI Garage to ten sam binarny plik używany do zarządzania klastrem.
Krok po kroku
# 0) Przestrzeń robocza
mkdir -p ~/garage-quickstart/{config,meta,data}
cd ~/garage-quickstart
# 1) Utwórz bazową konfigurację (trwałe ś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 zobacz 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 (placeholder). 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 (jeden węzeł) i zastosuj go
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 koszyk + klucz i nadaj prawa dostępu z minimalnymi uprawnieniami
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 „wymagany układ” pochodzą bezpośrednio z szybkiego startu z upstream.
Weryfikacja przy użyciu 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 napotkać 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
Współczesny szybki start zaleca 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 wdrożenia
Instalacje binarne i pakiety
Dokumentacja Garage jawne wspiera: pobieranie binarów z strony pobierania Garage, korzystanie z pakietów dystrybucyjnych (np. apk add garage na Alpine) lub budowanie z źródeł, jeśli to konieczne.
Docker i Docker Compose
Garage dostarcza obrazy kontenerów i dokumentuje metodę docker run dla szybkiego startu.
W produkcji zwykle korzystasz z compose (lub orchestratora), aby zarządzać magazynem trwałym, odwrotnym proxy i uaktualnieniami (restarty w sposób rolowy). Przewodnik Garage „wdrożenie na klastrze” zakłada Docker na każdym węźle i wskazuje typowe ścieżki hosta oraz rekomendację SSD dla metadanych.
systemd
Dokumentacja Garage zawiera przykład wzmocnionego wdrożenia systemd, w tym ostrzeżenia dotyczące DynamicUser= w systemd i miejsca, gdzie 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 kompatybilny z S3 Garage
Po=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 wykres Helm w repozytorium i ma oficjalne strony dokumentacji dla wdrożenia w Kubernetes.
Powszechnym pułapką jest fakt, że nadal musisz uruchomić i zastosować układ klastra po instalacji (możesz to automatyzować za pomocą zadania Kubernetes).
Konfiguracja, bezpieczeństwo i TLS
Backendy magazynowania i układ dysków
Garage dzieli magazynowanie na metadata_dir i data_dir. W referencji konfiguracyjnej 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 obsługuje konfigurację wielodyskowego data_dir z pojemnością na ścieżkę i automatycznym balansowaniem.
# Przykład: wiele HDD dla 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 koszyka S3
Garage nie implementuje ACLi typu AWS ani polityk koszyka; używa własnego systemu kontroli dostępu „dla każdego klucza dostępu i koszyka” zarządzanego przez CLI Garage / API administratora.
To oznacza, że „polityka”, którą zwykle przekładasz na Garage, to: który klucz dostępu ma uprawnienia do czytania/pisz/właściciel na które koszyki.
# Klucz do odczytu koszyka:
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 koszyka w stylu DNS vs. ścieżki
Garage może obsługiwać wirtualny host (styl DNS) do dostępu do koszyka, jeśli skonfigurujesz [s3_api].root_domain; styl ścieżki jest zawsze włączony.
Jeśli nie skonfigurujesz stylu vhost (DNS z gwiazdką + możliwe TLS z gwiazdką), wiele klientów może działać, jeśli zmusisz do stylu ścieżki, 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 rekomendacja to umieszczenie odwrotnego proxy przed nimi, najczęściej Nginx, aby obsługiwać HTTPS i multiplexować usługi na porcie 443.
Minimalny kształt Nginx (zobacz 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 z żądaniem; Garage szyfruje dane w spoczynku i usuwa klucz po żądaniu.
Tabela kompatybilności S3 Garage również zauważa, że punkty końcowe konfiguracji szyfrowania na poziomie koszyka nie są implementowane, więc traktuj SSE-C jako zachowanie na poziomie obiektu/żądania, a nie domyślne dla koszyka.
Operowanie Garage w produkcji
Monitorowanie i logowanie
Garage eksponuje metryki w formacie Prometheus i obsługuje eksportowanie śladów w formacie OpenTelemetry.
Kontrole i punkty końcowe metryk mogą być chronione tokenami (admin_token, metrics_token, 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 do przesyłania logów do syslog/journald zamiast stderr.
Trwałość, naprawy i typowe zadania utrzymaniowe
Garage zawiera tło „scrub” (weryfikacja integralności) i narzędzia do naprawy; scrub można uruchomić ręcznie i monitorować za pomocą poleceń pracownika/zadania, ale są one intensywne wobec dysków i mogą zwolnić klaster.
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 odzyskiwania
Minimum backupuj metadane, ponieważ zawierają one konfigurację klastra, stan koszyka/klucza i indeksy. Garage obsługuje okresowe snapshoty metadanych (metadata_auto_snapshot_interval) i snapshoty ręczne (garage meta snapshot --all).
Przewodnik migracji Garage jawnie zaleca backupowanie określonych plików/katalogów z każdego węzła metadata_dir (w tym snapshoty i pliki układu).
Dla danych obiektowych traktuj Garage jak każdy punkt końcowy S3: użyj narzędzi do backupu kompatybilnych z S3 (np. restic, duplicity) skierowanych do koszyka Garage, jak opisano w stronie integracji „Backups” w Garage.
Rozwiązywanie typowych błędów
NO ROLE ASSIGNED w garage status zwykle oznacza, że jeszcze nie utworzyłeś 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) w celu dopasowania do [s3_api].s3_region.
Błędy podpisu/żądania mogą być spowodowane niezgodnością stylu ścieżki vs. stylu vhost; skonfiguruj [s3_api].root_domain dla stylu vhost, lub wymuś 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 w koszyku”; sprawdź za pomocą garage bucket info <bucket> i upewnij się, że garage bucket allow ma odpowiednie flagi.
Uwagi dotyczące dostosowania wydajności, które są najważniejsze
Umieść metadata_dir na SSD, jeśli to możliwe; dokumentacja Garage wskazuje poprawę czasu odpowiedzi i potencjalnie znaczne zmniejszenie opóźnień.
Dostosuj block_size i kompresję ostrożnie: domyślne ustawienia Garage są zaprojektowane, aby być sensowne, ale dokumentacja konfiguracji wyjaśnia kompromis i zauważa, że zmiany dotyczą tylko danych przesyłanych nowo.
Jeśli masz NVMe, zwiększenie liczby współbieżnych zapisów bloku 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ętrznych klastra w ustawieniach 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 samodzielnie hostowanych, georozproszonych klastrów i prostoty operacyjnej, z pewnymi celowymi lukami w funkcjach S3 (np. brak polityk i ACLi koszyka S3; ograniczona obsługa wersji).
MinIO skupia się na szerokości API S3 i wdrożeniach wysokiej wydajności w środowisku firmowym (np. 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 celami dostępności 99,99%, oraz szerokim ekosystemem funkcji (klasy magazynowania, cykl życia, wydarzenia, IAM).
Więcej o MinIO:
- MinIO jako alternatywa dla AWS S3. Przegląd i instalacja MinIO
- Przykładowe parametry wiersza poleceń MinIO
