Garage ile kendi sunucunuzda S3 nesne depolama nasıl çalıştırılır

S3 uyumlu nesne depolama; yedekleme araçlarının, medya sunucularının, Nextcloud'un, Mastodon'un, Matrix'in ve daha birçok uygulamanın dosyalarını Amazon S3 API'si üzerinden sizin denetiminizdeki bir sunucuda saklamasını sağlar. Bu rehber böyle bir depoyu bir Linux sunucuda Garage ile kurar.

Kendi sunucusunda S3 çalıştırmak isteyenlerin olağan tercihi uzun süre MinIO idi. MinIO'nun GitHub deposu artık deponun bakımının yapılmadığını ve MinIO'nun orada önceden derlenmiş ikili dosyalar olmadan yalnızca kaynak kod olarak dağıtıldığını belirtir; GitHub depoyu Nisan 2026'dan beri arşivlenmiş gösterir. Mevcut MinIO kurulumları çalışmaya devam eder, ancak o depodan artık güncelleme almazlar.

Bu rehberde Garage'ı şu nedenlerle seçtik: bağımlılığı olmayan tek bir ikili dosya ve sürüm etiketli resmi bir Docker imajı olarak dağıtılır; tek bir TOML dosyasıyla yapılandırılır; belgeleri en düşük gereksinimleri (1 GB RAM, 16 GB disk) yayınlar ve onu küçük ile orta ölçekli self-hosted kurulumlar için tasarlanmış olarak tanımlar; tek sunucuda çalışır ve çoğaltmalı, çok bölgeli bir kümeye büyüyebilir; düzenli olarak yeni sürüm yayınlanır (2.4.1 sürümü Eylül 2026'da çıktı). SeaweedFS'i de inceledik; daha esnektir ancak ayrı ayrı kurup işletmeniz gereken birkaç bileşen (master, volume sunucuları, filer ve S3 ağ geçidi) çalıştırır.

Başlamadan önce Garage'ın sınırlarını bilin: nesne sürümlemeyi, Object Lock'u, bucket politikalarını veya ACL'leri desteklemez; yaşam döngüsü kuralları yalnızca süre dolumunu ve tamamlanmamış çok parçalı yüklemelerin iptalini kapsar. Bir araç değiştirilemez (Object Lock) yedeklere ihtiyaç duyuyorsa Garage ona uygun depo değildir. Bu rehber Garage'ı Docker Compose ile çalıştırır, S3 API'sini Caddy ile HTTPS üzerinden yayınlar, bir bucket ve bir erişim anahtarı oluşturup rclone ile test eder; güvenlik duvarı kurallarını, yedeklemeyi, güncellemeyi ve üç düğümlü kümeye giden yolu anlatır.

Adım 1 — Klasörleri oluşturun

Yapılandırmayı /opt/garage içinde, verileri ise Garage'ın kendi kurulum rehberinin kullandığı yollarda tutun:

sudo mkdir -p /opt/garage /var/lib/garage/meta /var/lib/garage/data
sudo chown $USER:$USER /opt/garage
cd /opt/garage

/var/lib/garage/meta meta veri veritabanını, düğüm anahtarını ve küme düzenini; /var/lib/garage/data ise saklanan veri bloklarını tutar.

Adım 2 — Yapılandırmayı yazın

garage.toml dosyasını oluşturun. Kabuk, Garage'ın hızlı başlangıç rehberindeki gibi dosyayı yazarken openssl ile yeni bir RPC sırrı ve yönetici belirteçleri üretir. 203.0.113.10 yerine sunucunuzun genel IP adresini, s3.example.com yerine alan adınızı yazın:

cat > garage.toml <<EOF
metadata_dir = "/var/lib/garage/meta"
data_dir = "/var/lib/garage/data"
db_engine = "sqlite"
metadata_auto_snapshot_interval = "6h"

replication_factor = 1

rpc_bind_addr = "[::]:3901"
rpc_public_addr = "203.0.113.10:3901"
rpc_secret = "$(openssl rand -hex 32)"

[s3_api]
s3_region = "garage"
api_bind_addr = "127.0.0.1:3900"
root_domain = ".s3.example.com"

[admin]
api_bind_addr = "127.0.0.1:3903"
admin_token = "$(openssl rand -base64 32)"
metrics_token = "$(openssl rand -base64 32)"
EOF
chmod 600 garage.toml
cat garage.toml

Ayarların anlamı:

• replication_factor = 1 tek kopya saklar; tek bir sunucunun yapabileceği budur. Değer her düğümde aynı olmalıdır ve sonradan kolayca değiştirilemez: belgeler bu değişikliği resmi olarak desteklenmeyen, tehlikeli bir işlem olarak tanımlar.
• db_engine = "sqlite": varsayılan motor LMDB daha hızlıdır ve çoğaltma katsayısı 2 veya üzeri olan kümeler için önerilir, ancak düzgün yapılmayan bir kapatmada bozulabilir. Tek düğümde yeniden eşitlenecek başka bir kopya olmadığı için SQLite daha güvenli seçimdir. metadata_auto_snapshot_interval kurtarma için en son iki meta veri anlık görüntüsünü saklar.
• api_bind_addr = "127.0.0.1:3900" S3 API'sini loopback adresinde tutar; TLS'yi önündeki Caddy ekler. 3903 numaralı porttaki yönetici API'si de loopback adresinde kalır.
• rpc_bind_addr ve rpc_public_addr yalnızca Garage düğümleri arasındaki trafik için kullanılır. Tek sunucuda güvenlik duvarı 3901 numaralı portu kapalı tutar.
• root_domain, backups.s3.example.com gibi virtual-host stilindeki bucket adreslerini etkinleştirir; path-style erişim her zaman çalışır (Adım 6).

Bu dosyadaki sırlar kümenizi ve yönetici API'nizi korur; bu yüzden dosya 600 izni alır.

Adım 3 — Garage'ı Docker Compose ile başlatın

compose.yaml dosyasını oluşturun. Dosya, Garage'ın kurulum rehberindeki Docker Compose örneğini izler; bu örnek Garage düğümlerinin birbirine doğrudan ulaşabilmesi için host ağını kullanır. Host ağıyla Docker port yayınlamaz ve ufw normal şekilde uygulanır:

services:
  garage:
    image: dxflrs/garage:v2.4.1
    container_name: garage
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./garage.toml:/etc/garage.toml:ro
      - /var/lib/garage/meta:/var/lib/garage/meta
      - /var/lib/garage/data:/var/lib/garage/data

Garage tam sürüm numarasıyla etiketlenmiş imajlar yayınlar; bu rehber yazılırken güncel sürüm v2.4.1 idi. En son sürüm için indirme sayfasına bakın. Konteyneri başlatın ve konteynerin içinde çalışıp aynı yapılandırma dosyasını okuyan garage komut satırı aracı için bir kısayol oluşturun:

docker compose up -d
docker compose logs --tail 20
echo "alias garage='docker exec garage /garage'" >> ~/.bashrc
source ~/.bashrc
garage status

garage status, NO ROLE ASSIGNED durumunda sağlıklı tek bir düğüm listeler. Sonraki adım için kimliğinin ilk birkaç karakterini kopyalayın.

Adım 4 — Depolama düzenini atayın

Bir Garage kümesi, her düğüme bir bölge ve kapasite atayıp bu düzeni uygulamadan veri saklamaz. Kapasite, Garage'a bu düğümde ne kadar alan kullanabileceğini söyler; /var/lib/garage/data klasöründeki boş alanın altında bir değer seçin. 563e yerine düğüm kimliğinizin başını yazın:

garage layout assign -z dc1 -c 100G 563e
garage layout show
garage layout apply --version 1
garage status
curl -s http://127.0.0.1:3903/health

garage status artık düğümü dc1 bölgesi ve kapasitesiyle gösterir; yönetici API'sinin sağlık uç noktası da Garage'ın çalışır durumda olduğunu bildirir.

Adım 5 — Bir bucket ve bir erişim anahtarı oluşturun

Bir bucket oluşturun, onu kullanacak uygulama için bir anahtar oluşturun ve bu anahtarın bucket'ı okuyup yazmasına izin verin:

garage bucket create backups
garage key create backups-key
garage bucket allow --read --write --owner backups --key backups-key
garage bucket info backups

garage key create, GK ile başlayan bir Key ID ve bir Secret key yazdırır. İkisini de parola yöneticinizde saklayın; uygulamalar bunları erişim anahtarı ve gizli anahtar olarak kullanır. garage bucket info anahtarı izinleriyle birlikte listeler.

Her uygulamaya kendi anahtarını ve yalnızca ihtiyaç duyduğu yetkileri verin. Yalnızca okuyan bir araç için tek başına --read verin. Anahtarlar ve bucket'lar birbirinden bağımsızdır; bir anahtara birden fazla bucket için izin verilebilir.

Adım 6 — S3 API'sini Caddy ile HTTPS üzerinden yayınlayın

/etc/caddy/Caddyfile dosyasına bir site bloğu ekleyin. Caddy, istekleri iletirken özgün Host başlığını korur; S3 istek imzaları buna dayanır:

s3.example.com {
    reverse_proxy 127.0.0.1:3900
}

Caddy'yi yeniden yükleyin ve yalnızca SSH ile web trafiğine izin verin. 3900–3903 arası portlar kapalı kalır:

sudo systemctl reload caddy
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
curl -sI https://s3.example.com

curl geçerli bir sertifikayla bağlanır ve istek imzalı olmadığı için Garage 403 gibi bir S3 hata durumuyla yanıt verir. Bu beklenen bir davranıştır ve proxy'nin çalıştığını kanıtlar.

Path-style mı, virtual-host stili mi? Bu kurulumda istemciler, bucket'ın yolun parçası olduğu path-style adresleri kullanır: https://s3.example.com/backups/file.txt. Virtual-host stili bucket'ı ana bilgisayar adına koyar: https://backups.s3.example.com/file.txt. Bunun için *.s3.example.com için joker bir DNS kaydı, Caddy'de s3.example.com, *.s3.example.com site adresi ve joker bir sertifika gerekir; Caddy bu sertifikayı ancak DNS sağlayıcınıza ait bir eklentiyle DNS doğrulaması üzerinden alabilir. Çoğu araç (rclone, restic, AWS CLI, Nextcloud) path-style kullanacak şekilde ayarlanabilir; bu yüzden oradan başlayın.

Adım 7 — rclone ile test edin

rclone bulut depolama için bir komut satırı aracıdır ve Ubuntu ile Debian'da paket olarak bulunur. Garage belgeleri onun için gereken yapılandırmayı verir:

sudo apt install rclone
mkdir -p ~/.config/rclone
nano ~/.config/rclone/rclone.conf

[garage]
type = s3
provider = Other
env_auth = false
access_key_id = GK_REPLACE_WITH_KEY_ID
secret_access_key = REPLACE_WITH_SECRET_KEY
region = garage
endpoint = https://s3.example.com
force_path_style = true
acl = private
bucket_acl = private

Dosyayı koruyun, ardından bucket'ları listeleyin ve bir test dosyasını yükleyip geri okuyun:

chmod 600 ~/.config/rclone/rclone.conf
rclone lsd garage:
echo "hello from garage" > hello.txt
rclone copy hello.txt garage:backups
rclone ls garage:backups
rclone cat garage:backups/hello.txt

backups bucket'ını, dosyayı boyutuyla birlikte ve içeriğini görmelisiniz. Diğer istemciler de aynı şekilde çalışır: AWS CLI için ~/.aws/config içinde region=garage ve endpoint_url=https://s3.example.com gerekir (eski sürümlerde --endpoint-url); restic gibi yedekleme araçları uç noktayı, bölgeyi, anahtar kimliğini ve gizli anahtarı alır.

Adım 8 — Üç düğümlü bir küme planlayın (isteğe bağlı)

Bir sunucunun kaybından sonra da korunması gereken veriler için Garage belgeleri replication_factor = 3 ile en az üç düğüm önerir; Garage bu durumda üç farklı bölgede üç kopya tutar. Çoğaltma katsayısı sonradan değiştirilmemesi gerektiği için kararı veri saklamaya başlamadan önce verin. Kurulum tek sunucudan birkaç noktada ayrılır:

• Garage'ı her düğüme aynı şekilde, aynı rpc_secret değeriyle ve replication_factor = 3 ile kurun; her düğümün rpc_public_addr değerine kendi genel IP adresini yazın. Belgeler kümeler için LMDB motorunu (db_engine = "lmdb") önerir.
• 3901/tcp portunu yalnızca düğümler arasında açın; örneğin her eş için sudo ufw allow from 203.0.113.11 to any port 3901 proto tcp.
• Düğümleri bağlayın, ardından her birine kendi bölgesini (örneğin her konum için bir tane) verin ve düzeni bir kez uygulayın:

garage node id
garage node connect 563e1ac825ee3323aa441e72c26d1030d6d4414aeb3dd25287c531e7fc2bc95d@203.0.113.11:3901
garage layout assign -z zone-a -c 1T 563e
garage layout assign -z zone-b -c 1T 8f2a
garage layout assign -z zone-c -c 1T c41d
garage layout apply --version 1

Tam kimliğini almak için her düğümde garage node id, diğer düğümlere bağlanmak için bir düğümden garage node connect çalıştırın; düğümler kümenin geri kalanını kendileri keşfeder. Caddy tek bir reverse_proxy satırında birden fazla hedef listeleyebilir; böylece tek bir HTTPS uç noktası istekleri düğümlere dağıtabilir.

Yedekleme ve geri yükleme

Durum üç yerde tutulur: /opt/garage (RPC sırrınızı içeren yapılandırma ve Compose dosyası), /var/lib/garage/meta (meta veri veritabanı, düğüm anahtarı ve düzen) ve /var/lib/garage/data (meta veri olmadan işe yaramayan veri blokları). Tek sunucuda iki şeyi yedekleyin.

1. Yapılandırma ve meta veri. Tutarlı bir meta veri anlık görüntüsü alın, ardından onu yapılandırmayla birlikte arşivleyin:

sudo mkdir -p /opt/backups
garage meta snapshot --all
sudo tar -czf /opt/backups/garage-meta-$(date +%F).tar.gz -C / opt/garage var/lib/garage/meta

Anlık görüntü, alındığı zamanın adıyla /var/lib/garage/meta/snapshots içine yazılır. Arşiv çalışan veritabanı dosyasını da içerir ve bu dosya tutarsız olabilir; geri yükleme anlık görüntüyü kullanır.

2. Nesnelerin kendisi. Her bucket'ı başka bir makinedeki depolamaya kopyalayın; örneğin başka bir Garage sunucusu, bir S3 sağlayıcısı veya offsite adlı ikinci bir rclone uzak noktası olarak tanımlanmış bir SFTP sunucusu:

rclone sync garage:backups offsite:garage-backups

Meta veriyi anlık görüntüden geri yükleyin (örneğin meta veri bozulmasından sonra); Garage'ın kurtarma rehberini izleyin. Garage'ı durdurun, hasarlı veritabanını kenara alın, en yeni anlık görüntüyü onun yerine kopyalayın, yeniden başlatın ve tabloları onarın:

cd /opt/garage
docker compose stop
sudo ls /var/lib/garage/meta/snapshots
sudo mv /var/lib/garage/meta/db.sqlite /var/lib/garage/meta/db.sqlite.bak
sudo cp /var/lib/garage/meta/snapshots/2026-10-09T03:00:00Z /var/lib/garage/meta/db.sqlite
docker compose start
garage repair -a --yes tables

Tek düğümde anlık görüntüden sonra yapılan değişiklikler kaybolur. Yeni bir sunucuda yeniden kurmak için Garage'ı 1–7. adımlardaki gibi kurun, bucket ve anahtarı yeniden oluşturun ve nesneleri rclone copy offsite:garage-backups garage:backups ile geri kopyalayın.

Garage güncelleme

Önce indirme sayfasından bağlantı verilen sürüm notlarını okuyun. Garage'ın yükseltme rehberi aynı ana sürüm içindeki güncellemeleri düğüm düğüm uygulanabilen küçük yükseltmeler olarak ele alır ve önce küme sağlığının kontrol edilmesini ister; ayrıca bir meta veri anlık görüntüsü de alın:

cd /opt/garage
garage repair --all-nodes --yes tables
garage worker list
garage meta snapshot --all
nano compose.yaml
docker compose pull
docker compose up -d
garage status

compose.yaml içinde yalnızca imaj etiketini yeni sürüme çevirin. Devam etmeden önce garage worker list onarım işçilerini tamamlanmış göstermeli; sonrasında garage status yeni sürümü gösterir. Bir kümede düğümleri birer birer yükseltin. Ana sürüm yükseltmeleri (örneğin 2.x'ten gelecekteki bir 3.x'e) kesinti ve bir garage migrate adımı gerektirebilir; Garage belgelerindeki sürüme özel taşıma rehberini izleyin.

Sorun giderme

garage status, NO ROLE ASSIGNED gösteriyor

Düzen uygulanmamış; bu yüzden düğüm hiçbir şey saklamaz ve S3 istekleri başarısız olur. garage layout show çalıştırın, ardından önerdiği sürüm numarasıyla garage layout apply komutunu uygulayın.

AuthorizationHeaderMalformed veya bir bölge hatası

İstemci istekleri farklı bir bölge için, çoğunlukla us-east-1 için imzalıyor. İstemci yapılandırmasında bölgeyi garage (s3_region değeri) olarak ayarlayın.

backups.s3.example.com gibi adreslerde NoSuchBucket veya DNS hataları

İstemci virtual-host stilini kullanıyor ancak joker DNS kaydı veya sertifika yok. İstemciyi path-style kullanacak şekilde değiştirin (rclone'da force_path_style = true, AWS CLI yapılandırmasında addressing_style = path) veya Adım 6'da anlatıldığı gibi joker DNS kurun.

SignatureDoesNotMatch veya RequestTimeTooSkewed

Önce anahtar kimliğini ve gizli anahtarı kontrol edin. S3 imzaları bir zaman damgası da içerir; bu nedenle istemci veya sunucu saatinin birkaç dakika kayması her isteği bozar. timedatectl ile kontrol edin ve zaman eşitlemeyi açın. Garage'ın önündeki hiçbir proxy'nin Host başlığını yeniden yazmadığından emin olun.

Boş alan olmasına rağmen disk dolu görünüyor

ext4'te Garage'ın çok sayıdaki küçük blok dosyası alandan önce inode'ları tüketebilir. df -h ile df -i çıktılarını karşılaştırın. Düzendeki kapasiteyi düşürün, /var/lib/garage/data için ayrı bir XFS diski ekleyin veya daha büyük bir diske geçin.

Küme düğümleri birbirini görmüyor

3901/tcp portu düğümler arasında açık olmalı, rpc_secret hepsinde aynı olmalı ve rpc_public_addr her düğümün erişilebilir IP adresini içermelidir. garage status yalnızca bağlı düğümleri listeler.

Sonraki adımlar

• Uygulama yedeklerinizi bu bucket'a gönderin; örneğin Vaultwarden yedeklerini.
• Aynı Caddy kurulumunu Reverse proxy olarak Caddy rehberiyle daha fazla servis için kullanın.
• Compose dosyalarını Docker Compose temelleri rehberinde daha ayrıntılı öğrenin.
• Nesne depolama için sunucuları S3 depolama hosting sayfasında karşılaştırın.
• Yönetici API'si, statik web sitesi barındırma ve izleme için Garage belgelerini okuyun.