إدارة VPS عبر REST API وcurl: الحالة والتشغيل وإعادة التثبيت والتجديد

طلب خادم عبر الـ API يتطلب طلبًا واحدًا، وهذا مشروح في اطلب VPS بأربعة استدعاءات API. هذه الصفحة عن كل ما يأتي بعده: الإجراءات الروتينية التي كنت ستنقر عليها في لوحة التحكم، مكتوبة كأوامر curl يمكنك لصقها في سكربت.

شغّلنا كل أمر أدناه على واجهتنا قبل النشر، والردود نسخ مختصرة مما عاد.

التحضير

متغيران يبقيان الأوامر قصيرة:

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"

المعالج والذاكرة والشبكة والقرص كسلسلة زمنية. قيمة 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"}'

يطبّق وكيل الضيف الاسم الجديد داخل النظام العامل، دون إعادة تشغيل على Linux. إذا كان الخادم متوقفًا، أو أزلت qemu-guest-agent، يعيد الاستدعاء 409 agent_unavailable ولا يتغير شيء.

أعد تثبيت النظام

هذا يمسح القرص. تُلزمك الواجهة بكتابة اسم المضيف الحالي للخادم في confirm، حتى لا يمسح سكربت بمعرّف خدمة خاطئ الجهاز الخطأ:

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، وتقدّم معرّف المعاملة، ونضيفه بعد التحقق. راجع الدفع بـ 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 — راجع كيف يدير وكيل ذكاء اصطناعي الـ VPS الخاص به عبر MCP ومرجع الـ API. ليس لديك خادم بعد؟ اختر خطة.