s3cmd را یک بار تنظیم کنید
s3cmd برای کارهای روزمرهٔ S3 ابزار سادهای است: اتصال در .s3cfg ثبت میشود و فایلها با آدرس s3://bucket/key شناسایی میشوند. این راهنما ابتدا تنظیم درست برای یک سرویس غیر AWS را میسازد، بعد با یک فایل کوچک همهٔ مجوزهای لازم را میسنجد.
فایل hello.txt روی سیستم شماست. آن را با نام tutorial/hello.txt در باکت خصوصی پارسپک میگذارید، وجودش را در فهرست چک میکنید، حجم و نوعش را بدون دانلود میخوانید، یک کپی روی دیسک خودتان میگیرید و در پایان از باکت برش میدارید.
مراحل را بهترتیب اجرا کنید. فرمان اول فقط اتصال را میسنجد؛ به همین دلیل، خطای Endpoint یا کلیدها با مشکل مسیر فایل قاطی نمیشود.
روش نصب را براساس سیستمعامل انتخاب کنید
روی Linux و macOS، نصب با pipx ابزار را از Python سیستم جدا نگه میدارد. برای اجرای موقت هم میتوانید از Docker استفاده کنید.
pipx انتخاب مناسبی است چون s3cmd را در محیطی جدا از Python سیستم نصب میکند. بستهٔ apt یا dnf هم قابل استفاده است، اما ممکن است از انتشار رسمی عقبتر باشد؛ پس بعد از نصب، نسخه را ببینید و مطمئن شوید تنظیم signature_v2 = False اعمال شده است.pipx install s3cmd
s3cmd --versionbrew install s3cmd
s3cmd --versionpy -m pip install --user s3cmd
s3cmd --versions3cmd شناخته نشد، یعنی پوشهٔ Scripts پایتون در PATH نیست. مسیر نصب را با py -m pip show -f s3cmd ببینید و همان پوشه را به PATH اضافه کنید. مسیر فایل تنظیمات روی ویندوز %USERPROFILE%\.s3cfg است، نه ~/.s3cfg.-v به کانتینر میدهید:docker run --rm -it \
-v "$PWD":/work -w /work \
python:3.12-slim \
sh -c "pip install --quiet s3cmd && s3cmd --config=/work/.s3cfg ls s3://c123456"حواستان باشد وقتی پوشهٔ کاری را به کانتینر میدهید، فایل .s3cfg با کلیدهای واقعی هم داخل همان پوشه است. آن پوشه را Commit نکنید.
فایل .s3cfg را برای پارسپک بسازید
این فایل هم کلیدها را نگه میدارد و هم نحوهٔ ساخت URL و امضا را مشخص میکند؛ بنابراین فقط جایگزینکردن Access Key و Secret Key کافی نیست.
s3cmd --configure یک ویزارد تعاملی است و در پایان فایل ~/.s3cfg را میسازد. ولی ویزارد همهٔ گزینههای لازم برای یک فضای غیر-آمازون را نمیپرسد؛ سادهتر این است که فایل را مستقیم بنویسید. توجه کنید که host_base فقط نام میزبان است، بدون https:// — پروتکل جداگانه با use_https تعیین میشود.[default]
access_key = YOUR_ACCESS_KEY
secret_key = YOUR_SECRET_KEY
host_base = c123456.parspack.net
host_bucket = c123456.parspack.net
bucket_location = us-east-1
use_https = True
signature_v2 = Falsehost_bucket تعیین میکند s3cmd آدرس درخواست را چطور بسازد و مهمترین سطر همین فایل است. اگر داخلش الگوی %(bucket)s نباشد — مثل نمونهٔ بالا — s3cmd نام باکت را در مسیر URL میگذارد (path-style)، یعنی https://c123456.parspack.net/نام-باکت/کلید. همین حالتی است که نمونهٔ rclone این مستندات هم استفاده میکند.اگر فرمانها خطای DNS یا NoSuchBucket دادند در حالی که نام باکت درست است، به احتمال زیاد باید حالت آدرسدهی را عوض کنید: host_bucket = %(bucket)s.c123456.parspack.net بگذارید تا s3cmd به virtual-host برگردد. یکی از این دو حالت روی هر فضای S3-سازگار جواب میدهد؛ اول path-style را امتحان کنید.
signature_v2 = False یعنی امضا با Signature V4 ساخته شود (پیشفرض نسخههای جدید، ولی نسخههای قدیمی V2 میساختند)، و bucket_location همان Region است — برای امضا استفاده میشود، نه برای جغرافیا. مگر پنل چیز دیگری گفته باشد، us-east-1 بگذارید.~/.s3cfg بگذارید، هر جای دیگری بسازیدش و مسیرش را به هر فرمان بدهید: s3cmd --config=./my.s3cfg .... اسکریپت نمونهٔ این صفحه، examples/s3cmd/run.sh، دقیقاً همین کار را میکند — یک فایل تنظیمات موقت از روی متغیرهای PARSPACK_S3_* میسازد و بعد از پایان کار پاکش میکند، پس فایل تنظیمات شخصی شما دست نمیخورد.فایل .s3cfg کلید مخفی شما را بهصورت متن ساده نگه میدارد. دسترسیاش را محدود کنید (chmod 600 ~/.s3cfg) و هیچوقت Commit نکنید.
فهرست Bucket را بهعنوان تست اتصال بگیرید
s3cmd ls s3://c123456
s3cmd ls را بدون آدرس بزنید.s3cmd ls s3://c123456آپلود: فایل را در باکت بگذارید
s3cmd put ./hello.txt s3://c123456/tutorial/hello.txt
/ تمام کنید (یعنی s3://c123456/tutorial/)، s3cmd نام فایل محلی را زیر همان مسیر تکرار میکند — نتیجه همان میشود، ولی وقتی میخواهید نام داخل باکت با نام محلی فرق کند باید نام کامل را بنویسید.printf 'hello ParsPack\n' > hello.txt
s3cmd put ./hello.txt s3://c123456/tutorial/hello.txtاگر tutorial/hello.txt از قبل وجود داشته باشد، آپلود جدید بدون هیچ سؤالی رویش مینویسد؛ نسخهٔ جداگانه ساخته نمیشود.
--mime-type=text/plain مقدار Content-Type را خودتان تعیین کنید؛ وگرنه s3cmd از پسوند فایل حدس میزند.s3cmd put --recursive ./dir/ s3://c123456/prefix/ کل یک پوشه را میفرستد.--multipart-chunk-size-mb عوض کنید.فهرست فایلها و مشخصات یک فایل
اول ببینید فایل در فهرست هست، بعد حجم و نوعش را بدون دانلود بخوانید.
ls روی یک مسیر که با / تمام میشود، فایلهای همان سطح را نشان میدهد. اگر خروجی خالی بود، یا آپلود انجام نشده یا مسیر را اشتباه نوشتهاید — این دو را با زدن ls روی یک سطح بالاتر از هم جدا کنید. برای دیدن همهٔ زیرمسیرها با هم --recursive اضافه کنید.s3cmd ls s3://c123456/tutorial/info را با مسیر دقیق فایل بزنید. این فرمان یک درخواست HEAD میفرستد: خود فایل دانلود نمیشود، فقط حجم، نوع، ETag و مجوزها برمیگردند.s3cmd info s3://c123456/tutorial/hello.txt/ یعنی «این سطح را فهرست کن»؛ بدون آن یعنی یک فایل دقیق.- و عدد بخشها دارد.info روی کلیدی که وجود ندارد، خطای Key not found میدهد؛ خروجی خالی نمیدهد.دانلود: فایل را روی سیستم خودتان بنویسید
s3cmd get s3://c123456/tutorial/hello.txt ./downloads/hello.txt
--force اضافه کنید. پوشهٔ مقصد باید از قبل وجود داشته باشد؛ s3cmd خودش نمیسازدش.mkdir -p downloads
s3cmd get s3://c123456/tutorial/hello.txt ./downloads/hello.txtلینک امضاشده: فقط دانلود، آن هم با یک محدودیت
s3cmd signurl s3://c123456/tutorial/hello.txt +900
+ یعنی «از الان چند ثانیه»؛ میتوانید یک timestamp مطلق هم بدهید.s3cmd signurl s3://c123456/tutorial/hello.txt +900دو نکته دربارهٔ همین یک خط: اول، AWSAccessKeyId و Signature بهجای X-Amz-Signature — یعنی signurl همیشه با Signature V2 امضا میکند، حتی وقتی signature_v2 = False گذاشتهاید. روی سرورهایی که فقط V4 را قبول میکنند این لینک با خطای امضا رد میشود. دوم، شِمای آدرس همیشه http:// است، حتی با use_https = True — این هم رفتار خود signurl است، نه اشتباه تنظیمات شما؛ روی Endpointـی مثل پارسپک که پورت ۸۰ باز نیست باید http:// را دستی به https:// عوض کنید (اسکریپت نمونهٔ این صفحه همین کار را خودکار انجام میدهد). اگر برنامهتان به لینک امضاشدهٔ مطمئن نیاز دارد، آن را با یکی از SDKها بسازید؛ بخش لینک امضاشده در صفحه S3 همین کار را در هشت زبان نشان میدهد.
حذف: نام را از باکت بردارید
s3cmd del s3://c123456/tutorial/hello.txt
del (یا هممعنیاش rm) دقیقاً همان یک کلید را حذف میکند. فایل روی سیستم شما دست نمیخورد. اگر کلید وجود نداشته باشد، s3cmd سکوت میکند و خطا نمیدهد.s3cmd del s3://c123456/tutorial/hello.txtپرچم --recursive را با احتیاط بزنید: s3cmd del --recursive s3://c123456/tutorial/ همهٔ فایلهای زیر آن مسیر را پاک میکند و برگشتی ندارد. برای دیدن اینکه چه چیزی حذف میشود، اول همان فرمان را با --dry-run بزنید.
خطا را دستهبندی کنید
اول فرمان فهرست Bucket را اجرا کنید. اگر آن هم خطا دارد، به جای بررسی فرمان فایل، Endpoint، روش آدرسدهی، Region و کلیدها را چک کنید.
--debug اضافه کنید. این پرچم هدرهای HTTP و رشتهٔ امضا را هم چاپ میکند — برای پیدا کردن مشکل امضا یا حالت آدرسدهی از همه مفیدتر است.| خطا | علت معمول | بررسی |
|---|---|---|
command not found: s3cmd | نصب انجام نشده یا مسیر نصب در PATH نیست | pipx list یا py -m pip show s3cmd |
SignatureDoesNotMatch | کلیدها اشتباهاند، یا نسخهٔ قدیمی s3cmd دارد V2 امضا میکند | access_key، secret_key، و signature_v2 = False |
NoSuchBucket یا خطای DNS | نام باکت غلط است، یا حالت آدرسدهی اشتباه است | host_bucket را بین path-style و %(bucket)s. عوض کنید |
AccessDenied | کلید به این باکت دسترسی ندارد | باکت را در پنل با همان کلید چک کنید |
Key not found | کلید در باکت وجود ندارد یا املایش فرق دارد | اول s3cmd ls روی مسیر پدر |
خطای مقصد در get | فایل مقصد از قبل هست، یا پوشهٔ مقصد وجود ندارد | --force اضافه کنید یا پوشه را با mkdir -p بسازید |
| Timeout / connection refused | Endpoint در دسترس نیست | host_base بدون https:// و بدون / انتها |
اجرای کامل همین سناریو
اگر خروجی هر فرمان شبیه نمونههای بالا بود، اتصال درست است و میتوانید مسیرها را با فایلهای واقعی خودتان عوض کنید.
pipx install s3cmd
cat > ~/.s3cfg <<'EOF'
[default]
access_key = YOUR_ACCESS_KEY
secret_key = YOUR_SECRET_KEY
host_base = c123456.parspack.net
host_bucket = c123456.parspack.net
bucket_location = us-east-1
use_https = True
signature_v2 = False
EOF
chmod 600 ~/.s3cfg
printf 'hello ParsPack\n' > hello.txt
mkdir -p downloads
s3cmd ls s3://c123456
s3cmd put ./hello.txt s3://c123456/tutorial/hello.txt
s3cmd ls s3://c123456/tutorial/
s3cmd info s3://c123456/tutorial/hello.txt
s3cmd get --force s3://c123456/tutorial/hello.txt ./downloads/hello.txt
s3cmd signurl s3://c123456/tutorial/hello.txt +900
s3cmd del s3://c123456/tutorial/hello.txtexamples/s3cmd/run.sh همین کارها را با قرارداد مشترک همهٔ نمونههای این مستندات انجام میدهد: پنج متغیر PARSPACK_S3_* را از محیط میخواند، یک فایل تنظیمات موقت میسازد و بعد از پایان پاکش میکند.examples/s3cmd/run.sh upload ./hello.txt tutorial/hello.txt
examples/s3cmd/run.sh list tutorial/
examples/s3cmd/run.sh head tutorial/hello.txt
examples/s3cmd/run.sh download tutorial/hello.txt ./downloaded.txt
examples/s3cmd/run.sh presign-get tutorial/hello.txt 900
examples/s3cmd/run.sh delete tutorial/hello.txtexamples/
├── .env.example
└── s3cmd/
└── run.sh # آپلود، فهرست، مشخصات، دانلود، لینک امضاشده و حذف با s3cmd