صيغة المفتاح
apm_<48 base62> (SHA-256)
نطاقات RBAC
full, read + 12 نطاقاً دقيقاً
مستوى التحكم
7 مجالات API + /enterprise
القياس والأحداث
HMAC Webhooks + Prometheus

1. المصادقة، توليد المفاتيح وضوابط الأمان

تعرض كل عقدة Apium Cloud OS مستوى التحكم الخاص بها تحت مسار وحدة تحكم معزول (/<console>/api/v1/...). وتقبل الطلبات بيانات الاعتماد إما عبر X-API-Key: apm_... أو Authorization: Bearer apm_....

  • توليد مفاتيح بإنتروبيا هجينة: عند إصدار مفتاح في الواجهة، يجمع المتصفح إحداثيات حركة الفأرة وتوقيتاتها (client_entropy) ممزوجة مع crypto.getRandomValues. ويدمج الخادم هذه الحمولة مع سلسلتين CSPRNG بطول 32 محرفاً وطابعاً زمنياً بالنانوثانية عبر SHA-256، منتجاً رمز apm_<48 base62>.
  • عرض نص واضح لمرة واحدة وتخزين مهشّر: يُعرض الرمز الخام apm_... مرة واحدة فقط عند الإنشاء. ويُحفظ ملخص SHA-256 الخاص به فقط في مخزن api_keys.
  • ضوابط الشبكة وفترة الصلاحية: يدعم كل مفتاح قائمة سماح بعناوين IP (allowed_ips) وطابع انتهاء صلاحية تلقائي (expires_at).
  • سجل التدقيق وOpenAPI: يُسجَّل كل استدعاء API في سجل التدقيق (GET /api/v1/api-audit)، وتُصدِّر العقدة مواصفة OpenAPI مقروءة آلياً (apium-cloud-os-openapi.json) لتوليد حزم SDK.

2. مصفوفة نطاقات RBAC ومستويات الترخيص

بدلاً من رموز المشرف بنمط الكل أو لا شيء، تفرض Apium Cloud OS مبدأ أقل امتياز عبر نطاقات مفصولة بفواصل. في الإصدار المجاني Lite، يُسمح بالوصول read فقط؛ بينما يتطلب full وجميع نطاقات الكتابة إصدارات Pro أو Ultra أو Extra.

نطاقات مفاتيح API وملفات أقل امتياز

التحكم بالوصول

اجمع بين النطاقات العامة أو على مستوى المورد لعزل بوتات الفوترة، ومراقبي SRE، وأتمتة الموارد البشرية.

النطاق / النمطمستوى الوصولملف المفتاح التشغيلي النموذجي
fullقراءة وكتابة غير مقيدة عبر جميع المجالات (Pro/Ultra/Extra)منسّق رئيسي أو متحكم IaC مخصص
readقراءة فقط شاملة عبر الموارد (باستثناء /system/config)مراقب أسطول مركزي أو لوحة BI خارجية
users:read / users:writeقراءة الحسابات والجلسات / إنشاء، تمديد، سحب، طرد وعمليات جماعيةبوتات فوترة Telegram وSaaS، وتأهيل HR/IAM
groups:read / groups:writeفحص مجموعات المستخدمين / تعيين وتعديل سياسات المجموعاتأتمتة الوصول المؤسسي حسب الأقسام
plans:read / plans:writeسرد باقات التعرفة / إنشاء/حذف الباقات وتطبيق محدّد حركة المرورمزامنة التعرفات التجارية ومحرك سياسات النطاق الترددي
webhooks:read / webhooks:writeسرد أهداف webhook / تسجيل أو إزالة نقاط نهاية HMACتزويد آلي لناقل الأحداث لكل مستأجر
monitoring:readالوصول إلى /overview، /health، /metrics، /sessions، /logs، /api-auditكاشطات Prometheus، Grafana، ومجمّعات SIEM وSOC
system:read / system:writeحالة النظام / وضع السلسلة، الصواعد، الخدمات ووضع الأمانأتمتة تجاوز الفشل SRE ونصوص دورة حياة الخدمات

3. خريطة نقاط النهاية الكاملة عبر 7 مجالات تحكم

تقع جميع المسارات الإدارية تحت /<console>/api/v1 وتغطي السطح التشغيلي الكامل للعقدة:

نقاط النهاية مجمّعة حسب المجال الوظيفي

سطح API

كل نظام فرعي يُدار في واجهة الويب مكشوف لأتمتة API الحتمية.

المجالنقاط النهاية الرئيسيةالقدرات
المستخدمون ودورة الحياة الجماعيةGET/POST /users, GET /users/generate, POST /users/bulk-create, POST /users/bulk-extendإنشاء الحسابات، التزويد الدفعي للأساطيل، والتمديد الجماعي للحصص أو TTLs
التحكم لكل مستخدمGET /users/:id/config, POST /users/:id/extend|revoke|restore|reset-traffic|rotate-token|kick, PUT /users/:id/group|expiration|restrictions, GET /users/:id/sessionsجلب إعدادات العميل، تدوير الرموز، طرد الجلسات الحية، وضبط الحدود لكل مستخدم
الباقات ومحدّد السرعةGET/POST /plans, DELETE /plans/:id, POST /shaper/applyإدارة قوالب التعرفة ودفع قواعد النطاق الترددي/التشكيل الحية
السلسلة والصواعدPUT /cascade/mode, POST /upstreams/check, POST /upstreams/:id/toggle, POST /upstreams/:id/reset-trafficتبديل أوضاع التوجيه المتسلسل، فحص عقد الخروج، تبديل الصواعد، تصفير العدادات
المراقبة والتدقيقGET /overview, GET /health, GET /metrics, GET /sessions, POST /sessions/:id/kick, GET/DELETE /logs, POST /logs/simulate, GET /api-auditفحوصات الصحة، قياسات Prometheus، إنهاء الجلسات الحية، وسجلات تدقيق API
Webhooks والمفاتيحGET/POST /webhooks, DELETE /webhooks/:id, GET/POST /api-keys, DELETE /api-keys/:idدورة حياة برمجية لمشتركي HMAC webhook ومفاتيح API المقيدة بنطاقات
الخدمات، الأمان والترخيصPOST /services/toggle|restart|update-adblock|unban-ip|clear-auth-logs, PUT /settings/security-mode, GET /license/status, POST /license/activateالتحكم بالخدمات، رفع حظر IP في Fail2ban، تحديثات AdBlock، وتفعيل الترخيص
Corporate GatewayGET /enterprise/overview, POST /enterprise/users/:id/toggle, .../enterprise/users/:id, .../enterprise/gateways/:idمستوى تحكم مخصص لمستخدمي Corporate Gateway وعقد البوابة

4. أمثلة عملية للطلبات والأحداث

A. التزويد الجماعي للمستخدمين والتمديد

أنشئ حسابات مرتبطة بباقة تعرفة (plan_id)، أو نفّذ تزويداً دفعياً، أو مدّد الاشتراكات مع الاستعادة التلقائية (auto_restore: true) دون إعادة تشغيل نوى النقل:

curl -X POST -H "X-API-Key: apm_..." \
  -H "Content-Type: application/json" \
  -d '{"username":"client_9042","plan_id":1}' \
  https://node.apium.cloud/<console>/api/v1/users

curl -X POST -H "Authorization: Bearer apm_..." \
  -H "Content-Type: application/json" \
  -d '{"add_days":30,"add_quota_gb":100,"auto_restore":true}' \
  https://node.apium.cloud/<console>/api/v1/users/42/extend

B. نقطة نهاية الاشتراك العامة (ترويسات العملاء القياسية)

تجلب تطبيقات العملاء مثل v2rayNG وNekobox وStreisand وHiddify رابطاً واحداً برمز مميز يعيد ملفات Base64 مع ترويسات الحصة وتاريخ الانتهاء القياسية:

GET /<console>/api/v1/subscriptions/<sub_token>

< HTTP/1.1 200 OK
< Profile-Title: Apium Cloud OS
< Profile-Update-Interval: 12
< Subscription-Userinfo: upload=104857600; download=2147483648; total=107374182400; expire=1798761600

C. Webhooks الموقّعة بـ HMAC-SHA256

بدلاً من استطلاع العقدة كل بضع ثوانٍ، اضبط خلفية الفوترة أو CRM لتلقي أحداث دفع فورية موثّقة عبر X-Apium-Signature:

POST https://billing.example.com/webhooks/apium
X-Apium-Event: user.created
X-Apium-Signature: sha256=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

{
  "event": "user.created",
  "timestamp": "2026-11-14T12:30:00Z",
  "data": { "user": { "id": 42, "username": "client_9042", "protocol": "hysteria2" } }
}

D. مقاييس Prometheus (GET /api/v1/metrics)

اربط أسطولك مباشرة بـ Prometheus وGrafana باستخدام مفتاح monitoring:read لتتبع الجلسات النشطة، وأعداد المستخدمين، وزمن RTT لسلسلة الصواعد:

# TYPE apium_active_sessions gauge
apium_active_sessions 1248
# TYPE apium_users_total gauge
apium_users_total{status="active"} 3410
# TYPE apium_upstream_latency_ms gauge
apium_upstream_latency_ms{id="1",name="NL-AMS-01"} 18

5. سيناريوهات تكامل واقعية

أين تتألق واجهة API في Apium Cloud OS

أنماط التكامل

معماريات إنتاجية شائعة مبنية فوق Apium REST API ومفاتيح RBAC وWebhooks وPrometheus.

السيناريوعناصر API المستخدمةالفائدة التشغيلية
بوتات Telegram وفوترة SaaSمفتاح users:write + POST /users, /users/bulk-create, /extend, Subscriptions + Webhooksتسليم فوري للمفاتيح بعد الدفع، تجديدات آلية، وصفر عمل إداري يدوي
تأهيل الموارد البشرية / IAM المؤسسيusers:write + groups:write + POST /users/:id/kick و/enterprise/...وصول VPN تلقائي عند التوظيف وسحب فوري للجلسة عند إنهاء الخدمة
SRE ومراقبة الأسطولمفتاح monitoring:read + GET /metrics, /health, /api-audit + قائمة سماح IPلوحات Grafana وتنبيهات دون كشف صلاحيات الكتابة
أتمتة السلسلة ومحدّد السرعةsystem:write + plans:write + PUT /cascade/mode, POST /upstreams/check, POST /shaper/applyتجاوز فشل ديناميكي عبر دول الخروج وإنفاذ آلي للنطاق الترددي