rclone: کپی، sync و مهاجرت فایل‌ها بین cloudها

rclone چیست، و در چه کاری خوب است

rclone یک برنامهٔ خط‌فرمان رایگان و open-source برای کپی، sync و انتقال فایل‌ها بین دیسک شما و ذخیره‌سازی ابری، یا بین دو cloud، است. اغلب «rsync برای ذخیره‌سازی ابری» نامیده می‌شود: یک باینری، نوشته‌شده با Go، که بیش از 70 backend ذخیره‌سازی را صحبت می‌کند، از جمله Amazon S3 و هر سرویس S3-compatible، Google Drive، OneDrive، Dropbox، Azure Blob، Backblaze B2، SFTP و WebDAV.

ایده‌ای که آن را مفید می‌کند remote است. هر حساب ذخیره‌سازی را یک‌بار توصیف می‌کنید، یک اسم کوتاه مثل s3old یا gdrive به آن می‌دهید، و از آن به بعد هر دستور به همان شکل روی هرکدام از آن‌ها کار می‌کند: rclone copy ./backups s3old:my-bucket/backups دقیقاً مثل rclone copy gdrive:Photos ./photos خوانده می‌شود. یک مسیر remote:path است، و برای object storage بخش اول مسیر همان bucket است.

در عمل rclone برای چهار کار استفاده می‌شود: بکاپ شبانه به object storage، مهاجرت‌های یک‌باره از یک provider به provider دیگر، درآوردن فایل‌ها از Google Drive یا دیگر cloudهای مصرفی، و mount کردن یک bucket طوری که مثل یک پوشهٔ local باشد. قبل از انتقال فایل‌ها را مقایسه می‌کند، پس یک اجرای دوم فقط چیزی را می‌فرستد که تغییر کرده، عملیات‌های ناموفق را retry می‌کند، و می‌تواند همه‌چیز را قبل از خروج از ماشین، سمت client رمزگذاری کند.

چیزی که نیست: یک client sync دوطرفه مثل برنامهٔ Dropbox (دستور جدیدتر bisync وجود دارد، اما یک ابزار عمدی است، نه یک سرویس پس‌زمینه)، یا یک برنامهٔ بکاپ با snapshotهای deduplicated. برای بکاپ‌های نسخه‌دار و deduplicated، ابزارهایی مثل restic از rclone به‌عنوان یک transport زیرشان استفاده می‌کنند.

نصب rclone روی لینوکس، macOS و ویندوز

rclone یک executable تکی بدون هیچ dependency است، پس نصبش بیشتر سوال این است که باینری از کجا می‌آید. پکیج‌های distro (apt install rclone) اغلب چند نسخه عقب‌ترند؛ برای هر چیزی که با APIهای ابری فعلی صحبت می‌کند، نسخهٔ رسمی را ترجیح دهید.

لینوکس و macOS: install script پروژه آخرین نسخه برای پلتفرم شما را دانلود می‌کند و آن را در /usr/bin (یا /usr/local/bin روی macOS) می‌گذارد. روی macOS، Homebrew هم کار می‌کند، اما build آن نمی‌تواند rclone mount را اجرا کند؛ اگر به mount نیاز دارید، باینری رسمی را به‌همراه macFUSE استفاده کنید.

ویندوز: winget install Rclone.Rclone سریع‌ترین راه است؛ Scoop و Chocolatey هم آن را دارند. بدون یک package manager، zip را از rclone.org/downloads دانلود کنید، rclone.exe را در پوشه‌ای مثل C:\rclone باز کنید، و آن پوشه را به PATH خود اضافه کنید. آن را از PowerShell یا cmd اجرا کنید؛ هیچ installer یا GUI مخصوص خودش ندارد. برای استفادهٔ rclone mount روی ویندوز به WinFsp هم نیاز دارید.

نتیجه را با rclone version بررسی کنید. یک باینری نصب‌شده از build رسمی می‌تواند بعداً خودش را با rclone selfupdate به‌روزرسانی کند؛ یک نسخهٔ پکیج‌شده باید از طریق package manager خودش به‌روز شود.

# Linux / macOS: official install script
sudo -v ; curl https://rclone.org/install.sh | sudo bash

# macOS with Homebrew (no rclone mount support)
brew install rclone

# Windows (PowerShell)
winget install Rclone.Rclone

# everywhere
rclone version

rclone config و مفهوم remote

rclone config یک ویزارد تعاملی شروع می‌کند: n برای یک remote جدید، یک اسم، نوع ذخیره‌سازی، بعد سوال‌هایی که آن نوع لازم دارد (کلیدها، endpoint، region، یا یک ورود مرورگری برای Google Drive و سرویس‌های OAuth دیگر). پاسخ‌ها در یک فایل INI معمولی نوشته می‌شوند، rclone.conf. rclone config file می‌گوید آن کجاست: معمولاً ~/.config/rclone/rclone.conf روی لینوکس و macOS، و %APPDATA%\rclone\rclone.conf روی ویندوز.

چون یک فایل متنی معمولی است، می‌توانید remoteها را دستی هم بنویسید، فایل را به یک سرور کپی کنید، یا آن را در ابزار secrets خودتان نگه دارید. آن را یک secret در نظر بگیرید: access keyها و OAuth tokenها را نگه می‌دارد. secretهایی که rclone خودش می‌نویسد فقط مبهم شده‌اند، نه رمزگذاری‌شده؛ rclone config اگر فایل باید روی یک ماشین مشترک بماند یک رمز configuration پیشنهاد می‌دهد.

هر [section] یک remote است. بعد با name: به‌همراه یک مسیر به آن آدرس می‌دهید. با object storage، تنها name: یعنی حساب، name:bucket یک bucket و name:bucket/prefix یک «پوشه» داخل آن. rclone lsd name: سریع‌ترین تست برای این است که کلیدها و endpoint کار می‌کنند.

فایل تنها راه نیست. هر گزینه می‌تواند از یک متغیر محیطی به نام RCLONE_CONFIG_<REMOTE>_<OPTION> بیاید، که برای containerها و CIای که ترجیح می‌دهید secretها را inject کنید تا یک فایل config بفرستید مناسب است.

دو remote در rclone.conf: AWS S3 و Google Drive

[s3old]
type = s3
provider = AWS
access_key_id = AKIA...
secret_access_key = ...
region = eu-central-1

[gdrive]
type = drive
scope = drive.readonly
token = {"access_token":"...","expiry":"..."}

# the same S3 remote from environment variables instead
# RCLONE_CONFIG_S3OLD_TYPE=s3
# RCLONE_CONFIG_S3OLD_PROVIDER=AWS
# RCLONE_CONFIG_S3OLD_ACCESS_KEY_ID=AKIA...

دستورهای اصلی، و copy در برابر sync

rclone copy فایل‌ها را از source به destination کپی می‌کند و فایل‌هایی که از قبل آنجا یکسانند را رد می‌کند. هیچ‌وقت چیزی را در destination حذف نمی‌کند، که آن را پیش‌فرض امن می‌کند.

rclone sync destination را دقیقاً مشابه source می‌کند، و این شامل حذف‌کردن فایل‌های destination که در source نیستند می‌شود. آن را به پوشهٔ غلط اشاره دهید، یا source و destination را جابه‌جا کنید، و داده حذف می‌شود، و object storage هیچ سطل زباله‌ای ندارد مگر اینکه versioning روشن باشد. همیشه اول یک دستور sync جدید را با --dry-run اجرا کنید، بخوانید چه چیزی را حذف می‌کرد، و فقط بعد آن را واقعاً اجرا کنید. --max-delete 100 یک کمربند ایمنی مفید برای jobهای زمان‌بندی‌شده است: اجرا به‌جای حذف‌کردن بیشتر از آن تعداد متوقف می‌شود.

rclone move کپی می‌کند و بعد هر فایل را از source، به‌محض رسیدن، حذف می‌کند؛ --delete-empty-src-dirs را اضافه کنید تا پوشه‌ها را هم تمیز کند. rclone check source و destination را مقایسه می‌کند و تفاوت‌ها را بدون تغییر چیزی گزارش می‌دهد (جلوتر بیشتر دربارهٔ آن).

برای نگاه‌کردن: rclone lsd remote: bucketها یا دایرکتوری‌ها را فهرست می‌کند، rclone ls remote:bucket هر object را با اندازه‌اش فهرست می‌کند، rclone lsf یک فهرست دوستانه با اسکریپت می‌دهد، و rclone size remote:bucket تعداد objectها و کل بایت‌ها را چاپ می‌کند، که اولین عددی است که بعد از یک مهاجرت مقایسه می‌کنید. rclone tree و rclone ncdu وقتی باید ببینید فضا کجا می‌رود کمک می‌کنند.

یک رفتار تقریباً همه را می‌لنگاند: مثل rsync با یک اسلش انتهایی، rclone محتوای دایرکتوری source را کپی می‌کند، نه خودِ دایرکتوری را. rclone copy ./photos remote:bucket فایل‌ها را در ریشهٔ bucket می‌گذارد؛ اگر پوشه را می‌خواهید remote:bucket/photos بنویسید. برای کپی یا تغییر‌نام یک فایل تکی، از copyto یا moveto استفاده کنید.

rclone lsd s3old:                       # buckets this key can see
rclone ls s3old:media/2026/             # objects and sizes
rclone size s3old:media                 # count + total bytes

rclone copy ./site s3old:media/site -P  # upload, never deletes
rclone sync ./site s3old:media/site --dry-run   # preview first
rclone sync ./site s3old:media/site -P  # then for real

rclone move ./outbox s3old:media/inbox --delete-empty-src-dirs
rclone copyto ./logo.png s3old:media/img/logo-v2.png

فلگ‌هایی که اهمیت دارند: dry run، سرعت و bandwidth

--dry-run (-n) نشان می‌دهد چه چیزی کپی یا حذف می‌شد بدون دست‌زدن به چیزی. --interactive (-i) قبل از هر اقدام مخرب می‌پرسد، که برای یک پاکسازی یک‌باره راحت است.

--progress (-P) throughput زنده، شمارش‌ها و ETA را نشان می‌دهد. برای jobهایی که بدون نظارت اجرا می‌شوند، به‌جایش --log-file rclone.log --log-level INFO استفاده کنید، تا بعداً بتوانید بخوانید چه اتفاقی افتاده.

--transfers (پیش‌فرض 4) تعداد فایل‌هایی است که موازی حرکت می‌کنند، و --checkers (پیش‌فرض 8) تعداد مقایسه‌هایی که موازی اجرا می‌شوند. object storage به‌ازای هر درخواست آهسته و در کل سریع است، پس فایل‌های کوچک زیاد از --transfers 16 تا 32 و --checkers 32 یا بیشتر سود می‌برند. آن‌ها را به‌تدریج بالا ببرید: providerها rate-limit می‌کنند، و درخواست‌های موازی زیاد به retry تبدیل می‌شوند.

--bwlimit bandwidth را سقف می‌گذارد، مثلاً --bwlimit 20M (بایت بر ثانیه، پس 20 MiB/s)، یا یک برنامهٔ زمانی مثل --bwlimit "08:00,10M 19:00,off" که در ساعات کاری throttle می‌کند و شب آزاد اجرا می‌شود.

--s3-chunk-size (پیش‌فرض 5 MiB) اندازهٔ part آپلودهای multipart را تنظیم می‌کند، و --s3-upload-concurrency (پیش‌فرض 4) تعداد partهای یک فایل که هم‌زمان آپلود می‌شوند. برای فایل‌های بزرگ روی یک لینک سریع، --s3-chunk-size 64M تعداد درخواست‌ها را به‌طور قابل‌توجهی کم می‌کند. استفادهٔ حافظه با transfers × upload-concurrency × chunk-size رشد می‌کند، پس یک chunk 64 MiB با 16 transfer می‌تواند چند گیگابایت RAM بگیرد. S3 حداکثر 10,000 part به‌ازای هر object اجازه می‌دهد؛ rclone وقتی اندازهٔ یک فایل را می‌داند خودش chunk size را بالا می‌برد، اما نه برای آپلودهای streamشده (rcat).

برای bucketهایی با میلیون‌ها object، --fast-list کل bucket را در درخواست‌های کمتر، به قیمت حافظه، فهرست می‌کند، و --checksum یا --size-only rclone را از خواندن زمان تغییر هر object باز می‌دارند، که روی S3 یک درخواست اضافه به‌ازای هر object هزینه دارد.

rclone copy /srv/backups s3old:backups/db \
  --transfers 16 --checkers 32 \
  --s3-chunk-size 64M --s3-upload-concurrency 4 \
  --bwlimit "08:00,20M 20:00,off" \
  --log-file /var/log/rclone-backup.log --log-level INFO

تنظیم یک remote سازگار با S3، با CDN.com.tr به‌عنوان مثال

هر سرویسی که API S3 را پیاده‌سازی کند از نوع s3 در rclone استفاده می‌کند. فیلدهایی که از provider به provider عوض می‌شوند provider، endpoint و بعضی وقت‌ها region هستند. وقتی rclone یکی دارد از provider نام‌گذاری‌شده استفاده کنید (AWS، Cloudflare، Minio، Wasabi و دیگران)؛ این ویژگی‌های آن سرویس خاص را روشن می‌کند. برای سرویسی که rclone فهرست نکرده، از provider = Other استفاده کنید.

object storage در CDN.com.tr سازگار با S3 است، و rclone یکی از clientهایی است که همان‌طور که هستند با آن کار می‌کند. endpoint https://s3.cdn.com.tr است؛ ابزارهایی که region می‌خواهند می‌توانند روی پیش‌فرض بمانند، و سرویس از path-style addressing انتظار دارد، که پیش‌فرض rclone برای provider = Other است. bucketها و access keyها در پنل (تب Access Keys) یا با cdnctl ساخته می‌شوند. secret key فقط یک‌بار، در زمان ساخت، نشان داده می‌شود، پس آن را مستقیم در config rclone یا secret manager خودتان کپی کنید.

کلیدها بهترین حالت را وقتی دارند که به bucketای که سرو می‌کنند scope شده باشند. کلیدی مثل این اجازهٔ ساختن bucket ندارد، پس به rclone بگویید سعی نکند: no_check_bucket = true بررسی ساخت bucket را که rclone معمولاً قبل از آپلود می‌کند رد می‌کند. به همان دلیل، یک کلید scope‌شده به یک bucket را با rclone lsd cdntr:my-bucket تست کنید نه با فهرست‌کردن کل حساب.

cdnctl اینجا control plane را مدیریت می‌کند: bucketها، کلیدها و اتصال‌ها به container appها. خواندن و نوشتن خودِ objectها کار یک client S3 مثل rclone است. (دستور جدای cdnctl cp به CDN file storage آپلود می‌کند، که یک محصول دیگر است؛ ببینید CDN file storage.)

rclone.conf: یک remote برای object storage در CDN.com.tr

[cdntr]
type = s3
provider = Other
access_key_id = <access key from the panel>
secret_access_key = <secret, shown once at creation>
endpoint = https://s3.cdn.com.tr
no_check_bucket = true

# test it
# rclone lsd cdntr:my-bucket
# rclone copy ./smoke.txt cdntr:my-bucket/ -v

مهاجرت بین providerها: R2، B2 یا AWS S3 به یک S3 دیگر

یک مهاجرت بین دو سرویس S3 یعنی دو remote و یک دستور. rclone هر دو طرف را فهرست می‌کند، آن‌ها را مقایسه می‌کند و هرچه گم است را کپی می‌کند، پس می‌توانید همان دستور را بارها اجرا کنید: اجرای اول حجم اصلی را منتقل می‌کند، اجراهای بعدی فقط تغییرات را، و اجرای نهایی در زمان cutover کوتاه است.

داده از ماشینی که rclone را اجرا می‌کند عبور می‌کند: از source دانلود می‌کند و به destination آپلود می‌کند. آن را روی سروری با bandwidth خوب به هر دو طرف اجرا کنید نه روی یک لپ‌تاپ، و اول قیمت‌گذاری egress provider source را بررسی کنید. AWS انتقال خروجی را صورتحساب می‌کند، Backblaze B2 egress رایگان تا چند برابر چیزی که ذخیره می‌کنید دارد، و Cloudflare R2 هیچ هزینه‌ای برای egress نمی‌گیرد. کپی سمت-سرور فقط داخل یک provider اتفاق می‌افتد.

تنظیماتی که مهاجرت‌های بزرگ را سریع‌تر و ارزان‌تر می‌کنند: --fast-list برای کم‌کردن درخواست‌های فهرست‌کردن، --checksum تا rclone اندازه‌ها و hashها را به‌جای گرفتن زمان تغییر هر object مقایسه کند، و --transfers و --checkers بالاتر اگر source اجازه می‌دهد. با copy شروع کنید، نه sync، تا یک اشتباه چیزی را حذف نکند؛ فقط برای آخرین pass، اگر objectهایی در این بین در source حذف شده‌اند، به sync (اول با --dry-run) سوئیچ کنید.

برای Backblaze B2 می‌توانید از نوع بومی b2 در rclone یا endpoint S3 خودِ B2 استفاده کنید؛ هر دو کار می‌کنند. کلیدهای R2 در داشبورد Cloudflare ساخته می‌شوند، و endpoint آن شناسهٔ حساب شما را دارد. صفحات مقایسهٔ ما این انتقال‌ها را با جزئیات توضیح می‌دهند: جایگزین Cloudflare R2، جایگزین Backblaze B2 و جایگزین IDrive e2. در سمت اپلیکیشن، تنها چیزهایی که عوض می‌شوند endpoint و کلیدها هستند.

# rclone.conf (source)
[r2]
type = s3
provider = Cloudflare
access_key_id = ...
secret_access_key = ...
endpoint = https://<ACCOUNT_ID>.r2.cloudflarestorage.com
region = auto

# 1. preview, 2. bulk copy, 3. repeat until the delta is small
rclone copy r2:media cdntr:media --dry-run
rclone copy r2:media cdntr:media \
  --fast-list --checksum --transfers 32 --checkers 64 -P

# cutover: stop writes, final pass, then compare
rclone sync r2:media cdntr:media --fast-list --checksum -P
rclone check r2:media cdntr:media --one-way

تایید یک مهاجرت با rclone check

rclone check source: dest: هر دو طرف را object به object مقایسه می‌کند و یک خلاصه چاپ می‌کند: چند فایل مطابقت دارند، چند تفاوت دارند، و کدام‌ها فقط در یک طرف وجود دارند. هیچ چیزی را تغییر نمی‌دهد. --one-way فقط به‌دنبال فایل‌های source می‌گردد که در destination گم یا متفاوت‌اند، که وقتی destination از قبل داده اضافه دارد همان چیزی است که می‌خواهید.

مقایسه از اندازه‌ها و، جایی که هر دو طرف یک نوع hash مشترک دارند، hashها استفاده می‌کند. روی S3 آن hash همان MD5 است، و اینجا نکته است: یک object که در چند part آپلود شده یک ETag دارد که MD5 آن نیست. rclone وقتی خودش فایل‌های multipart را آپلود می‌کند MD5 واقعی را در metadata آن object ذخیره می‌کند، اما objectهایی که ابزارهای دیگر نوشته‌اند اغلب این را ندارند، پس برای آن‌ها check فقط می‌تواند اندازه‌ها را مقایسه کند و در خروجی‌اش می‌گوید («hashes could not be checked»). وقتی به اطمینان byte-for-byte نیاز دارید، --download هر دو کپی را می‌خواند و محتوا را مقایسه می‌کند، به قیمت انتقال دوباره همه‌چیز.

برای گزارش‌هایی که می‌خواهید نگه دارید، فهرست‌ها را با --combined، --missing-on-dst و --differ در فایل‌ها بنویسید. rclone size را روی هر دو طرف به‌عنوان بررسی نهایی مقایسه کنید، و برای یک remote رمزگذاری‌شده از rclone cryptcheck استفاده کنید، که کپی رمزگذاری‌شده را در برابر source ساده بررسی می‌کند.

rclone size r2:media && rclone size cdntr:media

rclone check r2:media cdntr:media --one-way \
  --combined check-report.txt \
  --missing-on-dst missing.txt --differ differ.txt

# slow but exact: download and compare the bytes
rclone check r2:media cdntr:media --download

Google Drive، رمزگذاری و mount کردن، به‌طور خلاصه

Google Drive. در rclone config drive را انتخاب کنید، یک scope بگیرید (drive.readonly برای دانلود کافی است)، و دسترسی را در مرورگر تایید کنید. روی سروری بدون مرورگر، به auto config n جواب دهید و rclone authorize "drive" را روی ماشینی که مرورگر دارد اجرا کنید، بعد token را برگردانید. OAuth client داخلی rclone بین همهٔ کاربران مشترک است و rate-limit می‌شود؛ برای استفادهٔ سنگین، یک OAuth client خودتان در Google Cloud بسازید و در زمان راه‌اندازی وارد کنید. فایل‌های Google Docs فایل واقعی نیستند، پس rclone هنگام دانلود آن‌ها را export می‌کند (به docx، xlsx و مانند آن). Google همچنین آپلودها را به حدود 750 گیگابایت به‌ازای هر کاربر در روز محدود می‌کند، پس یک مهاجرت بزرگ *به داخل* Drive چند روز طول می‌کشد.

رمزگذاری. یک remote از نوع crypt یک remote دیگر را می‌پوشاند و محتوای فایل‌ها را، و به‌طور اختیاری اسم‌ها را، قبل از آپلود رمزگذاری می‌کند. آن را روی مثلاً cdntr:backups می‌سازید، بعد از طریق remote crypt می‌نویسید؛ provider فقط متن رمزشده را می‌بیند. رمز و salt در rclone.conf شما زندگی می‌کنند: اگر آن‌ها را گم کنید داده غیرقابل‌بازیابی است، پس آن‌ها را جدا از داده بکاپ بگیرید.

Mount کردن. rclone mount remote:bucket /mnt/bucket یک bucket را شبیه یک پوشه می‌کند (روی ویندوز، با WinFsp نصب‌شده به یک حرف درایو مثل X: mount کنید). --vfs-cache-mode writes یا full را اضافه کنید تا اپلیکیشن‌هایی که فایل‌ها را دوباره می‌نویسند درست کار کنند. یک mount برای مرور، کتابخانه‌های مدیا و خوانده‌های گاه‌به‌گاه خوب است؛ یک دیسک نیست، پس دیتابیس یا هر چیزی که به file locking نیاز دارد را روی آن نگذارید.

دانلود از Drive؛ یک remote رمزگذاری‌شده روی یک bucket اضافه کنید

rclone copy gdrive:Projects ./projects -P

# rclone.conf: encrypted backups inside an existing bucket remote
[secure]
type = crypt
remote = cdntr:backups/encrypted
filename_encryption = standard
password = <obscured by rclone config>
password2 = <obscured by rclone config>

rclone copy /srv/backups secure: -P

زمان‌بندی rclone: cron، systemd و Task Scheduler

rclone زمان‌بند مخصوص خودش را ندارد؛ باید توسط یکی اجرا شود. روی لینوکس، یک ورودی cron برای اکثر jobها کافی است. دستور را در flock بپیچید تا یک اجرای کند با اجرای بعدی overlap نشود، به یک فایل log کنید، و --config را به یک مسیر صریح اشاره دهید، چون cron با یک HOME متفاوت اجرا می‌شود و وگرنه remoteهای شما را پیدا نمی‌کند.

برای یک sync که حذف می‌کند، کمربندهای ایمنی اضافه کنید: --max-delete تا اجرایی که بسیار بیشتر از معمول حذف می‌کند متوقف شود، و --backup-dir تا فایل‌های overwrite و حذف‌شده را به‌جای گم‌کردن به یک پوشهٔ تاریخ‌دار منتقل کند. کد خروج rclone صفر در موفقیت و غیرصفر در شکست است، پس اسکریپت wrapper یا unit systemd می‌تواند هشدار بدهد؛ یک job که یک ماه است بی‌صدا شکست می‌خورد روش معمول خراب‌شدن بکاپ‌هاست.

روی ماشین‌های systemd، یک service به‌همراه یک timer logging در journal و Persistent=true می‌دهد، که یک job جامانده را بعد از reboot اجرا می‌کند. روی ویندوز، یک task در Task Scheduler بسازید که rclone.exe را با مسیر کامل config و یک فایل log اجرا می‌کند، زیر حسابی که به هم فایل‌ها و هم config دسترسی دارد.

# crontab -e  (02:30 every night)
30 2 * * * flock -n /tmp/rclone-backup.lock \
  rclone sync /srv/backups cdntr:backups/nightly \
  --config /home/backup/.config/rclone/rclone.conf \
  --max-delete 200 \
  --backup-dir cdntr:backups/deleted/$(date +\%F) \
  --log-file /var/log/rclone-backup.log --log-level INFO