MinIO'dan taşıma: rclone ile bucket'ları S3 uyumlu Object Storage'a kesintisiz aktarma ve doğrulama

MinIO topluluk sürümü bakım kipine geçtiğinden beri kendi sunucusunda MinIO çalıştıran birçok ekip aynı soruyu soruyor: Veriyi bozmadan ve uygulamayı uzun süre durdurmadan yönetilen bir S3 uyumlu depolamaya nasıl taşırım? Bu rehber sistem yöneticileri için yazıldı. rclone ile bucket'ları aşamalı kopyalamayı, aktarılan veriyi doğrulamayı ve geçiş gününü birkaç dakikalık yazma kesintisiyle tamamlamayı adım adım anlatıyor.

Taşıma kararını henüz vermediyseniz önce MinIO nedir ve topluluk sürümünün bakım kipine geçmesi ne anlama gelir yazısına bakın. Seçenekler orada karşılaştırılıyor. Bu yazı ise kararı vermiş olanlar için bir uygulama planı.

Ön koşullar

• MinIO sunucusuna erişebilen ve mc (MinIO Client) kurulu bir Linux makinesi. Kaynak ve hedefe aynı anda erişebilmesi gerekir.
• Bu makinede güncel bir rclone. Dağıtım paketleri çoğu zaman eski kalır. Resmi kurulum yöntemi rclone belgelerinin kurulum (install) sayfasında anlatılıyor. Kurulumdan sonra rclone version ile sürümü kontrol edin.
• MinIO tarafında en az okuma yetkisi olan bir erişim anahtarı. Envanter için admin yetkisi de gerekir.
• Hedef S3 uyumlu depolamanın endpoint adresi, bölge (region) bilgisi ve yazma yetkili bir erişim anahtarı.
• jq paketi (envanter betiği için).

Aktarımı çalıştıracağınız makineyi ağ açısından iyi seçin, çünkü bütün veri bu makineden geçer: kaynaktan indirilir, hedefe yüklenir. Genellikle en hızlı seçenek MinIO sunucusunun kendisi ya da aynı ağdaki bir makinedir.

1. Taşıma öncesi MinIO envanteri

rclone nesneleri taşır, MinIO'nun yönetim katmanını taşımaz. Kullanıcılar, politikalar, bucket politikaları, yaşam döngüsü (ILM) kuralları, olay bildirimleri ve eski nesne sürümleri hedefte kendiliğinden oluşmaz. Bu yüzden önce elinizde ne olduğunu yazıya dökün.

Aşağıdaki betik Ubuntu 24.04 ve Debian 12 için hazırlandı. Yalnız okuma yapar, MinIO'da hiçbir şeyi değiştirmez. Geri alınacak bir şey bırakmaz; oluşan metin dosyasını silmeniz yeterlidir. Betik, eski adlı bir mc alias'ının önceden tanımlandığını varsayar:

#!/usr/bin/env bash
# MinIO envanter betiği: yalnız okur, değişiklik yapmaz.
# Önce alias tanımlayın (bir kez):
#   mc alias set eski https://192.0.2.10:9000 ORNEK_ERISIM_ANAHTARI ORNEK_GIZLI_ANAHTAR
set -euo pipefail

ALIAS="eski"                                   # mc alias adı
CIKTI="minio-envanter-$(date +%Y%m%d).txt"     # rapor dosyası

{
  echo "== Bucket listesi =="
  mc ls "$ALIAS"

  echo "== Kullanıcılar =="
  mc admin user list "$ALIAS" || echo "admin yetkisi yok, atlandı"

  echo "== Politikalar =="
  mc admin policy list "$ALIAS" || echo "admin yetkisi yok, atlandı"

  # Her bucket için boyut, nesne sayısı, sürümleme, anonim erişim, ILM ve olaylar
  for b in $(mc ls --json "$ALIAS" | jq -r '.key' | sed 's#/$##'); do
    echo "== Bucket: $b =="
    mc du "$ALIAS/$b"                    # toplam boyut ve nesne sayısı
    mc version info "$ALIAS/$b" || true  # sürümleme açık mı
    mc anonymous get "$ALIAS/$b" || true # herkese açık erişim var mı
    mc ilm rule ls "$ALIAS/$b" || true   # yaşam döngüsü kuralları
    mc event ls "$ALIAS/$b" || true      # olay bildirimleri
  done
} | tee "$CIKTI"

Rapor elinize geçince her bucket için şu dört soruyu yanıtlayın:

1. Boyut ve nesne sayısı: Birkaç yüz bin nesneye kadar düz rclone sync yeterlidir. Milyonlarca nesne varsa 4. adımdaki liste karşılaştırmalı yöntemi planlayın.
2. Sürümleme: rclone varsayılan olarak her nesnenin yalnız güncel sürümünü kopyalar. Eski sürümleri hukuki ya da iş gereği saklamanız gerekiyorsa bunun için ayrı karar verin: ya eski MinIO'yu arşiv olarak tutarsınız ya da gerekli sürümleri ayrıca dışa aktarırsınız.
3. Anonim erişim: Herkese açık okunan bucket'lar var mı? Hedef depolama bucket'ları varsayılan olarak kapalı tutuyorsa paylaşım yöntemini (imzalı URL, uygulama üzerinden sunma) önceden değiştirin.
4. Uygulama kullanıcıları: Hangi uygulama hangi anahtarla hangi bucket'a yazıyor? Hedefte her uygulama için ayrı ve yalnız kendi bucket'ını gören bir anahtar oluşturun.

2. rclone'da MinIO ve hedef S3 remote tanımı

rclone'da her depolama bir "remote"tur. MinIO için provider=Minio, genel S3 uyumlu hedef için provider=Other kullanılır. MinIO path-style adreslemeyle çalışır; rclone S3 backend'inde bu varsayılan olarak açıktır.

Aşağıdaki betik Ubuntu 24.04 ve Debian 12 için hazırlandı. Anahtarları komut satırına yazmak yerine gizli girişle okur, böylece kabuk geçmişinde kalmazlar. Betik tekrar çalıştırılabilir: remote varsa günceller, yoksa oluşturur. Geri almak için rclone config delete minio ve rclone config delete hedef yeterlidir.

#!/usr/bin/env bash
# rclone remote tanımı: minio (kaynak) ve hedef (S3 uyumlu depolama)
set -euo pipefail

KAYNAK_ENDPOINT="https://192.0.2.10:9000"   # MinIO adresiniz
HEDEF_ENDPOINT="https://s3.example.com"     # hedef depolama endpoint'i
HEDEF_BOLGE="ORNEK_BOLGE"                   # sağlayıcının verdiği region değeri

read -rp  "MinIO erişim anahtarı: " K_KEY
read -rsp "MinIO gizli anahtar: "   K_SECRET; echo
read -rp  "Hedef erişim anahtarı: " H_KEY
read -rsp "Hedef gizli anahtar: "   H_SECRET; echo

tanimla() {
  # $1 remote adı, sonrası anahtar=değer çiftleri
  local ad="$1"; shift
  if rclone listremotes | grep -qx "${ad}:"; then
    rclone config update "$ad" "$@" >/dev/null
  else
    rclone config create "$ad" s3 "$@" >/dev/null
  fi
}

tanimla minio provider=Minio env_auth=false \
  access_key_id="$K_KEY" secret_access_key="$K_SECRET" \
  endpoint="$KAYNAK_ENDPOINT"

tanimla hedef provider=Other env_auth=false \
  access_key_id="$H_KEY" secret_access_key="$H_SECRET" \
  endpoint="$HEDEF_ENDPOINT" region="$HEDEF_BOLGE"

# Bağlantı testi: iki tarafın da bucket listesi gelmeli
rclone lsd minio:
rclone lsd hedef:

Beklenen çıktı, her iki remote için bucket adlarının listelenmesidir. SignatureDoesNotMatch hatası alırsanız ilk bakacağınız yer region değeridir. x509 sertifika hatası alırsanız MinIO'nun kendinden imzalı sertifika kullanıp kullanmadığını kontrol edin. Sertifika doğrulamasını kapatmak yerine CA dosyasını --ca-cert ile verin.

Hedefte bucket yoksa oluşturun: rclone mkdir hedef:BUCKET_ADI. Anahtarınızın bucket oluşturma yetkisi yoksa bucket'ı panelden açın ve aktarım komutlarına --s3-no-check-bucket ekleyin.

3. İlk eşitleme: rclone sync, --checksum ve paralellik ayarları

İlk geçişte amaç, verinin büyük kısmını uygulama çalışırken taşımaktır. Uygulama bu sırada MinIO'ya yazmaya devam eder; aradaki farkı sonraki turlar kapatır.

Önce mutlaka --dry-run ile deneyin. sync hedefi kaynağa eşitler, yani hedefte fazla olanı siler. Kaynak ile hedefin yerini yanlışlıkla değiştirirseniz silinen taraf MinIO olur. Bu yüzden ilk turlarda copy kullanmak daha güvenlidir. sync'i son turda, dry-run çıktısını okuduktan sonra çalıştırın.

# Kaynak: minio, hedef: hedef. Sıra her zaman "kaynak hedef" şeklindedir.
BUCKET="BUCKET_ADI"

# 1) Deneme: ne kopyalanacağını gösterir, hiçbir şey yazmaz
rclone copy "minio:$BUCKET" "hedef:$BUCKET" --dry-run --fast-list

# 2) Gerçek ilk kopya
rclone copy "minio:$BUCKET" "hedef:$BUCKET" \
  --checksum \
  --metadata \
  --fast-list \
  --transfers 16 \
  --checkers 32 \
  --s3-upload-concurrency 4 \
  --retries 5 --low-level-retries 20 \
  --stats 1m --log-level INFO \
  --log-file "rclone-$BUCKET-ilk.log"

Bayrakların ne işe yaradığı:

• --checksum: Karşılaştırmayı değişiklik zamanı yerine boyut ve MD5 ile yapar. S3'te değişiklik zamanını okumak nesne başına ek istek demektir. Checksum karşılaştırması hem daha doğru hem de genellikle daha hızlıdır.
• --metadata: Content-Type dışındaki kullanıcı metadata'sını da taşır. Uygulamanız x-amz-meta-* başlıklarına güveniyorsa bu bayrak gerekir.
• --fast-list: Listeyi daha az API çağrısıyla alır ama tüm listeyi belleğe yükler. rclone belgeleri nesne başına yaklaşık 1 KB bellek kullanımından söz eder. Birkaç milyon nesnede bu birkaç GB eder; makinenizin belleğini buna göre değerlendirin.
• --transfers ve --checkers: Aynı anda kaç dosyanın aktarılacağını ve karşılaştırılacağını belirler. Küçük dosyalar çoğunluktaysa bu değerleri artırmak hızı belirgin biçimde yükseltir. Büyük dosyalarda ise sınırı bant genişliği belirler. 16 ile başlayın, --stats çıktısındaki hız artmayı bırakınca durun. Hedef SlowDown ya da 503 döndürmeye başlarsa değeri düşürün.

Bir uyarı: Çok parçalı (multipart) yüklenmiş nesnelerin ETag değeri MD5 değildir. rclone kendi yüklediği büyük dosyalara MD5'i metadata olarak ekler. Ancak başka bir istemcinin MinIO'ya multipart olarak yüklediği nesnelerde MD5 bulunmayabilir. Bu nesnelerde rclone yalnız boyutu karşılaştırır. Doğrulama adımında bu durumu ayrıca ele alacağız.

Tüm bucket'lar için aynı komutu döngüyle çalıştırabilirsiniz. Yine de ilk seferde bucket'ları birer birer çalıştırıp log'u okumak hataları erken görmenizi sağlar.

4. Milyonlarca nesnede liste karşılaştırmalı kopyalama

On milyonlarca nesne içeren bir bucket'ta her sync turu iki tarafı baştan listeler. Bu hem saatler sürer hem de bellek sorunu çıkarabilir. rclone forumunda büyük MinIO kurulumları için önerilen yöntem şudur: listeleri bir kez dosyaya alın, farkı kabukta hesaplayın ve yalnız eksikleri kopyalayın.

Aşağıdaki komutlar Ubuntu 24.04 ve Debian 12 için hazırlandı. Yalnız liste dosyaları üretir ve hedefe kopyalama yapar, hiçbir şey silmez. Geri almak için oluşan .txt dosyalarını silmeniz yeterlidir.

BUCKET="BUCKET_ADI"
export LC_ALL=C   # sort ve comm aynı sıralamayı kullansın

# Yol ve boyut listesi; ayraç olarak | kullanılır
rclone lsf -R --files-only --fast-list --format "ps" --separator "|" \
  "minio:$BUCKET" | sort > kaynak.txt
rclone lsf -R --files-only --fast-list --format "ps" --separator "|" \
  "hedef:$BUCKET" | sort > hedef.txt

# Kaynakta olup hedefte olmayan ya da boyutu farklı olan satırlar
comm -23 kaynak.txt hedef.txt | cut -d'|' -f1 > eksik.txt
wc -l kaynak.txt hedef.txt eksik.txt

# Yalnız eksikleri kopyala; hedefi yeniden listelemez
rclone copy "minio:$BUCKET" "hedef:$BUCKET" \
  --files-from-raw eksik.txt --no-traverse \
  --checksum --metadata --transfers 32 --checkers 32 \
  --log-level INFO --log-file "rclone-$BUCKET-eksik.log"

--files-from-raw satır başındaki # karakterini yorum saymaz. Nesne adlarında bu karakter bulunabileceği için düz --files-from yerine bunu kullanın. Adında | geçen nesneler varsa farklı bir ayraç seçin.

Bu yöntemi bucket'ı ön eklere (prefix) bölerek paralel de çalıştırabilirsiniz. Örneğin minio:$BUCKET/2024 ve minio:$BUCKET/2025 için ayrı süreçler başlatırsınız. Her süreç kendi listesini tutar, böylece bellek tüketimi bölünür.

5. Doğrulama: rclone check ile karşılaştırma

Kopyalamanın "başarılı" görünmesi yeterli değildir. Her bucket için iki tarafı ayrıca karşılaştırın:

BUCKET="BUCKET_ADI"
rclone check "minio:$BUCKET" "hedef:$BUCKET" \
  --one-way --fast-list \
  --combined "fark-$BUCKET.txt"
echo "çıkış kodu: $?"

# Özet: işaretlere göre satır sayısı
cut -c1 "fark-$BUCKET.txt" | sort | uniq -c

--combined dosyasındaki işaretlerin anlamı şöyledir: = iki tarafta aynı, + yalnız kaynakta (hedefte eksik), * iki tarafta var ama farklı, ! okuma ya da hash hatası. --one-way hedefte fazladan nesne olup olmadığına bakmaz, çünkü taşımada önemli olan kaynaktaki her şeyin hedefte bulunmasıdır. Çıkış kodu 0 ise fark yoktur.

Kabul ölçütünüz şu olsun: +, * ve ! satır sayısı sıfır. Ayrıca mc du ile aldığınız nesne sayısı ve toplam boyut, hedefteki rclone size hedef:BUCKET_ADI çıktısıyla aynı olmalı.

MD5'i bulunmayan multipart nesnelerde rclone check yalnız boyutu karşılaştırır ve bunu log'a uyarı olarak yazar. Kritik bucket'larda bu açığı kapatmak için bir ön ek üzerinde --download bayrağıyla bayt bayt karşılaştırma yapın. Bu bayrak her iki taraftan veriyi indirdiği için tüm bucket'ta pahalıdır; örneklem olarak kullanın. Bayrakların tam listesini rclone check --help çıktısında görebilirsiniz.

6. Geçiş günü: son delta ve endpoint değişikliği

İlk kopya ve birkaç delta turu bittiğinde kaynak ile hedef arasında yalnız son birkaç saatte yazılan nesneler fark olarak kalır. Geçiş günü sırası:

1. Yazmaları durdurun. Uygulamayı bakım kipine alın ya da yalnız dosya yükleme özelliğini kapatın. Okumalar devam edebilir.
2. Son deltayı alın. Küçük bucket'larda önce --dry-run ile, ardından gerçek rclone sync çalıştırın. Bu tur, kaynakta silinmiş nesneleri hedeften de kaldırır. Büyük bucket'larda 4. adımdaki liste yöntemini tekrar çalıştırın; bu turun süresini artık büyük ölçüde listeleme belirler.
3. Doğrulamayı tekrarlayın. rclone check çıkış kodu 0 olmadan devam etmeyin.
4. Uygulama ayarlarını değiştirin. Endpoint, erişim anahtarı, gizli anahtar ve region değerini yeni depolamaya göre güncelleyin. SDK'nız virtual-hosted adreslemeye ayarlıysa ve hedef path-style bekliyorsa (ya da tersi) bucket bulunamaz. AWS SDK'larında bu ayar forcePathStyle ya da addressing_style adını taşır.
5. Yazmaları açın ve izleyin.

İlk saatlerde uygulama log'larındaki 403 ve 404 yanıtlarını sayın. Örneğin uygulama log'u tek bir dosyadaysa:

# Son 1.000 satırdaki S3 kaynaklı hata kodlarını say (log yolunu kendi uygulamanıza göre değiştirin)
tail -n 1000 /var/log/ORNEK_UYGULAMA/app.log | grep -oE '(AccessDenied|SignatureDoesNotMatch|NoSuchBucket|NoSuchKey)' | sort | uniq -c

Hataların anlamı genellikle şöyledir:

• 403 AccessDenied: Yeni anahtarın ilgili bucket'a yetkisi eksik ya da yanlış anahtar kullanılıyor.
• 403 SignatureDoesNotMatch: Region uyuşmuyor, sistem saati kaymış ya da gizli anahtar yanlış kopyalanmış.
• 404 NoSuchBucket: Bucket adı farklı ya da adresleme biçimi (path-style, virtual-hosted) yanlış.
• 404 NoSuchKey: Nesne gerçekten eksik. Son delta ile geçiş arasında yazılmış bir nesne olabilir; rclone check sonucuna dönün.

Geri dönüş planınızı hazır tutun. Sorun çözülemezse uygulamayı eski ayarlara çevirirsiniz ve geçişten sonra yeni depolamaya yazılmış nesneleri rclone copy hedef:BUCKET_ADI minio:BUCKET_ADI ile MinIO'ya geri taşırsınız. Bu yüzden MinIO'yu geçiş günü kapatmayın.

7. Eski MinIO'yu salt okunur tutma ve kapatma

Geçişten sonra MinIO'yu birkaç hafta salt okunur tutun. Böylece unutulmuş bir cron işi, eski ayarla çalışan bir sunucu ya da eski bir mobil uygulama sürümü yazmaya çalıştığında hata alır ve bunu fark edersiniz.

Uygulama kullanıcısının yazma yetkisini kaldırıp okuma yetkisi vermek için:

# Geri almak için attach ve detach komutlarının yerini değiştirmeniz yeterlidir
mc admin policy detach eski readwrite --user ORNEK_UYGULAMA_KULLANICISI
mc admin policy attach eski readonly  --user ORNEK_UYGULAMA_KULLANICISI

Bu dönemde mc admin trace eski ile MinIO'ya gelen istekleri izleyin. PutObject ya da DeleteObject çağrısı görüyorsanız kaynağını bulmadan kapatmaya geçmeyin. Okuma istekleri de sürüyorsa hangi istemciden geldiğini not edin, çünkü bunlar da eski ayarla çalışan sistemlerdir.

Birkaç hafta boyunca hiç istek gelmiyorsa servisi durdurun ve açılışta başlamasını engelleyin: sudo systemctl stop minio ve sudo systemctl disable minio. Diskleri ve veriyi hemen silmeyin. Sürümleme ya da arşiv gereği bekleyen bir şey kalmadığında ve yeni depolamanın yedeği de çalıştığında, saklama süreniz dolunca diskleri kurum prosedürünüze göre temizleyin. Yeni bucket'ların ayrı yedeğini almak için S3 yedekleme rehberindeki rclone ve restic adımlarını kullanabilirsiniz.

Sık yapılan hatalar

• Kaynak ve hedefi ters yazmak. rclone sync hedef: minio: MinIO'yu boş hedefe eşitler. Her sync öncesinde --dry-run çalıştırın ve silinecek nesne sayısına bakın.
• Yalnız nesneleri taşıyıp politikaları unutmak. Anahtarlar, bucket politikaları, ILM kuralları ve olay bildirimleri taşınmaz. Envanter raporunu kontrol listesi olarak kullanın.
• Sürümlemeyi atlamak. Hedefe yalnız güncel sürümler gelir. Eski sürümlere ihtiyaç varsa bu kararı taşımadan önce verin.
• Paralelliği körlemesine artırmak. Çok yüksek --transfers değeri hedefin sizi kısıtlamasına (throttling) yol açar ve toplam süreyi uzatır. Hızı --stats ile ölçerek artırın.
• --fast-list ile belleği bitirmek. Çok büyük bucket'larda süreç bellek yetersizliğinden kapanabilir. Bucket'ı ön eklere bölün ya da liste yöntemine geçin.
• Doğrulamayı yalnız log'a bakarak yapmak. "0 hata" yazan bir log satırı, eksik nesne olmadığını kanıtlamaz. rclone check ve nesne sayısı karşılaştırması şarttır.
• Region ve saat ayarı. İmza hatalarının büyük kısmı yanlış region ya da senkronize olmayan sistem saatinden çıkar. timedatectl çıktısında saat senkronizasyonunun açık olduğunu kontrol edin.

Sık sorulan sorular

Taşıma sırasında uygulama MinIO'yu kullanmaya devam edebilir mi?

Evet. İlk kopya ve delta turları uygulama çalışırken yapılır. Yazmaları yalnız geçiş gününde, son delta ve doğrulama süresince durdurursunuz. Bu sürenin uzunluğu, son turda listelenen ve kopyalanan nesne sayısına bağlıdır.

rclone sync ile rclone copy arasındaki fark nedir, hangisini kullanmalıyım?

copy yalnız ekler ve günceller, hedefte hiçbir şey silmez. sync ise hedefi kaynağın birebir kopyası yapar ve kaynakta olmayanı hedeften siler. İlk turlarda copy kullanın. Kaynakta silinen nesnelerin de hedefe yansıması gereken son turda, --dry-run ile denediğiniz sync'i çalıştırın.

MinIO'daki nesne sürümleri ve metadata taşınır mı?

Content-Type her durumda taşınır, kullanıcı metadata'sı ise --metadata bayrağıyla taşınır. Nesnelerin eski sürümleri varsayılan olarak taşınmaz; rclone yalnız güncel sürümü kopyalar. Eski sürümler gerekiyorsa MinIO'yu arşiv olarak tutmanız ya da sürümleri ayrıca dışa aktarmanız gerekir.

Milyonlarca küçük dosyada aktarım neden yavaş?

Küçük dosyalarda darboğaz bant genişliği değil, nesne başına yapılan API çağrılarıdır. --transfers ve --checkers değerlerini artırın, --checksum kullanın. Her turda iki tarafı yeniden listelemek yerine 4. adımdaki liste karşılaştırma yöntemine geçin.

Hedef depolama olarak neye bakmalıyım?

Temel ölçütler şunlardır: S3 API uyumluluğu, path-style desteği, bucket başına erişim anahtarı, verinin tutulduğu lokasyon ve trafik ücretlendirmesi. Verinin Türkiye'de kalması gerekiyorsa İstanbul lokasyonlu, sabit aylık paketli ve indirme trafiği dahil S3 uyumlu Object Storage seçeneğini değerlendirebilirsiniz.

Sonuç

MinIO'dan taşıma, adımları doğru sırayla uyguladığınızda riskli bir iş değildir. Önce envanter çıkarın, ardından rclone remote'larını tanımlayın. İlk kopyayı copy ve --checksum ile alın, büyük bucket'larda liste karşılaştırmasına geçin. Her turdan sonra rclone check ile doğrulayın. Geçiş gününde yalnız son deltayı alıp endpoint'i değiştirin. Eski MinIO'yu kapatmadan önce birkaç hafta salt okunur tutup gelen istekleri izleyin. Seçeneklerin ve bayrakların tam listesi rclone'un S3 backend belgesinde yer alır; aynı bilgiye rclone help backend s3 komutuyla da ulaşabilirsiniz.