API عمومی
یک API کوچک و فقط خواندنی HTTP برای دریافت وضعیت سرور از خارج از پنل: یک داشبورد وضعیت، یک مانیتور آپتایم، یک ربات Discord، یک قانون اتوماسیون خانگی. این توسط خود پنل ارائه میشود و همان دادههای زندهای را برمیگرداند که صفحات خود پنل نشان میدهند (از حافظه پنهان در حافظه)، بنابراین درخواست آن هرگز با Docker تماس نمیگیرد.
این تا زمانی که مدیر آن را فعال نکند خاموش است و تحت کنترل مدیر است. هیچ چیزی فاش نمیشود تا زمانی که یک توکن وجود داشته باشد.
فعالسازی
Section titled “فعالسازی”تنظیمات → API عمومی → کلید جدید. یک نام به آن بدهید، انتخاب کنید چه چیزی را میتواند ببیند (همه سرورها، یا زیرمجموعه خاصی)، و به صورت اختیاری تاریخ انقضا. کلید کامل (یک توکن Bearer) یک بار در یک پنجره نمایش داده میشود؛ آن را اکنون کپی کنید، زیرا پس از آن فقط یک پیشوند کوتاه برای شناسایی در لیست نگهداری میشود.

ایجاد اولین کلید به طور خودکار API را روشن میکند (سوئیچ اجازه دادن به برنامههای خارجی برای خواندن وضعیت یک کنترل مکث است: آن را خاموش کنید تا بدون لغو هیچ کلیدی، سرویسدهی متوقف شود). در هر زمان میتوانید یک کلید را از همان جدول لغو کنید؛ کلاینتهایی که از آن استفاده میکنند بلافاصله دسترسی خود را از دست میدهند.
توکنها به صورت هش SHA-256 (هرگز به صورت متن ساده) ذخیره میشوند، از راهاندازی مجدد پنل جان سالم به در میبرند و از سرورهایی که برای آنها محدود شدهاند طولانیتر عمر میکنند (یک سرور حذف شده به سادگی از نتایج آن توکن حذف میشود).
احراز هویت
Section titled “احراز هویت”توکن را به عنوان یک اعتبارنامه Bearer ارسال کنید:
Authorization: Bearer msm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxهیچ کوکی و هیچ CORS وجود ندارد: این برای کلاینتهای سرور به سرور و خط فرمان است، نه برنامههای مرورگر در مبدأ دیگر. اگر پنل پشت یک پروکسی معکوس قرار دارد، مطمئن شوید که پروکسی هدر Authorization را فوروارد میکند.
شکستها 401 با { "ok": false, "error": "..." } را برمیگردانند. هر چیزی غیر از GET (یا HEAD) 405 را برمیگرداند. مسیرهای ناشناخته 404 را برمیگردانند. هنگامی که API غیرفعال است، هر مسیر 404 را برمیگرداند.
محدودیت نرخ
Section titled “محدودیت نرخ”هر توکن بودجه خود را دارد، RATE_LIMIT_PUBLIC_API_PER_MIN (پیشفرض 120 درخواست در دقیقه؛ 0 محدودکننده را غیرفعال میکند). فراتر از حد، 429 را برمیگرداند. هر درخواست، حتی قبل از بررسی توکن آن، به سقف پنج برابر آن تعداد در هر IP کلاینت نیز شمارش میشود، بنابراین کاوش با توکنهای گمشده، بدشکل، باطل شده یا منقضی شده نمیتواند با چرخاندن آنها از بودجه عبور کند.
نقاط پایانی
Section titled “نقاط پایانی”GET /api/v1/servers
Section titled “GET /api/v1/servers”هر سروری که توکن برای آن محدود شده است.
{ "ok": true, "total": 1, "online": 1, "servers": [ { "id": "srv_ab12cd34", "name": "SMP", "type": "PAPER", "state": "running", "cpuPct": 18.4, "memoryMb": 2048, "memoryLimitMb": 4096, "uptimeSeconds": 11722, "players": { "online": 3, "max": 20 } } ]}GET /api/v1/servers/:id
Section titled “GET /api/v1/servers/:id”یک سرور، همان شیء زیر کلید server. برای یک شناسه ناشناخته و برای سروری که توکن برای آن محدود نشده است (بدون اوراکل وجود)، 404 را برمیگرداند و برای یک شناسه بدشکل، 400 را برمیگرداند.
فیلدهای پاسخ
Section titled “فیلدهای پاسخ”| فیلد | معنی |
|---|---|
total |
تعداد سرورهای قابل مشاهده برای این توکن (پس از فیلتر محدوده آن). |
online |
تعداد سرورهای در وضعیت: running. |
id |
شناسه پایدار سرور (srv_...). |
name |
نام نمایشی. |
type |
نوع سرور itzg (PAPER, FABRIC, AUTO_CURSEFORGE, …). |
state |
running, starting, stopped, یا crashed: خلاصهای پایدار از وضعیت داخلی پنل. |
cpuPct |
درصد CPU اخیر، یا null زمانی که سرور در حال اجرا نیست. |
memoryMb |
حافظه مقیم در مگابایت، یا null. |
memoryLimitMb |
محدودیت حافظه کانتینر پیکربندی شده در مگابایت، یا null. |
uptimeSeconds |
ثانیهها از زمان شروع کانتینر، یا null. |
players |
{ online, max }، یا null تا زمانی که سرور لیستی از بازیکنان را گزارش کند. |
curl -s https://panel.example.com/api/v1/servers \ -H "Authorization: Bearer $MSM_TOKEN" | jq