مهارت ابر آروان دقیقاً چه چیزی به دستیار یاد میدهد؟

نشانی پایهٔ هر محصول آروان، شیوهٔ احراز هویت، منطقهها، خطاهای رایج و شکل درست درخواستها را. دستیار با اینها و دو اسکریپت bash همراه مهارت، مستقیم با API آروان کار میکند: DNS، کش CDN، سرور ابری، فضای ذخیرهسازی و گواهی Let's Encrypt.

آیا دستیار بدون اجازهٔ من رکورد DNS را تغییر میدهد؟

طبق دستورالعمل مهارت، نه. پیش از هر کار تغییردهنده یا هزینهدار، نام حساب، متد، نشانی و بدنهٔ درخواست را نشان میدهد و تأیید میگیرد. اسکریپت arvan-api.sh هم هر درخواستی جز GET را بدون گزینهٔ --allow-write رد میکند.

گواهی SSL وایلدکارد آروان را چطور با این مهارت بگیرم؟

مهارت از افزونهٔ dns_arvan در acme.sh استفاده میکند: رکورد TXT اعتبارسنجی را از طریق API آروان میسازد و بعد پاک میکند. متغیر Arvan_Token باید با پیشوند Apikey شروع شود. تمدید با cron روزانهٔ acme.sh انجام میشود.

کلید API آروان را از کجا بگیرم؟

در پنل آروان از مسیر تنظیمات، IAM و کاربران ماشینی یک کاربر ماشینی بسازید. کلید فقط یک بار نشان داده میشود و دسترسیاش را برای هر محصول جدا تعیین میکنید. برای S3 فضای ذخیرهسازی کلید جدا لازم است.

این مهارت در ChatGPT یا Claude.ai هم کار میکند؟

در عمل نه چندان. کار اصلیاش با اسکریپتهای bash و curl و jq روی API زنده است، پس دستیاری لازم دارد که بتواند فرمان اجرا کند و به اینترنت دسترسی داشته باشد؛ در عمل دستیارهای برنامهنویسی مثل Claude Code، Cursor و Codex.

این مهارت رسمی آروان است؟

نه. سازندهاش erfnzdeh است و در مخزن نوشته که به ابر آروان وابسته نیست و تأییدش را ندارد. آخرین بررسی سازنده روی مستندات و API زنده مال ۲۲ شهریور ۱۴۰۵ است.

کار با API ابر آروان با Claude Code: DNS، کش CDN و SSL وایلدکارد

استقرار تمام شد و سرور تازه بالا آمده. حالا باید زیردامنهٔ جدید را به IP سرور وصل کنید، کش CDN را پاک کنید تا فایل‌های قدیمی سرو نشوند، و یادتان بیاید گواهی وایلدکارد ماه بعد منقضی می‌شود. هر سه کار با API ابر آروان شدنی است، ولی اول باید بفهمید کدام نشانی، کدام نسخه و کدام سرآیند احراز هویت به کدام محصول می‌خورد.

پاسخ کوتاه: برای کار با API ابر آروان از داخل Claude Code یا Cursor، مهارت (Agent Skill) «ابر آروان» را نصب کنید. این مهارت نقشهٔ API آروان، خطاهای واقعی‌اش و دو اسکریپت آماده را به دستیار برنامه‌نویسی‌تان می‌دهد، و دستیار پیش از هر تغییر درخواست را نشانتان می‌دهد و تأیید می‌گیرد.

کار با API ابر آروان بدون گشتن در مستندات

سختی کار با آروان این است که هر محصول نشانی پایه و مستند جدا دارد. سرور ابری سه نسل API دارد، و فضای ذخیره‌سازی برای S3 یک روش احراز هویت دیگر. سازنده نوشته که مهارت را ساخته تا دستیار این جزئیات را «حدس نزند». خلاصه‌ای از نقشه‌ای که در مهارت آمده:

کار	سرویس آروان	نشانی پایه
رکورد DNS، کش، فایروال	سرویس CDN نسخهٔ ۴٫۰	`napi.arvancloud.ir/cdn/4.0`
سرور ابری (نسل پیشنهادی)	نسخهٔ v3 سرور ابری	`ecc.{region}.arvanapis.ir/v3`
پشتیبان‌ها و فهرست دیسک‌ها	نسخهٔ v2 بی‌مستند	`napi.arvancloud.ir/ecc/v2`
این کلید مال کدام حساب است؟	شناسهٔ حساب	`dejban.arvancloud.ir/v1/me`
مدیریت فضای ذخیره‌سازی	سرویس Object Storage	`storage.arvanapis.ir/v1`

محاسبات لبه، کانتینر ابری، ویدیوی درخواستی، پخش زنده و تبلیغات ویدیویی هم در نقشه هستند. منطقه‌ها هم آمده‌اند: تهران (ir-central1)، تبریز (ir-northwest1)، آلمان (eu-west1) و اهواز (ir-southwest1). نکتهٔ اهواز را هم نوشته: میزبان v3 آن در TLS خطا می‌دهد و باید سراغ v1 یا v2 رفت. همهٔ درخواست‌ها، جز S3، با سرآیند Authorization: Apikey <uuid> احراز هویت می‌شوند.

زیردامنهٔ تازه و کش CDN: دستیار چه درخواستی می‌سازد؟

مثلاً به دستیار می‌گویید «زیردامنهٔ staging را به IP سرور جدید وصل کن و بعد کل کش دامنه را خالی کن». مهارت چند نکته را که معمولاً اشتباه می‌شود به دستیار گفته است:

نام رکورد فقط برچسب زیردامنه است، نه نام کامل دامنه. برای خود دامنه @ می‌نویسد.
شکل مقدار به نوع رکورد بستگی دارد. رکورد A آرایه می‌گیرد، MX یک شیء تکی و SRV فیلد target به جای host. نوع رکورد هم با حروف کوچک فرستاده می‌شود.
پاک کردن کش با POST روی /domains/{domain}/caching/purge انجام می‌شود، با {"purge":"all"} برای کل کش یا فهرستی تا ۵۰ نشانی.

پیش از ثبت، دستیار با گزینهٔ --dry-run همان درخواستی را که می‌خواهد بفرستد نشانتان می‌دهد. شکلش چیزی شبیه این است (دامنه و IP جای‌نما هستند):

S="${CLAUDE_SKILL_DIR}/scripts/arvan-api.sh"
"$S" --dry-run -d '{"type":"a","name":"staging","value":[{"ip":"1.2.3.4"}],"ttl":3600}' \
  "/cdn/4.0/domains/example.ir/dns-records"

بعد از «بله» شما، همان دستور با --allow-write اجرا می‌شود. برای قدم بعدی استقرار هم همین الگو تکرار می‌شود، پس می‌شود از دستیار خواست کل کار را در یک اسکریپت استقرار یا CI بنویسد.

گواهی SSL وایلدکارد آروان با acme.sh

در گرفتن گواهی، مهارت جلوی چند اشتباه رایج را می‌گیرد. ابزار acme.sh افزونهٔ داخلی dns_arvan دارد که رکورد TXT اعتبارسنجی (_acme-challenge) را از طریق API آروان می‌سازد و بعد پاکش می‌کند. مهارت ترتیب کار را این‌طور به دستیار یاد داده است:

اول مطمئن شود دامنه واقعاً به آروان سپرده شده. وضعیت active کافی نیست. دستیار ns_keys را با current_ns مقایسه می‌کند و dig SOA <domain> @8.8.8.8 می‌زند.
کلید را با پیشوند درست بدهد. افزونه مقدار Arvan_Token را عیناً در سرآیند می‌گذارد، پس باید با Apikey شروع شود.
گواهی ریشه و ستاره‌دار را با هم بگیرد:

export Arvan_Token="Apikey XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
~/.acme.sh/acme.sh --issue --dns dns_arvan \
  -d example.ir -d '*.example.ir' --server letsencrypt

نصب و تمدید خودکار را راه بیندازد. cron روزانهٔ acme.sh گواهی را نزدیک انقضا تمدید می‌کند. برای رساندن گواهی به سرورها، دستیار دستور --install-cert --reloadcmd را از deployHooks در فایل ~/.config/arvan/config.json می‌سازد: میزبان SSH، پوشه‌های گواهی و فرمان بارگذاری دوبارهٔ وب‌سرور.

یک نکتهٔ مخصوص ایران هم در مهارت هست. فیلترینگ DNS در ایران IPهای جعلی 10.10.34.34 تا 10.10.34.36 برمی‌گرداند، نه پاسخ خالی. پس اگر SOA یا NS خالی آمد، مشکل از سپردن دامنه است، نه فیلترینگ. اعتبارسنجی DNS-01 هم به این ترفندهای DNS داخلی ربطی ندارد، چون Let’s Encrypt رکورد را از بیرون ایران می‌خواند.

خطاهای API آروان را چطور بخوانیم؟

بخشی از مهارت جدول خطاهایی است که سازنده در درخواست‌های زنده دیده. مهم‌ترین‌ها:

خطای ۴۰۱: کلید اشتباه است یا باطل شده.
خطای ۴۰۳ با پیام Account requires info completion: اطلاعات حساب (احراز هویت) کامل نیست. این وضعیت سرور ابری را می‌بندد، ولی CDN، فضای ذخیره‌سازی و محاسبات لبه کار می‌کنند. یعنی مسیر درست است و کلید هم سالم.
خطای ۴۰۳ با پیام Upgrade plan: آن قابلیت طرح بالاتری می‌خواهد.
خطای ۴۰۵ با required_plan: قابلیتی از CDN که به طرح وابسته است؛ مثلاً خروجی گرفتن از DNS طرح حرفه‌ای می‌خواهد.
خطای ۴۲۰: سهمیهٔ سرور ابری پر شده.

با این جدول، دستیار به جای امتحان کردن مسیرهای مختلف، علت را همان اول می‌گوید.

دستیار چطور حساب آروان را امن نگه می‌دارد؟

مهارت روی کار با حساب واقعی ساخته شده و چند قفل دارد:

خواندن آزاد، نوشتن با اجازه. درخواست‌های GET بی‌تأیید اجرا می‌شوند. اسکریپت arvan-api.sh هر متد دیگری را بدون --allow-write رد می‌کند (با کد خروج ۴).
نام حساب در تأیید. هر کلید فقط یک حساب را می‌بیند و خیلی‌ها چند کلید دارند. برای همین پیش از هر نوشتن، دستیار از /v1/me نام حساب را می‌گیرد و در پیام تأیید می‌آورد.
فهرست دقیق کارهای حساس. تغییر DNS، پاک کردن کش، تنظیمات فایروال و محدودیت نرخ، کارهای سرور، نوشتن در فضای ذخیره‌سازی، نصب گواهی و فرمان‌های SSH همه پیش از اجرا تأیید می‌خواهند.
کلید بیرون از خروجی. اسکریپت کلید را از طریق یک فایل موقت به curl می‌دهد، نه در خط فرمان، و آن را چاپ نمی‌کند. درخواست ۴۲۹ را خودش دوباره می‌فرستد، و خطاهای سری ۵۰۰ را فقط برای GET.
عکس فوری از حساب. اسکریپت arvan-inventory.sh فقط می‌خواند: هویت حساب، سرورهای همهٔ منطقه‌ها، پشتیبان‌ها، دامنه‌های CDN، مصرف فضای ذخیره‌سازی و چند شمارش دیگر. برای سؤال «روی آروان چه دارم؟» بهترین شروع است.

نصب مهارت و ساختن کلید کاربر ماشینی

کلید بسازید. در پنل آروان از مسیر تنظیمات، IAM و کاربران ماشینی (Machine users) یک کاربر ماشینی بسازید. کلید فقط یک بار نشان داده می‌شود. دسترسی را برای هر محصول جدا بدهید؛ اگر فقط DNS و CDN لازم است، همان‌ها را باز کنید.
مهارت را نصب کنید. در ترمینال npx skills add erfnzdeh/arvancloud-agent-skill را بزنید. اگر پرسید کدام مهارت، arvancloud-api را انتخاب کنید. در Claude Code می‌توانید آن را افزونه هم نصب کنید:

/plugin marketplace add erfnzdeh/arvancloud-agent-skill
/plugin install arvancloud-api@arvancloud-agent-skill

کلید را به دستیار برسانید. در افزونهٔ Claude Code کلید را با /plugin configure arvancloud-api@arvancloud-agent-skill ذخیره کنید؛ در مخزن اعتبارنامه‌های سیستم نگه داشته می‌شود. در Cursor و جاهای دیگر کلید در یک متغیر محیطی است. نام پیش‌فرضش ARVAN_KEY است، و اگر خالی باشد دستیار می‌پرسد کلید در کدام متغیر است. در ~/.config/arvan/config.json فقط نام متغیر نوشته می‌شود، هیچ‌وقت خود کلید.
با یک کار فقط‌خواندنی شروع کنید. مثلاً بپرسید این کلید مال کدام حساب است، یا فهرست دامنه‌ها و رکوردهای یکی از آن‌ها را بخواهید.

پیش‌نیازها: bash، curl و jq برای اسکریپت‌ها، و acme.sh اگر گواهی می‌خواهید. فضای ذخیره‌سازی S3 کلید دسترسی و کلید مخفی جدایی دارد و با کلید کاربر ماشینی کار نمی‌کند.

مهارت یا سرور MCP: کدام برای ابر آروان؟

در بازارچه برای آروان یک سرور MCP هم هست: arvancai (راهنمایش: ابر آروان با هوش مصنوعی). فرقشان در شیوهٔ کار است:

سرور arvancai قابلیت‌های آماده به هر برنامهٔ سازگار با MCP می‌دهد و حالت فقط‌خواندنی دارد (ARVANCLOUD_READ_ONLY=1). برای مدیریت روزمره از داخل گفتگو مناسب است. نصب و تنظیمش در صفحهٔ arvancai آمده؛ با کلید خودتان روی کامپیوترتان اجرا می‌شود.
این مهارت API خام را به دستیار برنامه‌نویسی یاد می‌دهد: نوشتن اسکریپت، خودکارسازی استقرار و CI، گواهی با acme.sh و قلاب‌های نصبش، و پیدا کردن علت خطاهای API. چون کار با فرمان‌های ترمینال است، دستیاری لازم دارد که بتواند فرمان اجرا کند، مثل Claude Code، Cursor یا Codex.

اگر فرق کلی این دو شکل برایتان تازه است، تفاوت Skill و MCP را بخوانید. نصب هر دو با هم هم ایرادی ندارد.

پیش از سپردن حساب آروان به دستیار

مهارت غیررسمی است. سازنده‌اش erfnzdeh است و نوشته که به ابر آروان وابسته نیست. مجوزش MIT است.
نقشه تاریخ دارد. سازنده نشانی‌ها و مسیرها را ۲۲ شهریور ۱۴۰۵ با مستندات OpenAPI و درخواست‌های زنده سنجیده و خودش تأکید کرده که مستندات و API زنده مرجع نهایی‌اند.
کارها واقعی‌اند. بعد از تأیید شما، رکورد عوض می‌شود، کش خالی می‌شود و سرور ساخته یا خاموش می‌شود؛ برخی از این‌ها هزینه دارند. متن تأیید را واقعاً بخوانید، مخصوصاً نام حساب را.
همه‌چیز از API درنمی‌آید. مانده کیف پول فقط در پنل دیده می‌شود، و برخی قابلیت‌ها به طرح حساب یا تکمیل اطلاعات حساب بسته‌اند.

اگر هر هفته با DNS، کش و گواهی آروان سروکار دارید، دریافت مهارت را بزنید و اولین درخواست را فقط‌خواندنی بفرستید.