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) ליצירת SDKs.
2. מטריצת הרשאות RBAC ורמות רישיון
במקום אסימוני מנהל של הכול-או-כלום, Apium Cloud OS אוכפת גישת הרשאה מינימלית (least-privilege) באמצעות הרשאות (scopes) מופרדות בפסיקים. במהדורת Lite החינמית מותרת גישת read בלבד; full וכל הרשאות הכתיבה דורשות Pro, Ultra או Extra.
הרשאות API Key ופרופילי הרשאה מינימלית
בקרת גישהשלבו הרשאות גלובליות או ברמת משאב לבידוד בוטים של חיוב, מנטרי 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 | סטטוס מערכת / מצב קסקדה, upstreams, שירותים ומצב אבטחה | אוטומציית failover של 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 | ניהול תבניות תעריף ודחיפת כללי רוחב פס/עיצוב חיים |
| קסקדה ו-Upstreams | PUT /cascade/mode, POST /upstreams/check, POST /upstreams/:id/toggle, POST /upstreams/:id/reset-traffic | החלפת מצבי ניתוב קסקדה, בדיקת צומתי יציאה, הפעלה/כיבוי של upstreams ואיפוס מונים |
| ניטור וביקורת | 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. דוגמאות מעשיות לבקשות ואירועים
א. הקצאת משתמשים קבוצתית והארכה
צרו חשבונות המשויכים לתוכנית תעריף (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ב. נקודת קצה ציבורית למנויים (כותרות לקוח סטנדרטיות)
אפליקציות לקוח כגון v2rayNG, Nekobox, Streisand ו-Hiddify מושכות כתובת URL יחידה עם אסימון המחזירה פרופילים ב-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ג. 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" } }
}ד. מדדי Prometheus (GET /api/v1/metrics)
חברו את הצי שלכם ישירות ל-Prometheus ו-Grafana עם מפתח monitoring:read למעקב אחר סשנים פעילים, ספירות משתמשים ו-RTTs של קסקדות במעלה הזרם:
# 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, מנויים + Webhooks | אספקת מפתח מיידית לאחר תשלום, חידושים אוטומטיים, אפס עבודת מנהל ידנית |
| קליטת עובדים ב-HR / 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 | failover דינמי בין מדינות יציאה ואכיפת רוחב פס אוטומטית |