API سی دی انمدیریت CDN با APIMCP و هوش مصنوعیacme.sh DNSاتوماسیون

API سی دی ان و MCP؛ مدیریت CDN با API و هوش مصنوعی

با کلید API، REST API، سرور MCP و افزونه acme.sh DNS مدیریت CDN را خودکار کنید؛ از پرج کش و رکورد DNS تا گواهی وایلدکارت و دستیار هوش مصنوعی.

nsin••8 دقیقه مطالعه

تا وقتی یک سایت دارید، پنل گرافیکی کافی است. اما با ده دامنه، دیپلوی‌های روزانه و تیمی که می‌خواهد همه چیز تکرارپذیر باشد، کلیک کردن در پنل تبدیل به گلوگاه می‌شود. nsin برای همین سه راه خودکارسازی دارد: یک REST API، یک سرور MCP برای دستیارهای هوش مصنوعی، و افزونه‌ای برای acme.sh که گواهی وایلدکارت را خودکار می‌گیرد. همه آن‌ها یک چیز مشترک دارند: کلید API.

در این مقاله از ساخت کلید شروع می‌کنیم و می‌رسیم به نمونه‌هایی که می‌توانید همین امروز اجرا کنید. اگر با کش و پرج آشنا نیستید، اول راهنمای پاک کردن کش را ببینید.

کلید API؛ نقطه شروع همه چیز

کلید API به اسکریپت‌ها، CI و ابزارهای هوش مصنوعی اجازه می‌دهد به‌جای شما کار کنند: با همان دامنه‌ها، دامنه‌های اشتراکی و نقش‌های پنل. طبق مستندات کلید API:

  1. در پنل روی آواتار و Settings و API keys بروید.
  2. Create key را بزنید و یک نام بدهید (مثلاً CI deploy).
  3. انقضا (هرگز، ۳۰، ۹۰ یا ۳۶۵ روز) و حالت read-only را انتخاب کنید.
  4. کلید را همان لحظه کپی کنید.

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

دسترسی کامل یا فقط‌خواندنی

حالتچه کاری می‌تواند بکند
Full accessهر کاری که حساب شما می‌تواند: رکورد، قانون، کش، SSL.
Read-onlyهمه درخواست‌های GET به‌علاوه POST /analytics/query (در sandbox و فقط یک SELECT روی لاگ‌های شما). بدون نوشتن.

نقش‌های دامنه همچنان اعمال می‌شود: عضو اشتراکی با نقش Viewer حتی با کلید کامل نمی‌تواند رکورد را ویرایش کند. برای گزارش‌گیری و داشبورد، همیشه کلید read-only بسازید.

محدودیت‌ها و ایمنی

  • سقف نرخ: ۳۰۰ درخواست در دقیقه برای هر کلید؛ بیشتر از آن پاسخ 429.
  • حداکثر ۱۰ کلید فعال برای هر حساب.
  • مسیرهای حساب کاربری (/users/…)، صورتحساب (/billing/…)، ادمین و احراز هویت برای همه کلیدها بسته است و کلید نمی‌تواند کلید بسازد یا باطل کند.
  • کلید نمی‌تواند پول جابه‌جا کند: شارژ کیف پول، خرید پلن و انتخاب عضو پرداخت‌کننده دامنه فقط در پنل است.
  • باطل کردن کلید فوری اثر می‌کند و درخواست‌های بعدی 401 می‌گیرند.

اگر کلیدی لو رفت، فوراً باطلش کنید و کلید تازه بسازید. آن را در کد نگذارید؛ در متغیر محیطی یا مدیر رمز CI نگه دارید.

مدیریت CDN با REST API

آدرس پایه https://api.nsin.ir است و احراز هویت با یکی از دو هدر انجام می‌شود (مرجع REST API):

curl -H "Authorization: Bearer nsin_your_key_here" https://api.nsin.ir/domains/
curl -H "X-Api-Key: nsin_your_key_here"            https://api.nsin.ir/domains/

چند قاعده که جلوی خطاهای رایج را می‌گیرد:

  • در مسیرها {domain} خود نام دامنه است، نه شناسه عددی.
  • اسلش انتهایی مهم است: /domains/ و /domains/{domain}/records/ اسلش دارند ولی /domains/{domain} ندارد.
  • خطاها به شکل {"error": "..."} برمی‌گردند و زمان‌ها با قالب RFC 3339 و به وقت UTC هستند.
  • GET /whoami نشان می‌دهد کلید شما از کدام نوع است.

کدهای وضعیت پرکاربرد: 401 برای کلید نامعتبر، 403 برای نوشتن با کلید read-only یا نقش ناکافی، 402 برای دامنه بدون پلن فعال و 429 برای عبور از سقف نرخ.

سه نمونه عملی

export NSIN_KEY=nsin_your_key_here

# فهرست دامنه‌ها
curl -H "X-Api-Key: $NSIN_KEY" https://api.nsin.ir/domains/

# ساخت رکورد A پروکسی‌شده
curl -X POST -H "X-Api-Key: $NSIN_KEY" -H "Content-Type: application/json" \
  -d '{"name":"www","type":"A","destination":"203.0.113.10","proxied":true}' \
  https://api.nsin.ir/domains/example.com/records/

# پاک کردن کل کش یک دامنه
curl -X DELETE -H "X-Api-Key: $NSIN_KEY" \
  https://api.nsin.ir/domains/example.com/cache/

این‌ها همان نمونه‌های مستندات هستند؛ 203.0.113.10 و example.com مقدارهای نمونه‌اند و باید آدرس سرور و دامنه واقعی خودتان را جایشان بگذارید. مرجع کامل endpointها از سند OpenAPI ساخته می‌شود و گروه‌هایی مثل دامنه‌ها، رکوردهای DNS (با ویرایش و حذف دسته‌ای و ایمپورت BIND)، SSL، قوانین (۱۵ نوع)، کش، آنالیتیکس، آپتایم، توصیه‌ها، اشتراک‌گذاری و پشتیبانی را پوشش می‌دهد. همین سند را می‌توانید در ابزارهای سازگار با OpenAPI هم بارگذاری کنید.

کاربرد معمول برای تیم‌ها: در پایان پایپ‌لاین دیپلوی یک پرج هدفمند بفرستید (در REST با POST /domains/{domain}/cache/keys/purge که یا یک filter مثل مسیر /assets/* می‌گیرد یا فهرست entries، و در MCP با purge_cache_by_path) یا برای هر برنچ پیش‌نمایش یک رکورد DNS بسازید. نمونه سوم بالا کل کش را پاک می‌کند و بعد از آن هر صفحه یک بار از سرور شما گرفته می‌شود؛ پس بعد از هر دیپلوی به آن تکیه نکنید.

پرج کش به کلیدی که read-only نباشد، دسترسی ویرایش کش و پلنی که پرج کش را شامل شود نیاز دارد؛ در غیر این صورت پاسخ 403 (یا برای دامنه بدون پلن فعال، 402) می‌گیرید. برای درک پرج هدفمند، مقاله پرج کش را ببینید.

MCP: به دستیار هوش مصنوعی بگویید چه می‌خواهید

اگر ترجیح می‌دهید به‌جای نوشتن درخواست، به زبان طبیعی کار را بخواهید، nsin یک سرور MCP (Model Context Protocol) میزبانی می‌کند (مستندات MCP):

  • آدرس: https://api.nsin.ir/mcp (از نوع Streamable HTTP)
  • احراز هویت: همان کلید API با Authorization: Bearer nsin_…
  • نصب لازم نیست؛ سرور را nsin میزبانی می‌کند.

اتصال

برای Claude Code:

claude mcp add --transport http nsin https://api.nsin.ir/mcp \
  --header "Authorization: Bearer nsin_your_key_here"

در Claude.ai و Claude Desktop در Settings و بخش Connectors یک custom connector اضافه کنید؛ آدرس همان https://api.nsin.ir/mcp است و هدر Authorization: Bearer nsin_… را هم در صورت درخواست وارد کنید. در Cursor پیکربندی در فایل .cursor/mcp.json با کلیدهای url و headers انجام می‌شود.

دستیار چه کارهایی می‌تواند بکند؟

ابزارهای MCP دسته‌بندی مشخص دارند: دامنه‌ها و رکوردهای DNS، ایمپورت و اکسپورت زون، SSL، اشتراک‌گذاری، قوانین، کش، ترافیک و لاگ‌ها، آپتایم، مسیریابی ایمیل و حساب. چند نمونه:

  • purge_cache_by_path برای پرج مسیر، مثلاً /assets/* یا /blog/post-1. بدون * تطبیق زیررشته‌ای است، پس /logo.png مسیر /img/logo.png?v=2 را هم می‌گیرد.
  • set_developer_mode برای دور زدن موقت کش هنگام دیپلوی؛ مستندات صریحاً می‌گویند به‌جای حلقه پرج از آن استفاده کنید.
  • get_rule_schema و create_rule برای ساخت قانون: اول شمای بدنه هر نوع را می‌خوانید و بعد قانون را می‌سازید.
  • list_uptime_incidents و get_uptime_status برای بررسی قطعی.
  • run_analytics_query برای پرس‌وجوی سفارشی روی لاگ درخواست‌ها؛ فقط یک SELECT و فقط روی داده دامنه‌های خودتان، با سقف ۱۰٬۰۰۰ ردیف.

مثال درخواست: «۲۰ مسیر با بیشترین خطای 5xx در هفته گذشته را نشان بده». برای شناسایی قطعی‌هایی که کد 5xx ندارند (مثل تایم‌اوت و اتصال‌های ردشده)، مستندات فیلد errFault = 'origin' را پیشنهاد می‌کند.

ایمنی در کار با هوش مصنوعی

  • MCP از همان مجوزهای حساب شما استفاده می‌کند؛ نقش Viewer روی دامنه اشتراکی ابزارهای نوشتنی را مسدود می‌کند.
  • ابزارهای حذف دائمی پارامتر confirm: true می‌خواهند و دستیار باید پیش از آن از شما بپرسد.
  • کلیدهای read-only فقط فهرست ابزارهای خواندنی را می‌بینند.
  • تمام اقدامات همان اعتبارسنجی، ثبت audit و سقف ۳۰۰ درخواست در دقیقه را دارند.

پیشنهاد ما: برای کاوش و گزارش از کلید read-only استفاده کنید و کلید کامل را فقط وقتی بدهید که مطمئنید و هر اقدام نوشتنی را پیش از تأیید بخوانید، چون کلید کامل می‌تواند DNS زنده را تغییر بدهد و کش را پاک کند.

Agent skill

اگر می‌خواهید دستیارتان علاوه بر ابزار، «قضاوت» هم داشته باشد، یک agent skill هم هست که CDN، NSIN CLOUD، مسیریابی ایمیل و مهاجرت از سایر ارائه‌دهنده‌ها را پوشش می‌دهد. طبق مستندات، این skill به ارائه‌دهنده قدیمی دست نمی‌زند و بدون تأیید شما nameserver یا ترافیک زنده را جابه‌جا نمی‌کند.

acme.sh و گواهی وایلدکارت با DNS-01

برای گواهی وایلدکارت (*.example.com) باید چالش DNS-01 حل شود. افزونه dns_nsin برای acme.sh رکورد TXT با نام _acme-challenge را روی زون nsin شما اضافه و بعد از اعتبارسنجی حذف می‌کند (مستندات).

پیش‌نیازها: دامنه روی nsin باشد (nsin برای زون authoritative باشد) و یک کلید API که read-only نباشد.

curl -o ~/.acme.sh/dnsapi/dns_nsin.sh https://nsin.ir/docs/dns_nsin.sh
export NSIN_Api_Key="nsin_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# وایلدکارت
acme.sh --issue --dns dns_nsin -d example.com -d '*.example.com'

acme.sh کلید را در account.conf ذخیره می‌کند تا تمدیدهای بعدی هم خودکار انجام شود. متغیر اختیاری NSIN_Api آدرس پایه را تغییر می‌دهد و پیش‌فرض آن https://api.nsin.ir است.

عیب‌یابی سریع:

  • خطای read-only API key یا 403: کلید با دسترسی نوشتن بسازید.
  • invalid domain: دامنه در حساب شما نیست یا کلید دسترسی ندارد؛ با GET /domains/ بررسی کنید.
  • شکست اعتبارسنجی: احتمالاً DNS هنوز منتشر نشده؛ گزینه --dnssleep 60 یا بیشتر را اضافه کنید.
  • --debug 2 درخواست‌ها و پاسخ‌ها را نشان می‌دهد.

برای تصویر کلی SSL در nsin هم راهنمای گواهی SSL رایگان را ببینید.

نقشه راه پیشنهادی

  1. یک کلید read-only بسازید و با GET /domains/ امتحانش کنید.
  2. یک کلید کامل جدا برای CI بسازید و پرج بعد از دیپلوی را به پایپ‌لاین اضافه کنید.
  3. اگر وایلدکارت لازم دارید، dns_nsin را نصب کنید.
  4. MCP را به دستیار مورد علاقه‌تان وصل کنید و ابتدا فقط با کلید read-only بپرسید.
  5. کلیدها را دوره‌ای بررسی کنید: نمودار ۳۰ روزه مصرف و زمان آخرین استفاده در تب API keys هست.

پرسش‌های متداول

API سی دی ان nsin چه محدودیتی دارد؟

سقف ۳۰۰ درخواست در دقیقه برای هر کلید و ۱۰ کلید فعال برای هر حساب. بخش‌های حساب، صورتحساب، ادمین و احراز هویت برای کلیدها بسته است.

تفاوت کلید Full access و Read-only چیست؟

Full access هر کاری را که حساب شما مجاز است انجام می‌دهد. Read-only فقط خواندن (و پرس‌وجوی sandbox آنالیتیکس) دارد و برای داشبورد و کاوش با هوش مصنوعی ایمن‌تر است.

آیا MCP نیاز به نصب دارد؟

خیر. سرور توسط nsin میزبانی می‌شود؛ فقط آدرس و کلید را در Claude Code، Claude Desktop یا Cursor تنظیم می‌کنید.

آیا دستیار هوش مصنوعی می‌تواند پول خرج کند؟

خیر. شارژ کیف پول، خرید پلن و انتخاب عضو پرداخت‌کننده برای هیچ کلیدی باز نیست و فقط در پنل انجام می‌شود.

acme.sh با DNS nsin چطور گواهی وایلدکارت می‌گیرد؟

افزونه dns_nsin با API رکورد TXT چالش را می‌سازد و بعد از اعتبارسنجی حذف می‌کند. فقط کلید غیر read-only و دامنه‌ای که DNS آن روی nsin است لازم دارد.

شروع کنید

اگر هنوز دامنه‌تان روی CDN nsin نیست، از آنجا شروع کنید، بعد در پنل nsin به Settings و API keys بروید و اولین کلیدتان را بسازید. از همان کلید برای REST API، MCP و acme.sh استفاده می‌شود.