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 Gateway | GET /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/extendB. نقطة نهاية الاشتراك العامة (ترويسات العملاء القياسية)
تجلب تطبيقات العملاء مثل 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=1798761600C. 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"} 185. سيناريوهات تكامل واقعية
أين تتألق واجهة 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 | تجاوز فشل ديناميكي عبر دول الخروج وإنفاذ آلي للنطاق الترددي |