AWS CLI v2 · ابزار رسمی AWS
AWS CLI را به مقصد درست بفرستید
برای استفاده از AWS CLI روی پارسپک، باید آدرس مقصد را صریحاً با --endpoint-url مشخص کنید و روش آدرسدهی S3 را روی path-style بگذارید. بعد از این دو تنظیم، فرمانهای معمول aws s3 و aws s3api بدون تغییر مفهومی کار میکنند.
Docker یا نصب مستقیم
آزمون را با یک فایل کوچک و قابل حذف انجام میدهیم: hello.txt با کلید tutorial/hello.txt آپلود میشود؛ سپس فهرست، مشخصات، دانلود و لینک موقت را امتحان میکنید و در پایان فایل آزمایشی را پاک میکنید.
اگر --endpoint-url را جا بیندازید، AWS CLI درخواست را به سرورهای واقعی آمازون میفرستد و با خطای دسترسی یا باکت ناموجود برمیگردد — نه به فضای ابری شما.
۱
روش اجرا را براساس نوع استفاده انتخاب کنید
برای استفادهٔ همیشگی، نصب مستقیم راحتتر است. برای یک تست موقت یا محیط CI، تصویر رسمی amazon/aws-cli از تغییر سیستم میزبان جلوگیری میکند.
در حالت Docker، سه چیز را به کانتینر میدهید: پوشهٔ کاری (تا فایلهای آپلود و دانلود در دسترس باشند) و کلیدها بهصورت متغیر محیطی. توجه کنید که
ENTRYPOINT این تصویر خودِ aws است، پس مستقیم زیرفرمان را مینویسید، نه کلمهٔ aws را دوباره.بدون نصب · Docker
docker run --rm -it \
-v "$PWD":/aws -w /aws \
-e AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY \
-e AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY \
-e AWS_DEFAULT_REGION=us-east-1 \
amazon/aws-cli \
--endpoint-url https://c123456.parspack.net s3 ls s3://c123456اگر میخواهید هر بار این همه ننویسید، یک alias در شل خودتان بسازید تا
aws همان فرمان Docker باشد. برای نصب مستقیم، از نصبکنندهٔ رسمی نسخهٔ ۲ استفاده کنید — نسخهٔ ۱ که هنوز در بعضی مخزنهای توزیع هست، دیگر توصیه نمیشود.Linux · نصبکنندهٔ رسمی v2
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o awscliv2.zip
unzip awscliv2.zip
sudo ./aws/install
aws --versionmacOS · بستهٔ رسمی pkg
curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg"
sudo installer -pkg AWSCLIV2.pkg -target /
aws --versionWindows · PowerShell با msi
msiexec.exe /i https://awscli.amazonaws.com/AWSCLIV2.msi
aws --versionخروجی
aws --version باید با aws-cli/2. شروع شود. اگر عدد ۱ دیدید، نسخهٔ قدیمی از پکیج توزیع در PATH جلوتر است.۲
مشخصات اتصال را از دادهٔ فرمان جدا نگه دارید
کلیدها و Region را از محیط بخوانید، Endpoint را صریح به فرمان بدهید و نام Bucket را در آدرس یا پارامتر --bucket بنویسید.
terminal · کلیدها و Region
export AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY
export AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
export AWS_DEFAULT_REGION=us-east-1راه دیگر،
aws configure است که همین مقدارها را در ~/.aws/credentials و ~/.aws/config ذخیره میکند. اگر از AWS واقعی هم استفاده میکنید، پارسپک را در یک Profile جدا بگذارید تا با هم قاطی نشوند: aws configure --profile parspack و بعد --profile parspack روی هر فرمان.حالا مهمترین تنظیم: حالت آدرسدهی. AWS CLI بهصورت پیشفرض سراغ آدرسهای virtual-host میرود، یعنی نام باکت را جلوی نام دامنه میچسباند (
bucket.c123456.parspack.net). چنین نامی لزوماً در DNS وجود ندارد. با تنظیم زیر، نام باکت به مسیر URL منتقل میشود — همان حالتی که نمونهٔ rclone این مستندات هم استفاده میکند:terminal · اجباری کردن path-style
aws configure set default.s3.addressing_style pathاین یک بلوک به
~/.aws/config اضافه میکند. اگر نمیخواهید فایل تنظیمات شخصیتان دست بخورد — مثلاً در CI یا داخل کانتینر — همان بلوک را در یک فایل جدا بنویسید و مسیرش را با متغیر AWS_CONFIG_FILE بدهید. اسکریپت نمونهٔ examples/awscli/run.sh دقیقاً همین کار را میکند.فایل تنظیمات جدا
cat > ./aws-parspack.conf <<'EOF'
[default]
s3 =
addressing_style = path
EOF
export AWS_CONFIG_FILE=./aws-parspack.confدر ادامهٔ این صفحه،
--endpoint-url https://c123456.parspack.net روی همهٔ فرمانها تکرار شده تا هر فرمان بهتنهایی قابل کپی باشد. اگر نسخهٔ AWS CLI شما ۲.۱۳ یا بالاتر است، میتوانید یک بار export AWS_ENDPOINT_URL=https://c123456.parspack.net بزنید و دیگر آن پرچم را ننویسید.پرچم --endpoint-url را جا نیندازید. بدون آن، فرمان به سرورهای واقعی آمازون میرود؛ در بهترین حالت خطا میگیرید و در بدترین حالت — اگر حساب AWS فعالی هم دارید — روی باکت اشتباهی عمل میکنید.
۳
Endpoint و کلیدها را با فهرست Bucket بیازمایید
aws --endpoint-url https://c123456.parspack.net s3 ls s3://c123456
این فرمان محتوای سطح بالای باکت را نشان میدهد و هنوز کاری با فایل شما ندارد. اگر Endpoint یا کلیدها اشتباه باشند، همینجا خطا میگیرید. برای فهرست خود باکتها،
s3 ls را بدون آدرس بزنید.terminal
aws --endpoint-url https://c123456.parspack.net s3 ls s3://c123456خروجی نمونه
PRE tutorial/
۴
آپلود: فایل را در باکت بگذارید
aws s3 cp ./hello.txt s3://c123456/tutorial/hello.txt
فرمان
aws s3 cp شبیه cp سیستمعامل است، فقط یک سمتش میتواند آدرس s3:// باشد. مقصد را با نام کامل فایل بنویسید؛ اگر با / تمامش کنید، نام فایل محلی زیر آن مسیر تکرار میشود.terminal · ساخت فایل و آپلود
printf 'hello ParsPack\n' > hello.txt
aws --endpoint-url https://c123456.parspack.net \
s3 cp ./hello.txt s3://c123456/tutorial/hello.txtخروجی نمونه
upload: ./hello.txt to s3://c123456/tutorial/hello.txt
جایگزینیآپلود روی کلید موجود، بدون سؤال رویش مینویسد؛ نسخهٔ جدا ساخته نمیشود.
نوع محتوابا
--content-type text/plain مقدارش را خودتان تعیین کنید.پوشهٔ کامل
aws s3 cp --recursive ./dir/ s3://c123456/prefix/ یا aws s3 sync برای همگامسازی.۵
فهرست فایلها و مشخصات یک فایل
اینجا تفاوت aws s3 و aws s3api خودش را نشان میدهد: اولی خروجی خوانا برای آدم میدهد، دومی JSON خام برای اسکریپت.
aws s3 ls برای نگاه سریع خوب است. ولی اگر میخواهید خروجی را در اسکریپت پردازش کنید، aws s3api list-objects-v2 بزنید که همان چیزی را میدهد که خود API برمیگرداند — و همان چیزی است که نمونههای هشت زبان این مستندات هم استفاده میکنند.terminal · فهرست خوانا
aws --endpoint-url https://c123456.parspack.net \
s3 ls s3://c123456/tutorial/خروجی نمونه
2026-08-18 10:00:00 15 hello.txt
terminal · فهرست JSON برای اسکریپت
aws --endpoint-url https://c123456.parspack.net \
s3api list-objects-v2 --bucket c123456 --prefix tutorial/خروجی نمونه
{
"Contents": [
{
"Key": "tutorial/hello.txt",
"LastModified": "2026-08-18T10:00:00+00:00",
"ETag": "\"6f5902ac237024bdd0c176cb93063dc4\"",
"Size": 15,
"StorageClass": "STANDARD"
}
],
"KeyCount": 1
}
برای مشخصات یک فایل،
head-object بزنید. این یک درخواست HEAD است: خود فایل دانلود نمیشود، فقط حجم، نوع، ETag و زمان تغییر برمیگردند.terminal · مشخصات یک فایل
aws --endpoint-url https://c123456.parspack.net \
s3api head-object --bucket c123456 --key tutorial/hello.txtخروجی نمونه
{
"LastModified": "2026-08-18T10:00:00+00:00",
"ContentLength": 15,
"ETag": "\"6f5902ac237024bdd0c176cb93063dc4\"",
"ContentType": "text/plain",
"Metadata": {}
}
فیلدهای دقیق خروجی head-object بین فضاهای مختلف S3-سازگار کمی فرق میکند؛ نمونهٔ بالا شکل معمول آن است. اگر در اسکریپت به فیلد خاصی نیاز دارید، با --query 'ContentLength' --output text فقط همان را بگیرید تا به شکل کل خروجی وابسته نباشید.
اگر کلید نباشد
head-object خطای 404 با پیام Not Found میدهد؛ خروجی خالی نمیدهد.KeyCount صفریعنی آپلود انجام نشده یا Prefix اشتباه است؛ خطا نیست.
بیش از ۱۰۰۰ فایلپاسخ صفحهبندی میشود؛
aws s3api list-objects-v2 خودش صفحهها را دنبال میکند مگر --max-items بدهید.۶
دانلود: فایل را روی سیستم خودتان بنویسید
aws s3 cp s3://c123456/tutorial/hello.txt ./downloads/hello.txt
همان
cp با جهت برعکس. پوشهٔ مقصد اگر نباشد ساخته میشود، و اگر فایلی با همان نام باشد، بدون هشدار رویش نوشته میشود.terminal
aws --endpoint-url https://c123456.parspack.net \
s3 cp s3://c123456/tutorial/hello.txt ./downloads/hello.txtخروجی نمونه
download: s3://c123456/tutorial/hello.txt to ./downloads/hello.txt
برای فرستادن محتوا به خروجی استاندارد بهجای فایل، مقصد را
- بگذارید: aws ... s3 cp s3://c123456/tutorial/hello.txt -.۷
لینک امضاشده: فقط دانلود
aws s3 presign s3://c123456/tutorial/hello.txt --expires-in 900
لینک امضاشده یک URL موقت است که تا مدت مشخصی بدون کلید API کار میکند — برای دادن یک فایل از باکت خصوصی به کاربر، بدون Public کردن باکت. مقدار
--expires-in بر حسب ثانیه است و پیشفرضش ۳۶۰۰ است.terminal · لینک دانلود ۱۵ دقیقهای
aws --endpoint-url https://c123456.parspack.net \
s3 presign s3://c123456/tutorial/hello.txt --expires-in 900خروجی نمونه
https://c123456.parspack.net/c123456/tutorial/hello.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Date=20260818T100000Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=...
aws s3 presign فقط لینک دانلود (متد GET) میسازد؛ معادلی برای لینک امضاشدهٔ آپلود در AWS CLI وجود ندارد. اگر میخواهید کاربر مستقیم روی یک URL موقت فایل بفرستد، یا از mc استفاده کنید که هر دو را میسازد، یا از بخش لینک امضاشده در صفحه S3 که این کار را در هشت زبان نشان میدهد.
سقف انقضا برای لینک امضاشده با Signature V4 هفت روز است. کلید مخفی هیچوقت نباید به مرورگر یا اپ موبایل برسد؛ لینک را روی سرور و بعد از احراز هویت کاربر بسازید.
۸
حذف: نام را از باکت بردارید
aws s3 rm s3://c123456/tutorial/hello.txt
rm دقیقاً همان یک کلید را حذف میکند و فایل روی سیستم شما دست نمیخورد. اگر کلید وجود نداشته باشد، S3 باز هم پاسخ موفق میدهد — این رفتار خود پروتکل است، نه اشکال ابزار.terminal
aws --endpoint-url https://c123456.parspack.net \
s3 rm s3://c123456/tutorial/hello.txtخروجی نمونه
delete: s3://c123456/tutorial/hello.txt
aws s3 rm --recursive s3://c123456/tutorial/ همهٔ فایلهای زیر آن مسیر را پاک میکند و برگشتی ندارد. اول همان فرمان را با --dryrun بزنید تا فهرست چیزی که قرار است حذف شود را ببینید.
۹
خطا را از آدرس مقصد شروع کنید
اول مطمئن شوید فرمان واقعاً به Endpoint پارسپک رفته است. سپس Region، Credential و شیوهٔ آدرسدهی را بررسی کنید.
با
--debug میتوانید درخواست HTTP، هدرها و رشتهٔ امضا را ببینید — طولانی است ولی برای مشکل امضا یا حالت آدرسدهی از همه مفیدتر است.| خطا | علت معمول | بررسی |
|---|---|---|
خطای DNS یا Could not connect با نام باکت در ابتدای دامنه | حالت آدرسدهی هنوز virtual-host است | aws configure set default.s3.addressing_style path |
NoSuchBucket یا خطای دسترسی روی آدرس آمازون | --endpoint-url را جا انداختهاید | پرچم را به فرمان اضافه کنید یا AWS_ENDPOINT_URL را export کنید |
SignatureDoesNotMatch | کلیدها اشتباهاند یا Region با پنل یکی نیست | AWS_ACCESS_KEY_ID، AWS_SECRET_ACCESS_KEY، AWS_DEFAULT_REGION |
Unable to locate credentials | متغیرها export نشدهاند یا Profile اشتباه است | aws configure list |
An error occurred (404) ... Not Found | کلید در باکت نیست یا املایش فرق دارد | اول s3api list-objects-v2 با همان Prefix |
AccessDenied | کلید به این باکت دسترسی ندارد | باکت و کلید را در پنل چک کنید |
خروجی aws --version با aws-cli/1. شروع میشود | نسخهٔ قدیمی از پکیج توزیع در PATH جلوتر است | which -a aws؛ نسخهٔ ۲ را نصب کنید |
۱۰
اجرای کامل همین سناریو
اگر خروجی هر فرمان شبیه نمونههای بالا بود، اتصال درست است و میتوانید مسیرها را با فایلهای واقعی خودتان عوض کنید.
terminal · از ابتدا تا انتها
export AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY
export AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
export AWS_DEFAULT_REGION=us-east-1
aws configure set default.s3.addressing_style path
E=https://c123456.parspack.net
B=c123456
printf 'hello ParsPack\n' > hello.txt
aws --endpoint-url $E s3 ls s3://$B
aws --endpoint-url $E s3 cp ./hello.txt s3://$B/tutorial/hello.txt
aws --endpoint-url $E s3api list-objects-v2 --bucket $B --prefix tutorial/
aws --endpoint-url $E s3api head-object --bucket $B --key tutorial/hello.txt
aws --endpoint-url $E s3 cp s3://$B/tutorial/hello.txt ./downloads/hello.txt
aws --endpoint-url $E s3 presign s3://$B/tutorial/hello.txt --expires-in 900
aws --endpoint-url $E s3 rm s3://$B/tutorial/hello.txtاسکریپت نمونهٔ
examples/awscli/run.sh همین کارها را با قرارداد مشترک همهٔ نمونههای این مستندات انجام میدهد: پنج متغیر PARSPACK_S3_* را از محیط میخواند و یک فایل تنظیمات موقت برای path-style میسازد، پس ~/.aws شما دست نمیخورد.terminal · اسکریپت نمونه
examples/awscli/run.sh upload ./hello.txt tutorial/hello.txt
examples/awscli/run.sh list tutorial/
examples/awscli/run.sh head tutorial/hello.txt
examples/awscli/run.sh download tutorial/hello.txt ./downloaded.txt
examples/awscli/run.sh presign-get tutorial/hello.txt 900
examples/awscli/run.sh delete tutorial/hello.txtساختار فایلها
examples/
├── .env.example
└── awscli/
└── run.sh # آپلود، فهرست، مشخصات، دانلود، لینک امضاشده و حذف با AWS CLI