Garage - S3 kompatibel objektlagring snabbstart
Kör Garage i Docker på bara några minuter
Garage är en öppen källkod, självvärdbar, S3-kompatibel objektlagringssystem som är utformad för små- till medelstorleksdistributioner, med ett starkt fokus på hållbarhet och geografisk distribution.
Den här snabbstarten leder dig från en kopierings/infärgningskonfiguration för en enskild nod till produktionsinriktade mönster: klusterlayout, replikering, TLS via omvänd proxy, flerdiskslagringssystem, övervakning, reparationer och säkerhetskopiering/återställning.
För en bredare bild – objektlagring, PostgreSQL, Elasticsearch och AI-nativ datalagring – se artikeln Data Infrastructure for AI Systems.
Vad Garage är
Garage är en S3-kompatibel distribuerad objektlagring som är avsedd för självvärdbarhet, och syftar på att hålla sig lätt och enkel att drifta medan den stöder flersidiga/geo-distribuerade kluster.
Det släpps ut under licensen AGPL v3.
Några centrala idéer som styr hur du kör det:
Garage mäter nodkapacitet och fysisk plats (“zoner”) för att placera replikationer; ändringar i klustertopologi (lägg till/ta bort noder) hanteras genom versionerade layouter och omfördelning.
Objekt delas upp i fasta storleksblock (block_size), vilket möjliggör deduplikerings och valfri Zstandardkomprimering; blockhashar används för placering och deduplivering.
Garage avslutar inte TLS på dess S3 API/webbterminaler: du förväntas distribuera en omvänd proxy för HTTPS i verkliga distributioner.
Arkitektur och dataflöde
På en hög nivå interagerar du med Garage via S3-kompatibla klienter; trafiken kommer ofta via en omvänd proxy (TLS), nås en eller flera Garage API-terminaler (ofta “gateway”-noder) och serveras sedan av lagringsnoder som håller replikerade datablock.
Noder har roller: lagringsnoder med kapacitet mot gateway-noder som exponerar terminaler utan att lagra data; gateway-noder minskar latensen genom att undvika extra nätverkssteg och genom att “veta” vilka lagringsnoder som ska frågas.
Replikering styrs via replication_factor (t.ex. 3-vegs replikering över zoner), med tydliga tillgänglighets/feltoleransväxlingar som beskrivs i konfigurationsreferensen.
Snabbstart med kopiering/infärgning
Detta är avsiktligt en minimal enskildnod-distribution för att lära sig arbetsflöden: konfiguration → starta server → definiera layout → skapa buckett + nyckel → ladda upp ett objekt.
Förutsättningar
Du behöver docker, openssl och (valfritt) en S3-klient som awscli. Garage CLI är samma binär som används för att administrera klustret.
Steg för steg
# 0) Arbetsområde
mkdir -p ~/garage-quickstart/{config,meta,data}
cd ~/garage-quickstart
# 1) Skapa en startkonfiguration (persistenta sökvägar inuti behållaren)
cat > ./config/garage.toml <<EOF
metadata_dir = "/var/lib/garage/meta"
data_dir = "/var/lib/garage/data"
db_engine = "sqlite"
# Enskildnodslärande distribution (INGEN redundans). För produktion, se senare.
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"
# Valfri vhost-stil. Path-stil är alltid aktiverad.
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) Välj en bildtag (tillfällig). Exempeltaggar visas i Garage-dokumentationen.
GARAGE_IMAGE="dxflrs/garage:TAG_PLACEHOLDER"
# 3) Kör 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) Använd garage CLI inuti behållaren
alias garage='docker exec -ti garaged /garage'
# 5) Kontrollera nodstatus (du kommer sannolikt att se "NO ROLE ASSIGNED")
garage status
# 6) Tilldela en layout (enskild nod) och tillämpa den
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) Skapa en buckett + nyckel och bevilja minsta behörighet
garage bucket create example-bucket
garage key create example-app-key
garage bucket allow --read --write --owner example-bucket --key example-app-key
# 8) Visa nyckelinformation (spara den säkert)
garage key info example-app-key
Konfigurationsmönstret (S3 API på 3900, RPC på 3901, webbterminal på 3902, admin API på 3903) och “layout krävs”-arbetsflödet kommer direkt från den ursprungliga snabbstarten.
Validera med AWS CLI
Garage kräver att klienter använder den konfigurerade s3_region (ofta “garage”); om din klient använder us-east-1, kan du få AuthorizationHeaderMalformed omdirigeringar.
# Installera (en möjlighet)
python -m pip install --user awscli
# Konfigurera miljö (exempel)
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
Den ursprungliga snabbstarten rekommenderar att använda en ~/.awsrc-fil för att byta mellan terminaler/nycklar och noterar minsta AWS CLI-versioner för bekväma terminalhantering.
Installation och distributionsalternativ
Binärinstallation och paket
Garage-dokumentationen stöder explicit: att ladda ner binärer från Garages nedladdningssida, använda distributionspaket (t.ex. apk add garage på Alpine) eller bygga från källkoden om det behövs.
Docker och Docker Compose
Garage tillhandahåller behållarbilder och dokumenterar en minimal docker run-metod för snabbstart.
För produktion använder man vanligtvis compose (eller en orchestrator) för att hantera persistenslagring, omvänd proxy och uppgraderingar (rullande start). Garages “distribution på ett kluster”-guide antar Docker på varje nod och pekar ut de vanliga värdens sökvägar och SSD-rekommendationen för metadata.
systemd
Garage dokumenterar en förstärkt systemd-distribution, inklusive varningar kring systemd:s DynamicUser= och var persistensstatus hamnar på disken.
Ett minimalt enhetsexempel (anpassa sökvägar till din miljö):
# /etc/systemd/system/garage.service
[Unit]
Description=Garage S3-kompatibel objektlagring
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 och Helm
Garage levererar en Helm-kluster i repo och har officiella dokumentationsidor för Kubernetes-distribution.
Ett vanligt problem är att du fortfarande måste bootstrapa/ta tillämpa en klusterlayout efter installation (du kan automatisera det med en Kubernetes Job).
Konfiguration, säkerhet och TLS
Lagringsbakar och disklayout
Garage delar upp lagring i metadata_dir och data_dir. Konfigurationsreferensen rekommenderar att placera metadata_dir på snabb SSD för att förbättra svarsfrågor, medan data_dir kan ligga på större HDD.
För noder med flera dataenheter stöder Garage en flerdisk data_dir-konfiguration med kapacitet per sökväg och automatisk balansering.
# Exempel: flera HDD för datablock
metadata_dir = "/mnt/ssd/garage-meta"
data_dir = [
{ path = "/mnt/hdd1/garage-data", capacity = "8T" },
{ path = "/mnt/hdd2/garage-data", capacity = "8T" },
]
Åtkomstkontrollmodell mot S3-bucketpolicy
Garage implementerar inte AWS-stilens ACL eller bucketpolicyer; den använder sin egen “per access key per bucket”-behörighetsmodell som hanteras genom Garage CLI / admin API.
Detta innebär att den “policy” du vanligtvis översätter till Garage är: vilken accesskey får läsa/skriva/äga vilka bucket(s).
# Läsbar nyckel till en buckett:
garage key create ro-key
garage bucket allow --read example-bucket --key ro-key
# Ta bort åtkomst:
garage bucket deny example-bucket --key ro-key
DNS-stil mot path-stil för buckettadressering
Garage kan stödja virtuell värd (DNS) stil för buckettåtkomst om du konfigurerar [s3_api].root_domain; path-stil är alltid aktiverad.
Om du inte ställer in vhost-stil (wildcard DNS + eventuellt wildcard TLS), kan många klienter göras att fungera genom att tvinga path-stil, och Garage-dokumentationen visar klientexempel med force_path_style = true.
TLS
Garage:s S3 API och webbterminaler stöder inte TLS direkt; den officiella rekommendationen är att placera en omvänd proxy framför, ofta Nginx, för att servera HTTPS och multiplexa tjänster på port 443.
Ett minimalt Nginx “format” (se den officiella omvända proxy-kokboken för ett komplett exempel):
# /etc/nginx/sites-available/garage.conf (utdrag)
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;
}
}
Server-sidig kryptering
Garage stöder S3 SSE-C (“server-sidig kryptering med kundlevererade nycklar”): klienten skickar krypteringsnycklar i rubriker per begäran; Garage krypterar på plats och kassar nyckeln efter begäran.
Garage:s S3-kompatibilitetslista noterar också att konfigurationsändpunkter för buckett-nivåkryptering inte är implementerade, så behandla SSE-C som per-objekt/begäran beteende snarare än buckettstandard.
Drift av Garage i produktion
Övervakning och loggning
Garage exponerar mått i Prometheus-format och stöder export av spår i OpenTelemetry-format.
Admin och måttterminaler kan skyddas med token (admin_token, metrics_token och metrics_require_token), och spår kan exporteras via trace_sink (OTLP).
För loggning kan Garage anpassas via RUST_LOG, och konfigurationsreferensen dokumenterar miljövariabler för att skicka loggar till syslog/journald istället för stderr.
Hållbarhet, reparationer och vanliga underhållsaktiviteter
Garage innehåller bakgrunds“scrub” (integritetskontroll) och reparationstöd; scrubber kan startas manuellt och övervakas via arbetsgivare/aktivitetskommandon, men är diskintrusive och kan långsamt påverka klustret.
Topologiförändringar och kapacitetsjusteringar hanteras genom layouthantering; operationer tillämpas som nya layoutversioner.
Säkerhetskopierings- och återställningsstrategi
Minst säkerhetskopiera metadata, eftersom den innehåller klusterkonfiguration, buckett/nyckelstatus och index. Garage stöder periodiska metadata-snapshotter (metadata_auto_snapshot_interval) och manuella snapshotter (garage meta snapshot --all).
Garage:s migreringsguide rekommenderar explicit att säkerhetskopiera specifika filer/kataloger från varje nords metadata_dir (inklusive snapshotter och layoutfiler).
För objektdata, behandla Garage som någon S3-terminal: använd S3-kompatibla säkerhetskopieringsverktyg (t.ex. restic, duplicity) som riktas mot en Garage-buckett, som dokumenterats i Garages “Säkerhetskopieringar”-integrationsida.
Fel sökning för vanliga fel
NO ROLE ASSIGNED i garage status betyder vanligtvis att du inte har skapat/tillämpat en layout än. Lösning: garage layout assign … sedan garage layout apply.
AuthorizationHeaderMalformed indikerar ofta att en klient använder fel region; ställ in AWS_DEFAULT_REGION (eller motsvarande) för att matcha [s3_api].s3_region.
Signatur-/begäranfel kan orsakas av path-stil vs vhost-stil mismatch; konfigurera [s3_api].root_domain för vhost-stil, eller tvinga path-stil i klienter (t.ex. rclone:s force_path_style=true).
Åtkomstfel är ofta bara “nyckel inte tillåten på buckett”; undersök med garage bucket info <bucket> och se till att garage bucket allow har rätt flaggor.
Prestandatuningsnoter som är viktigast
Placera metadata_dir på SSD när det är möjligt; Garage-dokumentationen nämner förbättrad svarsfrekvens och “drastiskt minskad” latenspotential.
Justera block_size och komprimering noggrant: Garages standardvärden är avsedda att vara rimliga, men konfigurationsreferensen förklarar kompromissen och noterar att ändringar endast gäller för nyuppladdat data.
Om du har NVMe, kan ökad blockskrivkonkurrens förbättra genomströmmen men ökar minnesanvändningen; Garage ger vägledning för block_max_concurrent_writes_per_request.
Garages egna mätningar betonar kostnaderna för inre klusterlatens i geo-distribuerade konfigurationer, och visar designval (t.ex. undvikande av konsensusledare) som kan minska geo-latenspåverkan.
Kort jämförelse med MinIO och AWS S3
Garage är optimerad för självvärdbar, geo-distribuerade kluster och drifts enkelhet, med vissa medvetna S3-funktionsskillnader (t.ex. inga S3-bucketpolicyer/ACL; begränsad versionssupport).
MinIO fokuserar på S3 API:s omfattning och högpresterande företagsdistributioner (t.ex. beskriver MinIO:s egna material funktioner som objektlås, replikering och händelseaviseringar).
AWS S3 är den hanterade referensimplementationen med stark konsekvens, 11 nines hållbarhet och 99,99% tillgänglighet, samt ett brett funktionssystem (lagringsklasser, livscykel, händelse, IAM).
För mer detaljer se Garage vs MinIO vs AWS S3 Jämförelse.
Mer om Minio:
- Minio som alternativ till Aws S3. Minio översikt och installation
- MinIO Kommandoradsparametrar Snabbguide
