Garage - S3 kompatibel objektlagring Snabbstart
Kör Garage i Docker på bara några minuter
Garage är en öppen källkod, självvärdbaserad, S3-kompatibel objektlagringssystem som är utformad för små till medelstora distributioner, med ett starkt fokus på återhämtning och geografisk spridning.
Den här snabbstarten leder dig från en kopierings/klistra enkelservrarinstallation till produktionsinriktade mönster: klusterlayout, replikering, TLS via omvänd proxy, flerdiskslagringssystem, övervakning, reparationer och säkerhetskopiering/återställning.
För det bredare perspektivet – objektlagring, PostgreSQL, Elasticsearch och AI-nativ datalager – se artikeln Data Infrastructure for AI Systems.
Vad Garage är
Garage är en S3-kompatibel distribuerad objektlagring som är avsedd för självvärd, med syftet att förbli lättviktig och enkel att driva medan den stöder flersidiga/geo-distribuerade kluster.
Den släpps ut under AGPL v3 licensen.
Nyckelidéer som formar hur du kör den:
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 deduplivering och valfri Zstandardkomprimering; blockhashar används för placering och deduplering.
Garage avslutar inte TLS på dess S3 API/webbändpunkter: du förväntas distribuera en omvänd proxy för HTTPS i verkliga distributioner.
Arkitektur och dataflöde
På ett högre plan interagerar du med Garage genom S3-kompatibla klienter; trafiken kommer vanligtvis via en omvänd proxy (TLS), nås en eller flera Garage API-ändpunkter (ofta “gateway”-noder) och serveras sedan av lagringsnoder som håller replikerade datablock.
Noder har roller: lagringsnoder med kapacitet mot gateway-noder som exponerar slutpunkter utan att lagra data; gateways minskar latens 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/felhanteringsväxlingar som beskrivs i konfigurationsreferensen.
Kopierings/klistra snabbstart
Detta är avsiktligt minimal enkelservrardistribution för att lära sig arbetsflöden: konfiguration → starta server → definiera layout → skapa bucket + 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 hantera klustret.
Steg för steg
# 0) Arbetsområde
mkdir -p ~/garage-quickstart/{config,meta,data}
cd ~/garage-quickstart
# 1) Skapa en starterkonfiguration (pålitliga 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"
# Enkelservrar lä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 troligen se "NO ROLE ASSIGNED")
garage status
# 6) Tilldela en layout (enkel 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 bucket + 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 nyckelmaterial (spara det säkert)
garage key info example-app-key
Konfigurationsmönstret (S3 API på 3900, RPC på 3901, webbändpunkt på 3902, admin API på 3903) och “layout krävs”-arbetsflödet kommer direkt från den upströms 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="DIN_GARAGE_NYCKEL_ID"
export AWS_SECRET_ACCESS_KEY="DIN_GARAGE_HEMLIG_NYCKEL"
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 upströms snabbstarten rekommenderar att använda en ~/.awsrc-fil för att växla mellan slutpunkter/nycklar och noterar minsta AWS CLI-versioner för bekväm hantering av slutpunkter.
Installations- och distributionsalternativ
Binärinstallationer och paket
Garage-dokumentationen stöder explicit: ladda ner binärer från Garages nedladdningssida, använda distributionspaket (t.ex. apk add garage på Alpine) eller bygg 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 du vanligtvis compose (eller en orchestrator) för att hantera pålitlig lagring, omvänd proxy och uppgraderingar (rollbörjande omstartar). Garages “distribution på ett kluster”-guide antar Docker på varje nod och nämner de vanliga värdvägarna och SSD-rekommendationen för metadata.
systemd
Garage dokumenterar en förstärkt systemd-deploy, inklusive varningar kring systemd:s DynamicUser= och var pålitlig tillstånd hamnar på disken.
Ett minimalt enhetsexempel (anpassa vägar till din miljö):
# /etc/systemd/system/garage.service
[Unit]
Beskrivning=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-karta i repo och har officiella dokumentationsidor för Kubernetes-distribution.
Ett vanligt problem är att du fortfarande måste initiera/applya ett 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 svarsfrekvens, medan data_dir kan ligga på större HDD.
För noder med flera datadiskar stöder Garage en flerdisk data_dir-konfiguration med kapacitet per sökväg och automatisk balansering.
# Exempel: flera HDD:er 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" },
]
Tillgångskontrollmodell mot S3-bucketspolicyer
Garage implementerar inte AWS-stil ACL:er 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 “policy” du vanligtvis översätter till Garage är: vilken accesskey får läsa/skriva/ägare till vilka bucket(s).
# Läs-only nyckel till en bucket:
garage key create ro-key
garage bucket allow --read example-bucket --key ro-key
# Ta bort tillgång:
garage bucket deny example-bucket --key ro-key
DNS-stil vs path-stil bucketadressering
Garage kan stödja virtuell värd (DNS) stil bucketåtkomst om du konfigurerar [s3_api].root_domain; path-stil är alltid aktiverad.
Om du inte konfigurerar 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 S3 API och webbändpunkter stöder inte TLS direkt; den officiella riktlinjen ä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 “form” (se den officiella omvänd proxy recept för ett fullständigt 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-sidan kryptering
Garage stöder S3 SSE-C (“server-side encryption with customer-provided keys”): klienten skickar krypteringsnycklar i rubriker per begäran; Garage krypterar på disk och kassar nyckeln efter begäran.
Garage S3 kompatibilitetslista noterar också att bucketnivå krypteringskonfigurationsändpunkter inte är implementerade, så behandla SSE-C som per-objekt/begäran beteende snarare än bucketstandard.
Driva Garage i produktion
Övervakning och loggning
Garage exponerar Prometheus-formatet mått och stöder export av spår i OpenTelemetry-format.
Admin och måttändpunkter 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ållsåtgärder
Garage inkluderar bakgrunds “scrub” (integritetskontroll) och reparationstjänster; scrubs kan startas manuellt och övervakas via worker/task-kommandon, men de är diskintensiva och kan låsa upp 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, bucket/nyckelstatus och index. Garage stöder periodiska metadata-snapshotter (metadata_auto_snapshot_interval) och manuella snapshotter (garage meta snapshot --all).
Garage-migreringsguiden rekommenderar explicit att säkerhetskopiera specifika filer/kataloger från varje nods metadata_dir (inklusive snapshotter och layoutfiler).
För objektdata, behandla Garage som någon S3-ändpunkt: använd S3-kompatibla säkerhetskopieringsverktyg (t.ex. restic, duplicity) som riktas mot en Garage-bucket, som dokumenterats i Garages “Säkerhetskopior” integrationsida.
Felsökning av vanliga fel
NO ROLE ASSIGNED i garage status betyder vanligtvis att du inte har skapat/applikerat 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äran fel kan orsakas av path-stil vs vhost-stil matchning; konfigurera [s3_api].root_domain för vhost-stil, eller tvinga path-stil i klienter (t.ex. rclone’s force_path_style=true).
Behörighetsfel är ofta bara “nyckel inte tillåten på bucket”; undersök med garage bucket info <bucket> och se till att garage bucket allow har rätt flaggor.
Prestandatuning som mest betydelsefulla
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: Garage-standardvärden är avsedda att vara sunt, men konfigurationsreferensen förklarar växeln och noterar att förändringar endast gäller för nyuppladdat data.
Om du har NVMe, kan ökning av blockskrivningskonkurrens förbättra throughput men ökar minnesanvändning; Garage ger vägledning för block_max_concurrent_writes_per_request.
Garages egna benchmarkar betonar kostnaderna för intra-klusterlatens i geodistribuerade konfigurationer och lyfter fram designval (t.ex. undvikande av konsensusledare) som kan minska geolatenspåverkan.
Kort jämförelse med MinIO och AWS S3
Garage är optimerad för självvärd, geodistribuerade kluster och drifts enkelhet, med några avsiktliga S3-funktionsskylor (t.ex. inga S3-bucketpolicyer/ACL:er; begränsad versioneringssupport).
MinIO fokuserar på S3 API-bredd och högpresterande företagsdistributioner (t.ex. MinIO:s egna material beskriver funktioner som objektlås, replikering och händelseaviseringar).
AWS S3 är den hanterade referensimplementeringen med stark konsekvens, 11 nines hållbarhet och 99.99% tillgänglighet, samt ett brett funktionssystem (lagringsklasser, livscykel, händelsehantering, IAM).
Mer om Minio:
- Minio som alternativ till Aws S3. Minio översikt och installering
- MinIO Kommandoradparameter Cheatsheet
