مدیریت VPS با REST API و curl: وضعیت، روشن و خاموش، نصب مجدد، تمدید

سفارش سرور از طریق API یک درخواست است. این موضوع در سفارش VPS با 4 فراخوانی API آمده است. این صفحه درباره همه چیزهای بعد از آن است: کارهای روزمره‌ای که در غیر این صورت در داشبورد با کلیک انجام می‌دادید، به شکل فرمان‌های curl که می‌توانید در اسکریپت بچسبانید.

همه فرمان‌های زیر را پیش از انتشار روی API خودمان اجرا کردیم و پاسخ‌ها نسخه‌های کوتاه‌شده آن چیزی است که برگشت.

آماده‌سازی

دو متغیر فرمان‌ها را کوتاه نگه می‌دارند:

export API=https://api.eqvps.com/api/v1/eqvps
export EQVPS_TOKEN='paste-your-token-here'

توکن از POST /auth/register یا از Settings → API tokens در داشبورد می‌آید. اگر دیگران هم از این دستگاه استفاده می‌کنند، آن را از تاریخچه shell دور نگه دارید؛ خواندن آن از فایل با export EQVPS_TOKEN=$(cat ~/.eqvps_token) کافی است.

سرورهایتان را پیدا کنید

curl -s $API/services -H "Authorization: Bearer $EQVPS_TOKEN"

هر مورد یک id مثل 47HZ7YF دارد. این همان کد سرویس است که همه فراخوانی‌های دیگر می‌گیرند. سپس تصویر کامل یک سرور:

curl -s $API/services/47HZ7YF -H "Authorization: Bearer $EQVPS_TOKEN"

{ "data": {
    "id": "47HZ7YF", "status": "active", "queued": false,
    "product": { "slug": "nano", "name": "Nano" },
    "specs": { "vcpu": 2, "memory_mb": 1024, "disk_gb": 15 },
    "hostname": "agent-box",
    "vm": { "state": "running", "uptime": 5340 },
    "access": { "method": "ssh", "host": "203.0.113.10", "port": 21521, "user": "root", "nat": true, ... } } }

access می‌گوید چطور وارد شوید. در پلن با IPv4 اختصاصی پورت 22 است؛ در پلن NAT پورت فورواردشده شخصی شماست. این فراخوانی فقط می‌خواند، پس پرسیدن آن در حلقه بی‌خطر است.

اگر بدون کلید SSH سفارش داده‌اید، رمز root یک بار نمایش داده می‌شود:

curl -s "$API/services/47HZ7YF?reveal=1" -H "Authorization: Bearer $EQVPS_TOKEN"

تا وقتی سرور هنوز در حال بوت است، پاسخ password_pending است و آن نمایش یک‌باره مصرف نمی‌شود. نیم دقیقه صبر کنید و دوباره بپرسید.

روشن و خاموش: start، stop، reboot

curl -s -X POST $API/services/47HZ7YF/power \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"action": "reboot"}'

مقدار action یکی از start، stop یا reboot است. سروری که هنوز فعال نیست (هنوز در حال ساخت است یا به دلیل عدم پرداخت معلق شده) پاسخ 409 Service is not active می‌دهد. این خطای اسکریپت شما نیست. اول status را بررسی کنید.

معیارها

curl -s "$API/services/47HZ7YF/metrics?timeframe=day" -H "Authorization: Bearer $EQVPS_TOKEN"

CPU، حافظه، شبکه و دیسک به شکل سری زمانی. مقدار timeframe یکی از hour (پیش‌فرض)، day، week یا month است. برای کار cron که وقتی دیسک مدام بزرگ می‌شود خبرتان کند مفید است. شمارنده‌های ترافیک دوره صورت‌حساب فعلی در بررسی سرعت و ترافیک هستند.

تغییر نام سرور

curl -s -X POST $API/services/47HZ7YF/hostname \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"hostname": "web-01"}'

نام جدید را guest agent داخل سیستم در حال اجرا اعمال می‌کند و در Linux نیازی به راه‌اندازی مجدد نیست. اگر سرور خاموش است یا qemu-guest-agent را حذف کرده‌اید، فراخوانی 409 agent_unavailable برمی‌گرداند و چیزی تغییر نمی‌کند.

نصب مجدد سیستم‌عامل

این یکی دیسک را پاک می‌کند. API شما را وادار می‌کند hostname فعلی سرور را در confirm بنویسید، تا اسکریپتی با id سرویس اشتباه نتواند دستگاه اشتباهی را پاک کند:

curl -s -X POST $API/services/47HZ7YF/reinstall \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"os_id": 4, "confirm": "web-01"}'

os_id از فهرست available_os پلن شما در GET /products یا از جزئیات خود سرور می‌آید. نصب مجدد در پس‌زمینه انجام می‌شود؛ GET /services/{id} را بپرسید تا status دوباره active شود.

تمدید و موجودی

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

curl -s $API/services/47HZ7YF/renew-options -H "Authorization: Bearer $EQVPS_TOKEN"

برای پرداخت پیشاپیش، مثلاً سه ماه، با یک فراخوانی:

curl -s -X POST $API/services/47HZ7YF/renew \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"months": 3}'

مقدار months یکی از 1، 3، 6 یا 12 است و 12 با قیمت سالانه و تخفیف آن محاسبه می‌شود. پاسخ paid_from_balance: true و تاریخ انقضای جدید را می‌دهد. اگر موجودی مبلغ را پوشش ندهد، چیزی کسر نمی‌شود: paid_from_balance: false و به‌جای آن یک checkout_url برای آن صورت‌حساب می‌گیرید. پس از شارژ موجودی، POST $API/invoices/{invoice_id}/pay آن صورت‌حساب را از موجودی پرداخت می‌کند؛ اگر هنوز کم باشد، همان نوع checkout_url را برمی‌گرداند و چیزی کسر نمی‌کند. بررسی و شارژ موجودی:

curl -s $API/balance -H "Authorization: Bearer $EQVPS_TOKEN"

curl -s -X POST $API/balance/topup \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"amount": 25}'

پاسخ شارژ شامل یک checkout_url است. این پرداخت رمزارزی است: USDT، USDC یا ETH روی Base، Ethereum یا Polygon. موجودی پس از تأیید پرداخت روی زنجیره افزوده می‌شود. پرداخت تنها مرحله‌ای است که اسکریپت نمی‌تواند به‌جای شما انجام دهد، مگر اینکه کیف پول داشته باشد.

Monero هم کار می‌کند، اما فقط به شکل شارژ موجودی با بررسی دستی: XMR می‌فرستید، id تراکنش را ارائه می‌دهید و ما پس از تأیید آن را می‌افزاییم. ببینید پرداخت با Monero.

لغو، و تغییر نظر

لغو امن سرور را تا پایان دوره پرداخت‌شده روشن نگه می‌دارد و فقط تمدیدش نمی‌کند:

curl -s -X POST $API/services/47HZ7YF/cancel \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"type": "end_of_period", "reason": "moving the project elsewhere"}'

reason الزامی است. چند کلمه کافی است. پیش از تاریخ نظرتان عوض شد؟

curl -s -X POST $API/services/47HZ7YF/cancel/undo -H "Authorization: Bearer $EQVPS_TOKEN"

"type": "immediate" هم وجود دارد. سرور و داده‌هایش را فوراً پاک می‌کند، به "confirm": "<hostname>" نیاز دارد و قابل بازگشت نیست. مگر اینکه واقعاً همین را بخواهید، از end_of_period استفاده کنید.

توکن را زنده نگه دارید

توکن‌های جدید به‌طور پیش‌فرض یک سال عمر دارند. هر پاسخ احرازشده هدر X-Token-Expires-At دارد، تا اسکریپت زودتر متوجه شود. توکن را با یک توکن تازه عوض کنید:

curl -s -X POST $API/auth/token/refresh -H "Authorization: Bearer $EQVPS_TOKEN"

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

خطاهایی که ارزش رسیدگی دارند

این کار را به‌جای اسکریپت از یک کلاینت هوش مصنوعی انجام می‌دهید؟ همین عملیات به شکل ابزارهای MCP هم وجود دارد — ببینید چطور ایجنت هوش مصنوعی از طریق MCP خودش VPS اش را نگه می‌دارد و مرجع API. هنوز سرور ندارید؟ یک پلن انتخاب کنید.