# NexCMP 1.6.1 — full documentation > Complete NexCMP documentation in one file. Source: https://nexcmp.com/ar/docs/ · generated 2026-11-02. --- # ما هو NexCMP {#what-is-nexcmp} NexCMP هو برنامج تثبته على **خادمك الخاص** لتحويل بنيتك التحتية السحابية إلى منتج يمكنك بيعه. ويمنحك ما يلي: - **بوابة عملاء** حيث يقوم المستخدمون بالتسجيل، وشحن الرصيد، وطلب الأجهزة الافتراضية والخدمات الأخرى، وفتح وحدة التحكم، وإنشاء Snapshots والتواصل مع الدعم الفني؛ - **لوحة تحكم للمسؤول** (`/admin`) حيث تدير العملاء، والخطط، والأسعار، والمدفوعات، والبنية التحتية، والإعدادات؛ - **فوترة**: محفظة لكل عميل، واحتساب بالساعة أو بالشهر، وفواتير، وعروض ترويجية، وحصص للموارد؛ - **موزعون بعلامة بيضاء**: علامات تجارية أخرى تبيع سعتك الحوسبية تحت نطاقها الخاص؛ - **API**، وأداة سطر أوامر (`cmp`)، وخادم MCP للأتمتة؛ - ميزتا **AI Chat** (مساعد الدعم) و**AI Agent** (لإدارة الجهاز الافتراضي بلغة طبيعية) اختياريتان. ## ما يتصل به {#what-it-connects-to} لا يستضيف NexCMP الأجهزة الافتراضية بنفسه، بل يدير المنصة التي تقوم بذلك. والـ *source* (المسمى أيضاً مزود الخدمة) يكون واحداً مما يلي: | Source | الاستخدام النموذجي | الدليل | |---|---|---| | Apache CloudStack | سحابة خاصة أو عامة تضم zones وشبكات وموجهات افتراضية وعناوين IP عامة | [CloudStack](https://nexcmp.com/ar/docs/infrastructure/cloudstack/) | | Proxmox VE | خوادم فردية أو مجموعات خوادم تديرها بالفعل | [Proxmox VE](https://nexcmp.com/ar/docs/infrastructure/proxmox/) | تحتاج الوحدات الأخرى إلى بنية تحتية خاصة بها: [خوادم bare-metal](https://nexcmp.com/ar/docs/infrastructure/dedicated/)، و[عقد VPN والبروكسي](https://nexcmp.com/ar/docs/infrastructure/vpn-proxy-nodes/)، و[تخزين كائنات S3](https://nexcmp.com/ar/docs/infrastructure/s3/)، و[Kubernetes وPrivate Cloud](https://nexcmp.com/ar/docs/infrastructure/kubernetes-and-private-cloud/). راجع [متطلبات البنية التحتية](https://nexcmp.com/ar/docs/infrastructure/requirements/) للاطلاع على جدول شامل يغطيها جميعاً. ## كيف تم بناؤه {#how-it-is-built} يتكون NexCMP من برنامج واحد يعمل عبر خدمتي systemd على خادم Ubuntu واحد: - `nexcmp` — خادم الويب: بوابة العملاء، ولوحة تحكم المسؤول، وAPI، ومعالج الإعداد؛ - `nexcmp-vmd` — مشغّل الخلفية: مهام التجهيز التلقائي، والمزامنة مع CloudStack أو Proxmox لديك، ودورات الفوترة. تُحفظ البيانات في `/var/lib/nexcmp` (قواعد بيانات SQLite وملفات)، والإعدادات في `/etc/nexcmp`، والبرنامج في `/opt/nexcmp`. راجع [المعمارية](https://nexcmp.com/ar/docs/infrastructure/architecture/) للاطلاع على الصورة الكاملة. ## الخطوات التالية {#where-to-go-next} 1. تحقق من [المتطلبات](https://nexcmp.com/ar/docs/getting-started/requirements/). 2. احصل على ترخيص — [الترخيص والشراء](https://nexcmp.com/ar/docs/getting-started/license-and-purchase/). 3. قم بـ [التثبيت](https://nexcmp.com/ar/docs/getting-started/installation/)، ثم شغّل [معالج الإعداد](https://nexcmp.com/ar/docs/getting-started/setup-wizard/). 4. اربط منصتك: [CloudStack](https://nexcmp.com/ar/docs/infrastructure/cloudstack/) أو [Proxmox VE](https://nexcmp.com/ar/docs/infrastructure/proxmox/). --- # متطلبات خادم NexCMP {#requirements-for-the-nexcmp-server} تغطي هذه الصفحة الخادم الذي يشغّل NexCMP. أما متطلبات CloudStack أو Proxmox VE أو بنيتك التحتية الأخرى، فتجدها في [متطلبات البنية التحتية](https://nexcmp.com/ar/docs/infrastructure/requirements/). ## الخادم {#server} | العنصر | المتطلب | يتحقق منه برنامج التثبيت | |---|---|---| | نظام التشغيل | Ubuntu **22.04** أو **24.04** | نعم — يتوقف مع ظهور خطأ لأي نظام آخر | | معمارية المعالج (CPU) | x86_64 | نعم | | الذاكرة | 2 GB كحد أدنى (يرفض برنامج التثبيت أقل من 1.8 GB تقريباً) | نعم | | مساحة القرص الفارغة | مساحة 8 GB فارغة على `/` كحد أدنى | نعم | | الصلاحيات | root (`sudo`) | نعم | | الحزم | `curl`، و`ca-certificates`، و`zstd`، و`tar`، و`openssl`، و`python3`، و`openssh-client` — تُثبّت تلقائياً | تُثبّت إذا كانت مفقودة | | مع HTTPS | `nginx` و`certbot` — يُثبّتان تلقائياً ما لم تمرر `--no-nginx` | تُثبّت إذا كانت مفقودة | ::: tip تحديد السعة يعمل التثبيت الصغير (بضع مئات من العملاء) بسلاسة على 2 vCPU / 4 GB RAM. وتستهلك قواعد بيانات SQLite والنُسخ الاحتياطية وتحديثات النظام الاختيارية الجزء الأكبر من مساحة القرص — يُرجى توفير 20 GB أو أكثر لبيئات الإنتاج. ::: ## الشبكة {#network} | الاتجاه | المنفذ | الغرض | |---|---|---| | وارد | 80/tcp | التحقق من Let's Encrypt وإعادة التوجيه إلى HTTPS | | وارد | 443/tcp | بوابة العملاء، ووحدة تحكم الإدارة، وAPI | | وارد | 3000/tcp | معالج الإعداد عند التثبيت لأول مرة وللوصول في حالات الطوارئ فقط — انظر [التثبيت](https://nexcmp.com/ar/docs/getting-started/installation/#the-panel-port-3000) | | صادر | 443/tcp إلى `nexcmp.com` | تفعيل الترخيص، والتحقق اليومي من الترخيص، والتحديثات | | صادر | إلى CloudStack API / Proxmox API لديك | التجهيز والمزامنة | | صادر | 443/tcp إلى موفري خدمات الدفع والبريد الإلكتروني وAI المفعلين لديك | Stripe، وPayPal، وSMTP، وموفر خدمة AI، وغيرها | يحتاج الخادم إلى **عنوان IPv4 عام** إذا كنت تريد من Let's Encrypt إصدار الشهادة مباشرة. إذا كان النطاق يمر عبر وكيل من Cloudflare، فانظر [DNS وCloudflare](https://nexcmp.com/ar/docs/getting-started/dns-and-cloudflare/). ## DNS - **نطاق رئيسي** واحد (على سبيل المثال `cloud.example.com`) — حيث تكون البوابة `https://cloud.example.com/` ووحدة تحكم الإدارة `https://cloud.example.com/admin`. - اختياري: `admin.` و`partner.`. إذا كانت هذه الأسماء تشير إلى الخادم (أو إلى Cloudflare)، فسيضيفها برنامج التثبيت إلى الشهادة. - يجب أن يتطابق النطاق مع النطاق المسجل في ترخيصك. ## غير مطلوب على هذا الخادم {#not-required-on-this-server} يعمل NexCMP كمستخدم خدمة عادي غير مميز الصلاحيات (`nexcmp`). وهو **لا** يحتاج إلى صلاحيات root أثناء التشغيل، ولا إلى Docker، أو خادم قاعدة بيانات منفصل، أو Redis، أو أي برنامج hypervisor. --- # الترخيص والشراء {#license-and-purchase} > **المسار في لوحة الإدارة:** System › Admin › License & updates (`/license`) يتم تفعيل NexCMP عبر **مفتاح ترخيص** تديره في [حساب NexCMP الخاص بك](https://nexcmp.com/licenses). الإصدارات والأسعار الحالية مدرجة في [nexcmp.com/pricing](https://nexcmp.com/pricing)؛ وتوضح هذه الصفحة آلية عمل الترخيص بمجرد الحصول عليه. ## الحصول على ترخيص {#get-a-license} 1. أنشئ حساباً على [nexcmp.com](https://nexcmp.com/register) وتحقق من بريدك الإلكتروني. 2. اختر إصداراً: - **NexCMP Free** — لمشغلي الشبكات الذين يمتلكون ASN خاصاً بهم وشبكة فرعية مسجلة باسمهم. أرسل طلباً عبر [nexcmp.com/deploy](https://nexcmp.com/deploy) (الشركة، ASN، الشبكة الفرعية، نطاق اللوحة). يجب أن يكون البريد الإلكتروني لحسابك على نطاق الشركة المدرج في السجل العام (WHOIS) لـ ASN أو الشبكة الفرعية. تتم مراجعة كل طلب؛ وستتلقى بريداً إلكترونياً عند البت فيه، ولن يظهر مفتاح الترخيص إلا بعد الموافقة. - **NexCMP Source** — ترقية لمرة واحدة، دون الحاجة إلى ASN. راجع [nexcmp.com/pricing](https://nexcmp.com/pricing). 3. افتح صفحة الترخيص الخاصة بك. ستعرض **مفتاح الترخيص** (بالصيغة `NXC-XXXXX-XXXXX-XXXXX-XXXXX`)، و**النطاق الرئيسي**، وأمر تثبيت جاهزاً للاستخدام. ::: warning حافظ على سرية المفتاح يقوم مفتاح الترخيص بتفعيل عملية التثبيت. عامله ككلمة مرور: لا تلصقه في التذاكر أو المحادثات أو لقطات الشاشة. ::: ## محتويات الترخيص {#what-a-license-contains} | الحقل | المعنى | |---|---| | النطاق الرئيسي | اسم المضيف الذي تعمل عليه بوابتك. يتم ربط المفتاح به عند التفعيل. | | Reseller domains | أسماء مضيفين إضافية تُقدَّم كبوابات white-label — راجع [Resellers](https://nexcmp.com/ar/docs/customers/resellers/). | | Updates until | التاريخ الأقصى لتلقي **التحديثات وإصلاحات الأخطاء**. يبدأ ترخيص Free بمدة **1 عام** من تاريخ الموافقة عليه؛ يمكنك تجديده مقابل $99 سنوياً في صفحة الترخيص الخاصة بك. تُقدَّم الإصلاحات الأمنية دائماً، حتى بعد هذا التاريخ. | | Status | `active`، أو suspended / expired / revoked. | ## عند انتهاء العام المجاني {#when-the-free-year-ends} **يستمر البرنامج في العمل** عند تجاوز تاريخ "Updates until": ولا يتأثر العملاء أو الخدمات أو الفوترة بذلك. ستتوقف عن تلقي إصدارات الميزات الجديدة وتحديثات إصلاح الأخطاء (بينما تستمر الإصلاحات الأمنية في الوصول). جدد مقابل $99 سنوياً من صفحة الترخيص الخاصة بك على [nexcmp.com/licenses](https://nexcmp.com/licenses) للمتابعة؛ ويضيف التجديد 12 شهراً إلى تاريخ الانتهاء الحالي. يتضمن NexCMP Free إصلاحات الأخطاء فقط — دون دعم فني ودون تطبيقات. ## ما يوفره NexCMP Source {#what-nexcmp-source-adds} يُعد ترخيص Source ترقية لمرة واحدة لترخيصك بقيمة $1,999: ويشمل الكود المصدري الكامل، وجميع تطبيقات NexCMP (لنظام Android وiOS وWindows وmacOS وLinux ومتصفحات Chrome / Edge / Brave وFirefox) مصممة ومجهزة بعلامتك التجارية، بالإضافة إلى 30 يوم عمل مع مهندس خبير — ترحيل مجاني من VMware أو WHMCS أو لوحة تحكم أخرى، أو إعداد كامل وشامل من الألف إلى الياء. يتم تضمين إصدارات الكود المصدري الجديدة لمدة 12 شهراً؛ وتجديدها بعد ذلك ($99 سنوياً) اختياري، ويظل الكود المصدري الذي قمت بتنزيله ملكاً لك. راجع [شروط ترخيص Source](https://nexcmp.com/legal/source-license/). ## كيف يتحقق التثبيت من ترخيصه {#how-the-installation-checks-its-license} - عند التثبيت، يفعّل الخادم المفتاح لنطاقك ويتلقى **رمزاً موقعاً**. - يتم تجديد الرمز تلقائياً كل **24 ساعة**. ويظل صالحاً لمدة **14 يوماً**، لذا لا ضرر من انقطاع الإنترنت لفترة قصيرة. - يتم التحقق من صحة جميع الإصدارات والرموز عبر توقيع Ed25519 مدمج في البرنامج؛ ويُرفض أي تنزيل تم العبث به. يمكنك التحقق من الحالة في أي وقت من لوحة تحكم المسؤول أو باستخدام `sudo nexcmp status`. ## إذا لم يكن الترخيص صالحاً {#if-the-license-is-not-valid} عند انتهاء صلاحية الرمز، أو تعليق الترخيص، أو عدم تطابق النطاق: - **لا يمكن للعملاء إنشاء خدمات جديدة** وتُظهر لوحة تحكم المسؤول شريط تنبيه؛ - الخدمات قيد التشغيل بالفعل، **والفوترة والعملاء الحاليون لا يتأثرون**؛ - أصلح السبب (أعد توصيل الخادم بالإنترنت، وجدد عبر [nexcmp.com/licenses](https://nexcmp.com/licenses)) ثم انقر فوق **Check now** في License & updates. ## الانتقال إلى خادم أو نطاق جديد {#moving-to-a-new-server-or-domain} قم بالتفعيل على الخادم الجديد باستخدام المفتاح نفسه والنطاق المسجل (راجع [التثبيت](https://nexcmp.com/ar/docs/getting-started/installation/)). لتغيير النطاق المسجل، قم بذلك أولاً عبر صفحة الترخيص الخاصة بك على [nexcmp.com/licenses](https://nexcmp.com/licenses)، ثم أعد تشغيل برنامج التثبيت باستخدام `--domain` الجديد. --- # تثبيت NexCMP {#install-nexcmp} برنامج التثبيت عبارة عن سكريبت فردي يوفره خادم التراخيص الخاص بك. يفحص الجهاز، ويفعّل ترخيصك، وينزّل البرنامج ويتحقق منه، ويثبّت الخدمات ويهيئ nginx (اختيارياً) بشهادة Let's Encrypt. ## قبل أن تبدأ {#before-you-start} - خادم يستوفي [المتطلبات](https://nexcmp.com/ar/docs/getting-started/requirements/)، مع صلاحيات root. - **مفتاح الترخيص** و**النطاق الرئيسي** من [صفحة الترخيص](https://nexcmp.com/licenses) الخاصة بك — راجع [الترخيص والشراء](https://nexcmp.com/ar/docs/getting-started/license-and-purchase/). - سجل DNS للنطاق — راجع [DNS وCloudflare](https://nexcmp.com/ar/docs/getting-started/dns-and-cloudflare/). يمكنك أيضاً التثبيت أولاً وضبط DNS لاحقاً؛ حيث يخبرك برنامج التثبيت بما ينقصك ويمكن إعادة تشغيله ببساطة. ## التثبيت {#install} 1. سجّل الدخول إلى الخادم وانتقل إلى مستخدم root (أو أضف `sudo` في بداية الأمر). 2. شغّل الأمر الموجود في صفحة الترخيص الخاصة بك، والذي يبدو كالتالي: ```bash curl -fsSL https://nexcmp.com/install.sh | sudo bash -s -- \ --license NXC-XXXXX-XXXXX-XXXXX-XXXXX \ --domain cloud.example.com \ --email admin@example.com ``` 3. انتظر حتى تظهر علامات التحقق. يستغرق التثبيت الجديد بضع دقائق؛ حيث يُنشئ التشغيل الأول مخطط قاعدة البيانات وقد يستغرق ما يصل إلى دقيقة على الأقراص البطيئة. 4. اقرأ الملخص في النهاية، حيث يعرض روابط البوابة ولوحة الإدارة، و**رمز الإعداد**، والخطوة التالية. ![اكتمال برنامج التثبيت مع عرض رابط البوابة ورابط الإدارة ورمز الإعداد لمرة واحدة](https://nexcmp.com/ar/docs/images/getting-started/installation-01-finish.webp) ## المعلمات {#parameters} | المعلمة | القيمة الافتراضية | المعنى | |---|---|---| | `--license KEY` | مطلوبة عند أول تثبيت | مفتاح الترخيص. | | `--domain NAME` | مطلوبة عند أول تثبيت | النطاق الرئيسي. يجب أن يطابق الترخيص. تُزال `https://` والمسارات اللاحقة تلقائياً. | | `--email ADDRESS` | لا يوجد | البريد الإلكتروني للتواصل لتلقي إشعارات انتهاء صلاحية Let's Encrypt. بدونه تُسجَّل الشهادة بدون بريد إلكتروني. | | `--port N` | `3000` | المنفذ المحلي للوحة التحكم (1–65535). | | `--no-nginx` | معطّل | عدم تثبيت أو تكوين nginx / TLS. استخدم هذا الخيار إذا كنت تشغّل وكيل عكسي خاصاً بك أو ترغب في إلقاء نظرة على NexCMP أولاً. | | `--behind-cloudflare` | يُكتشف تلقائياً | فرض وضع "النطاق مخدوم عبر وكيل Cloudflare". يُكتشف عادةً من DNS. | | `--channel NAME` | `stable` | قناة الإصدار. | إعادة تشغيل برنامج التثبيت **بدون معلمات** تعيد استخدام المعلمات المحفوظة (`/etc/nexcmp/install.conf`) وتُجري الترقية بأمان، مع الاحتفاظ بالبيانات والإعدادات والحسابات. هذا هو تماماً ما يقوم به `sudo nexcmp update`. ## ما يفعله برنامج التثبيت {#what-the-installer-does} 1. **يفحص الجهاز** — Ubuntu 22.04/24.04، ومعمارية x86_64، وذاكرة وصول عشوائي (RAM) لا تقل عن 2 GB، ومساحة قرص فارغة 8 GB. 2. **يثبّت الحزم** المطلوبة (`curl`، `zstd`، `openssl`، `python3`، `openssh-client` …). 3. **يُنشئ مستخدم الخدمة** `nexcmp` والدلائل: `/opt/nexcmp` (البرنامج، مملوك للمستخدم root، للقراءة فقط بالنسبة للخدمة)، `/etc/nexcmp` (الإعدادات)، `/var/lib/nexcmp` (البيانات)، `/var/log/nexcmp`. 4. **يفعّل الترخيص** للنطاق ويخزن معرّف مثيل ثابت لهذا الجهاز. 5. **ينزّل أحدث إصدار يحق لك الحصول عليه**، ثم يتحقق من تجزئة SHA-256 وتوقيع Ed25519 الخاص به. يُرفض أي إصدار لا يحمل توقيعاً صالحاً، ولا يُرجع النظام أبداً إلى إصدار أقدم من الإصدار الأحدث قيد التشغيل. 6. **يكتب ملفات التكوين ووحدات systemd** (`nexcmp`، `nexcmp-vmd`، `nexcmp-update`) ويبدأ تشغيل الخدمات؛ وينتظر حتى يستجيب `/healthz`. 7. **يُعدّ nginx وTLS** (ما لم يتم تحديد `--no-nginx`): يحصل على شهادة Let's Encrypt عبر certbot (باستخدام تحدي webroot) للنطاق ولكل من `admin.` / `partner.` عندما يتم حل هذه الأسماء أيضاً. إذا كان DNS لا يشير إلى هذا الخادم (أو Cloudflare) بعد، فسيتم تخطي هذه الخطوة مع إظهار تنبيه. 8. **يعرض ملخصاً** يتضمن عناوين URL، وفي حال عدم وجود أي مسؤول بعد، يعرض **رمز الإعداد**. ## منفذ لوحة التحكم (3000) {#the-panel-port-3000} - خلال التثبيت لأول مرة، تستمع اللوحة على `0.0.0.0:3000` لتتمكن من فتح معالج الإعداد عبر `http://:3000/setup`. - بمجرد اكتمال المعالج **و**تفعيل TLS، تستمع اللوحة على `127.0.0.1` فقط؛ ويقوم nginx بتمرير `https://` إليها كوكيل. - لحالات الطوارئ (تعطل nginx، أو خطأ في DNS) يمكنك فتح المنفذ لفترة محددة: `sudo nexcmp open-port 30` (لمدة 30 دقيقة، ثم يُغلق تلقائياً) — أو استخدام نفق SSH: `ssh -L 3000:127.0.0.1:3000 ` ثم التصفح عبر `http://127.0.0.1:3000/`. ::: warning بروتوكول HTTP غير المشفر المنفذ 3000 يعتمد بروتوكول HTTP غير المشفر. استخدمه فقط لمعالج الإعداد على شبكة موثوقة، أو عبر نفق SSH. لا تتركه مفتوحاً. ::: ## التثبيت بدون نطاق عام (للمختبرات أو الاختبار) {#installing-without-a-public-domain-lab-or-test} يمكنك التثبيت على جهاز لا يتوفر له DNS بعد: ```bash curl -fsSL https://nexcmp.com/install.sh | sudo bash -s -- \ --license NXC-XXXXX-XXXXX-XXXXX-XXXXX --domain lab.example.com --no-nginx ``` ثم افتح المعالج عبر نفق SSH (`ssh -L 3000:127.0.0.1:3000 `، وتصفح `http://127.0.0.1:3000/setup`). أعد تشغيل برنامج التثبيت بدون `--no-nginx` بمجرد توفر DNS. ## Docker وKubernetes {#docker-and-kubernetes} لا توجد صورة حاوية منشورة. برنامج التثبيت (تثبيت systemd أصلي) هو طريقة التثبيت المدعومة. ## التحقق {#verify} ```bash sudo nexcmp status ``` يجب أن يظهر لك رقم الإصدار، و`nexcmp: active`، و`nexcmp-vmd: active`، و`healthz: ok`، و— حتى يكتمل المعالج — رمز الإعداد. تابع باستخدام [معالج الإعداد](https://nexcmp.com/ar/docs/getting-started/setup-wizard/). إذا حدث خطأ ما، فراجع [أخطاء التثبيت](https://nexcmp.com/ar/docs/troubleshooting/installation-errors/). --- # DNS وCloudflare {#dns-and-cloudflare} يحتاج NexCMP إلى اسم DNS واحد — وهو **نطاقه الرئيسي** — ويعمل بنمطين. ## النمط A: يشير DNS مباشرة إلى الخادم {#mode-a-dns-points-straight-at-the-server} 1. أنشئ سجل **A** بقيمة `cloud.example.com → ` (وسجل **AAAA** إذا كان الخادم يدعم IPv6). 2. اختياري، إذا كنت تستخدمهما: `admin.cloud.example.com` و`partner.cloud.example.com` للإشارة إلى عنوان IP نفسه. 3. شغّل (أو أعد تشغيل) [برنامج التثبيت](https://nexcmp.com/ar/docs/getting-started/installation/). سيكتشف أن الاسم يشير إلى عنوان IP العام الخاص بالخادم، ويحصل على شهادة Let's Encrypt عبر تحدي HTTP-01 على المنفذ 80. ## النمط B: النطاق ممرر عبر بروكسي Cloudflare {#mode-b-the-domain-is-proxied-by-cloudflare} أنشئ السجلات نفسها مع تفعيل السحابة البرتقالية (**Proxied**). يكتشف برنامج التثبيت أن الاسم لا يُحل إلا إلى عناوين Cloudflare وينتقل تلقائياً إلى نمط Cloudflare: - يظل nginx يستمع على المنفذين 80/443 على خادمك؛ - تتم قراءة عنوان IP الحقيقي للزائر من ترويسة `CF-Connecting-IP` — **فقط** للاتصالات القادمة من نطاقات Cloudflare المعلنة، لمنع تزويره من قِبل أي طرف آخر؛ - يتم الحصول على الشهادة عبر Let's Encrypt (تقوم Cloudflare بتوجيه التحدي إلى خادمك الأصلي)؛ وإذا تعذر ذلك بعد، يتم إنشاء **شهادة أصل موقعة ذاتياً** ليعمل النمط "Full"، مع إمكانية الترقية إلى Let's Encrypt عند إعادة تشغيل برنامج التثبيت لاحقاً. يمكنك فرض هذا النمط باستخدام `--behind-cloudflare`. ::: important تعيين نمط SSL/TLS في Cloudflare في Cloudflare، انتقل إلى **SSL/TLS › Overview** وحدد **Full (strict)** بمجرد أن يُفيد برنامج التثبيت بوجود شهادة Let's Encrypt. في حال استخدام شهادة أصلية موقعة ذاتياً، استخدم **Full**. سيؤدي خيار **Flexible** إلى حدوث حلقات إعادة توجيه متكررة. ::: ::: tip إذا كان خيار "Always Use HTTPS" مفعلاً، يُرسل Cloudflare طلب التحقق إلى المنفذ 443 في خادمك الأصلي. يتعامل برنامج التثبيت مع ذلك بإنشاء شهادة مؤقتة موقعة ذاتياً أولاً، ثم إعادة محاولة Let's Encrypt. ::: ## التحقق من ذلك {#check-it} ```bash dig +short cloud.example.com # A record (a Cloudflare address in mode B) curl -I https://cloud.example.com/healthz sudo certbot certificates # certificate name, domains and expiry ``` تتجدد الشهادات تلقائياً عبر مؤقت certbot. يستخدم التجديد مسار webroot `/var/www/nexcmp-acme`، لذا يجب أن يظل المنفذ 80 متاحاً وقابلاً للوصول (مباشرة أو عبر Cloudflare). ## مشكلات شائعة {#common-problems} | العَرَض | السبب | الحل | |---|---|---| | يُفيد برنامج التثبيت بأن "DNS … does not point to … (nor to Cloudflare) — skipping nginx/TLS" | سجل DNS مفقود أو غير صحيح أو لم يكتمل انتشاره | صحح السجل، وانتظر حتى يكتمل انتشاره، ثم أعد تشغيل برنامج التثبيت. | | يُظهر المتصفح `ERR_TOO_MANY_REDIRECTS` خلف Cloudflare | وضع SSL مضبوط على **Flexible** | اضبطه على **Full (strict)** (أو **Full**). | | خطأ Cloudflare رقم 525/526 | تم رفض شهادة الخادم الأصلي | استخدم **Full** مع شهادة أصلية موقعة ذاتياً، أو **Full (strict)** مع Let's Encrypt. | | تظهر عناوين IP الخاصة بـ Cloudflare فقط لجميع الزوار في السجلات | ليس في وضع Cloudflare | أعد تشغيل برنامج التثبيت باستخدام `--behind-cloudflare`. | المزيد في [أخطاء التثبيت](https://nexcmp.com/ar/docs/troubleshooting/installation-errors/). --- # معالج الإعداد {#setup-wizard} > **الموقع في لوحة الإدارة:** المعالج عبارة عن صفحة مستقلة في `/setup` لا تظهر إلا حتى إنشاء أول مسؤول. بعد ذلك تتوفر الفحوصات نفسها تحت System › Admin › Start (`/setup`). يحول المعالج التثبيت الجديد إلى لوحة تحكم جاهزة للعمل في أربع خطوات قصيرة. ويتم تشغيله على المنفذ 3000 (`http://:3000/setup`) أو، عند تفعيل TLS بالفعل، على `https:///setup`. ::: warning يختفي المعالج بعد الخطوة 3 بمجرد إنشاء المسؤول، يُغلق المعالج ويُحذف رمز الإعداد. للوصول إلى لوحة التحكم بعد ذلك، استخدم وحدة تحكم الإدارة. ::: ## الخطوة 0 — رمز الإعداد {#step-0-—-setup-code} يعرض برنامج التثبيت في النهاية **رمز إعداد يُستخدم لمرة واحدة**. يمكنك قراءته مجددًا عبر: ```bash sudo nexcmp status ``` الْصقه في **Setup code** وانقر على **Continue**. يحمي هذا الرمز المعالج: فلن يتمكن أي شخص يكتشف المنفذ المفتوح من إنشاء المسؤول بدونه. ![الخطوة 0 من معالج الإعداد تطلب رمز الإعداد لمرة واحدة](https://nexcmp.com/ar/docs/images/getting-started/setup-wizard-00-code.webp) ## الخطوة 1 — الترخيص {#step-1-—-license} | الحقل | القيمة | |---|---| | مفتاح الترخيص | `NXC-XXXXX-XXXXX-XXXXX-XXXXX` — مُفعَّل مسبقًا بواسطة برنامج التثبيت، لذا تعرض هذه الخطوة عادةً "Activated for cloud.example.com" | | النطاق الرئيسي | النطاق المسجل في الترخيص | إذا كان برنامج التثبيت قد فعّل الترخيص بالفعل، فسيتعرف عليه المعالج وينتقل إلى الخطوة التالية. وإلا، فأدخل المفتاح والنطاق وانقر على **Activate**. تُعرض الأخطاء باللون الأحمر — راجع [أخطاء التثبيت](https://nexcmp.com/ar/docs/troubleshooting/installation-errors/). ![الخطوة 1 من معالج الإعداد تعرض الترخيص المُفعَّل مسبقًا للنطاق الرئيسي](https://nexcmp.com/ar/docs/images/getting-started/setup-wizard-01-license.webp) ## الخطوة 2 — CloudStack (أو Connect later) {#step-2-—-cloudstack-or-connect-later} لديك خياران: - **الاتصال الآن.** أدخل **API URL** لـ CloudStack (`https://cloudstack.example.com/client/api`)، و**API key** و**Secret key**، وانقر على **Test connection**، ثم حدد **Zone**، و**Guest network for customer VMs**، و**Zone display name**، و**Country** المكون من حرفين. انقر على **Save CloudStack**. - **الاتصال لاحقًا.** انقر على **Connect later**. سيعمل كل شيء آخر؛ ويمكنك ربط CloudStack أو Proxmox VE لاحقًا ضمن Infrastructure. وإلى ذلك الحين، ستذكرك لوحة الحالة بعدم وجود أي مصدر متصل. ![الخطوة 2 من المعالج مع حقول CloudStack API URL وAPI key وSecret key معبأة بقيم تجريبية](https://nexcmp.com/ar/docs/images/getting-started/setup-wizard-02-cloudstack-form.webp) ::: important استخدم حساب CloudStack مخصصًا لا تستخدم مفتاح مسؤول ROOT. أنشئ نطاقًا وحسابًا مخصصين لـ NexCMP واستخدم مفتاح API الخاص به — راجع [CloudStack](https://nexcmp.com/ar/docs/infrastructure/cloudstack/#create-a-dedicated-account-and-api-key). يتحقق المعالج من أن الشبكة المحددة تنتمي إلى المنطقة وإلى حساب هذا المفتاح. ::: ![بعد Test connection: قوائم المنطقة وشبكة الضيوف، وحقلا اسم عرض المنطقة والدولة](https://nexcmp.com/ar/docs/images/getting-started/setup-wizard-02b-cloudstack-picked.webp) إذا كنت تخطط لاستخدام **Proxmox VE** فقط، فاختر **Connect later** واتبع [Proxmox VE](https://nexcmp.com/ar/docs/infrastructure/proxmox/). ## الخطوة 3 — المسؤول والعلامة التجارية {#step-3-—-administrator-and-brand} | الحقل | القواعد | |---|---| | البريد الإلكتروني للمسؤول (تسجيل الدخول) | عنوان بريد إلكتروني صالح. هذا هو اسم مستخدم المسؤول الخاص بك. | | كلمة المرور | 12 حرفًا على الأقل، تتضمن حروفًا وأرقامًا. | | اسم العلامة التجارية | يظهر لعملائك (الافتراضي "Cloud"). حتى 60 حرفًا. | | البريد الإلكتروني للدعم | القيمة الافتراضية هي البريد الإلكتروني للمسؤول. | ![الخطوة 3 من معالج الإعداد مع البريد الإلكتروني للمسؤول، وكلمة المرور، واسم العلامة التجارية، والبريد الإلكتروني للدعم](https://nexcmp.com/ar/docs/images/getting-started/setup-wizard-03-admin.webp) انقر على **Finish setup**. ستتم إعادة تشغيل اللوحة (حوالي 1–2 ثانية) وستنقلك الصفحة إلى تسجيل دخول المسؤول على `https:///admin/`. وإذا لم يستجب هذا العنوان بعد (في انتظار DNS أو TLS)، فستنقلك إلى `/` على العنوان الحالي بدلاً من ذلك. ![معالج الإعداد بعد اكتماله مع رسالة تفيد بإعادة تشغيل اللوحة](https://nexcmp.com/ar/docs/images/getting-started/setup-wizard-03-done.webp) ## ما يقوم معالج الإعداد بتهيئته لك {#what-the-wizard-sets-up-for-you} - اسم العلامة التجارية، ورابط الموقع (`https://`)، ورابط لوحة الإدارة (`https:///admin`)، ورابط وحدة التحكم (`https:///console`)، والبريد الإلكتروني للدعم، واسم المُرسل. - الإعدادات الافتراضية للوحدات المرفقة مع NexCMP: تكون ميزات DDoS & BGP، وAI، وweb SSH قيد **الإيقاف**؛ بينما قياس استهلاك النطاق الترددي قيد **التشغيل**. راجع [Modules](https://nexcmp.com/ar/docs/infrastructure/modules/). - في حال قمت بربط CloudStack: المزود رقم 1، ومنطقته الأولى، وشبكة الضيوف، وزوج مفاتيح العمليات المرفق بالأجهزة الافتراضية للعملاء لتمكينك من تقديم الدعم لهم. التالي: [تسجيل الدخول لأول مرة](https://nexcmp.com/ar/docs/getting-started/first-login/). --- # تسجيل الدخول الأول والخطوات التالية {#first-login-and-next-steps} > **المسار في لوحة الإدارة:** صفحة تسجيل الدخول هي `/admin`؛ بعد تسجيل الدخول تكون صفحة البداية هي Overview › Dashboard. ## العناوين {#addresses} | العنصر | URL | |---|---| | بوابة العملاء | `https:///` | | لوحة تحكم المسؤول | `https:///admin` | | الإعداد / الطوارئ عبر IP | `http://:3000/` (راجع [منفذ اللوحة](https://nexcmp.com/ar/docs/getting-started/installation/#the-panel-port-3000)) | | فحص الحالة التشغيلية | `https:///healthz` | ## تسجيل الدخول {#sign-in} 1. افتح `https:///admin`. 2. أدخل بريد المسؤول الإلكتروني وكلمة المرور اللذين أنشأتهما في معالج الإعداد. 3. ستصل إلى **Dashboard**. سيظهر شريط في الأعلى إذا كان الترخيص غير صالح أو لم يكن هناك أي مصدر متصل. ![صفحة تسجيل دخول المسؤول](https://nexcmp.com/ar/docs/images/getting-started/first-login-01-login.webp) ## قائمة التحقق الموصى بها {#recommended-checklist} نفّذ هذه الخطوات بالترتيب — كل منها ينقلك إلى صفحته المخصصة. | # | المهمة | الصفحة | |---|---|---| | 1 | تفعيل المصادقة الثنائية لحسابك الشخصي | [الأمان](https://nexcmp.com/ar/docs/administration/security/) | | 2 | ربط مصدر بنية تحتية (إذا اخترت "Connect later") | [CloudStack](https://nexcmp.com/ar/docs/infrastructure/cloudstack/) أو [Proxmox VE](https://nexcmp.com/ar/docs/infrastructure/proxmox/) | | 3 | التحقق من المناطق وقوالب الأجهزة / قائمة أنظمة التشغيل | [المناطق](https://nexcmp.com/ar/docs/infrastructure/zones/)، [القوالب](https://nexcmp.com/ar/docs/infrastructure/templates/) | | 4 | مراجعة الخطط والأسعار | [الخطط](https://nexcmp.com/ar/docs/catalog/plans/) | | 5 | إعداد الشعار والألوان والصفحات القانونية | [العلامة التجارية](https://nexcmp.com/ar/docs/customers/branding/)، [الصفحات القانونية](https://nexcmp.com/ar/docs/customers/legal/) | | 6 | إعداد البريد الإلكتروني الصادر وإرسال رسالة تجريبية | [SMTP والبريد الإلكتروني](https://nexcmp.com/ar/docs/administration/smtp-and-emails/) | | 7 | تفعيل قناة دفع واحدة على الأقل واختبار شحن الرصيد | [قنوات الدفع](https://nexcmp.com/ar/docs/billing/payment-channels/) | | 8 | تحديد الوحدات التي تبيعها | [الوحدات](https://nexcmp.com/ar/docs/infrastructure/modules/) | | 9 | إنشاء طلب تجريبي كعميل ثم حذفه | [الطلب](https://nexcmp.com/ar/docs/portal/ordering/) | | 10 | إنشاء أول نسخة احتياطية | [النسخ الاحتياطي والاستعادة](https://nexcmp.com/ar/docs/getting-started/backup-and-restore/) | ## إنشاء طلبك الأول (smoke test) {#create-your-first-order-smoke-test} 1. افتح بوابة العملاء في نافذة خاصة وسجّل حساباً تجريبياً. 2. أضف رصيداً (قسيمة أو دفعة تجريبية). 3. اطلب أصغر خطة في منطقتك. 4. راقب ظهورها في لوحة الإدارة ضمن Services › Virtual Machines، وافتح وحدة التحكم الخاصة بها، ثم قم بحذفها. إذا لم تصل الـ VM إلى حالة *running*، فافتح **Infrastructure › Cloud provider › Sync & errors** واقرأ الخطأ. --- # تحديث NexCMP {#updating-nexcmp} > **الموقع في لوحة الإدارة:** System › Admin › License & updates (`/license`) → بطاقة *Update*. ## ما ستحصل عليه {#what-you-receive} | نوع الإصدار | متى يُتاح | |---|---| | إصلاح أمني | **دائماً**، حتى بعد تاريخ "updates until" الخاص بك | | إصدار ميزات | فقط إذا تم نشره **في أو قبل** تاريخ "updates until" الخاص بك | يمكنك الاطلاع على كلا التاريخين ضمن **License & updates**. قم بتجديد الاستحقاق عبر [nexcmp.com/licenses](https://nexcmp.com/licenses). ## التحديث من لوحة الإدارة {#update-from-the-admin-console} 1. افتح **System › Admin › License & updates**. 2. في بطاقة **Update**، انقر على **Check for update**. تعرض البطاقة الإصدار الحالي، وأحدث إصدار يمكنك تثبيته، ووسم *security* عند الاقتضاء، وسجل التغييرات. 3. انقر على **Update to X.Y.Z** وأكّد العملية. يقوم البرنامج بتنزيل الإصدار، والتحقق من **توقيع SHA-256 وEd25519** الخاص به، واستبدال الملف الثنائي بشكل ذري (مع الاحتفاظ بنسخة `.bak`) وإعادة التشغيل. توقّع فترة توقف تبلغ حوالي **10 ثوانٍ**. 4. أعد تحميل الصفحة وتحقق من الإصدار في أعلى يمين License & updates. ![بطاقة Update التي تعرض الإصدار قيد التشغيل وزر Check for new version](https://nexcmp.com/ar/docs/images/getting-started/updating-01-card.webp) ## التحديث من سطر الأوامر {#update-from-the-command-line} ```bash sudo nexcmp update ``` يقوم هذا بتشغيل برنامج التثبيت المضمّن *داخل الإصدار المثبت حالياً* (وليس سكريبت يتم تنزيله في تلك اللحظة) مع المعلمات المحفوظة من `/etc/nexcmp/install.conf`. ويقوم بتحديث الملف الثنائي، ووحدات systemd، وقوالب nginx، وnode agent، مع الاحتفاظ بالبيانات والإعدادات والحسابات. ::: tip عدم التراجع إلى إصدار أقدم إذا قدّم الخادم إصداراً أقدم من الإصدار قيد التشغيل، فسيحتفظ برنامج التثبيت بالإصدار قيد التشغيل. ::: ## قبل التحديث {#before-you-update} 1. خذ نسخة احتياطية: `sudo nexcmp backup` — راجع [النسخ الاحتياطي والاستعادة](https://nexcmp.com/ar/docs/getting-started/backup-and-restore/). 2. اقرأ سجل التغييرات في بطاقة Update. للاطلاع على التغييرات منذ 1.3، راجع [ملاحظات الإصدار حتى 1.6.1](https://nexcmp.com/ar/docs/getting-started/release-notes/)، بما في ذلك تحديث عميل VPN وقواعد تسعير Bare Metal. 3. نفّذ التحديث خلال فترة هدوء؛ فلن تتأثر الأجهزة الافتراضية قيد التشغيل، ولكن لن يتمكن العملاء من استخدام البوابة لبضع ثوانٍ. ## بعد التحديث {#after-you-update} - شغّل `sudo nexcmp status` وتأكد من أن كلتا الخدمتين نشطتان. - افتح Dashboard للإدارة وصفحة **Needs attention**. - يتم تشغيل عمليات ترحيل قاعدة البيانات تلقائيًا عند أول تشغيل للإصدار الجديد. - إذا كنت تشغل عقد VPN، فحدّث العميل (agent) الخاص بها بشكل منفصل وتحقق من قراءات الاستخدام. يؤدي تحديث اللوحة إلى توفير العميل الجديد، لكنه لا يثبت أن كل عقدة بعيدة تقوم بتشغيله بالفعل. راجع [الحصة المخصصة لبيانات عقدة VPN](https://nexcmp.com/ar/docs/infrastructure/vpn-proxy-nodes/#data-allowance-on-a-vpn-node). إذا فشل التحديث، فراجع [أخطاء التحديث](https://nexcmp.com/ar/docs/troubleshooting/update-errors/). --- # ملاحظات الإصدار {#release-notes} > **الموقع في لوحة الإدارة:** System › Admin › License & updates (`/license`)، بطاقة **Update**. تغطي هذه الملاحظات التغييرات بعد 1.3 حتى **NexCMP 1.6.1**. أنشئ نسخة احتياطية قبل التحديث واستخدم الإصدار المتاح في بطاقة **Update** لتثبيتك. راجع [تحديث NexCMP](https://nexcmp.com/ar/docs/getting-started/updating/) للاطلاع على الأوامر والتحقق من التوقيعات. ## 1.6.1 - **مقاييس Bare Metal:** تعرض صفحة **Overview** للعميل مربعات المعالج (CPU)، والذاكرة (RAM)، ونشاط القرص، والشبكة مع السجل الأخير. تُظهر القياسات المفقودة شرطة وسبباً. تتطلب قراءات الشبكة عدّاد حركة مرور؛ ولا يتم استنتاجها من مخزون عتاد iDRAC. - **خطط Bare Metal النموذجية:** تستخدم أسماء النماذج `BM-40C-`. وتتلقى الخطط النموذجية المدمجة التي لم تقم بتعديلها أسماء محايدة. ويتم الاحتفاظ بالخطط المعدلة، كما تحتفظ الخطة المُشار إليها برمزها. تحقق من عتاد الخادم الفعلي قبل جعل الخطة قابلة للبيع. - **تغييرات الخطة:** تُفرز قائمة طلبات الإدارة على الخادم وتظل إجراءاتها مرئية أثناء التمرير الأفقي. - **الإبلاغ عن خطأ:** يتم تمرير النموذج مع إبقاء أزراره مرئية. ويحافظ حجب كلمة المرور على النص التشخيصي المحيط. - **التحميل:** يتم تحميل موارد الصفحة وبيانات الإدارة شائعة الاستخدام في وقت أبكر لتقليل تأخير التنقل. راجع [إعداد Bare Metal والتسعير وتحكم العملاء](https://nexcmp.com/ar/docs/infrastructure/dedicated/) و[الإبلاغ عن خطأ](https://nexcmp.com/ar/docs/administration/report-a-bug/). ## 1.6.0 - **إعداد Bare Metal:** أدخل شبكات iDRAC، وعنوان خادم ISO، وعنوان استدعاء اللوحة في **Safety › Management network connection**. تحظر القيم النموذجية العمليات المباشرة حتى تتم تهيئتها. - **استضافة ISO:** يُعد `sudo nexcmp dedicated-setup-iso` خادم الويب لملفات ISO على شبكة الإدارة. يمكن لبرنامج التثبيت تثبيت لوحة التحكم (console) وأدوات ISO باستخدام `--baremetal` أو خيارات ISO. تحظر الأدوات المفقودة العمليات المباشرة مع `tools_missing`. - **أسعار Bare Metal:** يبدأ أي تثبيت جديد أو غير مستخدم بأسعار USD. أما التثبيت الذي يحتوي بالفعل على بيانات تسعير بـ VND فيحتفظ بـ VND ويظل بحاجة إلى سعر تحويل USD/VND. لا يؤدي التحديث إلى إعادة تفسير تلك الأسعار الحالية على أنها دولارات. - **صفحة خادم العميل:** التجديد مسبقاً، وجدولة تغيير دورة الفوترة، وطلب تغيير الخطة، وقراءة الفواتير، وعرض بيانات تسجيل الدخول لنظام التشغيل بعد التثبيت. لا يمكن للمالك الجديد رؤية كلمة مرور المالك السابق. - **ملفات تعريف العملاء:** تجمع ثماني علامات تبويب كلاً من نظرة عامة، والخدمات، والفوترة، والحصص، والأمان، والدعم، ونظام الإحالة، والسجلات. تشترك الخدمات في جدول واحد قابل للبحث والفرز. - **إجراءات الخدمة:** تستخدم عمليات القفل، وإلغاء القفل، والإلغاء دون استرداد، أو الإلغاء مع الاسترداد مربع حوار مشتركاً. تعود المبالغ المستردة إلى المحفظة الأصلية أو رصيد الحساب المخصص؛ ولا يتم رد الأموال عبر بوابات الدفع تلقائياً. راجع [Dedicated servers](https://nexcmp.com/ar/docs/infrastructure/dedicated/) و[Managing customers](https://nexcmp.com/ar/docs/customers/managing-customers/). تظل ميزتا BYOIP وربط شبكة فرعية خاصة بالعميل بخادم Bare Metal غير متاحتين في NexCMP. ## 1.5.2 يمكن للمسؤول الرئيسي فتح **Report a bug** بجوار **Docs** وإرسال تذكرة إلى حساب الترخيص دون الحاجة إلى تسجيل دخول منفصل. التشخيصات اختيارية. لا يمكن للموظفين والعملاء ومساعدي الذكاء الاصطناعي إرسال بلاغات عبر هذا الإجراء. راجع [Report a bug](https://nexcmp.com/ar/docs/administration/report-a-bug/). ## 1.5.1 - **استخدام VPN:** ترفع عُقد الوكيل تقارير استهلاك البيانات إلى اللوحة. يُفصل الاشتراك الذي يستنفد حصته من الجيجابايت؛ ويصبح متاحاً مجدداً بعد ترقية سعة النطاق الترددي أو بدء فترة جديدة. تعرض العُقد التي لا تحتوي على تقارير استخدام عبارة **Not measured** ولا يتم فصلها بناءً على استهلاك الجيجابايت. - **وكيل VPN:** يعيد الإصدار 1.5.1 محاولة إرسال بيانات الاستخدام غير المؤكدة، ويرسل تقرير الاستهلاك النهائي عند إيقاف التشغيل، ويغلق الاتصالات المفتوحة عند إيقاف نقطة النهاية. يجب تحديث الوكلاء البعيدين بالإضافة إلى اللوحة. - **إضافات VPN الملغاة:** توقف بيع High IP Reputation وHigh Concurrency وHigh Priority Network. وتُحذف رسومها من مبالغ التجديد المستقبلية للاشتراكات الحالية؛ ولا يتم استرداد مبالغ الفترات السابقة. إذا تم حذف إضافة من الدليل، فتحقق من مبلغ التجديد يدوياً. - **تسميات البروتوكولات:** بروكسي IPv4 HTTP هو HTTP عادي. لا يتم تدوير عناوين IPv4. يوفر المنفذ 443 لبروكسي IPv6 بروتوكول SOCKS5؛ وهو ليس نقطة نهاية لبروكسي HTTPS. - **التثبيت الجديد:** تعيد عملية تهيئة قاعدة البيانات محاولة معالجة تعارضات الترحيل المؤقتة بين اللوحة وعامل التشغيل حتى لا يتطلب حفظ المزود الأول إعادة تشغيل. راجع [VPN and IPv6 proxy nodes](https://nexcmp.com/ar/docs/infrastructure/vpn-proxy-nodes/). ## 1.5.0 تُعد **AI Models** بوابة ووحدة فوترة اختيارية، وتكون معطلة افتراضياً. أضف مصادر النماذج التي تديرها أو المصرح لك بإعادة بيعها، ومزامنة النماذج، وتحديد الأسعار والمسارات، وتفعيل النماذج، ثم ابدأ المبيعات. لا توجد حسابات مزودين أو نماذج أو أسعار مدمجة مسبقاً. وهي منفصلة عن وحدة AI Chat وAI Agent. راجع [AI Models](https://nexcmp.com/ar/docs/infrastructure/ai-models/). ## 1.4.2 يستخدم تثبيت عقدة بروكسي IPv6 البرنامج الخفي ونصوص الشبكة البرمجية المرفقة في حزمة الإصدار. تتطلب اللوحة `sshpass` للتثبيت عبر SSH بكلمة المرور. تدير اللوحة جداول التدوير، ويستبعد إعداد العقدة عنوان البوابة من عمليات التخصيص. يمكن للهوية البصرية تعيين اسم عرض مخصص لخدمة VPN. راجع [VPN and IPv6 proxy nodes](https://nexcmp.com/ar/docs/infrastructure/vpn-proxy-nodes/). ## 1.4.0–1.4.1 - **إدارة الذكاء الاصطناعي:** تتوفر ميزات AI Chat للمسؤولين، وحسابات الذكاء الاصطناعي الشخصية، ومفاتيح API للمسؤولين، وخادم MCP للمسؤولين، وموصلات OAuth، واستيراد/تصدير الإعدادات، وقائمة مراجعة الإعداد. راجع [Configure with AI](https://nexcmp.com/ar/docs/configure-with-ai/overview/). - **الترخيص:** تتضمن مسارات عمل Free وSource الإصدارات الرسمية وإصدارات البناء المخصصة من المصدر. يستخدم الحساب والترخيص والتنزيلات والوثائق `nexcmp.com`. راجع [License and purchase](https://nexcmp.com/ar/docs/getting-started/license-and-purchase/). - **روابط الوثائق:** يفتح خيار **Docs** في لوحة الإدارة الدليل الخاص بالصفحة الحالية. - **العملات:** يتبع التثبيت الجديد لغة العميل افتراضياً. يتم جلب سعر USD/VND من جدول أسعار الصرف العامة أو من سعرك الثابت. راجع [Currency and exchange rates](https://nexcmp.com/ar/docs/catalog/currency-and-exchange-rates/). - **مناطق المصادر المختلطة:** تسري أسعار Cloud Server العامة عندما يتشارك CloudStack وProxmox VE نفس المنطقة. تستخدم الخطط مصدر البنية التحتية الخاص بها. - **الأسعار المشتقة من العروض:** تمثل النسبة المئوية هامش ربح على سعر البيع. ينتج عن هامش ربح بنسبة 40% على تكلفة قدرها $60 سعر بيع قدره $100، وذلك قبل أي تقريب. ## قائمة مراجعة الترقية {#upgrade-checklist} 1. قم بإجراء نسخ احتياطي، واقرأ بطاقة **Update**، ثم حدّث وشغّل `sudo nexcmp status`. 2. حدّث وكلاء VPN وتأكد من أن العُقد ترفع تقارير حركة المرور المقاسة قبل الاعتماد على آلية الفصل بحسب الجيجابايت. 3. في حال استخدام Bare Metal، تحقق من حقول شبكة الإدارة، والأدوات المطلوبة، ووحدة التسعير، والقوالب، ونماذج الخطط قبل فتح باب المبيعات أو بدء التشغيل الفعلي. 4. افتح ملف تعريف العميل وتحقق من قائمة خدماته. راجع المبلغ والتوزيع الأصلي للمدفوعات قبل تأكيد الإلغاء مع الاسترداد. 5. أبقِ الوحدات الاختيارية معطلة حتى تصبح بنيتها التحتية جاهزة. بالنسبة إلى AI Models، تحقق من وجود مزود ونموذج مسعّر وطلب عميل ناجح قبل فتح المبيعات. --- # النسخ الاحتياطي والاستعادة {#backup-and-restore} > **الموقع في لوحة الإدارة:** يظهر System › Admin › Backup (`/backup`) فقط عند تمكين وحدة DDoS & BGP؛ وبالنسبة للتثبيت القياسي، استخدم سطر الأوامر أدناه. ## ما تتضمنه النسخة الاحتياطية {#what-is-backed-up} يُنشئ `sudo nexcmp backup` أرشيفًا مضغوطًا واحدًا يحتوي على: | الجزء | المحتوى | |---|---| | `data/**/*.db` | كل قاعدة بيانات SQLite في `/var/lib/nexcmp`، منسوخة عبر API الخاص بالنسخ الاحتياطي المباشر في SQLite — متسقة حتى أثناء تشغيل اللوحة | | `files.tar` | جميع الملفات الأخرى في `/var/lib/nexcmp` (ملفات الإعدادات، وتحميلات العلامة التجارية، `secrets/`)، باستثناء قواعد البيانات ومجلد `updates/` | | `etc/` | نسخة من `/etc/nexcmp` (إعدادات برنامج التثبيت، ومعرّف النسخة، والمنفذ، والربط) | ::: warning يحتوي الأرشيف على المفاتيح الرئيسية الخاصة بك يحتوي `secrets/` على المفتاح الذي يشفّر مفاتيح API وبيانات اعتماد الدفع وكلمات مرور SMTP المخزنة في قاعدة البيانات. يتم إنشاء الأرشيف بالأذونات `0600`. احفظه مشفرًا خارج الخادم. فبدون هذه المفاتيح، لا يمكن لقاعدة البيانات المستعادة فك تشفير بياناتها السرية. ::: ## إنشاء نسخة احتياطية {#take-a-backup} ```bash sudo nexcmp backup # writes to /var/backups/nexcmp sudo nexcmp backup /mnt/nas/nexcmp # or to another directory ``` يعرض الأمر مسار الأرشيف، على سبيل المثال `/var/backups/nexcmp/nexcmp-backup-20261030-120000.tar.zst`. ### جدولة النسخ الاحتياطي {#schedule-it} ```bash echo '17 3 * * * root /usr/local/bin/nexcmp backup /var/backups/nexcmp && find /var/backups/nexcmp -name "nexcmp-backup-*" -mtime +14 -delete' | sudo tee /etc/cron.d/nexcmp-backup ``` انسخ المجلد خارج الجهاز (Object Storage، أو NAS، أو خادم آخر). ## الاستعادة {#restore} قم بالاستعادة على خادم تم تثبيت NexCMP عليه من **الإصدار نفسه (أو أحدث)**. 1. ثبّت NexCMP باستخدام [برنامج التثبيت](https://nexcmp.com/ar/docs/getting-started/installation/) بالترخيص والنطاق نفسهما، ولكن **لا** تشغّل معالج الإعداد. 2. أوقف الخدمات: ```bash sudo systemctl stop nexcmp-vmd nexcmp ``` 3. فك ضغط الأرشيف في دليل مؤقت: ```bash sudo mkdir /root/restore && sudo tar --zstd -xf nexcmp-backup-20261030-120000.tar.zst -C /root/restore ``` 4. أعد الملفات إلى مكانها: ```bash sudo tar -xf /root/restore/files.tar -C /var/lib/nexcmp sudo cp -a /root/restore/data/. /var/lib/nexcmp/ sudo cp -a /root/restore/etc/. /etc/nexcmp/ sudo chown -R nexcmp:nexcmp /var/lib/nexcmp ``` 5. شغّل الخدمات وتحقق منها: ```bash sudo systemctl start nexcmp nexcmp-vmd sudo nexcmp status ``` 6. سجّل الدخول إلى `https:///admin` باستخدام حساب مسؤول النظام *المنسوخ احتياطيًا*. ::: tip تدرب على العملية نفّذ الخطوات من 1 إلى 6 على خادم احتياطي مرة واحدة، قبل أن تحتاج إليها؛ فالنسخة الاحتياطية التي لم تختبر استعادتها أبدًا ليست سوى مجرد أمنية. ::: ## غير مشمول {#not-included} - إعدادات وشهادات nginx (يُعاد إنشاؤها بواسطة برنامج التثبيت؛ ويُعاد إصدار شهادات Let's Encrypt). - خوادم CloudStack / Proxmox VE الخاصة بك والأجهزة الافتراضية الموجودة عليها — قم بنسخها احتياطيًا باستخدام أدواتها الخاصة. --- # إلغاء تثبيت NexCMP {#uninstall-nexcmp} ::: warning سيفقد العملاء إمكانية الوصول يؤدي إلغاء التثبيت إلى إيقاف البوابة ونظام الفوترة. تستمر الأجهزة الافتراضية على CloudStack أو Proxmox VE في العمل، ولكن لن يديرها أو يفوترها أي شيء. يُرجى إنشاء [نسخة احتياطية](https://nexcmp.com/ar/docs/getting-started/backup-and-restore/) أولاً. ::: ## إزالة البرنامج مع الاحتفاظ بالبيانات {#remove-the-program-keep-the-data} ```bash sudo nexcmp uninstall ``` يؤدي هذا إلى تعطيل وإزالة خدمتي `nexcmp` و`nexcmp-vmd`، وموقع nginx ومقتطفه، و`/opt/nexcmp` والأمر `nexcmp`. **تبقى البيانات** في `/var/lib/nexcmp` و`/etc/nexcmp`، مما يتيح لأي عملية تثبيت لاحقة على نفس الخادم المتابعة من حيث توقفت. ## إزالة كل شيء {#remove-everything} ```bash sudo nexcmp uninstall --purge ``` يحذف بالإضافة إلى ذلك `/var/lib/nexcmp` و`/etc/nexcmp` و`/var/log/nexcmp` ومستخدم النظام `nexcmp`. لا يمكن التراجع عن هذا الإجراء. ## بعد إلغاء التثبيت {#after-uninstalling} - تُترك شهادات Let's Encrypt وحزمتا `nginx` / `certbot` في مكانها. يمكنك إزالة الشهادة باستخدام `sudo certbot delete --cert-name ` إذا أردت. - قم بتحرير النطاق من صفحة التراخيص الخاصة بك على [nexcmp.com/licenses](https://nexcmp.com/licenses) إذا كنت تنوي تفعيله في مكان آخر. - احذف حساب CloudStack المخصص أو رمز Proxmox API المميز الذي تم إنشاؤه لـ NexCMP إذا لم تعد بحاجة إليهما. --- # مرجع أمر `nexcmp` {#nexcmp-command-reference} يضع برنامج التثبيت أداة مساعدة في `/usr/local/bin/nexcmp`. قم بتشغيلها على خادم NexCMP. تتطلب الأوامر التي تُجري تغييرات على النظام صلاحيات `sudo`. (الأداة الخاصة بالعملاء للتعامل مع API هي برنامج مختلف، راجع [cmp CLI](https://nexcmp.com/ar/docs/developers/cmp-cli/)). | الأمر | يتطلب root | الوظيفة | |---|---|---| | `nexcmp status` | لا (تفاصيل إضافية مع `sudo`) | الإصدار، وحالة الخدمة (`nexcmp`، `nexcmp-vmd`)، و`/healthz`، وملخص الترخيص، وحالة المنفذ العام، ورمز الإعداد إذا لم يكتمل معالج الإعداد | | `nexcmp update` | نعم | تشغيل برنامج التثبيت المرفق مع الإصدار المثبت بالمعلمات المحفوظة — راجع [التحديث](https://nexcmp.com/ar/docs/getting-started/updating/) | | `nexcmp backup [dir]` | نعم | النسخ الاحتياطي إلى `/var/backups/nexcmp` (أو `dir`) — راجع [النسخ الاحتياطي والاستعادة](https://nexcmp.com/ar/docs/getting-started/backup-and-restore/) | | `nexcmp uninstall [--purge]` | نعم | إزالة الخدمات والبرنامج؛ كما يزيل `--purge` البيانات — راجع [إلغاء التثبيت](https://nexcmp.com/ar/docs/getting-started/uninstall/) | | `nexcmp open-port [minutes]` | نعم | وضع **طوارئ**: الاستماع على منفذ اللوحة (الافتراضي 3000) على جميع واجهات الشبكة لمدة 1–1440 دقيقة (الافتراضي 30)، ثم الإغلاق تلقائياً | | `nexcmp close-port` | نعم | إغلاق نافذة الطوارئ الآن | | `nexcmp fix-owner` | نعم | إعادة ملكية الملفات في `/var/lib/nexcmp` التابعة لـ root إلى المستخدم `nexcmp` | ## `nexcmp status` ```text Version : 1.6.1 nexcmp : active nexcmp-vmd : active healthz : ok License : active · domain cloud.example.com · token valid until 2026-11-12 · updates until 2027-10-30 Public port: 127.0.0.1 only (nginx proxy; emergency: sudo nexcmp open-port) ``` إذا كانت الملفات الموجودة في دليل البيانات مملوكة لـ root (على سبيل المثال تم إنشاؤها عبر تشغيل أمر `nexcmp` آخر باستخدام `sudo` بصلاحيات root)، فسيقوم `status` بطباعة تحذير، لأن مستخدم الخدمة لا يمكنه قراءتها — وتظهر هذه المشكلة عادةً بعرض الترخيص لرمز HTTP 421. قم بالإصلاح عبر `sudo nexcmp fix-owner`. كما يتم تطبيق الإصلاح نفسه تلقائياً عند كل بدء تشغيل للخدمة. ## الوصول في حالات الطوارئ {#emergency-access} عند تعطل النطاق أو nginx أو TLS، يظل بإمكانك الوصول إلى اللوحة: ```bash sudo nexcmp open-port 30 # http://:3000/ for 30 minutes sudo nexcmp close-port # close it earlier ``` طريقة أكثر أماناً، دون فتح أي شيء: `ssh -L 3000:127.0.0.1:3000 user@server` وتصفح `http://127.0.0.1:3000/`. ## البيئة {#environment} | المتغير | يُستخدم لـ | |---|---| | `NEXCMP_BASE` | تجاوز عنوان URL الأساسي لخادم الترخيص (الافتراضي `https://nexcmp.com`)؛ للاختبار فقط | الملفات والأدلة: البرنامج `/opt/nexcmp`، والتكوين `/etc/nexcmp`، والبيانات `/var/lib/nexcmp`، وسجلات الأحداث `/var/log/nexcmp` و`journalctl -u nexcmp -u nexcmp-vmd`. --- # متطلبات البنية التحتية {#infrastructure-requirements} > **الموقع في لوحة الإدارة:** Infrastructure (منطقة القائمة اليسرى) و System › Admin › License & updates (`/license`) لتمكين الوحدات. تسرد هذه الصفحة ما تحتاجه كل وحدة **خارج** خادم NexCMP. بالنسبة للخادم نفسه (Ubuntu، والذاكرة، والقرص، والمنافذ) راجع [متطلبات خادم NexCMP](https://nexcmp.com/ar/docs/getting-started/requirements/). ولتمكين الوحدات، راجع [الوحدات](https://nexcmp.com/ar/docs/infrastructure/modules/). ## وحدة تلو الأخرى {#module-by-module} | الوحدة | الحد الأدنى للبنية التحتية | التفاصيل | |---|---|---| | **الأجهزة الافتراضية على CloudStack** | Apache CloudStack 4.23 (تم اختباره)، وKVM، ومنطقة متقدمة (Advanced Zone) مزودة بشبكة ضيوف ونطاق IP عام؛ ونطاق وحساب مخصصان مع مفتاح API (يُحظر استخدام ROOT نهائياً)؛ وقالب جاهز واحد وعرض خدمة واحد على الأقل | [CloudStack](https://nexcmp.com/ar/docs/infrastructure/cloudstack/) | | **الأجهزة الافتراضية على Proxmox VE** | Proxmox VE 9.x (تم التحقق على 9.2)؛ ورمز API بدور مخصص؛ ومساحة تخزين تدعم الاستنساخ؛ وجسر شبكة (bridge)؛ وكتلة IPv4 مع بوابة توجيه؛ وقالب cloud-init واحد لكل نظام تشغيل وكل عقدة | [Proxmox VE](https://nexcmp.com/ar/docs/infrastructure/proxmox/) | | **قوالب أنظمة التشغيل** | CloudStack: جهاز بناء بنظام Linux مزود بـ libguestfs وخادم ويب للصورة. Proxmox VE: قوالب cloud-image مع guest agent | [قوالب أنظمة التشغيل](https://nexcmp.com/ar/docs/infrastructure/templates/) | | **Bare metal / Dedicated Server** | خوادم Dell مزودة بـ iDRAC 9 يمكن الوصول إليها عبر HTTPS (Redfish) من اللوحة على شبكة إدارة؛ وخادم HTTP على تلك الشبكة يقدم ملفات ISO؛ ومجلدات ISO قابلة للكتابة لخدمة NexCMP | [الخوادم المخصصة](https://nexcmp.com/ar/docs/infrastructure/dedicated/) | | **AI Models** | مصدر نماذج واحد أو أكثر مصرح لك بإعادة بيعه، مع API متوافق مع OpenAI أو متوافق مع Anthropic ومفتاحك الخاص؛ واتصال HTTPS صادر (المنفذ 443، اسم نطاق عام) من اللوحة إلى كل مصدر، أو بوابة داخلية مدرجة ضمن Allowed internal hosts؛ دون الحاجة إلى GPU أو أجهزة خاصة | [AI Models](https://nexcmp.com/ar/docs/infrastructure/ai-models/) | | **VPN** | مضيف Linux واحد أو أكثر (x86_64، وsystemd، وصلاحيات root) بعناوين IPv4 عامة على الواجهة أو موجهة إليها، مع اتصال HTTPS صادر إلى لوحتك | [عقد VPN والبروكسي](https://nexcmp.com/ar/docs/infrastructure/vpn-proxy-nodes/) | | **IPv6 Proxy** | مضيفو Linux (x86_64، وsystemd، و`nft`، و`ip`، و`ss`، و`sysctl`) بعنوان IPv4 عام، ومنافذ 80 و443 و60001-65535 شاغرة، وبادئة IPv6 من /32 إلى /64 تعمل لحركة المرور الصادرة؛ مع وصول SSH بكلمة مرور للتثبيت لمرة واحدة | [عقد VPN والبروكسي](https://nexcmp.com/ar/docs/infrastructure/vpn-proxy-nodes/) | | **Object Storage (S3)** | عنقود Ceph مزود بـ RADOS Gateway (RGW)، ومستخدم Admin Ops، ونقطة نهاية HTTPS عامة على المنفذ 443 | [S3](https://nexcmp.com/ar/docs/infrastructure/s3/) | | **Kubernetes** | CloudStack مع تفعيل خدمة Kubernetes Service (CKS)، وملف ISO واحد على الأقل لإصدار Kubernetes، وعرض خدمة مجاني لـ control-plane بمواصفات 2 vCPU و2048 MB بالضبط | [Kubernetes وPrivate Cloud](https://nexcmp.com/ar/docs/infrastructure/kubernetes-and-private-cloud/) | | **Private Cloud** | CloudStack مع عرض VPC وعرض شبكة واحد لكل خطة نطاق ترددي (بالإضافة إلى عرض مقفل بسرعة 1 Mbps) | [Kubernetes وPrivate Cloud](https://nexcmp.com/ar/docs/infrastructure/kubernetes-and-private-cloud/) | | **OS & ISO Images** | CloudStack بحيث يمكن لجهاز VM للتخزين الثانوي الوصول إلى الإنترنت لتنزيل صور العملاء (روابط مباشرة، دون إعادة توجيه)؛ مع تمكين حساب CloudStack من تسجيل القوالب وملفات ISO | [الوحدات](https://nexcmp.com/ar/docs/infrastructure/modules/) | | **Bandwidth** | لا يلزم أي شيء إضافي مع المصدر الافتراضي: يُقرأ الاستهلاك من إحصاءات VM في CloudStack. ولا يتم احتساب استهلاك أجهزة VM على Proxmox VE | [Bandwidth](https://nexcmp.com/ar/docs/catalog/bandwidth/) | | **AI Chat and AI Agent** | واجهة API متوافقة مع OpenAI (عنوان URL الأساسي والنموذج والمفتاح) يمكن لخادم اللوحة الوصول إليها. لا توجد برامج إضافية على خوادمك | [مزودو AI](https://nexcmp.com/ar/docs/ai/ai-providers/) | | **DDoS & BGP** | حزمة إضافية تتطلب مضيف موجه طرفي (edge router) مع برامج خلفية (daemons) تعمل بصلاحيات root (توجيه BGP، والتصفية، وإحصاءات التدفق). وهي ليست جزءاً من التثبيت القياسي | [الوحدات](https://nexcmp.com/ar/docs/infrastructure/modules/) | | **DDoS Shield** | حزمة DDoS & BGP الإضافية | [الوحدات](https://nexcmp.com/ar/docs/infrastructure/modules/) | | **طرفية Web SSH** | خدمة وكيل SSH منفصلة ومسار مخصص لها. وهي ليست جزءاً من التثبيت القياسي؛ ولا يحتاجها AI Agent | [الوحدات](https://nexcmp.com/ar/docs/infrastructure/modules/) | ## مسارات الشبكة في لمحة {#network-paths-at-a-glance} | من | إلى | المنفذ | الغرض | |---|---|---|---| | خادم اللوحة | خادم إدارة CloudStack | 443 أو 8080 (حسب طريقة نشره لديك) | API | | خادم اللوحة | عقدة Proxmox VE | 8006/tcp | واجهة API ووحدة التحكم | | خادم اللوحة | Dell iDRAC | 443/tcp (ومنفذ VNC، الافتراضي 5901) | Redfish ووحدة التحكم | | iDRAC | خادم ويب لملفات ISO | منفذ HTTP الذي تختاره (على سبيل المثال 8080) | الوسائط الافتراضية | | خادم اللوحة | Ceph RGW | 443/tcp | Admin Ops | | خادم اللوحة | عقدة وكيل IPv6 | منفذ SSH الذي تدخله | تثبيت لمرة واحدة | | عقد VPN والوكيل | اللوحة (عبر nginx) | 443/tcp | التسجيل ونبضات الحياة والتكوين | | العملاء | عقد VPN والوكيل | المنافذ 65001-65535 لكل عنوان IP لـ (VPN)؛ والمنافذ 80 و443 و60001-65535 لـ (وكيل IPv6) | الخدمة نفسها | ::: tip إبقاء شبكات الإدارة خاصة يجب أن تكون عناوين إدارة iDRAC ومراقب الأجهزة الافتراضية (Hypervisor) على شبكة لا يمكن للعملاء الوصول إليها. يرفض NexCMP عناوين iDRAC الخارجة عن النطاقات الخاصة المسموح بها. ::: ## قائمة التحقق قبل البدء بالبيع {#checklist-before-you-sell} 1. البنية التحتية خلف الخدمة الأولى متصلة و**Test connection** تظهر باللون الأخضر. 2. المنطقة جاهزة للبيع (راجع [Zones](https://nexcmp.com/ar/docs/infrastructure/zones/)): خادم خلفي نشط وخطة وقالب جاهز. 3. تم تكوين قناة دفع (راجع [Payment channels](https://nexcmp.com/ar/docs/billing/payment-channels/)). 4. البريد الإلكتروني يعمل (راجع [SMTP and e-mails](https://nexcmp.com/ar/docs/administration/smtp-and-emails/)). 5. لقد قمت بإنشاء طلب تجريبي واحد وحذفت الجهاز الافتراضي. --- # البنية المعمارية {#architecture} > **الموقع في لوحة الإدارة:** هذه صفحة مرجعية. الخدمات الموضحة هنا مرئية باستخدام `sudo nexcmp status`؛ ويتم تكوين الاتصالات ضمن Infrastructure وSystem › Settings. ## المخطط التوضيحي {#the-picture} ![البنية المعمارية لـ NexCMP: يصل العملاء إلى nginx عبر DNS واختياريًا Cloudflare، ويعيد nginx التوجيه إلى اللوحة على المنفذ 3000، وتتصل اللوحة وworker بـ CloudStack وProxmox VE وiDRAC وCeph وبوابات الدفع وSMTP ومزود الذكاء الاصطناعي، وتتصل عقد VPN ووكيل IPv6 باللوحة](https://nexcmp.com/ar/docs/images/infrastructure/architecture.svg) ### شرح المخطط بالتفصيل {#the-same-diagram-in-words} 1. يفتح العميل أو المسؤول `https://cloud.example.com` (البوابة) أو `https://cloud.example.com/admin` (لوحة الإدارة) أو يستدعي REST API. يوجّه نظام DNS الاسم إلى خادمك، أو إلى Cloudflare الذي يمرر الطلبات إليه كوكيل. 2. يستمع **nginx** على خادم اللوحة إلى المنفذين 80 (لإعادة التوجيه وتجديد الشهادات) و443 (TLS) ويمرر كل طلب إلى **اللوحة** على `127.0.0.1:3000`. بعد معالج الإعداد الأولي، تستمع اللوحة إلى واجهة الاسترجاع (loopback) فقط. 3. تتولى **اللوحة** (`nexcmp.service`) تقديم بوابة العملاء ولوحة الإدارة وREST API ومعالج الإعداد والملفات القابلة للتنزيل التي تحتاج إليها العقد (ملف binary للعميل، ونص التثبيت البرمجي، وأداة سطر الأوامر `cmp`). وتتحقق أيضًا من ترخيصك مرة واحدة يوميًا. 4. يستمع **worker** (`nexcmp-vmd.service`) على `127.0.0.1:8112`، وهو محلي فقط. ويتولى تشغيل كل ما يستغرق وقتاً أو يجب تنفيذه وفق جدول زمني: مهام التهيئة، والمزامنة مع CloudStack وProxmox VE، ودورات الفوترة، وجمع بيانات استهلاك النطاق الترددي، واتصالات وحدة تحكم المتصفح. 5. يُجري NexCMP اتصالات صادرة من هاتين العمليتين إلى: **CloudStack** (management API)، و**Proxmox VE** (واجهة API على المنفذ 8006 مع تثبيت الشهادة certificate pinned)، و**Dell iDRAC** (بروتوكول Redfish عبر HTTPS على شبكة الإدارة)، و**Ceph RGW** (بروتوكول S3 وAdmin Ops عبر HTTPS)، و**بوابات الدفع** (Stripe وPayPal وUSDT ومزودو التحويلات البنكية، والذين يتصلون أيضاً بعناوين webhook لديك)، و**خادم SMTP الخاص بك**، و**مزود AI** بواجهة API متوافقة مع OpenAI، واختيارياً **Telegram**. 6. تُشغّل **عُقد VPN** `cmp-agent`. وتُسجَّل كل عقدة لمرة واحدة برمز يُستخدم لمرة واحدة، ثم ترسل إشارة نبض heartbeat كل 5 ثوانٍ عبر HTTPS إلى لوحة التحكم وتتلقى إعداداتها في الرد. وتُثبَّت **عُقد بروكسي IPv6** لمرة واحدة بواسطة لوحة التحكم عبر SSH، ثم تسحب إعداداتها من اللوحة. 7. يتم حفظ الحالة في قواعد بيانات SQLite وبضعة ملفات في `/var/lib/nexcmp`. كما تُخزن بيانات الاعتماد الخاصة بـ CloudStack وProxmox وS3 وiDRAC ومزود AI مشفرة (AES-256-GCM) مع ملفات المفتاح الرئيسي في نفس المكان. ## الخدمات والعمليات {#services-and-processes} | العملية | يعمل بصلاحية | يستمع على | الوظيفة | |---|---|---|---| | `nginx` | root (عمال `www-data`) | 80, 443 | TLS، وإعادة التوجيه، والوكيل (proxy) إلى لوحة التحكم | | `nexcmp` | `nexcmp` | 3000 (جميع الواجهات أثناء التثبيت الأول، ثم `127.0.0.1`) | البوابة، ولوحة تحكم المشرف، وAPI، ومعالج الإعداد، والتنزيلات | | `nexcmp-vmd` | `nexcmp` | `127.0.0.1:8112` | المهام، والمزامنة، والفوترة، والنطاق الترددي، ووحدة التحكم | | `nexcmp-update` | root | لا يوجد | تطبيق التحديثات التي تطلبها لوحة تحكم المشرف (تنتظر وحدة مسار الطلب) | | `cmp-agent` (على عُقد VPN) | root | منافذ استماع VPN | إرسال التقارير إلى لوحة التحكم، وتشغيل مستمعي البروكسي على عناوين IPv4 العامة | تعمل لوحة التحكم والـ worker كمستخدم عادي دون أي قدرات Linux capabilities، مع نظام ملفات للقراءة فقط باستثناء `/var/lib/nexcmp` و`/var/log/nexcmp`. ولا يحتاجان إلى صلاحيات root، ولا Docker، ولا قاعدة بيانات منفصلة، ولا Redis. ## الملفات ومواقعها {#files-and-where-they-are} | المسار | المحتوى | |---|---| | `/opt/nexcmp` | البرنامج: الإصدارات، و`bin/`، والملفات المشتركة مثل منشئ القوالب. تعود ملكيته للمستخدم root، وهو للقراءة فقط بالنسبة للخدمة. | | `/etc/nexcmp` | إعدادات برنامج التثبيت (`install.conf`)، والمنفذ وربط الواجهات (`nexcmp.env`). | | `/var/lib/nexcmp` | قواعد بيانات SQLite، ومواد العلامة التجارية المرفوعة، ومجلد تنزيل العميل agent، وحالة الترخيص، وملفات المفتاح الرئيسي. احرص على نسخ هذا المسار احتياطياً. | | `/var/log/nexcmp` | سجلات الأحداث. | راجع [النسخ الاحتياطي والاستعادة](https://nexcmp.com/ar/docs/getting-started/backup-and-restore/). يجب نسخ ملفات المفتاح الرئيسي احتياطياً مع قواعد البيانات، وإلا فلن تتمكن قاعدة البيانات المستعادة من فك تشفير بيانات الاعتماد المخزنة فيها. ## اتجاهات الاتصال {#who-connects-to-whom} | الاتجاه | المسار | المنفذ | ملاحظات | |---|---|---|---| | من العميل إلى لوحة التحكم | الإنترنت، وDNS، وCloudflare (اختياري)، وnginx | 443 | راجع [DNS وCloudflare](https://nexcmp.com/ar/docs/getting-started/dns-and-cloudflare/). | | من لوحة التحكم إلى خادم الترخيص | `nexcmp.com` | 443 | التفعيل، والتحقق اليومي، والتحديثات. | | من لوحة التحكم إلى CloudStack | API | 443 أو 8080 | تستخدم وحدة تحكم الجهاز الافتراضي وميزات النطاق الترددي وKubernetes نقطة النهاية ذاتها. | | من لوحة التحكم إلى Proxmox VE | واجهة API ووحدة تحكم WebSocket | 8006 | شهادة مثبتة عبر SHA-256. | | من لوحة التحكم إلى iDRAC | Redfish | 443، VNC 5901 | شبكة الإدارة فقط. | | من iDRAC إلى خادم ISO | HTTP | المنفذ الخاص بك | يقوم iDRAC بسحب ملف ISO. | | من اللوحة إلى Ceph RGW | Admin Ops | 443 | | | من اللوحة إلى SMTP | SMTP | 587 أو 465 | | | من اللوحة إلى مزود الذكاء الاصطناعي | HTTPS | 443 | فقط عند تفعيل وحدة الذكاء الاصطناعي. | | من بوابة الدفع إلى اللوحة | Webhook | 443 | استدعاءات الرد من Stripe وPayPal. | | من العقدة إلى اللوحة | `cmp-agent` | 443 | التسجيل، نبضات القلب، والترقية. | | من اللوحة إلى عقدة وكيل IPv6 | SSH | المنفذ الذي تدخله | للتثبيت لمرة واحدة فقط. | ## أهمية ذلك {#why-it-matters} - **اللوحة التي يمكن الوصول إليها هي لوحة يمكن مهاجمتها.** أبقِ المنفذ 3000 مغلقا بمجرد اكتمال معالج الإعداد. يقوم برنامج التثبيت بذلك بالفعل عند تفعيل TLS. - **يجب أن يكون worker قيد التشغيل** لإنشاء أي شيء أو فوترته. يعرض `sudo nexcmp status` كلتا الخدمتين وفحص الحالة. - **خطط لجدران الحماية الصادرة.** إذا كانت حركة المرور الصادرة من خادم اللوحة تخضع للتصفية، فاسمح بالوجهات الواردة في الجدول أعلاه. - **تظل حركة مرور الإدارة بعيدة عن المسار العام.** تنتقل الاتصالات بـ CloudStack وProxmox VE وiDRAC وCeph مباشرة من خادم اللوحة إلى تلك الأنظمة، دون المرور عبر nginx أو Cloudflare إطلاقا. --- # الوحدات {#modules} > **المسار في لوحة الإدارة:** System › Admin › License & updates (`/license`)، البطاقة **Module**. ## الوظيفة {#what-it-does} الوحدة هي خدمة أو ميزة يمكنك تشغيلها أو إيقاف تشغيلها ككل. تكون الوحدة المتوقفة (**off**) مخفية من قائمة الإدارة ولا يمكن للعملاء شراؤها؛ وتستجيب مسارات API الخاصة بها بـ `404 module_disabled` عندما تكون الوحدة إضافة برمجية. يؤدي تشغيل الوحدة فقط إلى إتاحة الميزة: ولا يزال يتعين توصيل البنية التحتية الخاصة بها (راجع العمود الأخير). ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | الحساب | مسؤول بصلاحية كتابة. يمكن للموظفين ذوي صلاحية القراءة فقط رؤية مفاتيح التبديل ولكن لا يمكنهم تغييرها. | | البنية التحتية | راجع الجدول: تسرد كل وحدة متطلباتها. | | يعتمد على | تتطلب بعض الوحدات وحدات أخرى (تتطلب DDoS Shield وحدة DDoS & BGP). | ## تجهيز البنية التحتية {#prepare-the-infrastructure} غير مطلوب لمفتاح التبديل نفسه. قم بتوصيل البنية التحتية لكل وحدة كما هو موضح في الصفحة المرتبطة في الجدول. ## الربط في NexCMP {#connect-in-nexcmp} 1. افتح **System › Admin › License & updates** وانتقل إلى البطاقة **Module**. توضح البطاقة أن الوحدات المعطلة تكون مخفية من قائمة الإدارة ولا يمكن للعملاء شراؤها. 2. استخدم مفتاح تبديل الوحدة. تؤكد الصفحة **Saved: reloading menu** وتعيد التحميل، بحيث تتغير القائمة على الفور. ![بطاقة Module في License & updates مع مفتاح تبديل لكل وحدة](https://nexcmp.com/ar/docs/images/infrastructure/modules-01-license-modules.webp) ### الوحدات {#the-modules} | الوحدة (كما تظهر) | القيمة الافتراضية | ما تضيفه | المتطلبات | الصفحة | |---|---|---|---|---| | **Virtual Machines** | مفعلة دائما | كتالوج الأجهزة الافتراضية، الطلبات، وحدة التحكم، اللقطات | CloudStack أو Proxmox VE | [CloudStack](https://nexcmp.com/ar/docs/infrastructure/cloudstack/), [Proxmox VE](https://nexcmp.com/ar/docs/infrastructure/proxmox/) | | **Bandwidth** | **مفعّل** | الحصص، الإضافات، التنبيهات وإجراءات تجاوز الحد للأجهزة الافتراضية وKubernetes وS3 | لا شيء إضافي (إحصاءات أجهزة CloudStack الافتراضية) | [Bandwidth](https://nexcmp.com/ar/docs/catalog/bandwidth/) | | **OS & ISO Images** | معطّل | تسجيل العملاء لصور أنظمة التشغيل وملفات ISO الخاصة بهم، مع الفوترة لكل جيجابايت | CloudStack؛ اتصال بالإنترنت لجهاز التخزين الثانوي الافتراضي الخاص به | [المتطلبات](https://nexcmp.com/ar/docs/infrastructure/requirements/) | | **Kubernetes** | معطّل | مجموعات Kubernetes (CKS) | CloudStack مع تفعيل CKS | [Kubernetes وPrivate Cloud](https://nexcmp.com/ar/docs/infrastructure/kubernetes-and-private-cloud/) | | **Private Cloud** | معطّل | VPC مع خطط نطاق ترددي مخصص | عروض شبكات وVPC في CloudStack | [Kubernetes وPrivate Cloud](https://nexcmp.com/ar/docs/infrastructure/kubernetes-and-private-cloud/) | | **Object Storage** | معطّل | حسابات S3 على Ceph RGW، بالدفع حسب الاستخدام | Ceph RGW ومنطقة تتضمن خدمة S3 | [S3](https://nexcmp.com/ar/docs/infrastructure/s3/) | | **VPN** | معطّل | VPN على عقدك الخاصة | عُقد تشغّل `cmp-agent` | [عقد VPN والبروكسي](https://nexcmp.com/ar/docs/infrastructure/vpn-proxy-nodes/) | | **IPv6 Proxy** | معطّل | وكيل IPv6 على عقدك الخاصة | عُقد وكيلة مع بادئة IPv6 | [عقد VPN والبروكسي](https://nexcmp.com/ar/docs/infrastructure/vpn-proxy-nodes/) | | **Bare Metal** | معطّل | خوادم Dell عبر iDRAC: الطلبات، تثبيت نظام التشغيل، وحدة التحكم، الطاقة | iDRAC 9 على شبكة إدارة | [الخوادم المخصصة](https://nexcmp.com/ar/docs/infrastructure/dedicated/) | | **AI Models** | معطّل | بوابة لبيع الوصول إلى نماذج الذكاء الاصطناعي: مفتاح واحد لعدة نماذج، وأسعار مخصصة لكل نموذج، وحدود للاستخدام، وسجلات، وفوترة عبر المحفظة | مصادر نماذج توفرها بنفسك: API متوافق مع OpenAI أو متوافق مع Anthropic مع مفتاحك الخاص | [AI Models](https://nexcmp.com/ar/docs/infrastructure/ai-models/) | | **AI** | معطّل | AI Chat (دعم مؤتمت) وAI Agent (إدارة الأجهزة الافتراضية بلغة طبيعية) | مزود متوافق مع OpenAI | [مزودو AI](https://nexcmp.com/ar/docs/ai/ai-providers/) | | **DDoS Shield** | معطّل | حماية IP للعملاء؛ تتطلب DDoS & BGP، لذا يظل مفتاح التبديل الخاص بها معطلاً بدونها | حزمة DDoS & BGP الإضافية | أدناه | | **DDoS & BGP** | معطّل، **إضافة** | وحدة تحكم راوتر الحافة: BGP وRTBH وXDP والجلسات وحركة مرور الحافة | مضيف حافة مع برامج خلفية تعمل بصلاحيات root | أدناه | ### وظيفة كل مفتاح تبديل {#which-switch-does-what} - يتألف **Bare Metal** من مستويين. يُظهر مفتاح تبديل الوحدة قائمة الإدارة والـ API. أما البيع للعملاء فيتم عبر مفتاح تبديل منفصل يتطلب تأكيداً كتابياً ضمن **Services › Dedicated Server**، ويتم حظر أي عملية كتابة إلى iDRAC حتى تفعّل **live ops** ضمن **Infrastructure › Bare Metal › Safety**. راجع [الخوادم المخصصة](https://nexcmp.com/ar/docs/infrastructure/dedicated/). - بالنسبة إلى **Kubernetes** و**Private Cloud** و**VPN** و**IPv6 Proxy** و**Images**، يتحكم مفتاح تبديل الوحدة ومفتاح المبيعات في صفحة الخدمة في الإعداد نفسه. - يتطلب **AI** أيضاً إعداد مزود ضمن **System › Settings › AI provider**. - يتكون **AI Models** من طبقتين. يُظهر مفتاح تبديل الوحدة قائمة الإدارة وواجهة API. أما البيع للعملاء فهو مفتاح بيع منفصل في أعلى صفحات AI Models، ويكون معطلاً افتراضياً. راجع [AI Models](https://nexcmp.com/ar/docs/infrastructure/ai-models/). ### وحدات تُقرأ عند بدء التشغيل {#modules-read-at-start-up} هناك ثلاث ميزات ليست مفاتيح تبديل عادية؛ حيث تُقرأ **مرة واحدة عند بدء تشغيل الخدمات** وتتطلب بنية تحتية لا تتضمنها عملية التثبيت القياسية. | الميزة | الإعداد | الحالة | المتطلبات | |---|---|---|---| | DDoS & BGP | `module_ddos` | تظهر كـ **Add-on package** عندما تكون معطلة، و**Installed** عندما تكون مفعلة. لا يوجد مفتاح تبديل في وحدة التحكم. | برامج راوتر الحافة الخلفية (BGP وRTBH وXDP وإحصاءات التدفق) التي تعمل بصلاحيات root. تعمل لوحة التحكم كمستخدم غير مميز ولا يمكنها تشغيلها. | | الذكاء الاصطناعي | `module_ai` | مفتاح تبديل عادي. تتوافق المسارات معه فوراً؛ وتبدأ مهام AI Chat الخلفية (التحقيق في التذاكر، والردود المجدولة) عند إعادة تشغيل الخدمات التالية. تشير وحدة التحكم إلى أنه يوصى بإعادة التشغيل. | مزود AI. | | طرفية Web SSH | `feature_ssh_web` | معطل افتراضيًا، دون زر تبديل في وحدة التحكم | خدمة وكيل SSH منفصلة ومسارها. من دونها، تعرض علامة تبويب Console في البوابة بروتوكول VNC فقط. **لا يحتاج AI Agent إليها**: فهو ينفذ الأوامر عبر اتصال SSH تنشئه اللوحة بنفسها. | بعد تغيير أي إعداد بدء تشغيل، أعد تشغيل الخدمات: `sudo systemctl restart nexcmp nexcmp-vmd`. ## التحقق {#verify} 1. يظهر عنصر القائمة الخاص بالوحدة (أو يختفي) بعد إعادة التحميل. 2. بالنسبة للوحدة الموجهة للعملاء، تعرض البوابة عنصر القائمة الجديد للعميل المسجل دخوله. أما الوحدة المعطلة فلا تعرض شيئًا أو تعرض "coming soon". ## القيود والملاحظات {#limits-and-notes} - لا يؤدي تعطيل أي وحدة إلى حذف أي شيء؛ حيث تستمر أجهزة VMs والمجموعات وحسابات S3 والاشتراكات قيد التشغيل في العمل واحتساب الرسوم، ولكن لا يمكن للعملاء إنشاء عناصر جديدة فقط. - تسرد صفحات الحصص فقط الخدمات التي تم تفعيل وحداتها. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | لم يظهر عنصر القائمة | لم تتم إعادة تحميل الصفحة | أعد تحميل وحدة تحكم المشرف. | | زر تبديل DDoS Shield معطل | لم يتم تثبيت DDoS & BGP | يتطلب DDoS Shield الإضافة DDoS & BGP. | | "This module is an add-on package and cannot be switched here" (HTTP 409 أو 422) | حاولت (أو حاول برنامج نصي) تبديل حالة DDoS & BGP | هي حزمة إضافية؛ لا يوجد زر تبديل لها. | | "يتطلب DDoS Shield إضافة DDoS & BGP" | الأمر نفسه بالنسبة إلى DDoS Shield | ثبّت الإضافة أولاً. | | مسار وحدة يستجيب بالرمز 404 `module_disabled` | الوحدة معطلة | قم بتفعيل الوحدة. | | يجيب AI Chat لكن التحقيق في التذكرة لا يبدأ أبدًا | تم تفعيل وحدة AI دون إعادة تشغيل | `sudo systemctl restart nexcmp nexcmp-vmd`. | | يتعذر على موظفي القراءة فقط الحفظ | دورهم مخصص للقراءة فقط | استخدم حساب مسؤول. | --- # المناطق {#zones} > **المسار في لوحة الإدارة:** Infrastructure › Datacenter › Zone (`/infra/zones`). صفحة تفاصيل المنطقة هي `/infra/zones/`. ## الوظيفة {#what-it-does} **المنطقة** هي الموقع الذي يختاره العميل عند الطلب: دولة ومدينة مع عَلَم، بالإضافة إلى الخدمات المباعة هناك. وهي مفهوم بيعي منفصل عن المناطق والمجموعات والعُقَد الخاصة بالمنصات التي تدعمها. وتقوم بربط **البنية التحتية** بالمنطقة: مثل منطقة CloudStack، أو مجموعة Proxmox VE، أو عُقَد VPN بنطاقات IP، أو واجهة خلفية لـ S3. يتم إنشاء Zone 1 بواسطة [معالج الإعداد](https://nexcmp.com/ar/docs/getting-started/setup-wizard/) بالاسم المعروض والدولة اللذين أدخلتهما. أضف المزيد من المناطق عندما تمتلك بنية تحتية في مواقع أكثر، أو لمنح VPN وS3 مواقع خاصة بهما. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | الأذونات | حساب مسؤول. يمكن لدور الموظف المخصص للقراءة فقط الاطلاع دون إجراء تغييرات. | | البنية التحتية | لا تبيع المنطقة أي شيء حتى يتم ربط مورد بها (انظر "أي خدمة تُباع وأين" أدناه). | | يعتمد على | [CloudStack](https://nexcmp.com/ar/docs/infrastructure/cloudstack/) أو [Proxmox VE](https://nexcmp.com/ar/docs/infrastructure/proxmox/) لأجهزة VMs، و[عُقَد VPN والوكيل](https://nexcmp.com/ar/docs/infrastructure/vpn-proxy-nodes/) لـ VPN، و[S3](https://nexcmp.com/ar/docs/infrastructure/s3/) لـ Object Storage. | ## تجهيز البنية التحتية {#prepare-the-infrastructure} غير مطلوب. فالمنطقة هي سجل داخل NexCMP. ## الربط في NexCMP {#connect-in-nexcmp} ### إنشاء منطقة {#create-a-zone} 1. افتح **Infrastructure › Datacenter › Zone** وانقر على **Add zone**. 2. املأ النموذج: | الحقل | مثال للقيمة | ملاحظات | |---|---|---| | الدولة | `United States` | لتحديد العلم. | | المدينة | `New York` | اختياري. | | الاسم (الفيتنامية)، الاسم (الإنجليزية) | `New York` | الاسم الذي يراه العملاء بكل لغة. | | Slug | `us-new-york` | من a-z، و0-9، والشرطة (-)، من 2 إلى 32 حرفًا. يُملأ تلقائيًا من الدولة والمدينة حتى تُدخل القيمة الخاصة بك. | | مستوى الرؤية | Public | تكون مناطق **Public** مرئية لجميع العملاء؛ أما مناطق **Hidden** فلا يمنحها إلا المسؤول. | | الترتيب | `0` | تظهر الأرقام الأقل أولاً في القوائم. | | الخدمات المتاحة للبيع في هذه المنطقة | Virtual Machines (VM)، VPN، Object Storage (S3) | حدد خيارًا واحدًا على الأقل. | | نشط | On | يؤدي الخيار **Off** إلى إخفاء المنطقة عن العملاء. | | القيمة الافتراضية | معطّل | المنطقة المحددة مسبقًا للعملاء الذين لم يحددوا اختيارًا. توجد دائمًا منطقة افتراضية واحدة فقط. | ![مربع حوار Add zone مع تحديد الدولة والمدينة والـ slug والخدمات المحددة](https://nexcmp.com/ar/docs/images/infrastructure/zones-01-add-zone.webp) 3. انقر على **Create zone**. تعرض القائمة المنطقة مع علمها والمالك والخدمات وحالتها وأعداد أجهزة VM والخطط والبنية التحتية المرفقة. ![قائمة المناطق مع المنطقة الافتراضية ومنطقة ثانية](https://nexcmp.com/ar/docs/images/infrastructure/zones-02-list.webp) ### الاطلاع على العناصر المرفقة {#look-at-what-is-attached} انقر على أي صف لفتح المنطقة. تسرد علامة التبويب **Provider infrastructure** كل خادم خلفي مرفق مع مزوده ونوعه (CloudStack أو Proxmox VE) والمنطقة والحالة والأولوية. بينما تسرد علامة التبويب **VPN infrastructure** نطاقات VPN وعقدها للمنطقة وتربط بمجمع VPN. ![تفاصيل المنطقة مع علامة التبويب Provider infrastructure](https://nexcmp.com/ar/docs/images/infrastructure/zones-03-detail.webp) ### أين تُباع كل خدمة {#which-service-sells-where} | الخدمة | كيفية إضافتها إلى المنطقة | |---|---| | أجهزة Virtual Machines على CloudStack | يربط المعالج (أو **Infrastructure › Cloud provider › CloudStack**) CloudStack بالمنطقة 1. | | أجهزة Virtual Machines على Proxmox VE | في علامة التبويب **Clusters** الخاصة بالعنقود، انقر على **Attach cluster to zone**. ينضم العنقود إلى منطقة **موجودة مسبقًا**، وعادةً ما تكون تلك التي تبيع عبر CloudStack. | | VPN | عندما تبلّغ عقدة VPN عن نطاقات IP العامة الخاصة بها، فإنها تُنشئ منطقة لدولتها (أو تنضم إليها) وتضع النطاقات في مجمع VPN. يمكنك أيضًا تعيين المنطقة والعقدة لأي نطاق عبر **VPN IP pools**. | | IPv6 Proxy | تُنشئ عقدة IPv6 proxy الجديدة منطقتها في الحالة **off**. قم بتفعيل المنطقة هنا حتى يتمكن العملاء من اختيارها. | | Object Storage (S3) | حدد خدمة S3 في المنطقة، ثم اربط الخادم الخلفي عبر **Ceph S3 (RGW)**. | ### متى يمكن للمنطقة بيع أجهزة افتراضية؟ {#when-can-a-zone-sell-virtual-machines} تعرض المنطقة الوسم **not ready to sell VMs** حتى يتوفر لديها خادم خلفي واحد نشط وقابل للبيع على الأقل **و**خطة واحدة مرئية على الأقل **و**قالب واحد جاهز على الأقل في ذلك الخادم الخلفي. ويعرض نموذج طلب العميل المناطق الجاهزة فقط. ## التحقق {#verify} 1. تظهر المنطقة في القائمة كـ **On**، مع العلم الصحيح. 2. تعرض صفحة تفاصيلها الـ backend أو نطاقات VPN المتوقعة. 3. بالنسبة للأجهزة الافتراضية (VMs): اختفت علامة **not ready to sell VMs**. في بوابة العملاء، ابدأ طلباً وتأكد من توفر المنطقة. ## القيود والملاحظات {#limits-and-notes} - في هذا الإصدار من NexCMP، يطلب العملاء الأجهزة الافتراضية في **المنطقة الافتراضية** (zone 1). تُستخدم المناطق الأخرى لـ VPN وIPv6 Proxy وObject Storage، أو لتجهيز موقع قبل توفر بنيته التحتية؛ وتوضح الملاحظة أسفل قائمة المناطق الأمر نفسه. - لا يمكن حذف المنطقة إلا عندما لا يكون هناك أي شيء مرتبط بها: لا backends أو أجهزة افتراضية (VMs) أو خطط أو نطاقات VPN. ولا يمكن حذف المنطقة الافتراضية؛ عيّن منطقة أخرى كافتراضية أولاً. - المناطق المملوكة لموزع يمكنك تفعيلها أو إيقافها وإخفاؤها أو إظهارها فقط؛ أما حقولها الأخرى فتبقى مقفلة. - يُعد الـ slug جزءاً من المراجع الداخلية. اختره مرة واحدة. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | "اسم المنطقة مطلوب" / "اختر الدولة" / "اختر خدمة 1 على الأقل" | حقل مطلوب فارغ | أدخل الاسم، واختر الدولة، وحدد خدمة. | | "slug غير صالح (a-z 0-9 -، 2-32 حرفًا)" | يحتوي الـ slug على أحرف أخرى أو طول غير صحيح | استخدم الأحرف الصغيرة والأرقام والشرطات فقط. | | علامة "not ready to sell VMs" | لا يوجد backend نشط وقابل للبيع، أو لا توجد خطة أو قالب جاهز في تلك المنطقة | اربط البنية التحتية، ثم أضف خطة وقالب. راجع [Plans](https://nexcmp.com/ar/docs/catalog/plans/) و[Templates](https://nexcmp.com/ar/docs/infrastructure/templates/). | | خيار الحذف معطّل مع ظهور "still attached" | تحتوي المنطقة على backends أو أجهزة افتراضية (VMs) أو خطط أو نطاقات VPN | احذفها أو انقلها أولاً. | | خيار الحذف معطّل مع ظهور "Default zone" | المنطقة هي الافتراضية | عيّن منطقة أخرى كافتراضية. | | العملاء لا يرون المنطقة | مخفية، أو غير نشطة، أو لم يتم تحديد أي خدمة لها | اضبط Visibility على Public، وActive على On وحدد الخدمة. | | منطقة S3 مفقودة من نموذج backend | خدمة S3 غير محددة في المنطقة | عدّل المنطقة وحدد **Object Storage (S3)**. | --- # CloudStack > **الموقع في لوحة الإدارة:** Infrastructure › Cloud provider › CloudStack › API connection (`/infra/cloudstack?tab=connect`). يمكن أيضاً إجراء الاتصال الأول في [معالج الإعداد](https://nexcmp.com/ar/docs/getting-started/setup-wizard/)، الخطوة 2. ## الوظيفة {#what-it-does} يبيع NexCMP أجهزة افتراضية تعمل على سحابة Apache CloudStack لديك. فهو ينشر أجهزة VMs ويشغلها ويوقفها ويغير حجمها ويأخذ Snapshots لها ويحذفها عبر CloudStack API، ويوزع عناوين IP عامة من المنطقة، ويقرأ بيانات الاستخدام للفوترة وحركة البيانات، ويعرض السعة والحالة التشغيلية في لوحة تحكم الإدارة. يبقى CloudStack هو المصدر المعتمد لـ hypervisors؛ بينما يوفر NexCMP واجهة البيع والفوترة والبوابة للعملاء. استخدم هذه الصفحة عندما يكون CloudStack (أو سيكون) مصدر أجهزة VM الرئيسي لديك. ولمصدر ثانٍ إلى جانبه، راجع [Proxmox VE](https://nexcmp.com/ar/docs/infrastructure/proxmox/). ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | إصدار CloudStack | الإصدار 4.23 هو الإصدار المختبر. تتطلب وحدة تحكم VM الإصدار 4.18 أو أحدث، بينما يتطلب تغيير حجم CPU/RAM المباشر لجهاز VM قيد التشغيل الإصدار 4.23 مع KVM. | | نوع المنطقة | منطقة تحتوي على شبكة ضيف (guest network) واحدة على الأقل لأجهزة VMs الخاصة بالعملاء ونطاق IP عام بعناوين متاحة. | | Hypervisor | يُعد KVM هو برنامج Hypervisor المختبَر. | | الحساب | **نطاق وحساب مخصصان** تم إنشاؤهما لـ NexCMP. لا تستخدم أبدًا مفتاح مسؤول ROOT. | | إمكانية الوصول إلى API | يجب أن يتمكن خادم اللوحة من الوصول إلى عنوان URL الخاص بـ API لخادم الإدارة (`https://cloudstack.example.com/client/api`) عبر HTTP(S). وتستخدم وحدة تحكم الأجهزة الافتراضية وميزات عرض النطاق الترددي وKubernetes نقطة النهاية ذاتها. | | مفتاح اختياري للقراءة فقط | يتيح مفتاح ثانٍ للقراءة فقط لوحدة تحكم الإدارة عرض المضيفين ووحدات التخزين والأجهزة الافتراضية للنظام ونطاقات IP العامة. وهو غير مطلوب لبيع الأجهزة الافتراضية. | | عنوان IP عام | عناوين IPv4 عامة خالية في المنطقة. وتتم تهيئة البادئة التي يمكن لـ NexCMP بيعها ضمن Sales IP pools. | | القوالب | قالب واحد على الأقل جاهز ومفعّل به كلمة المرور وعرض خدمة واحد يمكن لحسابك رؤيته. راجع [Templates](https://nexcmp.com/ar/docs/infrastructure/templates/). | | التخزين | وحدة التخزين الأساسية لأحجام الحساب، والتخزين الثانوي في حال كنت تبيع Snapshots أو الصور. | | يعتمد على | لا شيء. تعتمد ميزات Kubernetes وPrivate Cloud وImages وBandwidth على هذه الصفحة. | ::: warning لا تستخدم مفتاح مسؤول ROOT أنشئ نطاقًا وحسابًا مخصصين لـ NexCMP. سيتيح المفتاح حينئذٍ الوصول إلى هذا النطاق فقط، ولن يؤثر أي مفتاح مسرّب على بقية السحابة الخاصة بك. كما يتحقق معالج الإعداد من أن الشبكة التي تختارها تنتمي إلى المنطقة **و**إلى الحساب الذي يمتلك المفتاح. ::: ## تجهيز البنية التحتية {#prepare-the-infrastructure} تستخدم الأوامر [CloudMonkey](https://cloudstack.apache.org/) (`cmk`) مع تسجيل الدخول كمسؤول CloudStack. استبدل الأسماء النموذجية والعناصر النائبة بين الأقواس الزاوية. ### إنشاء حساب ومفتاح API مخصصين {#create-a-dedicated-account-and-api-key} 1. أنشئ النطاق الذي سيحتوي على كل ما يمتلكه NexCMP. ```bash cmk create domain name=nexcmp ``` لاحظ `id` في المخرجات؛ حيث يتم استخدامه كـ `` أدناه. 2. ابحث عن الدور الذي تريد تعيينه للحساب. ```bash cmk list roles type=DomainAdmin filter=id,name ``` | الدور | متى تختاره | |---|---| | **Domain Admin** (موصى به) | مجموعة الميزات الكاملة: الأجهزة الافتراضية والشبكات ومشاريع Kubernetes وVPC والصور. ويتوقف نطاق وصوله عند نطاق `nexcmp`. | | User | دورة حياة الأجهزة الافتراضية فقط. لا يمكن للمستخدم العادي حذف الأجهزة الافتراضية نهائيًا ما لم يكن الإعداد العام `allow.user.expunge.recover.vm` مضبوطًا على true؛ حيث يقوم NexCMP عندئذٍ بإيقاف الجهاز الافتراضي ويقوم CloudStack بحذفه نهائيًا بعد `expunge.delay`. | 3. أنشئ الحساب ومستخدمه الأول. استخدم كلمة مرور عشوائية طويلة، فلن تحتاج إلى إدخالها مجددًا. ```bash cmk create account name=nexcmp-api username=nexcmp-api \ password='CHANGE-ME-LONG-RANDOM' email=ops@example.com \ firstname=NexCMP lastname=API roleid= domainid= ``` 4. إنشاء زوج مفاتيح API للمستخدم الجديد. ```bash cmk list users domainid= username=nexcmp-api filter=id,username cmk generate userkeys id= ``` انسخ `apikey` و`secretkey`. فهما **API key** و**Secret key** اللذان تدخلهما في NexCMP. يخزنهما NexCMP مشفرين ولا يعرض سوى الأحرف الأربعة الأخيرة بعد ذلك. 5. تأكد من أن النطاق لا يحتوي على قيود موارد مقيدة (Instances، ووحدات التخزين، وعناوين IP العامة، والشبكات، وSnapshots، والقوالب، والمشاريع). ```bash cmk list resourcelimits domainid= ``` ### إنشاء شبكة الضيف للأجهزة الافتراضية للعملاء {#create-the-guest-network-for-customer-vms} يتم نشر الأجهزة الافتراضية للعملاء داخل شبكة ضيف واحدة تابعة للحساب الجديد. وتعمل الشبكة المعزولة المزودة بموجّه افتراضي (VR) وخدمات Static NAT وFirewall وPort Forwarding بكفاءة، لأن NexCMP يربط عنوان IP عامًا بكل جهاز افتراضي باستخدام static NAT. ```bash cmk list networkofferings state=Enabled guestiptype=Isolated filter=id,name cmk create network name=customers displaytext=customers zoneid= \ networkofferingid= account=nexcmp-api domainid= ``` تحقق من سياسة egress الافتراضية للعرض: إذا كانت "deny"، فلن تمتلك الأجهزة الافتراضية للعملاء وصولًا صادرًا حتى تتم إضافة قواعد جدار الحماية لحركة المرور الصادرة. ### إظهار العروض والقوالب {#make-offerings-and-templates-visible} - يجب أن تكون **عروض الخدمة** و**عروض الشبكة** عامة أو مخصصة لنطاق `nexcmp`، وإلا فلن يتمكن الحساب من عرضها أو استخدامها. - قم بتسجيل أو مشاركة قالب واحد على الأقل (راجع [Templates](https://nexcmp.com/ar/docs/infrastructure/templates/)). يعرض NexCMP القوالب الجاهزة والمميزة. ### اختياري: مفتاح للقراءة فقط لصفحات البنية التحتية {#optional-read-only-key-for-infrastructure-pages} تستخدم علامات التبويب **Capacity** و**Host** و**Storage** و**System VM** وقائمة نطاقات IP العامة مفتاحاً ثانياً يحتاج فقط إلى صلاحية القراءة لستة أوامر. أنشئ دوراً محدوداً بدلاً من إعادة استخدام مفتاح مسؤول كامل الصلاحيات: ```bash cmk create role name=nexcmp-readonly type=Admin # is the id printed above for api in listHosts listCapacity listSystemVms listVlanIpRanges listClusters listStoragePools; do cmk create rolepermission roleid= rule=$api permission=allow done cmk create rolepermission roleid= rule='*' permission=deny ``` ثم أنشئ حساباً بهذا الدور (في النطاق ROOT، لأنه يقرأ بيانات على مستوى المنطقة بأكملها)، وأنشئ مفاتيحه كما في الخطوة 4، وأدخلها كـ **RO API key** في القسم التالي. ### التحقق من مسار الشبكة {#check-the-network-path} من خادم اللوحة: ```bash curl -fsS -o /dev/null -w '%{http_code}\n' https://cloudstack.example.com/client/api ``` أي استجابة HTTP (حتى 4xx) تثبت إمكانية الوصول إلى المنفذ. تعني مهلة الانتظار وجود مشكلة في جدار الحماية أو نظام DNS من جانبك. ## الربط في NexCMP {#connect-in-nexcmp} ### في معالج الإعداد {#in-the-setup-wizard} تطلب الخطوة 2 من [معالج الإعداد](https://nexcmp.com/ar/docs/getting-started/setup-wizard/) نفس القيم. يعرض **Test connection** المناطق والشبكات التي يمكن للمفتاح رؤيتها؛ اختر المنطقة وشبكة الضيف، واسماً معروضاً للمنطقة والدولة، ثم انقر على **Save CloudStack**. سيرفض المعالج أي شبكة لا تنتمي إلى تلك المنطقة أو لا تظهر للمفتاح. ![الخطوة 2 من المعالج مع إدخال عنوان URL ومفاتيح CloudStack API واختيار المنطقة والشبكة بعد Test connection](https://nexcmp.com/ar/docs/images/infrastructure/cloudstack-01-wizard-step.webp) ### لاحقاً، في لوحة تحكم المسؤول {#later-in-the-admin-console} 1. افتح **Infrastructure › Cloud provider › CloudStack** واختر علامة التبويب **API connection**. 2. املأ بطاقة **Connection**: | الحقل | مثال للقيمة | |---|---| | نقطة نهاية API | `https://cloudstack.example.com/client/api` | | مفتاح API (صلاحية كتابة) | `XXXX` (اتركه فارغاً للاحتفاظ بالمفتاح المحفوظ) | | المفتاح السري | `XXXX` | | مفتاح RO API / المفتاح السري RO | اختياري، من الحساب المخصص للقراءة فقط | | معرّف المنطقة (Zone ID) | معرّف UUID الخاص بمنطقتك | ![علامة التبويب API connection مع نقطة نهاية تجريبية ومفاتيح محجوبة](https://nexcmp.com/ar/docs/images/infrastructure/cloudstack-02-connect-form.webp) 3. انقر على **Test connection** قبل الحفظ. يختبر ذلك المفاتيح التي أدخلتها دون حفظها: مفتاح الكتابة مع `listZones` و`listCapabilities`، ومفتاح القراءة فقط مع `listSystemVms`. 4. انقر على **Save connection**. أبقِ خيار **Enable CloudStack connection** مفعلاً؛ إذ يؤدي إيقافه إلى إيقاف العامل لجميع مهام CloudStack دون فقدان أي بيانات. 5. افتح **Services › Virtual Machines › Policy › Provisioning** لتعيين شبكة الضيف الافتراضية، والعروض المخصصة، وزوج المفاتيح الافتراضي للأجهزة الافتراضية الجديدة. ![صفحة VM Policy، علامة التبويب Provisioning، مع معرّف الشبكة الافتراضية](https://nexcmp.com/ar/docs/images/infrastructure/cloudstack-04-provisioning.webp) 6. افتح **Infrastructure › Cloud provider › Sales IP pools**، وضمن **Configure sales ranges**، حدد **Sellable IP range prefixes** (على سبيل المثال `203.0.113.`) و**Excluded IP prefixes** إذا كانت هناك عناوين معينة في المنطقة يجب عدم بيعها أبداً. اترك البادئة فارغة للسماح بجميع العناوين المتاحة. ![صفحة Sales IP pools مع تحديد بادئة العناوين القابلة للبيع 203.0.113.](https://nexcmp.com/ar/docs/images/infrastructure/cloudstack-05-sales-ip-pool.webp) ### ما يقرأه NexCMP وما يكتبه {#what-nexcmp-reads-and-writes} | المجال | عمليات القراءة | التغييرات | |---|---|---| | VMs | القائمة، الحالات، سجل الاستخدام، نقطة نهاية وحدة التحكم | النشر، والتشغيل، والإيقاف، وإعادة التشغيل، وإعادة التثبيت، والإتلاف، وتغيير الحجم، وإعادة تعيين كلمة المرور ومفتاح SSH | | الأقراص واللقطات | وحدات التخزين، لقطات VM، النسخ الاحتياطية | الإنشاء، والإرفاق، وفصل الاتصال، وتعديل الحجم، والحذف، والتقاط اللقطات، والاستعادة | | الشبكات | الشبكات، والموجهات، وعناوين public IPs، والجدار الناري، وتوجيه المنافذ، وقواعد موازن التحميل | ربط وتحرير عناوين public IPs، وstatic NAT، والجدار الناري، وتوجيه المنافذ، وقواعد egress، والشبكات وقوائم ACLs لـ Private Cloud | | الكتالوج | عروض الخدمة والقرص والشبكة، والقوالب، وملفات ISOs، وأنواع أنظمة التشغيل | تسجيل وحذف القوالب وملفات ISOs (Images)، وعروض الخدمة عند إنشاء خطط مخصصة | | Kubernetes | الإصدارات المدعومة، والعناقيد، والتكوين | المشاريع، وحدود الموارد، والشبكات، والعناقيد (وحدة Kubernetes) | | مفتاح للقراءة فقط | المضيفات، والعناقيد، ومجمعات التخزين، وأجهزة system VMs، والسعة، ونطاقات عناوين VLAN IP | لا شيء | ### معالجة وذاكرة RAM فورية، وعرض النطاق الترددي {#live-cpu-and-ram-and-bandwidth} - **التبديل السريع (Hot-plug).** لا يمكن تغيير حجم VM قيد التشغيل دون إعادة تشغيل إلا عندما يتيح قالبها ذلك (قابلة للتوسع ديناميكيًا) ويقوم النظام الضيف بتشغيل معالجات CPU وذاكرة RAM الجديدة فورياً. يفعّل NexCMP ميزة Auto Scaling للقوالب التي ينتهي اسمها بـ `vN` مع N بقيمة 6 أو أكثر، أو عند تعيينها يدويًا في حقل **vCPU/RAM hot-plug** الخاص بالقالب. راجع [القوالب](https://nexcmp.com/ar/docs/infrastructure/templates/). - **مصدر عرض النطاق الترددي.** بالإعدادات الافتراضية، يقيس NexCMP حركة المرور من إحصاءات CloudStack VM (`listVirtualMachinesUsageHistory`، ويتم استطلاعها كل 5 دقائق وجمعها لكل واجهة شبكة لـ VM). تتضمن الأرقام حركة المرور بين أجهزة VM، لذا قد تكون أعلى قليلاً مما قد يحصيه موجه الحافة. حافظ على تمكين جمع إحصاءات CloudStack VM؛ يتم تخطي الفجوات الأطول من فترة الاحتفاظ بالإحصاءات. راجع [عرض النطاق الترددي](https://nexcmp.com/ar/docs/catalog/bandwidth/). ## التحقق {#verify} 1. يُرجع **Test connection** النتيجة "Write key: OK" مع منطقتك وإصدار CloudStack. 2. يُظهر **Infrastructure › Cloud provider › Providers** المزود كنشط مع وقت اختبار حديث. ولم تعد لوحة حالة لوحة التحكم تعرض "CloudStack: not connected". 3. يسرد **Sales IP pools** العناوين المتاحة (يتم تحديثه مرة كل دقيقة تقريبًا). 4. اطلب VM صغيرة من بوابة العملاء أو وحدة تحكم المسؤول وتأكد من وصولها إلى الحالة Running، وامتلاكها عنوان public IP، وإمكانية فتح وحدة التحكم. ## القيود والملاحظات {#limits-and-notes} - يمكن ربط عنقود CloudStack واحد في هذا الإصدار من NexCMP. يمكن لمربع الحوار **Add cloud provider** اختبار مفاتيح عنقود ثانٍ ولكنه لا يستطيع حفظه. - ترتبط منطقة CloudStack واحدة بمنطقة NexCMP الافتراضية؛ ويقتصر CloudStack ذو المناطق المتعددة على المنطقة التي تدخلها، مع تجاهل أجهزة VMs وعناوين IPs والشبكات للمناطق الأخرى. - يؤدي حذف شبكة الضيف في CloudStack إلى فشل كل عملية نشر جديدة. وتعرض وحدة تحكم المسؤول إشعارًا أحمر عند اختفاء الشبكة. - لا تغادر بيانات الاعتماد الخادم أبدًا. ولا تُرجع API سوى الأحرف الأربعة الأخيرة. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | `listCapabilities: cloudstack 401: unable to verify user credentials and/or request signature` | مفتاح API أو سر غير صحيح، أو مفتاح من مستخدم آخر، أو مشكلة في توقيت خادم اللوحة | أنشئ المفاتيح مجددًا باستخدام `cmk generate userkeys` والصق كليهما. وتحقق من وقت خادم اللوحة. | | الاختبار: `listZones: …` أو انتهاء المهلة | لا يمكن لخادم اللوحة الوصول إلى عنوان URL الخاص بـ API | تحقق من DNS والجدار الناري والمسار الدقيق لـ `/client/api`. | | المعالج: "network not found in that zone for this API key" | الشبكة المحددة تنتمي إلى حساب أو منطقة أخرى | أنشئ الشبكة في الحساب المخصص (انظر أعلاه) وشغّل **Test connection** مجددًا. | | المعالج: "pick a zone and a network" | لم يتم إجراء الاختبار، أو لم يتم تحديد منطقة أو شبكة | انقر فوق **Test connection** وحدد من كلتا القائمتين. | | شريط التنبيه "CloudStack key not configured" | لم يتم حفظ أي مفتاح بعد ("Connect later") | املأ بطاقة Connection، ثم **Save connection**، وبعدها **Test connection**. | | شريط الإشعار "CloudStack connection is OFF" | مفتاح التبديل **Enable CloudStack connection** معطّل | قم بتفعيله ثم احفظ. | | مفتاح القراءة فقط: "unusable …" في الاختبار | صلاحية دور مفقودة أو حساب غير صحيح | تحقق من الأوامر الستة المسموح بها وتأكد من أن الحساب في نطاق ROOT. | | "Zone public IP ranges not measured yet" أو "no public IP ranges declared" | لا يوجد مفتاح قراءة فقط، أو أن المنطقة لا تحتوي فعليًا على نطاق عام | أضف مفتاح القراءة فقط، أو أضف نطاق IP عام في CloudStack. | | "المجمع فارغ — انتظر 60 ثانية لمزامنة vmd" | يحدّث worker قائمة IP مرة كل دقيقة | انتظر دقيقة ثم أعد التحميل. | | "نفاد عناوين IP المجانية في النطاق 203.0.113." | جميع العناوين في البادئة القابلة للبيع محجوزة | أضف عناوين إلى المنطقة، أو وسّع البادئة، أو حرّر عناوين IP غير المستخدمة. | | "فشل جلب بيانات الشبكة (CloudStack لا يستجيب أو المفتاح يفتقر إلى الأذونات)" | فقد المفتاح صلاحية الوصول، أو أن CloudStack لا يستجيب | شغّل **Test connection**؛ وتحقق من تفعيل الحساب. | | "شبكة Guest network غير موجودة" | تم حذف الشبكة في CloudStack | أنشئ الشبكة مجددًا وعيّنها كشبكة افتراضية ضمن Provisioning. | --- # Proxmox VE > **الموقع في لوحة الإدارة:** Infrastructure › Cloud provider › Providers (`/infra/providers`)، ثم صفحة المزود (`/infra/providers/`) مع علامات التبويب Overview و Clusters و VMs و Servers و Credentials. يتم إعداد الخطط ضمن Services › Virtual Machines › Plans & pricing (`/vm/catalog`). ## الوظيفة {#what-it-does} يمكن لـ NexCMP بيع أجهزة افتراضية تعمل على مجموعة Proxmox VE واحدة أو أكثر، إلى جانب CloudStack أو بديلًا عنه. يتم إنشاء الجهاز الافتراضي باستنساخ كامل لقالب نظام التشغيل عبر full clone، ثم تهيئته بواسطة cloud-init: الحجم، وعنوان IP من مجمع تحدده، وكلمة مرور root ومفتاح SSH. ويحصل العملاء على التحكم بالطاقة والكونسول و Snapshots وإعادة التثبيت وإعادة تعيين كلمة المرور والمقاييس في البوابة. ولا يرون مطلقًا اسم المجموعة أو العقدة أو المصدر. استخدم هذا الخيار عندما تشغّل Proxmox VE بالفعل، أو لتقديم مجمع ثانٍ من الأجهزة الافتراضية بتسعير مختلف. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | Proxmox VE | الإصدار PVE 9.x. تم التحقق من التكامل على 9.2. ويتطلب محتوى التخزين `import` وخيار القرص `import-from` (الإصدار PVE 8.2 أو أحدث). | | الشبكة من اللوحة | اتصال HTTPS إلى واجهة API للمجموعة، `https://:8006`. بدون مسار أو اسم مستخدم أو استعلام. تتصل اللوحة و worker على حد سواء؛ ويتم تمرير كونسول المتصفح عبر اللوحة بالوكالة. | | الحساب | مستخدم PVE مخصص مع **API token** ودور مخصص بالامتيازات الموضحة أدناه. لا تستخدم `root@pam` مطلقًا. | | التخزين | سعة تخزين لأقراص الأجهزة الافتراضية تدعم الاستنساخ (مثل `local-lvm`). ولأداة إنشاء القوالب المدمجة، وحدة التخزين المسماة `local` مع أنواع المحتوى `import` و `snippets`. | | الشبكة | جسر Linux (مثل `vmbr0`) يصل إلى الشبكة التي توجد بها عناوين IP للعملاء. استخدم جسرًا يدعم VLAN إذا أدخلت وسم VLAN. | | عناوين IP | كتلة IPv4 (من /16 إلى /30) موجّهة إلى ذلك الجسر، مع بوابة. يعيّن NexCMP العناوين بنفسه؛ إذ لا يتضمن Proxmox إدارة لعناوين IP. | | القوالب | جهاز افتراضي قالب cloud-init واحد لكل نظام تشغيل، على كل عقدة يتم النشر إليها، مع QEMU guest agent. | | المنطقة | منطقة حالية لربط العنقود بها. راجع [Zones](https://nexcmp.com/ar/docs/infrastructure/zones/). | | يعتمد على | لا شيء. | ## تجهيز البنية التحتية {#prepare-the-infrastructure} شغّل الأوامر كـ root على أي عقدة في العنقود. ### 1. إنشاء دور ومستخدم ورمز API بالحد الأدنى من الصلاحيات {#_1-create-a-least-privilege-role-user-and-api-token} 1. أنشئ الدور. قائمة الصلاحيات مطابقة تماماً لما يستخدمه NexCMP؛ ولا تحتوي على أي صلاحية لتعديل المستخدمين أو تعريفات التخزين أو مركز البيانات. ```bash pveum role add NexCMP -privs "VM.Allocate VM.Clone VM.Config.CDROM VM.Config.CPU VM.Config.Cloudinit VM.Config.Disk VM.Config.HWType VM.Config.Memory VM.Config.Network VM.Config.Options VM.PowerMgmt VM.Audit VM.Console VM.Snapshot VM.Snapshot.Rollback VM.Backup VM.GuestAgent.Audit VM.GuestAgent.Unrestricted Datastore.Audit Datastore.AllocateSpace Datastore.AllocateTemplate Sys.Audit Sys.AccessNetwork SDN.Use SDN.Audit Pool.Audit Mapping.Audit Mapping.Use" ``` `Sys.AccessNetwork` مطلوب لتنزيل صور السحابة. لا يتوفر PVE 9 على صلاحية `VM.Monitor`؛ فلا تقم بإضافتها. 2. أنشئ المستخدم والرمز. يعني `--privsep 1` أن صلاحيات الرمز هي **التقاطع** بين أذونات المستخدم وأذونات الرمز نفسه. ```bash pveum user add nexcmp@pve --comment "NexCMP" pveum user token add nexcmp@pve api --privsep 1 ``` يعرض الأمر **سر الرمز مرة واحدة فقط** (UUID). انسخه الآن. معرّف الرمز هو `nexcmp@pve!api`. 3. امنح الدور **لكلٍّ من** المستخدم والرمز. هذه هي الخطوة التي يغفل عنها الكثيرون: عند فصل الصلاحيات، يتلقى الرمز فقط أخطاء 403 مثل `Datastore.Audit` إذا لم تكن لدى المستخدم أي صلاحية. ```bash pveum acl modify / --roles NexCMP --users nexcmp@pve pveum acl modify / --roles NexCMP --tokens 'nexcmp@pve!api' ``` 4. اختبره من خادم لوحة التحكم: ```bash curl -sk -H 'Authorization: PVEAPIToken=nexcmp@pve!api=' https://192.0.2.10:8006/api2/json/version ``` الحصول على مستند JSON يتضمن `version` يعني أن الرمز يعمل. (`-k` مخصص لهذا الفحص السريع فقط؛ حيث يقوم NexCMP بتثبيت الشهادة بنفسه، انظر أدناه). ### 2. التحقق من الجسر ووحدات التخزين {#_2-check-the-bridge-and-the-storage} ```bash pvesm status # storages, type, content and free space ip -br link show type bridge ``` - تحصل أجهزة العملاء الافتراضية على واجهات شبكة `virtio` على الجسر الذي تدخله في NexCMP. إذا قمت بتحديد VLAN، فيجب أن يدعم الجسر تمييز شبكات VLAN. - ضع أجهزة العملاء الافتراضية على جسر أو VLAN **منفصل عن عنوان إدارة العقدة**. إذا تشاركت الشبكة نفسها، فإن مجموعة عناوين IP التلقائية لإدارة جدار حماية Proxmox تفتح المنافذ 22 و8006 و3128 و5900-5999 و60000-60050 في العقدة لكل جهاز افتراضي على تلك الشبكة. إذا تعذر الفصل بينهما، فأضف قاعدة DROP صريحة لشبكة الأجهزة الافتراضية الفرعية نحو هذه المنافذ فوق قاعدة ACCEPT الخاصة بالإدارة. ### 3. ملاحظات التخزين (LVM-thin) {#_3-storage-notes-lvm-thin} - اترك خيار التصفير لـ thin-pool **على وضعه الافتراضي**. قد يؤدي إيقاف تشغيله (`lvchange -Zn`) إلى بقاء بيانات قديمة في الكتل المخصصة حديثاً وتلف جداول الأقسام أو أنظمة الملفات للأجهزة الافتراضية المستنسخة. - الأقراص التي تُظهر الحالة "write cache: disabled" قد تقوم بالاستنساخ بسرعة لا تتجاوز بضعة MB/s فقط. تحقق باستخدام `hdparm -W /dev/sdX` وقم بتفعيل ذاكرة التخزين المؤقت للكتابة إذا كان القرص يدعم الحماية من انقطاع الطاقة. ### 4. تمكين محتوى `import` (فقط لأداة إنشاء القوالب المدمجة) {#_4-enable-the-import-content-only-for-the-built-in-template-builder} تقوم أداة الإنشاء المدمجة بتنزيل صورة السحابة في وحدة التخزين المسماة `local` وإنشاء القالب منها. أضف `import` (و `snippets`) إلى قائمة محتويات وحدة التخزين تلك. احتفظ بالأنواع المستخدمة حالياً؛ حيث يستبدل `--content` القائمة بأكملها: ```bash pvesm status --storage local # note the current content pvesm set local --content iso,vztmpl,backup,import,snippets ``` ### 5. إنشاء قالب نظام تشغيل من صورة سحابية {#_5-build-an-os-template-from-a-cloud-image} القالب هو جهاز افتراضي مع cloud-init يقوم NexCMP باستنساخه. يتم تسجيل كل قالب ضمن **OS key** قصير مثل `ubuntu-24.04` مع معرّف الجهاز الافتراضي الخاص به. أنشئ قالباً واحداً لكل نظام تشغيل **على كل عقدة ستستقبل أجهزة افتراضية**، لأن عملية الاستنساخ تتم على العقدة المحددة. **الخيار A، موصى به: أنشئه بنفسك.** الصور السحابية الرسمية لأنظمة Ubuntu وDebian لا تحتوي على guest agent ولا تسمح بتسجيل الدخول بحساب root، بينما يقوم NexCMP بتعيين كلمة مرور root عبر cloud-init. جهّز الصورة أولاً: ```bash apt install -y libguestfs-tools wget -O noble.qcow2 https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img virt-customize -a noble.qcow2 --install qemu-guest-agent \ --write /etc/cloud/cloud.cfg.d/99-nexcmp.cfg:$'ssh_pwauth: true\ndisable_root: false\n' \ --write /etc/ssh/sshd_config.d/00-nexcmp.conf:$'PermitRootLogin yes\nPasswordAuthentication yes\n' ``` ثم أنشئ جهاز القالب الافتراضي (المعرّف 9000 مجرد مثال؛ احتفظ بمعرّفات القوالب أقل من قيمة `vmid from`، الافتراضية 1000): ```bash qm create 9000 --name tpl-ubuntu-24-04 --memory 2048 --cores 2 --cpu host --ostype l26 \ --scsihw virtio-scsi-single --net0 virtio,bridge=vmbr0 --agent 1 --serial0 socket --vga serial0 qm set 9000 --scsi0 local-lvm:0,import-from=$PWD/noble.qcow2,discard=on,iothread=1 qm set 9000 --ide2 local-lvm:cloudinit --boot order=scsi0 qm template 9000 ``` **الخيار B: أداة الإنشاء المدمجة.** تقوم بطاقة **Create OS template from cloud image** في علامة التبويب Clusters (انظر أدناه) بتنزيل صورة qcow2 وإنشاء القالب وتسجيله. وهي تُنشئ الجهاز الافتراضي مع cloud-init وخيار guest agent، لكنها لا تُعدّل محتوى الصورة. استخدمها فقط مع صورة تسمح بالفعل بتسجيل الدخول بحساب root وتشغيل guest agent، أو عند تقديم قصاصة vendor-data لـ cloud-init. يلزم وجود guest agent من أجل **Reset password** ولإظهار عنوان IP الخاص بالجهاز الافتراضي. ### 6. معرفة بصمة الشهادة (اختياري) {#_6-know-the-certificate-fingerprint-optional} يثق NexCMP بالعنقود عن طريق تثبيت بصمة SHA-256 لشهادة TLS الخاصة به، لذا لا مانع من استخدام شهادة موقعة ذاتياً. لمعرفة القيمة التي سيثبتها NexCMP: ```bash openssl x509 -in /etc/pve/local/pve-ssl.pem -noout -fingerprint -sha256 ``` ## الربط في NexCMP {#connect-in-nexcmp} 1. افتح **Infrastructure › Cloud provider › Providers** وانقر على **Add cloud provider**. اختر **Proxmox VE** واملأ ما يلي: | الحقل | مثال للقيمة | |---|---| | الاسم | `Proxmox cluster 1` | | نقطة النهاية | `https://192.0.2.10:8006` | | معرّف الرمز | `nexcmp@pve!api` | | سر الرمز | `XXXX` (معرّف UUID المطبوع في الخطوة 1) | | Slug | `pve-1` (الأحرف a-z، و0-9، والشرطة، و2-32 حرفاً) | | العقدة الافتراضية | `pve1` (فارغ: العقدة المتصلة التي تمتلك أكبر قدر من RAM المتاحة) | | التخزين | `local-lvm` | | الجسر | `vmbr0` | ![مربع حوار Add cloud provider مع تحديد Proxmox VE وقيم توضيحية لنقطة النهاية والرمز والتخزين](https://nexcmp.com/ar/docs/images/infrastructure/proxmox-01-add-provider.webp) 2. انقر على **Save & open provider**، وأدخل سبباً عند مطالبتك بذلك. يتم تشفير الرمز قبل تخزينه. 3. في تبويب **Overview**، انقر على **Test connection**. يؤدي أول اختبار ناجح إلى **تثبيت بصمة TLS الخاصة بالعنقود**؛ ومن حينها يتم رفض أي شهادة مختلفة. 4. افتح تبويب **Clusters**. تعرض بطاقة **Node · storage · bridge** ما يراه API؛ بينما تتضمن بطاقة **Cluster configuration** الإعدادات: | الحقل | المعنى | |---|---| | العقدة الافتراضية | العقدة المستخدمة للأجهزة الافتراضية الجديدة. تركه فارغاً يعني استخدام العقدة المتصلة التي تمتلك أكبر قدر من RAM المتاحة. | | التخزين، الجسر، VLAN | تخزين القرص، وجسر NIC، ووسم VLAN اختياري (0 يعني لا يوجد). | | نوع CPU | `host` افتراضياً. استخدم `x86-64-v2-AES` عندما تشتمل العقد على أجيال مختلفة من CPU. | | vmid بدءاً من | أول معرّف VM يتم منحه للأجهزة الافتراضية للعملاء (الافتراضي 1000). | | تخزين ISO، تخزين النسخ الاحتياطي | اتركه فارغاً ما لم تكن تستخدمهما؛ إذ يعني تركه فارغاً عدم تقديم ميزتي ISO والنسخ الاحتياطي. | | قالب نظام التشغيل | واحد في كل سطر، `os-key=vmid`، على سبيل المثال `ubuntu-24.04=9000`. | | بصمة TLS المثبتة (SHA-256) | يتم ملؤها بواسطة الاختبار الأول. امسحها وأعد الاختبار بعد استبدال شهادة العنقود. | ![تبويب Clusters، وبطاقة Cluster configuration مع أمثلة للعقدة والتخزين والجسر وقائمة قوالب نظام التشغيل](https://nexcmp.com/ar/docs/images/infrastructure/proxmox-03-cluster-config.webp) 5. اختياري: إذا استخدمت الخيار B أعلاه، فاملأ **Create OS template from cloud image** (مفتاح نظام التشغيل `ubuntu-24.04`، وvmid `9000`، والعقدة `pve1`، وعنوان URL لصورة qcow2) وانقر على **Create template**. تعمل العملية في الخلفية لبضع دقائق؛ وستظهر النتيجة في سجل التدقيق. ![بطاقة Create OS template from cloud image مع عنوان URL تجريبي لصورة Ubuntu](https://nexcmp.com/ar/docs/images/infrastructure/proxmox-04-template-from-image.webp) 6. انقر على **Add pool** في **Cluster IP pool** وأنشئ المجمع الذي تستمد منه الأجهزة الافتراضية عناوينها: | الحقل | مثال للقيمة | |---|---| | الاسم | `customers-1` | | CIDR | `198.51.100.0/24` | | البوابة | `198.51.100.1` (لا يُمنح أبداً لأي جهاز افتراضي) | | DNS | `1.1.1.1,8.8.8.8` (من 1 إلى 4 عناوين IPv4) | | الجسر، VLAN | `vmbr0`, `0` | | عناوين IP المستخدمة بالفعل | واحد في كل سطر، `ip note`، على سبيل المثال `198.51.100.10 monitoring` | لا يقوم NexCMP أبداً بتعيين عنوان الشبكة، أو عنوان البث، أو البوابة، أو أي عنوان محجوز. ولا يمكن لمجمعات العنقود نفسه أن تتداخل. كما لا يمكن حذف المجمع إلا عندما لا يكون أي من عناوينه قيد الاستخدام. ![مربع حوار Add IP pool مع مثال لشبكة /24 وبوابة](https://nexcmp.com/ar/docs/images/infrastructure/proxmox-05-ip-pool.webp) 7. في **Attach cluster to zone**، اختر المنطقة واسم العقدة اختيارياً، ثم انقر على **Attach to zone**. ينضم العنقود إلى المنطقة التي تبيع بالفعل أجهزة VMs، وبذلك يمكن لمنطقة واحدة أن تجمع بين CloudStack و Proxmox معاً. المصدر الجديد **لا يُباع افتراضياً** ولا يغيّر سلوك الخطط الحالية. ![بطاقة ربط العنقود بالمنطقة مع تحديد منطقة موجودة](https://nexcmp.com/ar/docs/images/infrastructure/proxmox-06-attach-zone.webp) 8. افتح **Services › Virtual Machines › Plans & pricing** وانقر على **Add plan**. في **Infrastructure source** اختر عنقود Proxmox، ثم حدد CPU و RAM والقرص والسعر. لا تتطلب خطة Proxmox أي عرض من CloudStack. لبيع التكوين نفسه من كلا المصدرين، استخدم **Clone** في الخطة واختر المصدر الآخر. يجب أن يكون قرص الخطة بحجم قرص القالب على الأقل؛ إذ لا يمكن لـ Proxmox تقليص القرص. ### استيراد جهاز VM موجود مسبقاً {#import-a-vm-that-already-exists} افتح علامة التبويب **Servers** لعرض أجهزة VMs على العنقود. يخصص **Import** جهاز VM موجوداً لحساب عميل دون أي رسوم: لا تتم فوترة الساعات أو وقت إيقاف التشغيل أو حركة المرور. يمكن للعميل تشغيل الجهاز وإيقافه وإعادة تشغيله وفتح وحدة التحكم، ولكن لا يمكنه حذفه؛ المسؤول فقط من يمكنه ذلك. يقرأ NexCMP البيانات فقط من العنقود أثناء الاستيراد. - يجب ربط العنقود بمنطقة **مع اسم العقدة** الخاصة بجهاز VM هذا (إذا تركت العقدة فارغة، فستشير عمليات الاستيراد إلى أن المنطقة غير مهيأة). - لجعل جهاز VM **محمياً** (بحيث يتم رفض الإيقاف وإعادة التشغيل وإعادة التثبيت واستعادة Snapshots والتدمير وتغيير الخطة)، قم باستيراده من سطر الأوامر باستخدام `--protect`: ```bash sudo -u nexcmp /opt/nexcmp/bin/nexcmp px-import --provider pve-1 --server-ref pve1/101 --account-id 12 --hostname web-1 --protect ``` ### الميزات المدعومة وغير المدعومة على Proxmox {#what-is-and-is-not-supported-on-proxmox} | الميزة | Proxmox VE | |---|---| | الإنشاء والتشغيل/إيقاف التشغيل/إعادة التشغيل والحذف | نعم | | تغيير حجم CPU و RAM وتوسيع القرص | نعم، ولكن يتم إيقاف جهاز VM وتعديله ثم إعادة تشغيله (لا يوجد تغيير فوري للحجم دون إيقاف) | | Snapshots | نعم، حتى 5 لكل جهاز VM: الإنشاء، والعرض، والاستعادة، والحذف | | إعادة التثبيت | نعم: يُعاد بناء جهاز VM من القالب ويحتفظ بمعرّفه وعنوان IP وإعداداته، مع كلمة مرور جديدة | | إعادة تعيين كلمة المرور | نعم، عبر guest agent | | وحدة التحكم | نعم، وحدة تحكم عبر المتصفح ممررة عبر اللوحة | | المقاييس | نعم: CPU والذاكرة والشبكة والقرص | | تحميل ISO، والنسخ الاحتياطي، والجدار الناري، و IPv6، وتوجيه المنافذ، وتغيير IP، ومساحات التخزين الإضافية، و Auto Scaling، و DDoS Shield، و VPC، وقياس استهلاك نقل البيانات | غير متاح. تخفي صفحة VM الخاصة بالعميل ما لا يمكن للمصدر تنفيذه. | ## التحقق {#verify} 1. يُظهر **Test connection** الحالة OK وتكون حالة المزود نشطة. 2. يعرض **Clusters** العقد الخاصة بك كمتصلة، مع التخزين والجسر. 3. يُظهر **Cluster IP pool** أعداد العناوين المتاحة والمستخدمة والمحجوزة. 4. يظهر مفتاح نظام التشغيل ضمن قوالب المنطقة في **Services › Virtual Machines › Template** بعد ربط العنقود. 5. اطلب جهاز VM تجريبياً من خطة تستخدم هذا العنقود. يجب أن يحصل على عنوان من المجمع وكلمة مرور root ووحدة تحكم تعمل؛ ويُظهر المجمع استخدام عنوان واحد. ## القيود والملاحظات {#limits-and-notes} ::: tip مناطق المصادر المختلطة منذ NexCMP 1.4.0، تعمل قائمة أسعار Cloud Server العامة أيضاً عندما يشترك CloudStack وProxmox VE في منطقة واحدة. تستخدم كل خطة **Infrastructure source** الخاصة بها. بعد ربط الكتلة (cluster)، تحقق من قائمة الأسعار العامة وأجرِ طلباً تجريبياً لكل مصدر. ::: - يمكن إضافة عدة عناقيد Proxmox، بحيث يمثل كل منها مزوداً واحداً. - توفر المنطقة مصدراً افتراضياً واحداً؛ ويتم نشر الخطة التي تملك **Infrastructure source** الخاص بها إلى ذلك العنقود تحديداً، طالما أن العنقود نشط وموجود في منطقة الخطة. - تحتفظ المجموعة الموجودة خلف نفس المنطقة مثل CloudStack بخططها القديمة على CloudStack. اختبر طلبًا بالكامل قبل الإطلاق. - يمكن استبدال رمز API المميز فقط، ولا يمكن عرضه أبدًا. استبدله في علامة التبويب **Credentials**: أنشئ الرمز المميز الجديد في Proxmox أولاً، وأدخله، ثم شغّل **Test connection**، وبعد ذلك قم بإلغاء الرمز المميز القديم. - تقتصر إجراءات الاختبار والمزامنة ومعلومات المجموعة على ست استدعاءات في الدقيقة لكل مسؤول. - يتولى NexCMP فوترة عملائك؛ بينما تتحمل أنت تكلفة عتاد المجموعة وتراخيصها. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | اختبار: "Key rejected (wrong access key / secret, or revoked)" أو HTTP 401/403 | معرّف الرمز المميز أو السر غير صحيح، أو تم منح قائمة التحكم بالوصول للرمز المميز فقط | أعد تشغيل أمري `pveum acl modify` (المستخدم **والرمز المميز**) وتأكد من أن معرّف الرمز المميز هو `user@realm!tokenid`. | | اختبار: "Could not connect to the provider" أو "Timed out" | جدار حماية، أو مضيف أو منفذ غير صحيح | تحقق من `https://host:8006` من خادم اللوحة. | | اختبار: "Invalid endpoint or not on the allowlist" | تحتوي نقطة النهاية على مسار أو مستخدم أو استعلام أو أنها ليست عبر HTTPS | استخدم `https://host:8006` تمامًا. | | "شهادة TLS الخاصة بالعنقود لا تتطابق مع البصمة المثبتة" | تم استبدال شهادة المجموعة | امسح **Pinned TLS fingerprint** في علامة التبويب Clusters، واحفظ، ثم شغّل **Test connection** مجددًا. | | تم رفض الاسم اللطيف (Slug) | ليس a-z أو 0-9 أو شرطة، أو ليس بطول 2-32 حرفًا | استخدم شيئًا مثل `pve-1`. | | "تنسيق Token id: user@realm!tokenid و secret مطلوب" | معرّف الرمز المميز أو السر مفقود | أدخلهما معًا؛ السر هو الـ UUID المعروض عند إنشاء الرمز المميز. | | "سطر قالب غير صالح: …" | سطر في **Template OS** ليس `key=vmid` | استخدم أحرفًا، وأرقامًا، و`.`، و`_`، و`-` في المفتاح ومعرّف vmid لا يقل عن 100. | | "مفتاح OS: a-z 0-9 . _ - و vmid ≥ 100" | مفتاح أو معرّف غير صالح في **Create template** | صحح مفتاح نظام التشغيل واستخدم معرّف vmid متاحًا. | | "vmid … already exists" عند إنشاء قالب | معرّف vmid مستخدم بالفعل | اختر معرّفًا آخر. | | "عنوان url يشير إلى عنوان داخلي" | عنوان URL الخاص بالصورة هو عنوان IP داخلي | استخدم عنوان URL عامًا؛ يتولى Proxmox تحليل الأسماء. | | فشلت مهمة القالب أثناء التنزيل | لا يحتوي التخزين `local` على محتوى `import` | `pvesm set local --content …,import,snippets`، ثم أعد المحاولة. يجب أن ينتهي اسم الملف بـ `.qcow2` أو `.raw` أو `.vmdk` أو `.ova` أو `.ovf`. | | "cluster has no online nodes" أو "node … is not online" | العقدة الافتراضية معطلة أو تمت كتابتها بشكل غير صحيح | صحح **Default node** أو اتركه فارغًا. | | "الصورة لا تنتمي إلى العنقود" | نظام تشغيل الخطة غير موجود في **Template OS** | أضف المفتاح إلى القائمة واحفظ. | | ينتظر النشر ثم يفشل أثناء الاستنساخ | قالب الجهاز الافتراضي ليس موجودًا على العقدة المحددة | أنشئ القالب على تلك العقدة، أو اضبط **Default node** على العقدة التي تحتوي عليه. | | لا يمكن للعميل تسجيل الدخول كمستخدم root | الصورة تحظر تسجيل الدخول كمستخدم root | أعد إنشاء القالب كما في الخيار A. | | إعادة تعيين كلمة المرور لا تُحدث أي تغيير | لا يوجد guest agent في النظام الضيف | ثبّت `qemu-guest-agent` وفعّله في القالب. | | "الاسم وCIDR والبوابة مطلوبة" | حقل مجمع مفقود | املأ الحقول الثلاثة كلها. | | إنشاء المجمع: "يتداخل مع المجمع …" أو "يجب أن تكون البوابة ضمن النطاق (ليست عنوان شبكة/بث)" أو "cidr: يجب أن يكون عنوان الشبكة …" | مجمع متداخل، أو بوابة غير صحيحة، أو CIDR ليس على حد من حدود الشبكة | استخدم نطاقاً متاحاً، وبوابة بداخله، وCIDR مكتوباً كعنوان شبكة (على سبيل المثال `198.51.100.0/24`). | | الاستيراد: "المنطقة غير مهيأة" | تم ربط العنقود دون اسم عقدة الجهاز الافتراضي | اربط العنقود بالمنطقة باستخدام اسم العقدة. | --- # قوالب أنظمة التشغيل وملفات ISO {#os-templates-and-isos} > **المسار في لوحة الإدارة:** Services › Virtual Machines › Template (`/vm/templates`). تُعرض قوالب Proxmox لكل عنقود في Infrastructure › Cloud provider › Providers › (cluster) › Clusters. ## الوظيفة {#what-it-does} القالب هو صورة نظام التشغيل التي يبدأ منها الجهاز الافتراضي الجديد. لا يخزّن NexCMP الصور بنفسه: بل يقرأ ما يبلّغ عنه CloudStack (القوالب الجاهزة والمميزة) أو ما تدرجه لعنقود Proxmox، ويتيح لك اختيار ما يُباع منها، مع اسم وأيقونة ومستخدم تسجيل دخول موجه للعملاء. توضح هذه الصفحة كيفية تجهيز صور تعمل بسلاسة مع NexCMP: تسجيل الدخول بكلمة المرور، والترقية الحية لـ CPU وRAM، وملف swap، وقرص root يتوسع تلقائياً ليلائم حجم الخطة. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | أداة بناء قوالب CloudStack | جهاز Linux مزود بـ `libguestfs-tools` (`virt-customize`، `virt-sparsify`، `guestfish`) و`qemu-utils` و`curl` ونحو 5 GB من المساحة الحرة على القرص. لا حاجة إلى KVM أو صلاحيات root. يلزم اتصال بالإنترنت لتثبيت الحزم (أو البناء باستخدام `--offline`). | | مكان أداة البناء | تأتي مع كل إصدار في `/opt/nexcmp/releases//share/templates/` على خادم اللوحة. لست بحاجة لتشغيلها هناك: انسخ المجلد إلى أي جهاز Linux. | | خادم ويب | أي خادم HTTP(S) يمكن لجهاز التخزين الثانوي الافتراضي في CloudStack الوصول إليه، لنشر ملف `.qcow2` المكتمل. ولا يشترط أن يكون متاحاً عبر الإنترنت. | | CloudStack | حساب يمتلك صلاحية تسجيل القوالب، ومُعرّف المنطقة (zone ID) ونوع نظام تشغيل متطابق. راجع [CloudStack](https://nexcmp.com/ar/docs/infrastructure/cloudstack/). | | Proxmox VE | أجهزة افتراضية لقوالب cloud-init مع QEMU guest agent، جهاز واحد لكل نظام تشغيل وكل عقدة. راجع [Proxmox VE](https://nexcmp.com/ar/docs/infrastructure/proxmox/). | | يعتمد على | ربط [CloudStack](https://nexcmp.com/ar/docs/infrastructure/cloudstack/) أو [Proxmox VE](https://nexcmp.com/ar/docs/infrastructure/proxmox/) أولاً. | ## تجهيز البنية التحتية {#prepare-the-infrastructure} ### CloudStack: بناء قالب {#cloudstack-build-a-template} الصور الأساسية المدعومة (يتم تنزيل صورة المورّد والتحقق من المجموع الاختباري الخاص بها قبل إجراء أي تغيير): | الصورة | `--distro` | مستخدم تسجيل الدخول | |---|---|---| | Ubuntu 22.04 | `ubuntu-22.04` | `ubuntu` | | Ubuntu 24.04 | `ubuntu-24.04` | `ubuntu` | | Debian 12 | `debian-12` | `debian` | | Rocky Linux 9 | `rocky-9` | `rocky` | توزيعات إضافية: أضف سطراً إلى `distros.conf` (رابط الصورة، وملف المجموع الاختباري، والعائلة `deb` أو `rpm`). 1. انسخ أداة البناء إلى جهاز البناء وشغّلها: ```bash cp -r /opt/nexcmp/releases//share/templates ~/templates && cd ~/templates ./build-template.sh --distro ubuntu-24.04 --version v7 --work ./out ``` أضف `--panel-url https://cloud.example.com` لتضمين عميل مراقبة اختياري يعمل عند أول إقلاع ويسجل نفسه في لوحتك (عبر HTTPS فقط). بدونه، لن يُضاف أي عميل. خيارات أخرى: `--base ` لاستخدام صورة قمت بتنزيلها، و`--offline` لتخطي تثبيت الحزم. 2. النتيجة هي `out/ubuntu-24.04-v7.qcow2` وملف `.sha256` الخاص به. تنتهي عملية البناء بتشغيل `verify-image.sh`، والذي يفحص الصورة المكتملة في وضع القراءة فقط ويرفض أي صورة غير صالحة (يتم الاحتفاظ بها كـ `.unverified`). يمكنك تشغيله مجددًا في أي وقت: `./verify-image.sh out/ubuntu-24.04-v7.qcow2 --no-agent`. ما تضعه أداة البناء في الصورة: | العنصر | السبب | |---|---| | `qemu-guest-agent` | يمكن لـ CloudStack الاستعلام من الجهاز الافتراضي عن وحدات المعالجة المركزية وعناوين IP، وتجميد نشاطه مؤقتًا لإنشاء Snapshots. | | cloud-init مع مصدر بيانات CloudStack، و`set_passwords` عند كل إقلاع، وتسجيل الدخول عبر SSH بكلمة المرور | يتم جلب كلمة المرور المُنشأة من الموجه الافتراضي ويعمل خيار **Reset password**. | | قاعدة udev لمعالجات CPU وذاكرة RAM المضافة أثناء التشغيل | تصبح معالجات vCPU وذاكرة RAM المضافة أثناء التشغيل نشطة تلقائيًا، مما يسمح بعمل التوسيع المباشر وAuto Scaling. | | خدمة ملف swap | يُنشئ `/swapfile` بالقيمة الأقل بين 50% من الذاكرة (RAM) و4 GiB بعد توسيع القرص. `touch /etc/cmp-swap.disabled` يعطل ذلك. | | cloud-init `growpart` و`resizefs` | يتوسع قرص الجذر (root) الصغير إلى حجم قرص الخطة عند أول إقلاع. | | معرّف machine-id فارغ، وبدون مفاتيح مضيف SSH | يحصل كل جهاز افتراضي على هويته الخاصة. | ::: warning تسمية القالب ` ` يقوم NexCMP بتفعيل **Auto Scaling** للقوالب التي ينتهي اسمها بـ `vN` أو `vN.M` مع **N بقيمة 6 أو أكثر** (`Ubuntu 24.04 v7`، `Rocky Linux 9 v7.1`). تفرض أداة البناء ذلك لـ `--version`. سجّل القالب بالاسم المطبوع تمامًا. ::: 3. انشر الملف وسجّله في CloudStack. استخدم قيمة SHA-256 التي طبعتها عملية البناء، ولا تقم بالتسجيل إلا بعد اكتمال كتابة الملف بالكامل: ```bash cmk list ostypes keyword="Ubuntu 24.04" filter=id,description cmk register template name="Ubuntu 24.04 v7" displaytext="Ubuntu 24.04 v7" \ url=https://files.example.com/ubuntu-24.04-v7.qcow2 zoneid= format=QCOW2 hypervisor=KVM \ ostypeid= passwordenabled=true sshkeyenabled=true isdynamicallyscalable=true \ requireshvm=true isextractable=false ispublic=true isfeatured=true \ checksum="{SHA-256}" \ details[0].guest.cpu.mode=host-passthrough details[0].rootDiskController=osdefault ``` - يتيح `passwordenabled=true` لـ CloudStack إنشاء كلمة مرور الجهاز الافتراضي. - يتيح `isdynamicallyscalable=true` إمكانية التوسيع المباشر أثناء التشغيل. - يلزم `host-passthrough` لإقلاع صور Rocky وAlma الحالية؛ بينما يحافظ `osdefault` على توافقية وحدة التحكم بالقرص. 4. انتظر حتى يصل القالب إلى حالة **Download Complete / Ready**. تحتفظ صورة المورّد بحجمها الافتراضي الصغير (حوالي 3.5 GiB لـ Ubuntu وDebian، و10 GiB لـ Rocky). تذكّر أن حجم قرص الخطة لا يمكن أن يكون أصغر من قرص القالب. ### Proxmox VE: إنشاء قالب {#proxmox-ve-make-a-template} أنشئ قالب جهاز افتراضي cloud-init لكل نظام تشغيل على كل عقدة تنشر إليها، مع تثبيت guest agent وتمكين تسجيل دخول root، ثم سجّله كـ `os-key=vmid`. الأوامر الكاملة متوفرة في [Proxmox VE](https://nexcmp.com/ar/docs/infrastructure/proxmox/). أداة بناء CloudStack الموضحة أعلاه **ليست** مخصصة لـ Proxmox: فهي تُعدّ cloud-init لمصدر بيانات CloudStack. ### ملفات ISO {#isos} يقوم العملاء بتركيب ملفات ISO الخاصة بهم عبر وحدة **Images** (CloudStack) أو وحدة Dedicated Server. وهي منفصلة عن قوالب أنظمة التشغيل في هذه الصفحة. راجع [Modules](https://nexcmp.com/ar/docs/infrastructure/modules/) و[Dedicated servers](https://nexcmp.com/ar/docs/infrastructure/dedicated/). ## الربط في NexCMP {#connect-in-nexcmp} 1. افتح **Services › Virtual Machines › Template**. انقر فوق **Sync now** أو انتظر حتى 15 دقيقة. تضيف المزامنة القوالب الجاهزة والمميزة في CloudStack. ![صفحة Template التي تسرد القوالب المتزامنة مع حالتها الجاهزة وعمود CPU hot-plug](https://nexcmp.com/ar/docs/images/infrastructure/templates-01-list.webp) 2. انقر على **Edit** في القالب الجديد وحدد ما يراه العملاء: | الحقل | مثال للقيمة | |---|---| | اسم العرض للعملاء | `Ubuntu 24.04 LTS` | | عائلة نظام التشغيل | `ubuntu` (الأيقونة والمستخدم الافتراضي) | | الإصدار | `24.04` | | اسم مستخدم تسجيل الدخول | `ubuntu` (في Windows: `Administrator`؛ الأنظمة الأخرى: `root`) | | الأيقونة | عنوان URL للصورة، أو مسار أو اسم | | الترتيب | `10` | | نشط | On | | التوصيل السريع لـ vCPU/RAM (الترقية المباشرة) | **Auto by name (v6 or later)** أو **Yes** أو **No (needs a restart)** | ![مربع حوار تعديل القالب مع اسم موجه للعميل، وعائلة نظام التشغيل، ومستخدم تسجيل الدخول وخيار التوصيل السريع](https://nexcmp.com/ar/docs/images/infrastructure/templates-02-edit.webp) 3. قم بتفعيل القالب. يتم إخفاء أي قالب لم يعد معروضاً في CloudStack تلقائياً (وسيصلك تنبيه عبر Telegram إذا تم إعداده)؛ ولا يتم حذفه أبداً من NexCMP. ### استبدال قالب بإصدار بناء أحدث {#replace-a-template-with-a-newer-build} استخدم **More › Replace with new version** في القالب المباع. اختر القالب الجديد والجاهز والمعطل حالياً. سيشير الإدخال المباع بعد ذلك إلى إصدار البناء الجديد ويحتفظ باسمه وترتيبه وأيقونته؛ ويتم تعطيل القديم كمسار للرجوع (للرجوع، استخدم **Replace** في الإدخال الجديد). لا تتأثر أجهزة VM قيد التشغيل. إذا كان إصدار البناء الجديد ينتمي لعائلة نظام تشغيل مختلفة، فقم بتحديد مربع التأكيد أولاً. ## التحقق {#verify} 1. يُظهر الصف **ready**، وبالنسبة لإصدارات البناء المسماة `vN` بقيمة N تبلغ 6 أو أكثر، **CPU hot-plug: supported**. 2. انشر جهاز VM تجريبياً واحداً من القالب وتحقق من داخل جهاز VM: - يمكنك تسجيل الدخول باستخدام كلمة المرور المعروضة في البوابة؛ - `df -h /` يُظهر حجم قرص الخطة؛ - بعد الترقية المباشرة (**Change plan** بدون إعادة تشغيل)، يزداد حجم `nproc` و`free -m`؛ - `swapon --show` يعرض `/swapfile` (يتم تخطي ذلك في الأقراص التي تقل مساحتها الفارغة عن swap بالإضافة إلى 2 GiB)؛ - `systemctl is-active qemu-guest-agent` يطبع `active`. 3. إذا قمت بتضمين العميل مسبقاً، فسيظهر جهاز VM ضمن الأجهزة المضيفة الخاضعة للمراقبة في اللوحة بعد دقيقة واحدة من أول إقلاع. يحتاج جهاز VM إلى عنوان IP عام خاص به: حيث تتعرف عليه اللوحة من خلال عنوان IP العام للمصدر. ## القيود والملاحظات {#limits-and-notes} - أداة البناء مخصصة لنظام Linux فقط وتبني صور Linux. يمكن تسجيل الصور الأخرى (مثل Windows) في CloudStack بطرق أخرى؛ ويعرض NexCMP ما يبلّغ عنه CloudStack. - يتم توفير عميل amd64 فقط؛ ويتم تخطي تثبيت العميل في المعماريات الأخرى. - يتم فحص الصورة باستخدام `guestfish` ولكن لا يتم إقلاعها مطلقاً بواسطة أداة البناء. احرص دائماً على نشر جهاز VM تجريبي واحد قبل بيع أي صورة جديدة. - تخطَّ العميل على جهاز VM واحد باستخدام `touch /etc/cmp-agent.disabled` قبل أول إقلاع. قم بإزالته لاحقاً باستخدام `systemctl disable --now cmp-agent cmp-agent-install; rm -rf /etc/cmp-agent /usr/local/bin/cmp-agent`، ثم احذف العميل في وحدة تحكم المسؤول. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | فشل `virt-customize` في تنزيل الحزم | جهاز البناء لا يملك اتصال شبكة صادراً | أصلح DNS أو الخادم الوكيل على ذلك الجهاز، أو قم بالبناء باستخدام `--offline` على صورة أساسية تحتوي على الحزم بالفعل. | | `libguestfs: error: /usr/bin/supermin exited with error status 1` | نواة المضيف غير قابلة للقراءة بواسطة المستخدم الحالي (Ubuntu) | `sudo chmod +r /boot/vmlinuz*`، أو شغّل البناء كـ root. | | المجموع الاختباري مختلف، أو لم تعد صورة المورّد موجودة | يقوم المورّدون بنقل ملفات "latest" الخاصة بهم | قم بتنزيل الصورة بنفسك، وتحقق منها بمقارنتها بملف المجموع الاختباري الخاص بالمورّد ثم مررها باستخدام `--base`. | | Rocky: يتعذر تركيب نظام XFS أحدث | نواة المضيف قديمة جداً | قم بالبناء على جهاز بنواة حديثة. | | `--version must be v6 or higher` | يجب أن يكون الاسم `vN` بقيمة N تبلغ 6 أو أكثر | استخدم `--version v7`. | | `--panel-url must be a plain https:// URL` | يتم تنزيل العميل وتشغيله كـ root، لذلك يتم رفض بروتوكول HTTP العادي | استخدم عنوان `https://` URL دون مسافات أو علامات اقتباس أو سلسلة استعلام. | | يبقى القالب بحالة **not ready** | لم ينتهِ CloudStack من التنزيل بعد | انتظر **Download Complete**، وتحقق من قدرة جهاز VM لوحدة التخزين الثانوية على الوصول إلى عنوان URL. | | يُظهر الصف **no-pass** | تم تسجيل القالب دون `passwordenabled=true` | أعد تسجيله باستخدام ذلك الخيار. | | خاصية التوصيل السريع لـ CPU تظهر كـ **unsupported** | الاسم لا ينتهي بـ `vN` (حيث N هو 6 أو أكثر) | أعد تسمية القالب، أو اضبط **vCPU/RAM hot-plug** على **Yes** في Edit إذا كانت الصورة تتضمن قاعدة udev. | | ظهور "قائمة قوالب فارغة" بعد الاتصال الأول | لم تتم عملية المزامنة بعد | انقر على **Sync now** (يتطلب تشغيل الـ worker) أو انتظر دورة الـ 15 دقيقة. | --- # الخوادم المخصصة (bare metal) {#dedicated-servers-bare-metal} > **المسار في لوحة الإدارة:** Infrastructure › Bare Metal (Servers `/infra/baremetal`، IP Pools، Stock / iDRAC import، Operations، Templates، Customer ISOs، Safety). الخطط والاشتراكات: Services › Dedicated Server (`/dedicated`). فعّل الوحدة من System › Admin › License & updates (`/license`). ## الوظيفة {#what-it-does} يدير NexCMP الخوادم الفعلية **مباشرة عبر iDRAC الخاصة بها**، من خلال Redfish API. يستأجر العملاء خادماً كاملاً: يقومون بتشغيله وإيقافه، وفتح وحدة تحكم المتصفح، وتوصيل ملف ISO أو تثبيت نظام تشغيل من قالب، والاطلاع على تفاصيل العتاد والمقاييس. لا يطّلع العملاء مطلقاً على عنوان iDRAC أو اسم المستخدم أو كلمة المرور. استخدمه لإعادة بيع الخوادم المخصصة من رفوفك الخاصة. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | العتاد | خوادم Dell مزودة بـ **iDRAC 9** وRedfish API. | | شبكة الإدارة | **أنت من يوفره.** يجب أن يتمكن خادم اللوحة من الوصول إلى كل iDRAC عبر **HTTPS 443** (ومنفذ VNC الخاص بـ iDRAC، الافتراضي **5901**، لوحدة التحكم console)، ويجب أن يتمكن كل iDRAC من الوصول إلى خادم الويب لملفات ISO أدناه. يجب أن يكون عنوان iDRAC عبارة عن **عنوان IPv4 ضمن نطاق خاص** (RFC 1918، ببادئة /16 أو أصغر) تقوم بإدراجه في الإعداد `dedicated_bmc_cidrs`. يتم رفض أسماء DNS وعناوين IPv6. لا يقوم NexCMP بإنشاء هذه الشبكة ولا يمكنه اختبارها نيابةً عنك. | | حساب iDRAC | حساب واحد بصلاحية **Administrator** على كل iDRAC. يستخدمه NexCMP لقراءة الخادم وإرسال الأوامر القليلة المسموح بها (الطاقة، الوسائط الافتراضية، الإقلاع لمرة واحدة، وحدة التحكم console). ولا يقوم مطلقًا بإنشاء حسابات iDRAC لعملائك. | | الأدوات على خادم اللوحة | `xorriso` و`genisoimage` (لبناء ملف ISO للتثبيت لكل خادم) و`novnc` (صفحة وحدة التحكم console في المتصفح). قم بتثبيتها باستخدام `sudo apt-get install -y xorriso genisoimage novnc`، أو دع برنامج التثبيت يقوم بذلك: شغّله مع `--baremetal`، أو مرر له خيارات خادم ISO؛ كما يقوم التحديث بتثبيتها أيضًا إذا كانت وحدة Bare Metal مفعّلة بالفعل. إذا كان أحدها مفقودًا، فستدرجه صفحة **Safety** في إشعار أحمر، وسيرفض مفتاح **live ops** التفعيل (الخطأ `tools_missing`)، وستفيد وحدة التحكم console وعملية تثبيت نظام التشغيل بأن هناك أداة مفقودة بدلاً من الفشل لاحقًا. | | خادم ويب لملفات ISO | خادم **HTTP** عادي على شبكة الإدارة يقدّم مجلد ISO الخاص بـ NexCMP لأجهزة iDRAC. عنوانه هو عنوان IPv4 خاص ومنفذ اختياري، على سبيل المثال `http://10.20.0.2:8080`، **بدون مسار**، ويُخزن في `dedicated_iso_base_url`. ويجب أن يدعم نطاقات البايت (byte ranges). تتم كتابة المجلد بواسطة worker اللوحة، لذلك يعمل خادم الويب عادةً على **خادم اللوحة نفسه**، مستمعًا على عنوان يملكه ذلك الخادم على شبكة الإدارة. يوفّر NexCMP موقع nginx جاهزًا وأمرًا من خطوة واحدة لإعداده (انظر أدناه). | | مجلدات ISO | مجلد لملفات ISO وداخله `pub` (ما تقرأه أجهزة iDRAC) و`server` (ملفات ISO الخاصة بالعملاء). يستخدم الأمر المكوّن من خطوة واحدة `/srv/nexcmp-iso`؛ ودونه تعتمد الإعدادات الافتراضية على التثبيت (الإعدادات `dedicated_iso_lib_dir` و`dedicated_iso_pub_dir` و`dedicated_iso_server_dir`). يجب أن يتمكن worker الخاص بـ NexCMP من **الكتابة** إليها. وهو يعمل بنظام ملفات للقراءة فقط باستثناء `/var/lib/nexcmp`، لذا يحتاج المجلد في مكان آخر إلى ملف systemd drop-in (يقوم الأمر المكوّن من خطوة واحدة بتثبيته). | | عنوان رد الاتصال (Callback) | `dedicated_callback_base`، وهو `https://` يمكن للخادم الجاري تثبيته الوصول إليه ويشير إلى لوحتك. | | التخزين | مساحة قرص خالية لمكتبة ISO ولملفات ISO المقدمة من العملاء. | | يعتمد على | وحدة **Bare Metal**، ونطاق (zone)، وتجمعات عناوين IP للخوادم. | ::: warning القيم النموذجية ليست إعدادات تهيئة يحمل التثبيت الجديد قيمًا نموذجية في `dedicated_bmc_cidrs` و`dedicated_iso_base_url` و`dedicated_callback_base` (شبكة نموذجية خاصة و`https://example.com`). وهي لا تمثل شبكتك. طالما أن أيًا منها لا يزال بقيمة نموذجية، ستعرض صفحات Bare Metal إشعارًا أحمر **Management network not configured**، وسيفشل استيراد iDRAC في فحص قائمة السماح، وسيرفض مفتاح **live ops** التفعيل (الخطأ `config_placeholder`). قم بتعيين القيم الثلاث ضمن **Infrastructure › Bare Metal › Safety › Management network connection** (انظر أدناه). ::: ## تجهيز البنية التحتية {#prepare-the-infrastructure} 1. **ضع كل وحدة iDRAC على شبكة إدارة** لا يمكن للعملاء الوصول إليها، وعيّن لكل منها عنوان IPv4 خاصاً وثابتاً. تحقق من Redfish API من خادم اللوحة: ```bash curl -sk -u 'nexcmp-admin:XXXX' https://10.20.0.11/redfish/v1/Systems | head ``` 2. **أنشئ حساب مسؤول على iDRAC** لصالح NexCMP (من واجهة ويب iDRAC، أو `racadm`). استخدم كلمة مرور قوية وفريدة. لا تعِد استخدام الحساب المدمج في iDRAC مطلقاً. 3. **نشر مجلد ISO لأجهزة iDRAC - بأمر واحد.** على خادم اللوحة، بصلاحيات root، مع العنوان الذي يملكه ذلك الخادم على شبكة الإدارة وشبكة iDRAC: ```bash sudo nexcmp dedicated-setup-iso --listen 10.20.0.2:8080 --allow 10.20.0.0/24 ``` يجب أن يكون `--listen` عنوانًا لهذا الخادم (عنوان IPv4 خاص، والمنفذ 8080 إذا تم حذفه). يدرج `--allow` شبكة (أو شبكات) iDRAC (عناوين CIDR خاصة، /16 أو أصغر، حتى 8، مفصولة بفواصل)؛ وحدها يمكنها التنزيل، كما يستخدمها الأمر أيضًا كـ `dedicated_bmc_cidrs` عندما يكون ذلك الإعداد لا يزال بالقيمة النموذجية. يحدد `--dir /path` مجلد ISO آخر (الافتراضي `/srv/nexcmp-iso`). يقوم الأمر بما يلي: - إنشاء المجلد مع `pub` و`server` بداخله، بملكية مستخدم خدمة NexCMP؛ - إنشاء المجموعة `nexcmp-iso` وإضافة مستخدم nginx إليها، حتى يتمكن nginx من قراءة ملف ISO أثناء وصله بواسطة iDRAC ودون أن يتمكن أي طرف آخر من ذلك؛ - تثبيت موقع nginx المسمى `nexcmp-iso` (يُحتفظ به فقط إذا قبله `nginx -t`، ويتم تثبيت nginx إذا كان مفقودًا) وملف systemd drop-in باسم `nexcmp-vmd.service.d/iso.conf` (`ReadWritePaths` للمجلد، `SupplementaryGroups=nexcmp-iso`)؛ - كتابة إعدادات ISO (`dedicated_iso_base_url`، والمجلدات الثلاثة، والمجموعة) وإعادة تشغيل worker الخاص بـ NexCMP. يمكن تشغيله مرة أخرى بقيم أخرى، ويقوم `sudo nexcmp dedicated-setup-iso --remove` بإزالة موقع nginx وملف drop-in مرة أخرى (تبقى ملفات ISO). كما يمكن تشغيله وقت التثبيت: أضف `--iso-listen` و`--iso-allow` (و`--iso-dir`) إلى أمر التثبيت. **لا** يقوم الأمر بإنشاء شبكة الإدارة ولا يتصل بأي iDRAC؛ وإذا كانت القيم غير صحيحة، أو لم يكن العنوان موجودًا على هذا الخادم أو كان المنفذ مشغولاً، فسيتوقف مع عرض رسالة قبل تغيير أي شيء، ولا يتم الاحتفاظ بموقع nginx يرفضه `nginx -t`. 4. **ما يوفّره خادم ويب ISO.** يستجيب موقع nginx لـ `GET` (و`HEAD`، مع نطاقات البايت) للمسار `/pub/.iso` ولا شيء غير ذلك: لا سرد للأدلة، ولا أي مسار آخر تحت المجلد (لا يمكن الوصول إلى المكتبة و`server/`)، ولا أي طريقة أخرى، وفقط من شبكات `--allow` (يحصل أي طرف آخر على 403). يعرض NexCMP كل ملف ISO يحتاج iDRAC إلى قراءته كملف أو رابط قصير الأجل في `pub`؛ يتبع nginx الرابط فقط عندما يكون للرابط ولهدفه نفس المالك (مستخدم الخدمة)، وبالتالي يُرفض أي رابط يشير إلى ملف نظام. تحقّق من ذلك من مضيف آخر على شبكة الإدارة: ```bash curl -I http://10.20.0.2:8080/ # 403 or 404, never a listing curl -I http://10.20.0.2:8080/pub/ # 403 or 404 ``` يجب أن يستجيب ملف اختبار في `pub` لطلب `Range` برمز 206. *إجراؤه يدويًا بدلاً من ذلك:* يُشحن موقع nginx وملف drop-in كقوالب في حزمة الإصدار (`share/dedicated/nginx-iso.conf` و`share/dedicated/vmd-iso.conf` ضمن `/opt/nexcmp/releases//`). انسخها، واستبدل علامات `__...__` (عنوان الاستماع، المجلد، أسطر allow، والمجموعة) مع الالتزام بالقواعد المذكورة أعلاه. 5. **جهّز صور أنظمة التشغيل.** ضع ملفات ISO ذاتية التثبيت في مجلد المكتبة (راجع **Templates** أدناه). يمكن للعملاء أيضاً إضافة ملفات ISO من رابط؛ حيث يتم تنزيلها إلى الخادم ولا تُمرر أبداً إلى iDRAC كرابط URL. ## الربط في NexCMP {#connect-in-nexcmp} ### 1. تفعيل الوحدة {#_1-turn-the-module-on} في **System › Admin › License & updates**، قم بتفعيل **Bare Metal**. سيظهر قسم **Bare Metal** ضمن Infrastructure. راجع [Modules](https://nexcmp.com/ar/docs/infrastructure/modules/). ### 2. تعيين اتصال شبكة الإدارة {#_2-set-the-management-network-connection} افتح **Infrastructure › Bare Metal › Safety**. تحتوي البطاقة **Management network connection** على القيم الثلاث التي تحدد ما إذا كان أي شيء يمكن أن يعمل: | الحقل | الإعداد | ما يجب إدخاله | |---|---|---| | شبكة iDRAC ‏(CIDR) | `dedicated_bmc_cidrs` | الشبكة (أو الشبكات) الخاصة لأجهزة iDRAC لديك، على سبيل المثال `10.20.0.0/24`. نطاقات CIDR خاصة فقط، /16 أو أصغر، حتى 8 نطاقات، مفصولة بفواصل. يمكن فقط استيراد أجهزة iDRAC الواقعة ضمن هذه النطاقات. | | خادم ISO لأجهزة iDRAC | `dedicated_iso_base_url` | `http://[:port]`، دون مسار: عنوان خادم ويب ISO من القسم السابق، على سبيل المثال `http://10.20.0.2:8080`. يقوم الأمر المكون من خطوة واحدة بملئه نيابةً عنك. | | عنوان معاودة الاتصال باللوحة | `dedicated_callback_base` | `https://`، دون مسار: العنوان الذي يتصل به الخادم الجاري تثبيته للإبلاغ عن الاكتمال. يجب أن يكون قابلاً للوصول من شبكة ذلك الخادم. يُرفض `example.com` و`localhost` وما شابه ذلك. | يتحقق النموذج من التنسيق أثناء الكتابة ويتحقق منه الخادم مجددًا عند الحفظ؛ تُرفض أي قيمة خاطئة مع توضيح السبب وتبقى القيمة المخزنة كما كانت. يحمل أي حقل لا يزال يحتوي على القيمة النموذجية الافتراضية شارة حمراء بعنوان **Not configured**، وتعرض كل صفحة من صفحات Bare Metal الإشعار الأحمر **Management network not configured** حتى تصبح القيم الثلاث حقيقية. تُسجَّل التغييرات في سجل التدقيق مع السبب الذي أدخلته. لا يُعدّ حفظ القيمة النموذجية مرة أخرى تهيئةً لها ما لم تكن قد كتبتها بنفسك. ### 3. التحقق من بوابة الأمان (اتركها مغلقة في الوقت الحالي) {#_3-check-the-safety-gate-leave-it-closed-for-now} افتح **Infrastructure › Bare Metal › Safety**. يُعد **Live ops** المفتاح على مستوى النظام لكل أمر كتابة إلى iDRAC (الطاقة، الوسائط الافتراضية، وحدة التحكم، وتثبيت نظام التشغيل). يبدأ في وضع إيقاف التشغيل (**off**)، ولا يمكن تفعيله طالما أن اتصال شبكة الإدارة أعلاه لا يزال يحتوي على قيم نموذجية (يستجيب المفتاح بـ `config_placeholder` ويذكر أسماء الحقول). تُرفض عمليات الكتابة على مستوى API ومجددًا داخل worker، بينما تستمر قراءة الحالة في العمل. يحمي قفل ثانٍ، وهو **ops_locked**، كل خادم: تكون الخوادم المستوردة حديثًا مقفلة دائمًا، حتى عند تفعيل live ops. ![صفحة Safety مع تعطيل Live ops وقائمة الإجراءات المحظورة](https://nexcmp.com/ar/docs/images/infrastructure/dedicated-01-safety.webp) ### 4. استيراد الخوادم {#_4-import-servers} 1. افتح **Infrastructure › Bare Metal › Stock / iDRAC import**. 2. ضمن **Add one server**، أدخل عنوان iDRAC والحساب وكلمة المرور، ثم انقر على **Test connection**. يُرسل الاختبار أوامر قراءة فقط ولا يحفظ أي شيء. | الحقل | مثال للقيمة | |---|---| | عنوان iDRAC (رابط URL أو مضيف) | `10.20.0.11` | | الحساب | `nexcmp-admin` | | كلمة المرور | `XXXX` | | المعرّف | `rack1-01` (فارغ: يتم توليده تلقائياً) | | تعيين عنوان IP من نطاق | اختياري؛ حدد نطاق عناوين IP لخدمة الخادم | | التضمين في قائمة المبيعات | معطّل حتى تصبح جاهزاً | ![المخزون واستيراد iDRAC مع عنوان تجريبي واختبار قراءة ناجح](https://nexcmp.com/ar/docs/images/infrastructure/dedicated-02-import-server.webp) 3. انقر على **Save to stock**. يقرأ NexCMP الطراز، وCPU، وRAM، والأقراص، وبطاقات NIC، وعلامة الخدمة من iDRAC. يدخل الخادم إلى المخزون بحالة **مقفول**. 4. بالنسبة لعدد كبير من الخوادم، استخدم **Bulk import**: خادم واحد في كل سطر، مع فصل الحقول بفاصلة، أو فاصلة منقوطة، أو علامة Tab. تتحقق ميزة **المعاينة** من القائمة المسموحة، ومن عدم تكرار عنوان iDRAC أو علامة الخدمة، وتقرأ مواصفات العتاد (حتى أربعة خوادم في المرة الواحدة). ### 5. ملفات ISO الخاصة بالعملاء وعنوان ويب ISO {#_5-customer-isos-and-the-iso-web-address} افتح **Infrastructure › Bare Metal › Customer ISOs**. - إن **HTTP address serving ISOs to iDRAC** هو `dedicated_iso_base_url`، وهو نفس القيمة الموجودة في بطاقة Safety (قابلة للتعديل في أي من المكانين). أدخل عنوان شبكة الإدارة لخادم ويب ISO لديك. - تحدد **حدود ISO للعملاء** حجم ملف ISO الواحد، وإجمالي مساحة تخزين ISO، والحد الأدنى للمساحة الحرة، ومدة الاحتفاظ بملفات ISO (بالساعات)، والحد الأقصى لوقت التنزيل، وعدد التنزيلات المتزامنة. ![ملفات ISO للعملاء مع عنوان HTTP لـ iDRACs وحدود ISO](https://nexcmp.com/ar/docs/images/infrastructure/dedicated-03-iso-settings.webp) ### 6. قوالب نظام التشغيل {#_6-os-templates} افتح **Infrastructure › Bare Metal › Templates**. يعرض هذا القسم ملفات ISO ذاتية التثبيت الموجودة في مجلد المكتبة. انقر على **Register** على أحد الملفات لتعبئة عائلة نظام التشغيل، والإصدار، والحساب (تُملأ مسبقاً من اسم الملف)، ثم قم بالتبديل إلى **Enable** للقالب. تفعيل القالب لا يبدأ أي عملية: لا يزال كل تثبيت يخضع لبوابة الأمان. يؤدي **إلغاء التسجيل** إلى إزالة سطر القالب فقط، ولا يحذف الملف أبداً. ![قوالب Bare Metal مع ملف ISO مسجل وآخر غير مسجل](https://nexcmp.com/ar/docs/images/infrastructure/dedicated-04-os-templates.webp) ### 7. مجموعات عناوين IP {#_7-ip-pools} افتح **Infrastructure › Bare Metal › IP Pools** وأضف نطاقات IPv4 التي تتلقاها الخوادم كعناوين خدمة. يحصل كل خادم على عنوان واحد؛ ويقوم خيار **Assign an IP from a pool** عند الاستيراد بأخذ العنوان المتاح التالي. تُحتسب العناوين المتاحة لكل مجموعة. ![مجموعات عناوين IP لخوادم Bare Metal مع نطاقات تجريبية وعدد العناوين المتاحة](https://nexcmp.com/ar/docs/images/infrastructure/dedicated-05-ip-pools.webp) ### 8. الخطط والبيع {#_8-plans-and-sale} 1. افتح **Services › Dedicated Server › Plans & pricing**. عدّل الخطط النموذجية الأربع (المسماة `BM-40C-` في 1.6.1) أو أنشئ خططك الخاصة: السعر ودورات الفوترة ورسوم الإعداد. **في عمليات التثبيت الجديدة، يتم إدخال الأسعار بالدولار الأمريكي بدقة السنت، ويُخصم من المحفظة هذا المبلغ تماماً: لا يلزم وجود سعر صرف.** أما التثبيت الذي يحتوي بالفعل على خطط مسعّرة بالدونغ الفيتنامي فيحتفظ بالدونغ ولا يزال بحاجة إلى سعر صرف في إعداداته (بدونه، تُرفض الطلبات مع `dedicated_fx_unavailable`). تبدأ الخطط النموذجية بسعر 0 وتكون **معطلة**: تحتاج الخطة المعروضة للبيع إلى سعر أعلى من 0. تحقق من كل خطة مقارنةً بالعتاد الذي تستورده فعلياً؛ فاسم الخطة النموذجية لا يكتشف عتاد الخادم ولا يغيّره. 2. افتح الخادم (Infrastructure › Bare Metal › the server › **Sales**)، و**اربط الخطة** وفعّل **Sellable**. 3. فعّل **live ops** (صفحة Safety، مع التأكيد المكتوب) وقم بإلغاء قفل الخوادم التي تريد تشغيلها (تبويب **Lock** الخاص بالخادم، مع كتابة سبب يُسجَّل في سجل التدقيق). 4. في **Services › Dedicated Server**، قم بتفعيل المبيعات. يتطلب ذلك خطوتين: قراءة التبعات، ثم كتابة `ENABLE SALES`. وحتى ذلك الحين، لن يرى العملاء أي صفحة طلب ولن يتم تحصيل أي مبالغ منهم. ![خطط Dedicated Server مع إيقاف مفتاح المبيعات](https://nexcmp.com/ar/docs/images/infrastructure/dedicated-06-plans.webp) ### ما يمكن للعملاء فعله في صفحة الخادم الخاصة بهم {#what-customers-can-do-on-their-server-page} تحتوي صفحة الخادم لدى العميل على ست عشرة علامة تبويب ضمن سبع مجموعات (Overview، وControl، وNetwork، وHardware، وBilling، وActivity، وSettings). تضم مجموعة **Billing** ما يلي: - **الخطة والتجديد**: الدفع مسبقاً لمدة تتراوح بين 1 و24 شهراً في خطوة واحدة؛ ويُحتسب التاريخ الجديد بدءاً من تاريخ التجديد الحالي مع الخصم من المحفظة مرة واحدة. يمكن تفعيل التجديد التلقائي أو إيقافه. - **Billing cycle**: اختر دورة فوترة أخرى (على سبيل المثال ربع سنوية)؛ وتُطبّق اعتباراً من التجديد **التالي**، دون خصم أو استرداد أي مبالغ حالياً. - **Change plan**: يمكن للعميل **طلب** خطة أخرى، دون خصم أي مبلغ مقابل هذا الطلب. ويمكنك الموافقة عليه أو رفضه عبر **Services › Dedicated Server › Plan changes** بعد ترقية العتاد أو نقل الخادم. في حال الموافقة على الترقية، يُخصم فرق السعر عن المدة المتبقية التي دفعها العميل مسبقاً؛ أما التخفيض فلا يترتب عليه أي استرداد مالي ويُطبّق اعتباراً من الفترة التالية. - **Invoices**: جميع فواتير هذا الخادم (الطلب، والتجديدات، والترقيات). في **Plan changes**، يمكنك فرز الطلبات حسب المعرّف (ID)، أو التاريخ، أو الحالة، أو الخطط، أو الخادم؛ ويشمل الفرز النتيجة الكاملة على الخادم. يظل عمود الإجراءات مرئياً عند التمرير أفقياً على الشاشات الضيقة. في الجزء العلوي من **Overview**، تعرض أربع لوحات حية **CPU** و**RAM** و**Disk** و**Network**، مع رسم بياني صغير لآخر 24 ساعة. تمثل CPU وRAM وDisk نسب الاستخدام المئوية من آخر استطلاع لـ iDRAC (يمثل Disk نشاط الإدخال/الإخراج وليس المساحة الخالية)؛ بينما يمثل Network سرعة البيانات الواردة والصادرة الحالية بالإضافة إلى الإجمالي الشهري، مأخوذًا من عداد حركة المرور. تعرض اللوحة **—** وسببًا وجيزًا عندما يكون الخادم متوقفًا، أو يتعذر الوصول إلى iDRAC، أو عندما لا يبلغ الجهاز عن تلك القيمة؛ ولا تعرض أبدًا القيمة 0 مصطنعة. تأتي هذه القراءات من Dell iDRAC، وبدون عداد حركة المرور تظل لوحة Network عند **—**. يتم تحديث اللوحات كل دقيقة أثناء فتح الصفحة، وتؤدي النقرة إلى فتح علامة التبويب **Hardware** أو **Bandwidth**. في صفحة **Overview**، تعرض بطاقة **Access** اسم المستخدم وكلمة مرور نظام التشغيل الذي قمت بتثبيته، وتكون مخفية افتراضياً مع زري **Show** و**Copy**. وتتاح بعد كل عملية تثبيت وليس لمرة واحدة فقط، ولا يرى المالك الجديد للخادم كلمة مرور المالك السابق مطلقاً. وإذا تم تغيير كلمة مرور نظام التشغيل من داخل الخادم، فستظل البطاقة تعرض الكلمة المحددة وقت التثبيت. لا تظهر علامة التبويب **Bandwidth** إلا عندما يغذيها عداد حركة المرور (راجع Limits). لا توجد علامة تبويب **Subnet**: فجلب بادئة IP الخاصة بك إلى خادم مستأجر ليس مدعوماً في NexCMP. ### ما يمكن للعملاء فعله وما لا يمكنهم فعله {#what-customers-can-and-cannot-do} | يمكن للعملاء | غير ممكن إطلاقًا | |---|---| | عرض العتاد، والحالة الصحية، وحالة الطاقة، والمقاييس | عرض عنوان iDRAC أو اسم المستخدم أو كلمة المرور | | التشغيل، وإيقاف التشغيل الآمن، وإعادة التشغيل، والإيقاف الإجباري، وإعادة الضبط | تغيير حسابات iDRAC أو إعدادات شبكة iDRAC | | فتح وحدة تحكم المتصفح (جلسة واحدة في كل مرة) | تغيير إعدادات BIOS أو RAID، ومسح السجلات، وتحديث البرامج الثابتة، وإعادة ضبط iDRAC | | تحميل ملف ISO أو رابط ISO خاص، وتعيين الإقلاع لمرة واحدة، وإعادة تثبيت نظام التشغيل من قالب مفعّل | تشغيل استدعاءات Redfish المباشرة (هذه الوظائف غير متوفرة في NexCMP) | لا ينشئ NexCMP حسابات iDRAC للعملاء: فهم يستخدمون عناصر التحكم في البوابة فقط، ولا يُعرض لهم عنوان iDRAC أو بيانات تسجيل الدخول الخاصة به مطلقاً. ## التحقق {#verify} 0. في **Safety**، لا تعرض بطاقة **Management network connection** أي شارة حمراء ولا تعرض صفحات Bare Metal أي إشعار أحمر. ومن أي مضيف على شبكة الإدارة، لا يعرض `curl -I http:///` أي ملفات. 1. يُرجع خيار **Test connection** في نموذج الاستيراد الطراز وCPU وRAM وservice tag. 2. يظهر الخادم في **Servers** مع عتاده. وعندما تكون **live ops off**، يُرفض إجراء الطاقة مع ظهور "Server control is temporarily disabled system-wide". 3. بعد تفعيل live ops وإلغاء قفل خادم اختبار واحد، قم بإيقاف تشغيل الخادم وتشغيله من **Operations** أو من صفحة الخادم، وافتح وحدة التحكم. 4. قم بإنشاء طلب تجريبي باستخدام خطة تجريبية: يتم تعيين الخادم، وتثبيت نظام التشغيل، وينتهي التثبيت بإرسال الخادم لتقرير يفيد بجاهزيته إلى اللوحة. ## القيود والملاحظات {#limits-and-notes} - يمتلك كل خادم فعلي اشتراكًا نشطًا واحدًا على الأكثر. - لا يتم إرسال أمر كتابة إلا إذا كان **كلا** الأمرين محققًا: تشغيل live ops **و**فتح قفل الخادم. ويتكرر هذا التحقق داخل worker مباشرة قبل كل أمر. - تنتظر حالة **Installing** استجابة نظام التشغيل الجديد على المنفذ الخاص به (SSH 22، أو Windows 3389، أو Proxmox 8006) قبل اكتمال الطلب؛ وتخضع عملية التثبيت لحد زمني أقصى (`dedicated_install_timeout_min`، وهو 150 دقيقة افتراضيًا). - يتم احتساب عرض النطاق الترددي للخوادم المخصصة عبر وكيل لعد حركة المرور لا يشكل جزءاً من التثبيت القياسي. وبدونه لا يُسجَّل أي شيء، وتخفي البوابة علامة التبويب Bandwidth، ويُبلغ API عن `capabilities.bandwidth` كـ `false`. - إجراءات المسؤول على الخادم المستأجر (القفل، وإلغاء القفل، والإلغاء مع استرداد المبلغ أو بدونه) هي نفس الإجراءات الموحدة المتبعة مع كل خدمة أخرى، مع إعادة المبالغ المستردة إلى الرصيد الذي تم الدفع منه. - لا تتم إعادة بيع الخوادم عبر الموزعين: تُباع خدمة Dedicated من الموقع الرئيسي فقط. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | فشل الاختبار بسبب خطأ في العنوان | العنوان ليس بصيغة IPv4 حرفية ضمن `dedicated_bmc_cidrs` (خاص، /16 أو أصغر) أو أن المنفذ غير مسموح به | استخدم عنوان IPv4 الخاص بـ iDRAC وأضف شبكته ضمن Safety › Management network connection (`dedicated_bmc_cidrs`). يتم رفض أسماء DNS وعناوين IPv6. | | إشعار أحمر "Management network not configured"، أو يرد مفتاح العمليات المباشرة بـ `config_placeholder` | إحدى القيم `dedicated_bmc_cidrs` أو `dedicated_iso_base_url` أو `dedicated_callback_base` لا تزال تحتوي على القيمة النموذجية الافتراضية | أدخل القيم الفعلية ضمن Safety › Management network connection. | | يتم رفض أحد الحقول عند الحفظ | صيغة غير صحيحة (نطاق CIDR ليس خاصاً أو أوسع من /16، أو عنوان ISO ليس `http://[:port]`، أو الاستدعاء ليس `https://`)، أو استخدام عنوان نموذجي مثل `example.com` | اقرأ الرسالة الموجودة أسفل الحقل؛ تظل القيمة المخزنة دون تغيير. | | يتوقف `nexcmp dedicated-setup-iso` قبل إجراء أي تغيير | `--listen` ليس عنواناً لهذا الخادم، أو المنفذ مستخدم بالفعل، أو توجد قيمة غير صالحة | استخدم العنوان الخاص بهذا الخادم على شبكة الإدارة، أو منفذاً آخر، أو صحح القيمة المذكورة في الرسالة. | | "تختلف شهادة TLS الخاصة بـ iDRAC عن الشهادة المثبتة - توقفت عمليات الاستقصاء وإجراءات الكتابة" | تم استبدال شهادة iDRAC (شهادة جديدة، أو استبدال وحدة iDRAC) | افتح الخادم، وانتقل إلى علامة التبويب **Access**، وقارن بين بصمتي الإصبع، وإذا كان التغيير مقصوداً، فانقر على **Repin certificate**. | | "تم تعطيل التحكم في الخادم مؤقتًا على مستوى النظام" | ميزة Live ops معطلة | قم بتفعيلها من **Safety**. | | "هذا الخادم مقفل أمام العمليات" | القفل المخصص لكل خادم مغلق | افتح القفل في علامة التبويب **Lock** الخاصة بالخادم مع تحديد السبب. | | "لا تزال هناك عملية أخرى قيد التشغيل على هذا الخادم" | العملية السابقة لم تكتمل بعد | انتظر؛ وتحقق من **Operations**. | | "توجد جلسة وحدة تحكم أخرى مفتوحة بالفعل على هذا الخادم" | جلسة وحدة تحكم واحدة فقط في كل مرة | أغلق الجلسة الأخرى. | | "وحدة التحكم الخاصة بالخادم غير متاحة مؤقتًا" | وحدة iDRAC لا تستجيب | تحقق من شبكة الإدارة ومن وحدة iDRAC. | | فشل تثبيت ISO مع ظهور الخطأ 403 أو 404 من iDRAC | خادم الويب لا يمكنه قراءة الملف أو أن العنوان الأساسي غير صحيح | تحقق من أذونات خادم ويب ملفات ISO ومن **HTTP address serving ISOs to iDRAC**. | | "هذه الخطة غير متوفرة في الموقع المحدد" | لا يوجد خادم متاح للبيع بهذه الخطة في تلك المنطقة | اربط الخطة بخادم وقم بتفعيل **Sellable**. | | "لا يتوفر أي عنوان IPv4 لتعيينه في الوقت الحالي" | مجمع عناوين IP فارغ | أضف عناوين إلى المجمع. | | "التثبيت التلقائي لنظام التشغيل غير متاح حاليًا" | متطلبات التثبيت المسبقة مفقودة | تحقق من تفعيل القالب وقابلية الكتابة في مجلدات ISO؛ لا يزال بإمكان العملاء التثبيت عبر ISO ووحدة التحكم. | | توقف التثبيت | الخادم الجاري تثبيته لا يمكنه الوصول إلى عنوان رد الاتصال | تحقق من `dedicated_callback_base` ومن قدرة شبكة الخادم على الوصول إلى لوحتك عبر HTTPS. | --- # عقد VPN ووكيل IPv6 {#vpn-and-ipv6-proxy-nodes} > **المسار في لوحة الإدارة:** Infrastructure › VPN & Proxy nodes › Agents & external nodes (`/agents`)، وVPN IP pools (`/vpn/pool`)، وIPv6 Proxy nodes (`/vpn/proxy6/nodes`). الخدمات نفسها متاحة تحت Services › VPN وServices › IPv6 Proxy. يتم تفعيل كلا الوحدتين في System › Admin › License & updates. ## الوظيفة {#what-it-does} يوفر NexCMP إمكانية بيع وصول VPN والوكيل الذي يخرج عبر **عناوين IP تمتلكها**، على خوادم تديرها بنفسك. يتوفر نوعان من العقد: - **عقدة VPN.** برنامج صغير مكتوب بلغة Go باسم `cmp-agent`، يعمل على خادم Linux لديك. يكتشف عناوين IPv4 العامة على الخادم، ويفتح منافذ استماع SOCKS5 وHTTP وUDP على كل عنوان مبيوع، ويخرج حركة المرور من **نفس عنوان IP** الذي اتصل به العميل (same-IP egress). يُرسل تقاريره إلى اللوحة كل بضع ثوانٍ. - **عقدة بروكسي IPv6.** خدمة بروكسي تمنح العملاء عناوين من بادئة IPv6 تقوم بتوجيهها إلى المضيف. تقوم اللوحة بتثبيتها نيابة عنك عبر SSH. استخدمها لإعادة بيع عناوين IP نظيفة في البلدان التي تمتلك فيها خوادم. ## المتطلبات {#requirements} ### عقدة VPN {#vpn-node} | العنصر | المتطلب | |---|---| | نظام التشغيل | توزيعة Linux مع systemd ونواة بإصدار 4.15 أو أحدث (دعم ربط IPv6 الحر). الملف التنفيذي للعميل المرفق مخصص لـ **x86_64** (amd64) فقط. | | الصلاحيات | root، من أجل التثبيت. تحتفظ الخدمة فقط بـ `CAP_NET_ADMIN` و`CAP_NET_RAW` و`CAP_DAC_READ_SEARCH`. | | الأدوات | `curl` أو `wget`، و`sha256sum` (يرفض برنامج التثبيت المتابعة دون فحص الملف). | | العناوين العامة | عناوين IPv4 عامة معينة على واجهة في المضيف (واحد `/32` لكل منها)، **أو** بادئة موجهة إلى المضيف تقوم بإضافتها كشبكة فرعية إضافية (IPv4 من /16 إلى /32، وIPv6 من /48 إلى /128). يتم تجاهل النطاقات الخاصة ونطاقات CGNAT ونطاقات التوثيق. | | الشبكة، الواردة | يتصل العملاء بكل عنوان IP عام مَباع عبر **المنافذ 65001-65535** (TCP لـ SOCKS5 وHTTP، وUDP لـ UDP associate). تستخدم كل نقطة نهاية مجموعة من ثلاثة منافذ متتالية. | | الشبكة، الصادرة | HTTPS (443) إلى نطاق لوحتك. يبحث العميل أيضاً عن بلده عبر `ip-api.com` (HTTP) و`ipinfo.io` (HTTPS)، بحد زمني أقصاه 3.5 ثانية. | | البريد | الاتصالات الصادرة إلى المنفذ 25 محظورة دائمًا؛ ولا يوجد إعداد لفتحه. | | واجهات Docker وVPN والواجهات الافتراضية | الواجهات المسماة `docker*` و`veth*` و`br-*` و`cni*` و`flannel*` و`virbr*` و`cali*` و`tun*` و`tap*` و`wg*` و`tailscale*` لا تقدم عناوين. | | يعتمد على | الوحدة **VPN**، ومنطقة (يتم إنشاؤها تلقائياً من بلد المضيف)، ولوحة NexCMP يمكن الوصول إليها عبر HTTPS. | ### عقدة وكيل IPv6 {#ipv6-proxy-node} | العنصر | المتطلب | |---|---| | نظام التشغيل | Linux مع systemd على **x86_64**. يجب أن تكون الأوامر `systemctl` و`nft` و`ip` و`ss` و`sysctl` و`useradd` متوفرة؛ وإلا فسيتوقف التثبيت مع ذكر الأمر المفقود. | | الوصول من أجل التثبيت | عنوان IPv4 عام (يتم رفض العناوين الخاصة وعناوين loopback وCGNAT)، ومنفذ SSH، وحساب بصلاحيات root أو `sudo` مع **كلمة المرور** الخاصة به. تُستخدم كلمة المرور للتثبيت فقط ولا يتم تخزينها. | | المنافذ الشاغرة | يجب أن تكون المنافذ **80 و443 وكل منفذ أعلى من 60000** شاغرة. لا يقوم برنامج التثبيت أبداً بإيقاف أو تعديل الخدمات قيد التشغيل بالفعل؛ بل يبلغ عن المنافذ المشغولة ويتوقف. | | IPv6 | بادئة عامة بين **/32 و/64** داخل `2000::/3` يمكن للمضيف استخدامها كمصدر لحركة المرور الصادرة، وتُسلم إما **موجهة** إلى المضيف أو **on-link** مع NDP proxy (انظر أدناه). | | الشبكة | يتصل العملاء بعنوان IPv4 الخاص بالعقدة عبر المنفذ 80 (بروكسي HTTP)، والمنفذ 443 (SOCKS5)، والمنافذ 60001-65535 (منفذ واحد لكل عنوان IP ثابت). لا تمتلك العقدة شهادة، لذا لا يوجد بروكسي HTTPS. تخرج حركة المرور عبر IPv6 فقط، وإلى الوجهات التي تمتلك عنوان IPv6 فقط. تسحب العقدة إعداداتها من اللوحة عبر HTTPS. | | برمجيات العقدة على خادم اللوحة | يأتي برنامج العقدة الخفي وسكربت الشبكة الخاص به ضمن حزمة إصدار NexCMP. تنسخهما اللوحة من مجلد التثبيت الخاص بها (`/opt/nexcmp/releases//bin`، أو `/opt/nexcmp/bin` في الإصدارات المخصصة) إلى كل عقدة أثناء التثبيت. يحتاج خادم اللوحة أيضًا إلى `sshpass` وعميل SSH؛ يضيف برنامج التثبيت `sshpass`، وعلى الخوادم المثبتة قبل 1.4.2 يمكنك إضافته عبر `sudo apt-get install -y sshpass`. | | يعتمد على | الوحدة **IPv6 Proxy**، ورابط اللوحة الذي تعاود العقد الاتصال به (**IPv6 Proxy › Settings › Panel URL for nodes**، الافتراضي `https://`). | ## تجهيز البنية التحتية {#prepare-the-infrastructure} ### عقدة VPN {#vpn-node-1} 1. **قم بتهيئة المضيف** بنظام Linux مدعوم وعناوين IPv4 العامة التي ترغب في بيعها، سواء كانت مهيأة على واجهة الشبكة أو موجهة إلى المضيف. 2. **إذا كنت تبيع نطاقًا موجّهًا**، فاحرص على إدخاله كـ **Extra subnet** عند إضافة العقدة. يقوم العميل بتثبيت مسار `local dev lo` حتى يقبل المضيف حركة المرور لكل عنوان في النطاق، ثم يُبلّغ عن العناوين التي يعثر عليها. يقرأ العميل أيضًا جدول التوجيه الفعلي للمضيف ولا يبيع أو يلتقط عنوان **gateway** مطلقًا: إذا كان النطاق يحتوي على الخطوة التالية (next-hop) لأحد مسارات المضيف (على سبيل المثال عنوان الموجه لنطاق on-link)، يثبت العميل مسارات `local` فقط للأجزاء المحيطة به من النطاق، ويُبلّغ اللوحة بعنوان gateway، فتحتفظ اللوحة بهذا العنوان خارج التجمع وخارج كل عملية تخصيص. كما يزيل المسارات التي ثبّتها عند تغيير الشبكة الفرعية الإضافية أو إيقاف العميل. 3. **افتح جدار الحماية.** اسمح بحركة مرور TCP وUDP الواردة عبر المنافذ **65001-65535** على العناوين العامة، وحركة مرور HTTPS الصادرة إلى اللوحة. 4. **اختياري: عدادات البايتات لكل عنوان IP.** تتيح محاسبة Conntrack (`net.netfilter.nf_conntrack_acct = 1`) لدور المراقبة حساب البايتات لكل عنوان IP. يمكن للوحة تشغيلها عن طريق إرسال أمر `acct` إلى العميل، والذي يكتب أيضاً `/etc/sysctl.d/99-cmp-agent.conf`. دور VPN نفسه لا يحتاج إليها. 5. **تحقق من اللوحة من العقدة:** ```bash curl -fsS -o /dev/null -w '%{http_code}\n' https://cloud.example.com/install.sh ``` ### عقدة وكيل IPv6 {#ipv6-proxy-node-1} تصل بادئة IPv6 إلى العقدة بإحدى طريقتين. يختبر برنامج التثبيت كلتيهما باتصالات صادرة حقيقية ويحتفظ بما يعمل بنجاح. | النوع | المعنى | ما تقوم بتهيئته | |---|---|---| | **Routed** | يقوم مزود الخدمة بتوجيه بادئة (على سبيل المثال /48 أو /56) **إلى عنوان العقدة نفسه**. يمكن للحزم الصادرة استخدام أي عنوان في البادئة كمصدر لها وتعود الردود إلى العقدة. | اطلب من مزودك بادئة موجّهة تكون قفزتها التالية هي العقدة. لا يلزم أي شيء إضافي على العقدة: تستخدم خدمة الوكيل مقابس شفافة وجدول توجيه سياسات ثابتاً و`nft`. | | **On-link** | توجد البادئة /64 على نفس شبكة LAN الخاصة بالعقدة. لا تعمل الردود إلا إذا أجابت العقدة على استكشاف الجوار (neighbour discovery) لكل عنوان قيد الاستخدام (**NDP proxy**). | تضبط الخدمة، على تلك الواجهة فقط، `net.ipv6.conf..accept_ra=2` و`forwarding=1` و`proxy_ndp=1`، وتتذكر القيم القديمة، وتستعيدها عند توقفها، وتحظر إعادة توجيه عناوين التجمع حتى لا تصبح العقدة موجّهاً للتجمع. | كيفية عمل الفحص: تحاول العقدة إنشاء اتصال TCP بعنوان IPv6 عام (المنفذ 443) من عنوان عشوائي للبادئة المرشحة، خلال 6 ثوانٍ. العناوين المرشحة هي العناوين العمومية على الواجهات ذات بادئة /64 أو أقصر، بالإضافة إلى مسارات من النوع `local` أو `unreachable` أو `blackhole` بين /16 و/64. تُقبل البادئة الأقصر من /64 كـ **routed** إذا عملت بادئة /64 عشوائية بداخلها بنجاح. ::: warning لا تستخدم البادئة نفسها مرتين لا يجوز أن تتداخل البادئة مع بادئة لعقدة أخرى، ولا يجوز أن تكون أوسع من بادئة تنتمي بالفعل إلى تجمع IPv6 الخاص باللوحة نفسها. يُسمح ببادئة /64 **داخل** تجمع اللوحة. يتم الإبلاغ عن حالات التداخل كـ "assign range … (node …)" في نتيجة التثبيت، ويتم تخطي البادئة. ::: القيود التي تطبقها العقدة تلقائياً: لا يمكن للعملاء إرسال البريد (المنافذ 25، 465، 587، 2525) من عناوين التجمع، وتقتصر حركة مرور IPv4 الخاصة بالبرنامج الخفي (daemon) على الردود وعلى اللوحة وDNS. ## الربط في NexCMP {#connect-in-nexcmp} ### عقدة VPN {#vpn-node-2} 1. في **System › Admin › License & updates**، قم بتشغيل **VPN**. راجع [Modules](https://nexcmp.com/ar/docs/infrastructure/modules/). ![بطاقة Module مع مفتاحي تبديل VPN وIPv6 Proxy](https://nexcmp.com/ar/docs/images/infrastructure/vpn-proxy-nodes-01-modules.webp) 2. افتح **Infrastructure › VPN & Proxy nodes › Agents & external nodes**. لديك طريقتان لإضافة عقدة. **أ. التثبيت عبر SSH.** انقر فوق **+ Add server (SSH)** واملأ الحقول التالية: | الحقل | مثال للقيمة | |---|---| | عنوان IPv4 للخادم | `192.0.2.50` | | منفذ SSH | `22` | | مستخدم SSH | `root` | | كلمة مرور SSH | `XXXX` | | الاسم المعروض | `node-ny-1` (فارغ: التسمية وفقاً لعنوان IP) | | دور الخادم | External VPN / Proxy Node | | تعيين المنطقة | تلقائياً حسب GeoIP (إنشاء / تعيين Zone)، أو منطقة حالية | | شبكة فرعية إضافية (اختياري) | اتركه فارغاً للمسح التلقائي للواجهات، أو كتلة موجّهة مثل `203.0.113.0/24` | | تمكين للبيع بعد التثبيت | مفعّل لتمييز كل عنوان تم اكتشافه على أنه متاح للبيع | انقر فوق **Connect & install**. تتصل اللوحة عبر SSH، وتُشغّل برنامج التثبيت ذا السطر الواحد على العقدة باستخدام تذكرة لمرة واحدة، وتعرض اسم العقدة وموقع GeoIP والنطاقات المكتشفة. ![مربع حوار Add Node via SSH مع مثال لعنوان الخادم والدور](https://nexcmp.com/ar/docs/images/infrastructure/vpn-proxy-nodes-02-add-server-ssh.webp) **ب. التثبيت اليدوي.** انقر على **Generate manual install token**. يظهر الأمر **مرة واحدة فقط**؛ انسخه وشغّله على العقدة: ```bash curl -fsSL https://cloud.example.com/install.sh | sudo sh -s -- --token XXXX --name node-ny-1 ``` يؤدي التثبيت عبر الرمز المميز إلى تسجيل الجهاز للمراقبة فقط: لدواعي الأمان، لا تسمح اللوحة للجهاز الذي يحمل الرمز المشترك بمنح نفسه دور VPN (إضافة `--roles vpn` إلى الأمر ليس لها أي تأثير). بعد ظهور الجهاز في القائمة، افتحه وأضف دور **VPN** بنفسك. يؤدي التثبيت عبر SSH (الخيار أ) إلى منح العقدة دور VPN منذ البداية. يؤدي إنشاء رمز جديد إلى إلغاء الرمز القديم؛ وتستمر المضيفات المسجلة بالفعل في العمل لأنها تستخدم مفتاحها الخاص. ![مربع حوار أمر التثبيت يوضح أمر الرمز لمرة واحدة](https://nexcmp.com/ar/docs/images/infrastructure/vpn-proxy-nodes-03-install-command.webp) ما يقوم به برنامج التثبيت: ينزّل `cmp-agent-linux-amd64` من لوحتك، و**يتحقق من تجزئة SHA-256 الخاصة به**، ويثبته في `/usr/local/bin/cmp-agent`، ويسجله باستخدام الرمز، ويكتب `/etc/cmp-agent/agent.json`، ثم يشغّل خدمة systemd المسماة `cmp-agent`. لإزالته: `curl -fsSL https://cloud.example.com/install.sh | sudo sh -s -- --uninstall`. 3. بعد أول إشارة نبض، تظهر العقدة في القائمة. ويتم تحديد بلدها عبر GeoIP (بحث العقدة نفسها أولاً، ثم قاعدة بيانات اللوحة)؛ ويتم إنشاء **منطقة** لهذا البلد وجعلها عامة إذا لم تكن موجودة، وتصبح العناوين التي عُثر عليها في المضيف نطاقات تجمع. 4. افتح **Infrastructure › VPN & Proxy nodes › VPN IP pools** للاطلاع على النطاقات ومنطقتها وعقدتها، ولتغيير المنطقة أو العقدة أو مفتاح **Sellable** لكل نطاق. يتيح خيار **Enable range** للطلبات الجديدة استخدام عناوين IP الشاغرة فيها؛ بينما يوقف **Disable range** التعيينات الجديدة فقط، مع استمرار عمل عناوين IP المؤجرة. ![تجمعات عناوين IP لـ VPN مع النطاقات التي أبلغت عنها العقدة](https://nexcmp.com/ar/docs/images/infrastructure/vpn-proxy-nodes-04-vpn-pool.webp) 5. افتح **Services › VPN**، وحدد قائمة الأسعار وفعّل المبيعات. مفتاح التبديل **Sell VPN** في **Subscriptions** هو المفتاح نفسه لوحدة VPN في License & updates. 6. **اختياري: إعادة تسمية الخدمة.** في **Settings › Branding**، يغيّر **VPN service display name** كيفية تسمية خدمة VPN في قائمة العميل وصفحة الطلب وصفحة التفاصيل وقائمة النشر (على سبيل المثال `IPv4 Proxy` أو `Datacenter Proxy` أو `Static Residential Proxy`؛ حتى 40 حرفاً، والترك فارغاً يُبقي `VPN`). يغيّر هذا التسميات فقط: لا تتغير المسارات والبيانات و API. ### عقدة وكيل IPv6 {#ipv6-proxy-node-2} 1. في **System › Admin › License & updates**، فعّل **IPv6 Proxy**. 2. افتح **Infrastructure › VPN & Proxy nodes › IPv6 Proxy nodes** وانقر على **Add node (SSH)**. أدخل عنوان IPv4 الخاص بالعقدة، ومنفذ SSH، واسم المستخدم، وكلمة المرور، واسمًا اختياريًا، و**السبب** (يُسجل في سجل التدقيق)، ثم انقر على **Install**. ![مربع حوار Add IPv6 node مع عنوان وسبب توضيحيين](https://nexcmp.com/ar/docs/images/infrastructure/vpn-proxy-nodes-05-proxy6-add-node.webp) 3. تقوم اللوحة بعد ذلك، بالترتيب: بفحص الجهاز والمنافذ، ونسخ برنامج daemon، وسكربت الشبكة، ووحدة الخدمة، وملف بيئة خاص بالعقدة (رمز العقدة ومفتاح توقيع كلمة المرور)، وتشغيل **الفحص** للبادئات القابلة للاستخدام، وتسجيل البادئات في التجمع، وبدء تشغيل الخدمة، والانتظار حتى 90 ثانية لأول تقرير. يعرض **Install log** كل خطوة. 4. تُنشئ العقدة الجديدة منطقتها في حالة **إيقاف التشغيل** (استنادًا إلى GeoIP لعنوان IPv4 الخاص بالعقدة). قم بتفعيل المنطقة ضمن **Infrastructure › Datacenter › Zone** حتى يتمكن العملاء من اختيارها. 5. عيّن **Mbps cap** إجماليًا لكل عقدة (من 10 إلى 100000 لكل اتجاه). وضمن **Services › IPv6 Proxy**، حدد قائمة الأسعار وفعّل المبيعات. 6. تحقق من **IPv6 Proxy › Settings › Panel URL for nodes**. تتصل العقد بهذا العنوان (`https://host`، بدون مسار) لسحب إعداداتها وإرسال التقارير. تركه فارغًا يعني `https://`. يجب أن يكون مضيفًا يشير عنوانه مباشرة إلى اللوحة، حتى يصل عنوان IPv4 الخاص بالعقدة إليها دون تغيير. ::: tip جدول التدوير يمكن للعملاء ضبط فترة تدوير تلقائي تتراوح بين 30 و600 ثانية. في NexCMP، تدير اللوحة هذا الجدول (بالإضافة إلى التنظيف الساعي لسجلات الاتصال)؛ وتلتقط العقد عنوانًا جديدًا خلال حوالي 5 ثوانٍ. ::: ### كيفية إرسال العقدة لتقاريرها {#how-a-node-reports} | | عقدة VPN (`cmp-agent`) | عقدة وكيل IPv6 | |---|---|---| | التسجيل | تذكرة أو رمز لمرة واحدة عبر HTTPS، ثم مفتاحها الخاص | تثبيت عبر SSH لمرة واحدة، ثم رمز العقدة | | نبض الاتصال | كل **5 ثوانٍ** (10 ثوانٍ لعميل المراقبة فقط)؛ يمكن للوحة ضبطها من 3 إلى 300 ثانية. وبعد حدوث فشل، تتراجع تدريجيًا بخطوات مدتها 5 ثوانٍ حتى 60 ثانية | ترسل العقدة تقريرًا كل 60 ثانية تقريبًا وتسحب التكوين | | تظهر كمتصلة | نبض اتصال خلال آخر **60 ثانية** | **alive** خلال آخر **120 ثانية**، وإلا فتكون **missed heartbeat** | | تغيير التكوين | يُطبق عند نبض الاتصال التالي | يُطبق خلال 5 ثوانٍ تقريبًا | | التحديثات | يمكن للوحة إرسال أمر `upgrade` مع الإصدار الجديد ورابط URL وتجزئة SHA-256 | إعادة التثبيت من صف العقدة | ### حصة البيانات على عقدة VPN {#data-allowance-on-a-vpn-node} بدءاً من NexCMP **1.5.1**، يرسل وكيل عقدة VPN حركة المرور التي نقلها مع كل إشارة heartbeat، وتضيفها اللوحة إلى استهلاك الخطة للفترة الحالية. ويظهر الرقم نفسه للعميل (علامتا التبويب Overview و Bandwidth) ولك (VPN › Subscriptions، والعمود Used، وصف العقدة). - **قطع الخدمة.** عندما تستهلك الخطة حصتها من الجيجابايت للفترة، تتوقف اللوحة عن إرسال نقاط النهاية الخاصة بتلك الخطة إلى العميل، مما يؤدي إلى رفض الاتصالات الجديدة وإغلاق الاتصالات المفتوحة. يتم القطع خلال دورة نبضة اتصال واحدة (heartbeat)، لذا قد تتجاوز الخطة حدها قليلاً. لا يتم قطع الخطط ذات الفئة غير المحدودة (Unlimited) مطلقًا. - **إعادة الفتح.** تعود الخطة للعمل خلال دورة نبضة اتصال واحدة (heartbeat) بعد شراء العميل لمزيد من سعة النطاق الترددي أو عند بدء الفترة التالية. - **غير مقاس.** تظهر العقدة التي لم يرسل عميلها (agent) بيانات الاستخدام (مثل إصدار عميل أقدم) بالحالة **Not measured**، ولا تُقطع خططها أبداً بسبب استهلاك GB. - **حدّث الـ agent.** استخدم الـ agent **1.5.1** على العقد. لا يزال استهلاك إصدارات الـ agent الأقدم يُحتسب، ولكن قد تفقد بايتات إشارة heartbeat فاشلة، أو نقطة نهاية متوقفة، أو عملية إعادة تشغيل، كما أنها لا تغلق الاتصالات المفتوحة عند قطع الخطة. حدّث من صف العقدة (Reinstall) أو باستخدام الأمر `upgrade`. - يتم احتساب الحمولة (payload) التي تمر عبر الـ proxy، لذا فهي أقل قليلاً (حوالي 1 %) من البايتات المنقولة عبر الشبكة. ### إضافات VPN المتوقفة {#retired-vpn-add-ons} لم تعد High IP Reputation وHigh Concurrency وHigh Priority Network متوفرة في الطلبات الجديدة. تحتفظ الاشتراكات الحالية بالإضافات المحددة، ولكن تُحذف الرسوم الملغاة من مبالغ تجديدها. لا يوجد استرداد للفترات المدفوعة مسبقاً. يعتمد التعديل على السعر الحالي للإضافة في الدليل؛ وإذا قمت بتغيير هذا السعر أو حذفت الإضافة، فراجع مبلغ تجديد الاشتراك قبل موعد التجديد التالي. ## التحقق {#verify} 1. صف العقدة متصل بالإنترنت. بالنسبة لعقدة VPN، يُظهر **Agents & external nodes** منطقتها وبلدها ودورها والنطاقات المكتشفة. 2. تسرد **VPN IP pools** النطاقات التي تحتوي على عناوين IP شاغرة؛ وتعرض صفحة تفاصيل المنطقة بنية VPN التحتية. 3. اطلب خطة VPN أو بروكسي تجريبية. يحصل العميل على نقطة نهاية `ip:port` واسم مستخدم وكلمة مرور؛ اتصل من خلالها وتحقق من أن عنوان IP العام الظاهر هو عنوان IP الخاص بالعقدة (على سبيل المثال `curl --proxy socks5h://USER:XXXX@IP:PORT https://ifconfig.me`). 4. في عقدة IPv6، شغّل على المضيف: ```bash systemctl is-active nft list tables | grep proxy6 ss -ltn | grep -E ':(80|443|6[0-9]{4})\b' ``` ## القيود والملاحظات {#limits-and-notes} - يمكن لمضيفي Windows تشغيل وكيل المراقبة، ولكن ليس دور VPN. - حصة البيانات (GB لكل فترة) لخطة VPN: بدءاً من NexCMP 1.5.1، تجمع اللوحة حركة المرور المُبلَّغ عنها من agent عقدة VPN وتقطع بروكسيات الخطة عند استنفاد الـ GB المخصصة للفترة (انظر "حصة البيانات على عقدة VPN" أدناه). لا تملك خطط IPv6 Proxy حصة GB؛ بل تحدد السرعة بوحدة Mbps لكل خطة. - لا يتم تدوير عناوين IPv4 الخاصة بخطة VPN. يُبلّغ العميل عن IP مدرج في القائمة السوداء، وتوافق أنت أو الموزع على استبداله من نفس المنطقة. يتم تدوير IPv6 Proxy فقط. - يتم الإبلاغ عن 64 نطاقاً كحد أقصى لكل heartbeat. - تستخدم كل مجموعة نقاط نهاية VPN ثلاثة منافذ لكل عنوان IP مُباع. ومع المنافذ 65001-65535 يخدم كل عنوان IP عدداً محدوداً من نقاط النهاية (178 مجموعة منافذ)؛ وتتخطى اللوحة المجموعات التي استُخدمت من قبل. - يُسمح بحذف عقدة بروكسي IPv6 فقط عندما لا تحتفظ أي خطة بعنوان IP عليها. يؤدي ذلك إلى إزالة نطاقات العقدة والـ token الخاص بها؛ ولا يتم إلغاء تثبيت البرنامج على المضيف. - من الممكن إعادة بيع نطاق يستضيف أيضاً أجهزتك الافتراضية الخاصة: حيث تستخدم VPN المنافذ 65001-65535 فقط، لذا تتشارك عنوان IP مع الخدمات الأخرى. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | "فشل التسجيل (رمز غير صالح أو يتعذر الوصول إلى الخادم)" | رمز غير صحيح أو مستخدم بالفعل، أو يتعذر الوصول إلى اللوحة | أنشئ رمزاً جديداً، أو أعد محاولة التثبيت عبر SSH. | | "عدم تطابق توقيع الملف - STOP" | يختلف الوكيل الذي تم تنزيله عن تجزئة SHA-256 المنشورة | تحقق من مجلد `/dl/` في اللوحة وتأكد من عدم وجود ما يُعدّل التنزيل أثناء نقله. | | "هذا المثبّت مخصص لنظام Linux فقط" / "البنية … غير مدعومة بعد" | Windows، أو بنية غير x86_64 (يتضمن الإصدار الـ agent لـ x86_64 فقط) | استخدم مضيف Linux ببنية x86_64. | | العقدة لا تظهر أبداً | لا يمكن للعقدة الوصول إلى اللوحة عبر HTTPS | اختبر `curl https:///install.sh` من العقدة؛ وتحقق من DNS والجدار الناري. | | تظهر العقدة مع بلد غير صحيح | فشلت عمليات البحث عن البلد، لذلك تم استخدام قاعدة بيانات العناوين الخاصة باللوحة | اسمح بالوصول الصادر إلى `ip-api.com` و`ipinfo.io`، أو حدد المنطقة بوضوح في نموذج SSH. | | لم يتم اكتشاف أي نطاقات | لا يوجد IPv4 عام على واجهة غير افتراضية | أضف عنواناً عاماً، أو أدخل الكتلة الموجّهة كـ **Extra subnet**. | | تعمل VPN، لكن حركة المرور تخرج من عنوان IP آخر | عنوان IP المُباع غير مخصص أو غير موجه إلى المضيف | تأكد من وجود عنوان IP على إحدى الواجهات أو أنه مغطى بواسطة `local … dev lo`. | | "خادم اللوحة لا يحتوي على sshpass" | لا يمكن لمضيف اللوحة تسجيل الدخول إلى العقد باستخدام كلمة مرور | شغّل `sudo apt-get install -y sshpass openssh-client` على خادم اللوحة، ثم ثبّت العقدة مرة أخرى. | | "غير موجود في الحزمة المثبتة" عند تثبيت عقدة IPv6 | إصدار اللوحة أقدم من 1.4.2، أو أنها بنية مخصصة بدون ملفات العقدة | حدّث NexCMP إلى 1.4.2 أو أحدث؛ وفي حال استخدام بنية مخصصة، استخدم `build.sh` الذي يحزم الآن `brandy-proxy6d` و`brandy-proxy6-net`. | | "SSH: …" في بداية تثبيت IPv6، أو "لا يُسمح بالاتصال عبر SSH بالعناوين الداخلية/الاسترجاعية" | منفذ أو مستخدم أو كلمة مرور غير صحيحة، أو SSH محظور، أو العنوان خاص | استخدم عنوان IPv4 العام الخاص بالعقدة وتحقق من إمكانية الوصول يدوياً باستخدام `ssh -p PORT USER@IP`. | | "البنية … غير مدعومة (x86_64 فقط)" | العقدة ليست ببنية x86_64 | استخدم مضيفاً ببنية x86_64. | | "أمر مفقود في العقدة: …" | `nft` أو `ip` أو `ss` أو `sysctl` أو `systemctl` أو `useradd` غير مثبت | ثبّت الحزم، ثم شغّل التثبيت مرة أخرى. | | "المنافذ قيد الاستخدام بواسطة خدمة أخرى على العقدة: … — يجب أن تكون المنافذ 80 و443 و60001-65535 شاغرة" | المنفذ 80 أو 443 أو منفذ أعلى من 60000 مشغول | انقل الخدمة الأخرى؛ فلن يقوم برنامج التثبيت بإيقافها. | | "لم يتم العثور على بادئة IPv6 مع وصول إلى الإنترنت من العقدة (فشل فحص الخروج الفعلي)" | لا توجد بادئة موجهة، أو يتعذر استخدام بروكسي NDP، أو لا يتوفر اتصال IPv6 صادر | تحقق من توجيه البادئة إلى العقدة، ووجود اتصال IPv6 على الواجهة، وعدم وجود ما يحظر حركة المرور الصادرة. | | "جميع النطاقات المكتشفة تنتمي بالفعل إلى عقدة أخرى" | البادئة مستخدمة بالفعل من قبل عقدة أخرى | أزلها من العقدة الأخرى أو اختر بادئة بديلة. | | ينتهي التثبيت بـ "no initial report received from node" | بدأت الخدمة لكنها لم تتمكن من الوصول إلى اللوحة خلال 90 ثانية | تحقق من عنوان URL للوحة المقدم للعقد ومسار HTTPS من العقدة إليها؛ راجع **Install log**. | | يُظهر صف العقدة **missed heartbeat** | لا توجد تقارير لمدة 120 ثانية | تحقق من الخدمة على العقدة، وساعتها، ومسار الاتصال باللوحة. | | لا يرى العملاء أي موقع IPv6 | المنطقة معطلة | فعّل المنطقة تحت **Zone**. | --- # AI Models {#ai-models} > **المسار في لوحة الإدارة:** System › Admin › License & updates (`/license`) لتفعيل الوحدة. ثم Services › AI Models: Providers (`/ai/providers`) وModels (`/ai/models`) وProfit (`/ai/profit`) وAudit (`/ai/audit`). يستخدم العملاء AI › API في بوابة العملاء. ## الوظيفة {#what-it-does} يُعد AI Models بوابة وطبقة فوترة على لوحتك الخاصة. يحصل عملاؤك على مفاتيح API ويستدعون **نقطة نهاية واحدة على نطاقك**، بتنسيق متوافق مع OpenAI أو متوافق مع Anthropic. تختار أنت النماذج التي تريد تقديمها وتكلفة كل منها لكل 1 مليون رمز (tokens). يتحقق NexCMP من المفتاح والحدود والمحفظة، ويرسل الطلب إلى مزود أضفته، ويقيس الرموز ويخصم من محفظة العميل مسبقة الدفع. **أنت من يوفر مصادر النماذج.** لا يأتي NexCMP مع أي مزود أو نموذج أو عنوان افتراضي أو سعر، ولا يوفر نماذج أو مفاتيح API أو رموزاً (tokens) أو حسابات لدى المزودين. ::: warning تحقق من شروط المصادر أولاً تقيد العديد من مصادر النماذج إعادة البيع أو تمرير الوصول إلى أطراف ثالثة. لا تستخدم إلا المصادر المصرح لك باستخدامها وإعادة بيعها، والتزم بشروطها وبالقوانين السارية عليك. لا تُعد هذه الصفحة استشارة قانونية. ::: يُعد AI Models منتجاً منفصلاً عن **AI Chat and AI Agent** (الوحدة **AI**، راجع [مزودي الذكاء الاصطناعي](https://nexcmp.com/ar/docs/ai/ai-providers/)). ولا تعتمد أي من الوحدتين على الأخرى. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | الوحدة | تفعيل **AI Models** ضمن License & updates،‏ Modules. وتكون معطلة افتراضياً. | | المزودون | مصدر نماذج واحد أو أكثر مصرّح لك بإعادة بيعه، يوفّر كل منها واجهة API متوافقة مع OpenAI (`/chat/completions`) أو واجهة API متوافقة مع Anthropic (`/messages`)، أو كليهما. يتطلب كل منها عنوان URL أساسي ومفتاح API. | | الشبكة | يجب أن تتمكن اللوحة من الوصول إلى كل مزود عبر **HTTPS على المنفذ 443** باستخدام اسم نطاق عام. وأي مزود على مضيف داخلي أو منفذ آخر أو بروتوكول HTTP عادي يجب إدراجه ضمن **Allowed internal hosts** (الإعداد `ai_endpoint_allow`). | | العملاء | حساب عميل ببريد إلكتروني موثق ورصيد في المحفظة. | | العتاد | لا يوجد. يقتصر دور NexCMP على إعادة توجيه الطلبات فقط: دون الحاجة إلى GPU أو ملفات نماذج. | ## تجهيز البنية التحتية {#prepare-the-infrastructure} 1. احصل على مفتاح API من كل مصدر نماذج ستستخدمه، وسجّل عنوان URL الأساسي له (على سبيل المثال `https://api.example.com/v1`). 2. تحقق من شروط المصدر بشأن إعادة البيع. 3. إذا كان المصدر يعمل داخل شبكتك، فحدد عنوانه، على سبيل المثال `http://10.0.0.5:8000/v1`. وستقوم بإدراج `10.0.0.5:8000` ضمن **Allowed internal hosts**. ## الربط في NexCMP {#connect-in-nexcmp} ### 1. تفعيل الوحدة {#_1-turn-the-module-on} افتح **System › Admin › License & updates**، وابحث عن بطاقة **Module**، ثم قم بتفعيل **AI Models**. ستتم إعادة تحميل القائمة ويظهر **Services › AI Models**. وطالما أن الوحدة معطلة، فإن صفحات العملاء وصفحات المسؤول والبوابة تستجيب جميعها بـ `404 module_disabled`، ولن يتم الاتصال بأي مزود. ![بطاقة Module مع تفعيل مفتاح AI Models](https://nexcmp.com/ar/docs/images/infrastructure/ai-models-01-modules.webp) ### 2. إضافة مزود {#_2-add-a-provider} 1. افتح **AI Models › Providers** واختر **Add provider**. 2. أدخل **slug** قصيرًا، و**اسمًا** (تراه أنت فقط)، و**النوع** (OpenAI-compatible أو Anthropic-compatible أو Both)، و**base URL** و**API key**، بالإضافة إلى **الأولوية** (تتم تجربة الرقم الأقل أولاً). 3. احفظ. يتم تخزين المفتاح مشفرًا ولا تظهر سوى آخر أربعة أحرف منه بعد ذلك. لا يمكن إدخال المفتاح إلا من جلسة مسؤول مسجل دخوله. استخدم **Both** فقط للبوابة التي تدعم كلا التنسيقين بالفعل. إن NexCMP **لا** يحول بين التنسيقين: يتم الوصول إلى النموذج الذي يقدمه مزود OpenAI-compatible عبر `/ai/v1/chat/completions`، والنموذج الذي يقدمه مزود Anthropic-compatible عبر `/ai/v1/messages`. ![صفحة Providers تسرد ثلاثة مزودين كعينة مع النوع والأولوية والحالة](https://nexcmp.com/ar/docs/images/infrastructure/ai-models-02-providers.webp) ### 3. اختبار الاتصال {#_3-test-the-connection} اختر **Test connection** لدى المزود. يقرأ NexCMP `GET /models` بالمفتاح ويفيد بـ **ok**، أو يوضح سبب الفشل: **auth** (مفتاح خاطئ)، أو **blocked**، أو **billing**، أو **unreachable**. يقتصر الاختبار على 6 اختبارات في الدقيقة. ### 4. مزامنة النماذج {#_4-sync-the-models} اختر **Sync models**. يقرأ NexCMP قائمة نماذج المزود ويضيف كل نموذج جديد **معطلاً ودون سعر**. يتم تمييز أي نموذج لم يعد المزود يدرجه في القائمة. وطالما أن الوحدة قيد التشغيل، تتم أيضًا مزامنة القائمة تلقائيًا كل 6 ساعات (الإعداد `ai_models_sync_hours`). ### 5. تحديد الأسعار وتفعيل النماذج {#_5-set-prices-and-switch-models-on} 1. افتح **AI Models › Models**. 2. لكل نموذج ترغب في بيعه، حدد **سعر البيع** بالدولار الأمريكي لكل 1 مليون token: **input** و**cached input** و**output**. 3. يمكنك اختياريًا إدخال **التكلفة** الخاصة بك للنموذج. عندئذٍ يعرض **Profit** الإيرادات مقابل التكلفة حسب اليوم وحسب النموذج، ويتم رفض أي سعر بيع يقل عن تكلفتك مضافًا إليها الحد الأدنى لهامش الربح (الإعداد `ai_min_margin_pct`، القيمة الافتراضية 10) ما لم تؤكد خسارة متعمدة. يستخدم **Set price from cost** هامش ربح تختاره أنت؛ لا يوجد هامش ربح افتراضي. 4. قم بتفعيل النموذج. لا يمكن تفعيل أي نموذج ليس له سعر بيع. وإذا تُرِك سعر cached input عند الصفر، فسيتم احتسابه بسعر input. ![صفحة Models مع أسعار بيع input وcached input وoutput ومفاتيح التفعيل والتعطيل](https://nexcmp.com/ar/docs/images/infrastructure/ai-models-03-models.webp) ### 6. المسارات والتبديل عند الفشل {#_6-routes-and-failover} في صفحة النموذج، يسرد **Routes** المزودين الذين يقدمونه بالترتيب. أضف مزودًا ثانيًا كبديل احتياطي، وحدد الترتيب، واختياريًا حدد اسم نموذج مختلف لكل مزود (يمكن أن يختلف الاسم المرسل إلى المزود عن الاسم الذي تنشره). عندما يُرجع المزود خطأ في الخادم أو خطأ في التفويض أو الفوترة أو نموذجًا مفقودًا أو حدًا لمعدل الطلبات، يجرب NexCMP المسار التالي. إذا انتهت مهلة القراءة بعد إرسال الطلب، فإنه **لا** يُرسل إلى مزود آخر، وبذلك لن تدفع مرتين. يتم تنظيم معدل كل مزود عند `ai_provider_rpm` طلب في الدقيقة (50 افتراضيًا). إذا استمر المزود في إرجاع أخطاء التفويض أو الفوترة، فسيقوم NexCMP بتنبيه المسؤول عبر Telegram عند إعداد Telegram. ### 7. تفعيل مفتاح البيع {#_7-open-the-sale-switch} في الجزء العلوي من صفحات AI Models، يكون **مفتاح البيع** (الإعداد `feature_ai_models`) معطلاً افتراضيًا. وطالما أنه معطل، يرى العملاء أن الخدمة لم تفتح بعد، وتفيد قائمة الأسعار العامة بأنها غير متاحة. تأكد من تفعيل نموذج واحد على الأقل ووجود سعر بيع ومسار مزود بمفتاح، ثم قم بتفعيله. ### ما يمكن للعملاء فعله {#what-customers-can-do} في بوابة العملاء، **AI › API**: - يعرض **Models** النماذج والأسعار الخاصة بك، وbase URL وأوامر أمثلة جاهزة للاستخدام. - **API Keys**: إنشاء المفاتيح وإعادة تسميتها وتدويرها وتعطيلها وحذفها. يُعرض المفتاح السري مرة واحدة فقط؛ ويُخزّن رمز التجزئة فقط. لكل مفتاح: النماذج المسموح بها، وتاريخ انتهاء الصلاحية، وميزانية مرنة (تحذير) وميزانية صارمة (حظر مع `402`)، وعدد الطلبات في الدقيقة وعدد tokens في الدقيقة. - **Usage** حسب النموذج والمفتاح واليوم، مع إمكانية التصدير. - **Logs**: سجلات طلبات قابلة للتصفية (الوقت، المفتاح، النموذج، tokens، التكلفة، الحالة، زمن الاستجابة). **لا تُسجَّل نصوص المطالبات والردود.** يُحتفظ بالسجلات لمدة 90 يومًا افتراضيًا (`ai_log_retention_days`). - **Settings**: ميزانية الحساب وعنوان البريد الإلكتروني لتنبيهات الميزانية. - **Playground**: المحادثة مع نموذج، ومقارنة النماذج جنبًا إلى جنب، ونسخ الكود المتطابق. ![صفحة API Keys للعميل مع عناوين URL الأساسية لكلا تنسيقي API](https://nexcmp.com/ar/docs/images/infrastructure/ai-models-04-keys.webp) نقاط نهاية البوابة، على نطاقك: ```text POST /ai/v1/chat/completions OpenAI-compatible POST /ai/v1/messages Anthropic-compatible (also /ai/v1/messages/count_tokens) GET /ai/v1/models model list GET /ai/v1/models/pricing public price list, no key needed ``` ### المحفظة والفوترة {#wallet-and-billing} يتم خصم استخدام الذكاء الاصطناعي من محفظة الدفع المسبق نفسها كأي خدمة أخرى. قبل إرسال الطلب إلى المزود، يحجز NexCMP مبلغًا يعادل أقصى تكلفة محتملة للطلب؛ وإذا كان الرصيد أقل من الحد الأدنى (`ai_min_balance_cents`، 20 سنتًا افتراضيًا) أو غير كافٍ، يُرفض الطلب مع `402 insufficient_balance` و**لا يتم استدعاء أي مزود**. يتم جمع الاستخدام لكل حساب وتسويته في قيود دفتر أستاذ المحفظة بعد كل ساعة، مع فحص دوري كل 5 دقائق؛ ويُخصم الاستخدام الذي لم تتم تسويته بعد تلقائيًا من الرصيد الذي تراه البوابة. يمكن للموزعين بيع AI Models على نطاقهم الخاص: ينطبق هامش الربح أو الخصم الخاص بهم على سعر البيع لديك، وتُخصم أسعار الجملة من محفظة الجملة الخاصة بهم. يتحكم مفتاح تبديل للذكاء الاصطناعي لكل موزع، وهو مفعّل افتراضيًا، فيمن يحق له البيع. ## التحقق {#verify} 1. بعد الخطوة 3، يُظهر **Test connection** الحالة **ok** وعدد النماذج. 2. بعد الخطوة 4، تُدرج النماذج الجديدة كمعطلة، ودون تحديد سعر. 3. بصفتك عميلًا لديه محفظة مشحونة، أنشئ مفتاحًا واستدعِ البوابة: ```bash curl https://your-domain/ai/v1/chat/completions \ -H "Authorization: Bearer sk-ai-…" -H "Content-Type: application/json" \ -d '{"model":"model-one","messages":[{"role":"user","content":"hello"}]}' ``` يتضمن الرد `200` إجابة النموذج. يُظهر **Usage** الطلب، ويُظهره **Profit** إذا كنت قد أدخلت تكلفة. 4. عندما يكون رصيد المحفظة صفرًا، يُرجع الاستدعاء نفسه `402 insufficient_balance`. ## القيود والملاحظات {#limits-and-notes} - لا تتضمن الوحدة أي مزود أو نموذج أو سعر مدمج مسبقًا، ولا يتم قراءة أي قائمة أسعار من أي مزود مطلقًا. - تُرفض الأدوات التي تعمل لدى المزود وتُحسب تكلفتها لكل استدعاء، مثل البحث على الويب، لتعذر قياس استهلاكها. ويتم تمرير قائمة قصيرة فقط من معلمات الطلب. - يتم احتساب استهلاك tokens من رد المزود؛ وإذا خلا الرد منها، يقدّر NexCMP الاستهلاك ويصنّف السجل على أنه تقديري. - تتم تنقية الأخطاء الواردة من المزود قبل أن تصل إلى العميل (تُزال الأسماء والمضيفون والعناوين واسم النموذج لدى المزود). ولا يرى العملاء مطلقًا المزود الذي تولى معالجة الطلب. - يصل العملاء إلى البوابة عبر نطاق لوحتك، لذا يجب أن يكون بروتوكول TLS الخاص بذلك النطاق يعمل بشكل صحيح. - لا يقدّم NexCMP اتفاقية مستوى الخدمة أو الضبط الدقيق أو استضافة GPU لهذه الوحدة. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب والحل | |---|---| | تُرجع كل صفحة من صفحات AI Models والبوابة الرد `404 module_disabled` | الوحدة معطلة. فعّل **AI Models** ضمن License & updates, Modules. | | فشل إضافة المزود مع `endpoint_host_not_allowed` أو `endpoint_must_be_https` أو `invalid_endpoint_port` | يجب أن يكون عنوان URL الأساسي بصيغة HTTPS على المنفذ 443 لنطاق عام. بالنسبة للمضيف الداخلي أو منفذ آخر أو بروتوكول HTTP عادي، أدرج `host:port` ضمن **Allowed internal hosts**. | | `blocked_endpoint` | العنوان هو عنوان IP، أو يتم حل الاسم إلى عنوان خاص. أدرجه ضمن **Allowed internal hosts** إذا كان هذا ما تريده. | | **Test connection** يُظهر `auth` | المفتاح غير صحيح أو لا يملك صلاحية الوصول. أدخل المفتاح مرة أخرى. | | يتعذر تفعيل النموذج (`no_price`) | عيّن سعر البيع أولًا. | | يتلقى العملاء `503 ai_unavailable` | مفتاح البيع معطّل، أو مفتاح AI الخاص بالموزع معطّل. | | يتلقى العملاء `503 upstream_unavailable` | لا يوجد مسار مفعّل بمفتاح يخدم هذا النموذج بالتنسيق المطلوب. تحقق من مسارات النموذج ونوع المزود. | | يتلقى العملاء `402 insufficient_balance` | رصيد المحفظة أقل من الحد الأدنى أو غير كافٍ للطلب. اطلب من العميل شحن الرصيد. | --- # Object Storage (S3, Ceph RGW) {#object-storage-s3-ceph-rgw} > **الموقع في لوحة الإدارة:** Infrastructure › Cloud provider › Ceph S3 (RGW) (`/infra/s3`). الحسابات: Services › Object Storage › S3 accounts (`/s3`). التسعير: Services › Object Storage › PAYG pricing (`/s3/policy`). فعّل الوحدة ضمن System › Admin › License & updates. ## الوظيفة {#what-it-does} ينشئ العملاء حسابات S3 من البوابة ويحصلون على مفاتيح الوصول. يتولى NexCMP إنشاء وحذف المستخدمين المطابقين على **Ceph RADOS Gateway (RGW) لديك** عبر RGW Admin Ops API، ويقرأ الاستخدام للفوترة، ويحاسب بنظام الدفع حسب الاستخدام: التخزين الزائد عن الفئة المجانية لكل جيجابايت شهريًا (يُحسب بالساعة) وحركة مرور التنزيل لكل جيجابايت. عمليات الرفع مجانية. استخدم هذا الخيار عندما تدير كتلة Ceph مع RGW وترغب في إعادة بيع خدمة التخزين السحابي كائنات. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | Ceph | كتلة تحتوي على ديمون RGW واحد على الأقل، مع تفعيل **Admin Ops API** (يتضمن الإعداد الافتراضي `rgw_enable_apis` القيمة `admin`). | | Admin user | مستخدم RGW مخصص لـ NexCMP يتمتع بالصلاحيات الموضحة أدناه. لا تستخدم مستخدمًا يمتلك بيانات العملاء. | | Endpoints | نقطة نهاية S3 التي يستخدمها العملاء، ونقطة نهاية Admin Ops. تُكتب كلتاهما بالصيغة `https://host` **بدون مسار، وعلى المنفذ 443 فقط**، ويجب أن يتم حلهما إلى عنوان **عام**: يتم رفض عناوين loopback وlink-local وmulticast والعناوين الخاصة وunique-local. | | Certificate | شهادة صالحة لمضيف نقطة النهاية. | | Usage log | تفعيل تسجيل الاستخدام في RGW (`rgw_enable_usage_log = true`)، حتى تتمكن واجهة API الخاصة بالاستخدام من الإبلاغ عن حركة المرور. | | المنطقة | منطقة رئيسية تم تحديد الخدمة **Object Storage (S3)** فيها. راجع [Zones](https://nexcmp.com/ar/docs/infrastructure/zones/). | | التخزين | سعة تخزينية كافية في Ceph للحصص التي تبيعها. | | يعتمد على | الوحدة **Object Storage**. تُحسب حركة مرور التنزيل أيضًا ضمن [Bandwidth](https://nexcmp.com/ar/docs/catalog/bandwidth/). | ## تجهيز البنية التحتية {#prepare-the-infrastructure} على عقدة إدارة Ceph: 1. أنشئ مستخدم الإدارة وامنحه صلاحيات Admin Ops المطلوبة: ```bash radosgw-admin user create --uid=nexcmp-admin --display-name="NexCMP admin" radosgw-admin caps add --uid=nexcmp-admin --caps="users=*;buckets=*;usage=read;metadata=read" radosgw-admin user info --uid=nexcmp-admin ``` انسخ `access_key` و`secret_key` من المخرجات. وهما يمثلان **Admin access key** و**Admin secret key** في NexCMP. 2. فعّل سجل الاستخدام وأعد تشغيل البوابات: ```bash ceph config set client.rgw rgw_enable_usage_log true ``` 3. ضع البوابات خلف اتصال HTTPS على المنفذ 443 (وكيل عكسي أو بروتوكول TLS الخاص بـ RGW)، وانشر اسم DNS، ثم اختبر الاتصال من خادم اللوحة: ```bash curl -fsS -o /dev/null -w '%{http_code}\n' https://s3.example.com/ ``` يجب أن تتلقى استجابة S3 بتنسيق XML (رمز HTTP 200 أو 403)، وليس انتهاء مهلة الاتصال. ## الربط في NexCMP {#connect-in-nexcmp} 1. **قم بتعيين خدمة S3 للمنطقة.** افتح **Infrastructure › Datacenter › Zone**، وعدّل المنطقة وحدد **Object Storage (S3)**. تظهر المناطق الرئيسية التي تحتوي على خدمة S3 فقط في نموذج الواجهة الخلفية. 2. افتح **Infrastructure › Cloud provider › Ceph S3 (RGW)** وانقر على **Add backend**: | الحقل | مثال للقيمة | |---|---| | اسم الواجهة الخلفية | `Ceph RGW 1` | | المنطقة | المنطقة من الخطوة 1 | | نقطة نهاية RGW Admin Ops | `https://s3.example.com` | | نقطة نهاية S3 للعميل | `https://s3.example.com` | | منطقة توقيع S3 | `default` | | مفتاح وصول Admin | `XXXX` | | المفتاح السري لـ Admin | `XXXX` | | نشط | مفعّل | | تمكين المبيعات (يتطلب اختبار الاتصال أولاً) | **معطّل** حاليًا | | سبب التغيير | `initial setup` | ![مربع حوار واجهة S3 الخلفية مع أمثلة لنقاط النهاية والمنطقة والمفاتيح المقنعة](https://nexcmp.com/ar/docs/images/infrastructure/s3-02-backend-dialog.webp) 3. انقر على **OK** (حفظ)، ثم على **Check** في الصف. يستدعي NexCMP واجهة برمجة تطبيقات Admin Ops API باستخدام مفتاح المسؤول. تعني رسالة **Ceph connection successful** والشارة **Verified** أن الاتصال يعمل بنجاح. 4. انقر على **Edit**، وفعّل **Enable sales** ثم احفظ التغييرات. يرفض NexCMP إتاحة المبيعات حتى ينجح الفحص. 5. افتح **Services › Object Storage › PAYG pricing** واضبط التسعير: | الحقل | المعنى | |---|---| | التخزين الزائد عن الفئة المجانية (VND/GB/شهر) | سعر التخزين؛ يُفوتر بالساعة بحساب السعر الشهري مقسومًا على 730. | | التنزيل (VND/GB) | سعر حركة البيانات الصادرة. | | الرفع (VND/GB) | دائمًا 0. | | الفئة المجانية مع Running VM (GB) | محددة بـ 100 GB لكل حساب طالما يمتلك العميل جهاز VM واحد قيد التشغيل على الأقل، وتتم مشاركتها عبر حسابات S3 التابعة له بحسب الحجم. | | حد المديونية (VND) | الحد المسموح به للاستخدام غير المدفوع. | | حد الفوترة (VND) | يتم تجميع الاستخدام في فاتورة واحدة بمجرد تجاوز هذا المبلغ. | | الحد الأدنى للرصيد لإنشاء S3 (VND) | رصيد المحفظة المطلوب لإنشاء حساب. | | الحد الأقصى لحسابات S3 لكل عميل، الحصة الفنية الافتراضية (GB) | الحدود المفروضة على الحسابات الجديدة. | ![نموذج تسعير S3 PAYG](https://nexcmp.com/ar/docs/images/infrastructure/s3-04-pricing.webp) يتم إدخال أسعار S3 بعملة VND. وتُحوّل للعرض والخصم من المحفظة بسعر الصرف الساري؛ راجع [العملة وأسعار الصرف](https://nexcmp.com/ar/docs/catalog/currency-and-exchange-rates/). ## التحقق {#verify} 1. يعطي **Check** نتيجة "Ceph connection successful". 2. بصفتك عميلاً (أو باستخدام حساب اختباري)، أنشئ حساب S3. على Ceph، يعرض `radosgw-admin user list` مستخدمًا جديدًا، وتدرجه **S3 accounts** في القائمة. 3. أنشئ bucket باستخدام أي عميل S3 ومفاتيح العميل مقابل نقطة نهاية العميل. قم برفع ملف. 4. بعد دورة الفوترة للساعة التالية، ستعرض **S3 accounts** بيانات الاستخدام. ## القيود والملاحظات {#limits-and-notes} - تحتفظ الواجهة الخلفية المرتبطة بحسابات بالفعل بـ **المنطقة ونقطة النهاية والإقليم** الخاصة بها؛ ولتغييرها، أنشئ واجهة خلفية جديدة. - يمكن أن تمتلك المنطقة الواحدة واجهة خلفية خاصة بها؛ وترتبط الحسابات والواجهات الخلفية بالمنطقة بصورة دائمة. - تُعد الفئة المجانية وقاعدة "الرفع مجاني" قواعد ثابتة وليست خيارات قابلة للتعديل. - تُخزن المفاتيح مشفرة؛ ولا تعرض لوحة التحكم سوى حقل "leave blank to keep the current key". ويتم دائمًا إدخال زوج المفاتيح معًا. - تُعرض المفاتيح السرية للعملاء مرة واحدة فقط عند الإنشاء ولا تظهر مجددًا أبدًا. ويتم استبدال المفتاح المفقود عبر تدويره. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | "Endpoint requires HTTPS" | تستخدم نقطة النهاية بروتوكول HTTP غير المشفر | انشر HTTPS على المنفذ 443. | | "منفذ نقطة النهاية غير مسموح به" | منفذ آخر غير 443 | استخدم منفذ HTTPS القياسي. | | "عنوان نقطة النهاية غير مسموح به" | يتحول الاسم إلى عنوان خاص أو محلي حلقي (loopback) أو محلي للارتباط أو محلي فريد | استخدم عنوانًا عامًا. | | "يجب أن تتضمن نقطة النهاية البروتوكول والمضيف فقط" | يحتوي عنوان URL على مسار أو استعلام أو معلومات مستخدم | استخدم `https://host` فقط. | | "فشل في حل نقطة النهاية" | يتعذر حل DNS من خادم اللوحة | أصلح DNS. | | "Failed to connect to Ceph" | خطأ في الجدار الناري أو TLS | اختبر باستخدام `curl` من خادم اللوحة. | | "Ceph returned HTTP 403 AccessDenied" | مفاتيح خاطئة أو صلاحيات مفقودة | تحقق من المفاتيح وأعد تشغيل `radosgw-admin caps add`. | | "Invalid Ceph response" | نقطة النهاية ليست واجهة RGW Admin Ops API | وجّهها إلى RGW، وليس إلى صفحة ويب. | | "يجب أن ينجح اختبار الاتصال قبل تفعيل المبيعات" | قمت بتفعيل المبيعات قبل نجاح **Check** | شغّل **Check**، ثم فعّل المبيعات. | | "جميع المفاتيح الجديدة لنقطة النهاية مطلوبة" | تم تغيير نقطة النهاية دون تقديم كلا المفتاحين | أدخل مفتاح الوصول والمفتاح السري معًا. | | "يحتوي النظام الخلفي بالفعل على موارد مرتبطة؛ أنشئ نظاماً خلفياً جديداً لتغيير المنطقة أو نقطة النهاية" | توجد حسابات على هذه النهاية الخلفية | أنشئ نهاية خلفية جديدة. | | "حدد المنطقة الرئيسية المزودة بخدمة S3" | المنطقة ليست رئيسية أو لا تحتوي على خدمة S3 | حدد **Object Storage (S3)** في المنطقة. | | "Invalid region" | تحتوي المنطقة على محارف أخرى غير الحروف والأرقام و`-` و`_` | استخدم `default` أو اسم zonegroup الخاص بـ RGW لديك. | | "ملخص استخدام Ceph مفقود؛ لم تتم الفوترة" | سجل الاستخدام معطل | فعّل `rgw_enable_usage_log`. | --- # Kubernetes وPrivate Cloud {#kubernetes-and-private-cloud} > **المسار في لوحة الإدارة:** Kubernetes: Infrastructure › Cloud provider › CloudStack › Kubernetes (CKS) (`/infra/cloudstack?tab=k8s`)، ثم Services › Kubernetes (Overview, Clusters, Versions, Policy). Private Cloud: Services › Private Cloud (Overview `/vpc`, VPC `/vpc/list`, Plans & pricing `/vpc/plans`). قم بتفعيل كلا الموديولين ضمن System › Admin › License & updates. ## الوظيفة {#what-it-does} - **Kubernetes.** يُنشئ العملاء مجموعات Kubernetes مُدارة على CloudStack الخاص بك باستخدام CloudStack Kubernetes Service (CKS). مستوى التحكم مجاني؛ ويدفع العملاء مقابل عُقد **worker**. يقوم NexCMP بإنشاء شبكة منفصلة وعنوان IP عام لكل مجموعة ويعزل مجموعات كل عميل على حدة. - **Private Cloud.** يحصل العملاء على شبكة خاصة (CloudStack VPC) تتضمن موجهًا، وشبكات فرعية (tiers)، وقواعد جدار حماية (network ACLs)، وأجهزة افتراضية بداخلها. تُباع وفق **خطة نطاق ترددي** بسرعة مخصصة وغير محدودة الاستهلاك (على سبيل المثال 50، 100، 500 Mbps، و1 و3 Gbps). يمكن لكل عميل امتلاك VPC واحد افتراضيًا. يعتمد كلاهما على [CloudStack](https://nexcmp.com/ar/docs/infrastructure/cloudstack/) ويستخدمان API الخاص به عبر الاتصال نفسه. ## المتطلبات {#requirements} ### Kubernetes {#kubernetes} | العنصر | المتطلب | |---|---| | CloudStack | 4.23 (تم اختباره). يجب أن يكون CKS **مُفعّلًا** (`cloud.kubernetes.service.enabled = true`). | | الحساب | حساب **Domain Admin** في النطاق المخصص، حتى يتمكن NexCMP من إنشاء مشروع CloudStack لكل عميل وتحديد قيود الموارد بداخله. راجع [CloudStack](https://nexcmp.com/ar/docs/infrastructure/cloudstack/#create-a-dedicated-account-and-api-key). | | `endpoint.url` | يجب أن يشير الإعداد العام في CloudStack إلى management API الخاص بك، بحيث يمكن للأجهزة الافتراضية في المجموعة الوصول إليه. يعرض NexCMP القيمة ونتيجة فحص نقطة النهاية. | | الإصدارات | إدخال إصدار مدعوم واحد على الأقل من Kubernetes مع ملف ISO الخاص بملفاته الثنائية، بالحالة **Enabled**. لا يمكن طرح الإصدارات التي تجاوزت نهاية فترة الدعم للبيع. | | عرض Control-plane | عرض خدمة مجاني مع **2 vCPU و2048 MB RAM وحد أقصى للمعالج (CPU cap) بدقة** (`limitcpuuse = true`)، مرئي للحساب. يرفض الخادم أي شيء آخر مع `cp_offering_invalid`. | | الشبكة | عرض شبكة معزولة يدعم CKS ومُفعّل. | | عناوين IP | عناوين IPv4 عامة ومتاحة ضمن النطاق القابل للبيع؛ تستخدم كل مجموعة عنوانًا واحدًا. | | السعة | تستهلك كل مجموعة منك ما بين 2 إلى 4 GB من الذاكرة العشوائية (RAM) لمستوى التحكم وجهاز افتراضي صغير للموجه. راقب علامات تبويب السعة. | ### Private Cloud {#private-cloud} | العنصر | المتطلب | |---|---| | CloudStack | 4.23 (تم اختباره) مع تفعيل VPC. | | عرض VPC | عرض VPC واحد. يمنح العرض المزدوج (dual-stack) كل tier نطاق IPv6 /64 أيضًا. | | عروض شبكة Tier | **عرض شبكة واحد لكل خطة نطاق ترددي**، تم إنشاؤه لـ VPC، مع تعيين **معدل الشبكة** (Mbps) مساويًا للخطة، بالإضافة إلى عرض **مقفل (locked)** واحد بسرعة **1 Mbps** يُطبّق عند قفل VPC بسبب عدم الدفع. | | الحساب | الحساب المخصص (يُوصى بـ Domain Admin). تظل شبكات VPC في الحساب، وليس في المشاريع. | | عناوين IP | عناوين IPv4 عامة ومتاحة (يستخدم كل VPC عنوانًا واحدًا لـ source NAT). | | مساحة العناوين | يتلقى كل VPC نطاق /16 من `10.128.0.0/9`. احتفظ بهذا النطاق غير مستخدم في شبكاتك الخاصة. | | يعتمد على | اتصال CloudStack نشط؛ موديول **Private Cloud**. | ## تجهيز البنية التحتية {#prepare-the-infrastructure} ### Kubernetes: تفعيل CKS وإضافة الإصدارات {#kubernetes-enable-cks-and-add-versions} 1. قم بتفعيل الخدمة وتعيين نقطة النهاية، ثم أعد تشغيل خادم الإدارة: ```bash cmk update configuration name=cloud.kubernetes.service.enabled value=true cmk update configuration name=endpoint.url value=https://cloudstack.example.com/client/api sudo systemctl restart cloudstack-management ``` يتم استدعاء `endpoint.url` بواسطة وحدة تحكم المجموعة، لذا يجب أن يكون عنوانًا يمكن لأجهزة المجموعة الافتراضية الوصول إليه. 2. أنشئ ملف ISO للملفات الثنائية الخاصة بـ Kubernetes للإصدار الذي ترغب في بيعه، باستخدام سكربت `create-kubernetes-binaries-iso.sh` من شجرة مصادر CloudStack، واستضفه على خادم ويب ثم قم بتسجيله: ```bash cmk add kubernetessupportedversion name="Kubernetes 1.35.0" semanticversion=1.35.0 \ url=https://files.example.com/setup-v1.35.0-calico-amd64.iso zoneid= \ mincpunumber=2 minmemory=2048 cmk list kubernetessupportedversions filter=name,semanticversion,state,isostate ``` انتظر حتى تصبح حالة ISO هي **Ready** ويكون الإصدار **Enabled**. 3. أنشئ عرض Control-plane، مقصورًا على نطاق NexCMP: ```bash cmk create serviceoffering name=K8S-CP-2-2 displaytext="Kubernetes control plane" \ cpunumber=2 cpuspeed=1000 memory=2048 limitcpuuse=true offerha=false domainid= ``` 4. تحقق من تفعيل عرض شبكة CKS: ```bash cmk list networkofferings state=Enabled forvpc=false filter=id,name ``` ### Private Cloud: إنشاء العروض {#private-cloud-create-the-offerings} في واجهة مستخدم CloudStack (**Service Offerings › Network Offerings › Add network offering**) أو باستخدام `cmk`: 1. عرض ما لديك في القائمة: ```bash cmk list vpcofferings filter=id,name,state cmk list networkofferings forvpc=true filter=id,name,networkrate,state ``` 2. استخدم عرض VPC مفعلاً (مزدوج المكدس dual-stack إذا كنت تريد IPv6). وإذا احتجت إلى عرض جديد، فقم باستنساخ عرض VPC الافتراضي في CloudStack وتفعيله. 3. بالنسبة إلى **كل** خطة نطاق ترددي تبيعها، أنشئ عرض شبكة **لـ VPC** (استنسخ "isolated network offering for VPC networks" الافتراضي) واضبط **Network rate (Mb/s)** على سرعة الخطة: `50`، `100`، `500`، `1000`، `3000`. فعّل كل عرض. 4. أنشئ عرضاً إضافياً مع **معدل شبكة 1** (`VPC-LOCKED-1M`) لشبكات VPC المقفلة: لا يزال بإمكان العملاء الوصول إلى خوادمهم عبر SSH، ولكن السرعة ستكون محدودة. 5. دوّن معرّف UUID لكل عرض. سيحتاجه NexCMP في القسم التالي. ::: warning معرّفات العروض المرفقة مسبقًا غير موجودة في سحابتك يتم ملء نموذج Private Cloud مسبقاً بمعرّفات UUID لعروض تنتمي إلى تثبيت CloudStack آخر. استبدل **كل** معرّف بالمعرّف الخاص بك، وإلا سيفشل أول طلب VPC. ::: ## الربط في NexCMP {#connect-in-nexcmp} ### Kubernetes {#kubernetes-1} 1. افتح **Infrastructure › Cloud provider › CloudStack** واختر التبويب **Kubernetes (CKS)**. تعرض البطاقة الموجودة على اليمين **CKS status on CloudStack (read-only)** كلاً من `kubernetesserviceenabled`، و`endpoint.url` مع **Endpoint check**، وعرض شبكة CKS، وإعدادات `cloud.kubernetes.*`، وقائمة ملفات ISO والإصدارات. انقر فوق **Recheck** بعد إصلاح أي شيء. 2. في **Sales config**، اختر **Control plane Offering** (يظهر تحذير إذا لم يكن بالضبط 2 vCPU / 2048 MB / CPU cap)، واضبط **Max workers per cluster** (من 1 إلى 9: يسمح CKS بـ 10 عقد بما في ذلك عقدة التحكم)، وفعّل الخيار **Enable CKS for this backend** ثم اضغط على **Save**. يظل المفتاح معطلاً حتى يتم اختيار عرض. ![علامة التبويب Kubernetes (CKS) مع تحديد عرض لوحة التحكم وبطاقة حالة CKS](https://nexcmp.com/ar/docs/images/infrastructure/kubernetes-and-private-cloud-01-cks.webp) 3. افتح **Services › Kubernetes › Versions** وانقر على **Sync from CloudStack**. فعّل الخيار **Available for new clusters** للإصدارات التي تبيعها، وحدد الإصدار الافتراضي، وتاريخ **End of life (EOL)** إذا أردت. 4. افتح **Services › Kubernetes › Policy**. في **Worker plans** أضف خططًا باستخدام **Plan code** (A-Z، و0-9، وشرطة، حتى 16 حرفًا). اضبط **NVMe per worker (GB)**، و**Min and max workers**، وحدود المجموعات (المجموعات النشطة لكل حساب، وعمليات الإنشاء خلال 24 ساعة، والحد الأقصى الإجمالي، وعمليات CKS المتزامنة). ثم فعّل **Sell Kubernetes (CKS)**. يجب أن تظل خطة واحدة على الأقل متاحة للبيع. ![سياسة Kubernetes مع خطط العمال ومفتاح المبيعات](https://nexcmp.com/ar/docs/images/infrastructure/kubernetes-and-private-cloud-03-policy.webp) ### Private Cloud {#private-cloud-1} 1. افتح **Services › Private Cloud** (نظرة عامة). في بطاقة السياسة، استبدل **VPC offering** و**Locked offering tier** بمعرّفات UUID الخاصة بك. تحقق من الحدود (عدد VPCs لكل حساب، والطبقات، والأجهزة الافتراضية، وقواعد ACL لكل VPC، والرصيد المطلوب لإنشائها محسوبًا بساعات رسوم الخطة، وتغييرات الخطة خلال 24 ساعة، والعمليات المتزامنة حيث يعني 0 التوقف في حالات الطوارئ) وخوادم DNS. انقر على **Save** (سيُطلب منك تحديد سبب). ![نظرة عامة على Private Cloud مع حقلي عرض VPC والعرض المقفل](https://nexcmp.com/ar/docs/images/infrastructure/kubernetes-and-private-cloud-04-vpc-policy.webp) 2. افتح **Services › Private Cloud › Plans & pricing**. لكل خطة، انقر فوق **Edit** واضبط **VND price per month**، و**On sale**، ومعرّف UUID الخاص بـ **CloudStack tier offering** الذي يطابق معدل شبكته سرعة الخطة بوحدة Mbps. يُظهر الصف التكلفة والربح عند الاستخدام الكامل، ليتسنى لك معرفة الخطط التي تقل عن تكلفتك. ![مربع حوار تعديل الخطة لخطة النطاق الترددي لـ Private Cloud](https://nexcmp.com/ar/docs/images/infrastructure/kubernetes-and-private-cloud-05-vpc-plan.webp) 3. فعّل **Sell Private Cloud**. لتجربتها أولاً، أضف معرّفات حسابات الاختبار إلى **Beta accounts**: حيث يمكن لتلك الحسابات استخدام الخدمة بينما يكون مفتاح المبيعات معطلاً. ## التحقق {#verify} 1. Kubernetes: تعرض بطاقة الحالة `kubernetesserviceenabled: true`، وفحص نقطة نهاية سليمًا، وإصدارًا مفعلاً. أنشئ مجموعة اختبار بعامل واحد بصفتك عميلاً؛ حيث يجب أن تصل إلى حالة running ويُظهرها `kubectl get nodes` كجاهزة. احذفها بعد ذلك: تعود الشبكة وعنوان IP إلى التجمع. 2. Private Cloud: أنشئ VPC بأصغر خطة بصفتك عميلاً تجريبياً. يظهر VPC بحالة نشطة، وتحصل الطبقة على شبكتها الفرعية، وتصل VM في الطبقة إلى الإنترنت عبر موجّه VPC، ويسري مفعول **Change plan** إلى خطة أكبر خلال حوالي 20 ثانية دون انقطاع الاتصالات. ## القيود والملاحظات {#limits-and-notes} - Kubernetes: تتم فوترة عقد workers مثل أجهزة VM بأسعار الخطة وتُحتسب كأجهزة VM ضمن حدود VM. يمكن أن يضم العنقود 9 workers كحد أقصى بسبب حد CKS البالغ 10 عقد. - Kubernetes: تكون control plane والموجّه وعنوان IP العام للعنقود مجانية للعميل، بينما تتحمل أنت تكلفتها. - Private Cloud: جميع الخطط **غير محدودة الاستهلاك**. الأسعار في النموذج بالدونغ الفيتنامي شهرياً؛ ويستخدم عمود التكلفة سعراً مرجعياً لا يخصك، لذا استخدم أرقامك الخاصة. - يقتصر VPC المقفل على سرعة 1 Mbps، ولا تتم فوترته ولا يُحذف تلقائياً. - تستخدم Private Cloud موجّهاً واحداً لكل VPC، وليس زوجاً احتياطياً متكرراً. وإذا تعطل مضيفه، يُعيد CloudStack بناءه خلال بضع دقائق. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | `cp_offering_invalid` / "هذا العرض ليس 2 vCPU / 2048 MB / limitcpuuse" | يحتوي عرض control-plane على أحجام أخرى أو يفتقر إلى حد أقصى للـ CPU | أنشئ العرض كما في الخطوة 3 واختره مرة أخرى. | | مفتاح تبديل **Enable CKS** معطّل | لم يتم اختيار أي عرض لـ control-plane | اختر واحداً أولاً. | | `kubernetesserviceenabled: false` | CKS معطّل في CloudStack | قم بتمكينه وأعد تشغيل خادم الإدارة. | | فشل فحص نقطة النهاية | تعذر الوصول إلى `endpoint.url` من أجهزة VM الخاصة بالعنقود | عيّن عنوان URL يمكن الوصول إليه، وأعد تشغيل خادم الإدارة، وانقر على **Recheck**. | | "EOL: لا يمكن التمكين للبيع" | انقضى تاريخ نهاية دورة حياة الإصدار | سجّل إصداراً أحدث. | | "لا توجد إصدارات: انقر على Sync from CloudStack" | لم يتم تسجيل أي إصدار Kubernetes | سجّل إصداراً وقم بالمزامنة. | | "الواجهة الخلفية لـ CKS معطلة: لا يمكن للعملاء إنشاء عناقيد حتى في حال تفعيل علامة البيع" | مفتاح البيع مفعّل ولكن الواجهة الخلفية لـ CKS معطلة | قم بتمكين CKS في علامة التبويب CloudStack. | | "يجب أن تكون خطة واحدة 1 على الأقل مطروحة للبيع" | تمت إزالة آخر خطة worker | احتفظ بخطة واحدة على الأقل، أو أوقف مبيعات Kubernetes. | | العنقود عالق في مرحلة الإنشاء | عدم كفاية السعة أو فقدان ملف ISO | تحقق من علامات تبويب السعة وحالة ملف ISO الخاص بالإصدار. | | فشل VPC جديد في الخطوة الأولى | معرّف عرض VPC أو عرض الطبقة غير صالح | استبدل كل UUID خاص بالعرض بمعرّف من CloudStack لديك. | | "يجب أن يكون cs_offering_id عبارة عن UUID" | معرّف العرض ليس UUID | الصق المعرّف من `cmk list networkofferings`. | | فشل تغيير الخطة | عرض الطبقة الجديد غير موجود أو أن معدل نقل الشبكة غير صحيح | تحقق من UUID الخاص بالعرض ومعدل نقل الشبكة له. | --- # الخطط والأسعار {#plans-and-pricing} > **المسار في لوحة الإدارة:** Services › Virtual Machines › Plans & pricing (`/vm/catalog`)، مع علامات التبويب Plan وCustom plan وCycle وOffering CloudStack. توجد القوالب في صفحة منفصلة: Services › Virtual Machines › Template (`/vm/templates`). ## الوظيفة {#what-it-does} تُعد **الخطة** مواصفات يشتريها العملاء: vCPU وRAM وقرص الجذر وسعر محدد، ضمن منطقة معينة، ومن مصدر واحد (CloudStack أو عنقود Proxmox VE). يختار العميل خطة ونظام تشغيل و**دورة فوترة** (بالساعة أو شهرياً أو لفترة أطول مسبقة الدفع). تُباع الخطط في بوابة العملاء وعبر API وفي مواقع الموزعين. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | Source | اتصال CloudStack (تشير الخطة إلى CloudStack service offering) أو ربط عنقود Proxmox VE بالمنطقة. راجع [CloudStack](https://nexcmp.com/ar/docs/infrastructure/cloudstack/) و[Proxmox VE](https://nexcmp.com/ar/docs/infrastructure/proxmox/). | | المنطقة | منطقة تتيح بيع الأجهزة الافتراضية. راجع [المناطق](https://nexcmp.com/ar/docs/infrastructure/zones/). | | القوالب | قالب واحد مفعّل وجاهز على الأقل. راجع [قوالب نظام التشغيل](https://nexcmp.com/ar/docs/infrastructure/templates/). | | سعر الصرف | فقط في حال إدخال الأسعار بعملة VND. راجع [العملة وأسعار الصرف](https://nexcmp.com/ar/docs/catalog/currency-and-exchange-rates/). | | الأذونات | مسؤول؛ يتطلب كل تغيير في السعر تحديد السبب. | ## تجهيز البنية التحتية {#prepare-the-infrastructure} - **CloudStack:** أنشئ عروض الخدمة (service offerings) التي تريد بيعها (عامة، أو مشتركة مع نطاق NexCMP). تشير الخطة إلى عرض واحد. تسرد علامة التبويب **Offering CloudStack** العروض وعروض الأقراص مباشرة من CloudStack (مخزنة مؤقتاً لمدة 60 ثانية). عندما يكون جدول الخطط فارغاً، ينشئ الـ worker ست خطط تلقائياً من عروضك الفعلية. - **Proxmox VE:** لا يلزم إعداد أي شيء في Proxmox؛ فالخطة تحدد مواصفات CPU وRAM والقرص الخاصة بها. ويجب ألا يكون حجم القرص أصغر من قرص القالب. ## الربط في NexCMP {#connect-in-nexcmp} ### كيفية تخزين الأسعار {#how-prices-are-stored} يخزن NexCMP كل سعر بصيغة **ميكرو دولار في الساعة** (µ$/hour؛ حيث يعادل 1 µ$ قيمة 1/1,000,000 USD). يمكنك إدخال السعر بالوحدة التي تفضلها ليقوم النموذج بتحويله تلقائياً: | الوحدة | ملاحظات | |---|---| | USD / ساعة (6 منازل عشرية) | يُخزن كما هو. | | USD / شهر | يُقسم على إعداد عدد الساعات شهرياً (730). | | VND / شهر | يُحوَّل مرة واحدة وفق سعر الصرف الحالي، ثم يُخزن بصيغة µ$/hour. لا يظهر إلا عند توفر سعر صرف. | يعرض النموذج النتيجة: µ$/hour، وUSD/hour، والسعر الشهري وكل دورة فوترة. **السعر الشهري = السعر بالساعة × 730**؛ أما الدورة الأطول فهي **السعر الشهري × عدد الأشهر × (1 − نسبة الخصم)**. ### إضافة خطة {#add-a-plan} 1. افتح **Services › Virtual Machines › Plans & pricing** وانقر على **Add plan**. 2. املأ النموذج: | الحقل | مثال للقيمة | |---|---| | اسم الخطة | `VM-2-4` | | Slug | فارغ: يُنشأ من الاسم | | المنطقة | منطقتك الافتراضية | | مصدر البنية التحتية | فارغ لـ CloudStack، أو عنقود Proxmox | | عرض خدمة CloudStack (مباشر) | اختر واحداً (يظهر فقط لـ CloudStack) | | CPU (نواة)، وRAM (ميجابايت)، وقرص الجذر (GB) | `2`, `4096`, `40` | | عرض القرص | اختياري، لحجم مخصص لقرص الجذر | | إدخال السعر حسب / السعر | `USD / month`, `12` | | الوصف المختصر | `2 vCPU, 4 GB RAM, 40 GB NVMe` | | الترتيب | `10` | | نشط | تشغيل: يمكن للعملاء الشراء | | مستوى الرؤية | مرئي في الكتالوج | | سبب تغيير السعر | `initial price` | 3. انقر على **OK**. ستظهر الخطة في الجدول مع سعرها بالساعة وسعرها الشهري وخلية لكل دورة مفعّلة. ![جدول الخطط موضحاً الأسعار بالساعة وشهرياً وحسب كل دورة](https://nexcmp.com/ar/docs/images/catalog/plans-02-list.webp) ### دورات الفوترة {#billing-cycles} افتح علامة التبويب **Cycle** لتحديد الدورات التي يمكن للعملاء اختيارها والخصومات المطبقة عليها. | الدورة | القيمة الافتراضية | ملاحظات | |---|---|---| | بالساعة | مفعلة دائما | تتم الفوترة ساعة بساعة. | | شهرياً | مفعّل، 0% | | | 1 year | مفعّل، 10% | | | 2 years | مفعّل، 15% | | | 3 سنوات | مفعّل، 20% | | يمكنك إعادة تسمية أي دورة وتعديل نسبة الخصم الخاصة بها (من 0 إلى 90%) وتفعيلها أو تعطيلها. يسري التغيير على الأجهزة الافتراضية (VMs) المشتراة أو المجددة **بعد** الحفظ؛ بينما تحتفظ الأجهزة الافتراضية قيد التشغيل بسعرها المقفل. ![علامة التبويب Cycle مع الخصومات لكل دورة فوترة](https://nexcmp.com/ar/docs/images/catalog/plans-03-cycles.webp) ### تحديد خطة أساسية واشتقاق باقي الخطط {#set-a-base-plan-and-derive-the-others} يُعيد خيار **Set base plan + derive other plans** تسعير الجدول بالكامل استناداً إلى سعر واحد. اختر الخطة الأساسية وسعرها، ثم اختر إما الإبقاء على **نسب الأسعار الحالية** بين الخطط أو الحساب وفق **أسعار المكونات** (µ$/ساعة لكل vCPU ولكل جيجابايت RAM ولكل جيجابايت NVMe، مع خصم باقة اختياري من 0 إلى 50%). يعرض جدول المعاينة الأسعار القديمة والجديدة قبل تطبيق أي تغييرات. انقر فوق **Apply** واذكر السبب. عند تطبيق أسعار جديدة: تحصل الأجهزة الافتراضية العاملة بالنظام **بالساعة** على السعر **الأقل** بدءاً من ساعة الفوترة التالية، بينما تحصل الأجهزة مسبقة الدفع عليه عند التجديد. وإذا **ارتفع** السعر، تحتفظ الأجهزة الافتراضية قيد التشغيل بسعرها القديم. ### الخطط المخصصة {#custom-plans} تتيح علامة التبويب **Custom plan** للعملاء تحديد مواصفاتهم من vCPU وRAM ومساحة NVMe. حدد سعر الوحدة بالساعة لكل vCPU وكل جيجابايت RAM وكل جيجابايت NVMe (اتركه فارغاً لاشتقاقه من نسبة خصم مئوية)، والحد الأدنى والأقصى ومقدار الزيادة لكل منها، ودورات الفوترة المطبقة. ينبغي أن تكلف الخطة **المخصصة** أكثر من الخطة الثابتة ذات المواصفات نفسها، وإلا سيتجاهل العملاء الخطة الثابتة؛ وتحدد الصفحة الصفوف التي تكون فيها الخطة المخصصة أرخص. فعّل **Enable custom plans for customers** لبيعها؛ ويؤدي التعطيل إلى عرض "Coming soon" في البوابة. يحصل كل جهاز افتراضي مخصص على صف خطة مخفي خاص به؛ ولا يمكن تعديل هذه الصفوف أو حذفها طالما أن الجهاز الافتراضي موجود. ### التعديل والإخفاء والاستنساخ والحذف {#change-hide-clone-delete} | الإجراء | الوظيفة | |---|---| | **Edit** | يغيّر الاسم والوصف والترتيب والسعر وحالة التفعيل ومستوى الظهور. | | **On/Off** | **Off**: لا يمكن للعملاء الشراء؛ ولا تتأثر الأجهزة الافتراضية قيد التشغيل. | | **Hide / Show** | الخطة المخفية لا تظهر في الكتالوج، ولكن الأجهزة الافتراضية الحالية تحتفظ بها ويمكن للمسؤول تعيينها. | | **Clone** | ينشئ خطة جديدة في المنطقة نفسها بمصدر أو حجم أو سعر جديد، مع إمكانية إخفاء الخطة القديمة اختيارياً. لبيع المواصفات نفسها من CloudStack وProxmox، انسخ الخطة واختر المصدر الآخر. | | **Move up/down** | يغيّر الترتيب. | | **Delete** | يزيل الخطة من البيع ومن الجدول. وتحتفظ بها الأجهزة الافتراضية التي تستخدمها بالفعل. | ::: warning الخطط قيد الاستخدام مقفلة بمجرد أن ترتبط بالخطة أجهزة افتراضية (VMs)، يتم قفل **zone, offering, CPU, RAM, disk and source** حتى لا يتم تغيير الأجهزة الافتراضية قيد التشغيل دون تنبيه. استخدم **Clone** لإنشاء الإعداد الجديد؛ مع احتفاظ الخطة القديمة بأجهزتها الافتراضية. ::: ## التحقق {#verify} 1. تظهر الخطة في الجدول بالسعر المتوقع بالساعة والشهري. 2. في بوابة العملاء، ابدأ طلباً: توفر المنطقة الخطة وتتطابق أسعار الدورات مع علامة التبويب **Cycle**. 3. قم بإنشاء طلب تجريبي، وتحقق من الخصم من المحفظة مقارنة بالسعر المعروض، ثم احذف الجهاز الافتراضي (VM). ## القيود والملاحظات {#limits-and-notes} - تنتمي الخطة إلى منطقة **واحدة** ومصدر **واحد**. - تُخزَّن الأسعار بوحدة µ$/hour؛ ويُشتق سعر VND المعروض ويُقرّب عبر **VND rounding step** (راجع صفحة العملات). المحفظة تكون دائمًا بعملة USD. - يحصل الموزعون على سعر جملة وتجزئة مشتق من سعر القائمة؛ ولا يؤدي تغيير سعر خطة حالية إلى نسخ أسعار الموزع المخصصة إلى نسخة مستنسخة قمت بتعديل تكوينها. - يتم التحقق من حدود Min وmax وstep للخطط المخصصة مقارنة بحدود CloudStack نفسها؛ وتعيين حد أقصى للقرص أعلى من `storage.max.volume.size` الخاص بـ CloudStack يؤدي إلى فشل النشر واسترداد المبلغ. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | "اسم الخطة مطلوب" / "عرض الخدمة مطلوب" | حقل مفقود | أدخل الاسم؛ وبالنسبة إلى CloudStack اختر offering. | | "يجب أن يكون CPU/RAM/disk > 0" | أحد الأحجام فارغ أو قيمته صفر | أدخل القيم الثلاث. | | "سعر غير صالح (يجب أن يكون µ$/hr بين 1 … 100,000,000)" | السعر خارج النطاق المسموح | تحقق من الوحدة والمبلغ. | | "تغيير السعر يتطلب تحديد سبب" | سبب التغيير فارغ عند التعديل | اكتب سببًا (3 أحرف أو أكثر). | | "العرض "X" هو 4c/8192 ولكن الخطة تحدد 2c/4096 - سيقوم CloudStack بالتهيئة وفقًا للعرض. هل تريد الحفظ؟" | أرقام الخطة تختلف عن أرقام الـ offering | اجعلها متطابقة، أو أكّد للاحتفاظ بحجم CloudStack. | | "فشل جلب العروض من CloudStack" | الاتصال متوقف أو المفتاح يفتقر إلى الصلاحيات | راجع [CloudStack](https://nexcmp.com/ar/docs/infrastructure/cloudstack/). | | "القالب غير جاهز على CloudStack - سيفشل النشر. هل تريد التمكين على أي حال؟" | قمت بتمكين قالب غير مكتمل التجهيز | انتظر حتى يصبح القالب جاهزًا. | | لا يمكن تعديل الخطة ("has VMs - locked") | توجد أجهزة افتراضية تستخدم الخطة | قم باستنساخها. | | الخطة لا تظهر للعملاء | معطلة، أو مخفية، أو المنطقة غير جاهزة | تحقق من **Active** و**Visibility** وعلامة المنطقة. راجع [Zones](https://nexcmp.com/ar/docs/infrastructure/zones/). | | "حدد دورة فوترة 1 على الأقل" | لم يتم تحديد أي دورة للخطط المخصصة | حدد خيارًا واحدًا على الأقل. | | "يجب أن يكون خصم الحزمة بين 0–50%" | خارج النطاق | استخدم قيمة من 0 إلى 50. | | خيار سعر VND مفقود | لا يوجد سعر صرف حتى الآن | قم بتحديث سعر الصرف أولاً. | --- # حصص Bandwidth والإضافات {#bandwidth-quotas-and-add-ons} > **المسار في لوحة الإدارة:** Services › Bandwidth: Summary (`/bandwidth`) وAdd-on (`/bandwidth/addons`) وQuotas, pricing & policy (`/bandwidth/policy`). يقع مفتاح الوحدة في System › Admin › License & updates. ## الوظيفة {#what-it-does} تمنح ميزة Bandwidth كل خدمة مقاسة **حصة** ترافيك شهرية. يقيس NexCMP الاستخدام، ويحذر العميل عند 80% و100%، وعند تجاوز الحصة، يتصرف وفقًا لـ **سياسة التجاوز** الخاصة بك. يمكن للعملاء شراء **إضافات** من التيرابايت الإضافية من محفظتهم؛ ويمكنك أيضًا منح إضافات مجانًا. | الخدمة | الحصة | |---|---| | أجهزة افتراضية | لكل VM شهرياً (الافتراضي 2048 GB، أي 2 TB) | | Kubernetes | حصة الـ VM مضروبة في عدد العقد العاملة (workers) | | Object Storage | حركة تنزيل البيانات لكل عميل شهرياً (الافتراضي 100 GB)؛ وما يتجاوز ذلك يُحسب بالسعر العادي حسب الاستخدام | | VPN | يحتفظ بحصة خطته؛ يمكن ترقية النطاق الترددي من صفحة VPN | | Private Cloud | **غير محدود** | ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | الوحدة | يكون **Bandwidth** مفعلاً افتراضياً. أوقفه من License & updates لإخفائه. | | مصدر القياس | مع المصدر الافتراضي، **إحصاءات CloudStack VM**. حافظ على تفعيل جمع إحصاءات VM في CloudStack؛ وتكفي فترة الاحتفاظ الافتراضية البالغة 720 دقيقة. | | Proxmox VE | أجهزة VM على Proxmox VE **لا يتم قياس استهلاكها**. | | سعر الصرف | يُدخل سعر الإضافة بعملة VND. راجع [Currency and exchange rates](https://nexcmp.com/ar/docs/catalog/currency-and-exchange-rates/). | | يعتمد على | [CloudStack](https://nexcmp.com/ar/docs/infrastructure/cloudstack/) لحركة بيانات الـ VM وKubernetes، و[S3](https://nexcmp.com/ar/docs/infrastructure/s3/) لعمليات تنزيل التخزين. | ## تجهيز البنية التحتية {#prepare-the-infrastructure} لا يلزم اتخاذ أي إجراء إضافي بعد ربط CloudStack. يقرأ NexCMP `listVirtualMachinesUsageHistory` لجميع أجهزة VM التابعة للحساب عبر استدعاء واحد كل 5 دقائق، ضمن نوافذ زمنية لا تتجاوز ساعتين. وتغطي كل عينة دقيقة واحدة ويتم **تجميعها**. تؤخذ العينات بأثر رجعي مدته ثلاث دقائق لتوفير وقت كافٍ لوصولها. وأي فجوة تتجاوز مدة الاحتفاظ في CloudStack (نحو 12 ساعة) يتم تجاوزها وتسجيلها. ::: info دلالة الأرقام يُحسب الاستخدام على واجهة الشبكة الخاصة بكل VM، لذا فهو يشمل حركة البيانات بين أجهزة VM وليس فقط حركة البيانات إلى الإنترنت. وقد تكون القيمة أعلى قليلاً مما يسجله موجه الحافة (edge router). ::: ## الربط في NexCMP {#connect-in-nexcmp} 1. افتح **Services › Bandwidth › Quotas, pricing & policy**. 2. اضبط القيم واضغط **Save**؛ سيُطلب منك ذكر السبب ويتم تسجيله. يطبّق العامل التغيير في غضون 30 ثانية تقريباً. | الحقل | القيمة الافتراضية | المعنى | |---|---|---| | تمكين عرض النطاق الترددي (قائمة العملاء وشراء الإضافات) | مفعّل | مفتاح التبديل للجانب البيعي للوحدة. | | VM، جيجابايت/شهر (Kubernetes = هذه القيمة × workers) | 2048 | الحصة لكل VM في الفترة الزمنية. | | S3، جيجابايت تنزيل/شهر لكل عميل | 100 | ما يتجاوز ذلك يخضع لنظام الدفع حسب الاستخدام المعتاد لـ S3. | | Quota direction (VM, Kubernetes) | In + out | أو **Outbound only**. | | +1 TB price (VND) | 100,000 | يتم تحويله إلى سنتات وفقاً لسعر الصرف المحدد. | | الحد الأقصى لكل عملية شراء (TB) | 50 | | | Overage policy | suspend | **notify** أو **throttle** أو **suspend** (أدناه). | | فرض التعليق الفعلي بدءاً من | تاريخ الترحيل + 24 ساعة | قبل هذا التاريخ لا يتم تعليق أي شيء؛ ويكتفى بإنذار العملاء. | | حد تقييد السرعة (Mbps) | | يُستخدم فقط مع خيار throttle. | ![سياسة عرض النطاق الترددي: الحصص الافتراضية، وسعر الإضافات، وسياسة تجاوز الاستهلاك](https://nexcmp.com/ar/docs/images/catalog/bandwidth-01-policy.webp) ### سياسات تجاوز الحصة {#overage-policies} | السياسة | الإجراء عند تجاوز الخدمة نسبة 100% | |---|---| | **notify** | يتم إشعار العميل فقط، دون أي إجراء آخر. | | **throttle** | مثل notify حاليًا: محدد السرعة غير متصل في هذا الإصدار. | | **suspend** (افتراضي) | يتم تعليق VM أو الكتلة أو حساب S3 حتى يشتري العميل باقة إضافية أو تبدأ الفترة التالية. يسري مفعوله فقط بدءًا من تاريخ **suspend-from**. | تعمل تنبيهات 80% و100% (الجرس والبريد الإلكتروني) دائمًا، مرة واحدة لكل حد وفترة وخدمة. إذا قمت بإلغاء قفل خدمة تم تعليقها بسبب نقل البيانات بينما لا تزال متجاوزة للحصة، فإن الفحص التالي (خلال 5 دقائق) سيعلقها مجددًا. لإبقائها قيد التشغيل، **امنح باقة إضافية**. ### مراقبة الاستخدام ومنح الباقات الإضافية {#watch-usage-and-grant-add-ons} افتح **Services › Bandwidth › Summary**. حيث يسرد كل خدمة مع استخدامها في الفترة الحالية، والحصة شاملة الباقات الإضافية، والحصة المتبقية، وعلامتي 80% و100%. تعرض لوحات مؤشرات الأداء (KPI) عدد الخدمات، والباقات الإضافية المباعة في آخر 30 يومًا، وحالة أداة التجميع (قيد التشغيل، المؤشر). ويعرض جدول **Daily** الفترة الحالية يومًا بيوم. ![ملخص نقل البيانات مع حالة أداة التجميع والاستخدام لكل خدمة](https://nexcmp.com/ar/docs/images/catalog/bandwidth-02-summary.webp) لمنح العميل سعة إضافية، استخدم **Grant** في الخدمة (باقة إضافية بتيرابايت كاملة دون أي رسوم). افتح **Add-on** لعرض سجل عمليات الشراء والمنح، بدءًا من الأحدث، مع تصفية حسب النوع. ![سجل الباقات الإضافية يوضح عمليات الشراء والمنح المجانية](https://nexcmp.com/ar/docs/images/catalog/bandwidth-03-addons.webp) ### ما يراه العملاء {#what-customers-see} تحصل بوابة العملاء على قائمة **Bandwidth** تتضمن الاستخدام، والحصة المتبقية، وإجراء **buy +1 TB** مدفوعًا من المحفظة (حتى الحد الأقصى لكل عملية شراء لديك). الباقات الإضافية صالحة للفترة الحالية. ## التحقق {#verify} 1. أداة التجميع في **Summary** قيد التشغيل ومؤشرها يتقدم كل بضع دقائق. 2. يظهر استخدام VM التي تشهد حركة مرور بعد حوالي 10 إلى 15 دقيقة. 3. لرؤية التنبيهات، اخفض حصة VM إلى بضعة غيغابايت على تثبيت **تجريبي** وقم بتوليد بعض حركة المرور. لا تفعل ذلك في بيئة الإنتاج: فالحصة تنطبق على كل VM. ## القيود والملاحظات {#limits-and-notes} - يُحتسب الاستخدام لكل فترة (شهر). تنطبق الباقات الإضافية والحصص على الفترة الحالية. - يحميك "Enforce actual suspend from" من تعليق خدمات العملاء بمجرد تفعيل الوحدة لأول مرة. - تكتفي سياسة throttle بالإشعار فقط في هذا الإصدار. - ينطبق تغيير الحصة على كل موقع، بما في ذلك مواقع الموزعين. وتتبع أسعار التجزئة والجملة للباقات الإضافية الخاصة بالموزعين نسبة الخصم أو الهامش الربحي المحددة لهم. - يُعد نقل البيانات لـ **الخوادم المخصصة** أمرًا منفصلًا؛ راجع [الخوادم المخصصة](https://nexcmp.com/ar/docs/infrastructure/dedicated/). ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | يظل الاستخدام عند الصفر لـ VM قيد التشغيل | العامل (worker) متوقف، أو CloudStack غير متصل، أو إحصاءات VM معطلة | تحقق من `sudo nexcmp status` و**Test connection** في [CloudStack](https://nexcmp.com/ar/docs/infrastructure/cloudstack/)؛ وقم بتمكين إحصاءات VM في CloudStack. | | فجوات في بيانات الاستخدام | تم تجاوز فترة الاحتفاظ في CloudStack، أو تعطل العامل (worker) لأكثر من 12 ساعة تقريبًا | لا يمكن استردادها؛ يتم تسجيل الفجوة. | | الاستخدام أعلى قليلًا من المتوقع | يتم تضمين حركة المرور بين أجهزة VM وحركة مرور الواجهات الأخرى | أمر متوقع؛ وضّح ذلك للعملاء. | | خدمة معلقة تعود إلى حالة التعليق بعد إلغاء قفلها | لا تزال متجاوزة للحصة | امنح باقة إضافية أو ارفع الحصة. | | لا يتم تعليق أي شيء بالرغم من أن السياسة هي **suspend** | تاريخ suspend-from يقع في المستقبل | اضبطه على الوقت الحالي (تعرض الصفحة "ACTIVE" عندما يكون ساري المفعول). | | "يجب أن يكون bw_over_policy هو notify أو throttle أو suspend" | تم إرسال سياسة غير صالحة عبر واجهة برمجة التطبيقات API | استخدم إحدى القيم الثلاث. | | لا تُظهر الأجهزة الافتراضية في Proxmox أي استهلاك | غير خاضعة للقياس | Expected. | | لا يمكن للعملاء شراء الإضافات | عرض النطاق الترددي متوقف أو المحفظة فارغة | تحقق من المفتاح والمحفظة. | --- # العملة وأسعار الصرف {#currency-and-exchange-rates} > **المكان في لوحة التحكم:** Finance › Payment channels › Exchange rates (`/payments/fx`) للاطلاع على الأسعار. System › Settings › Brand (`/settings/branding`) لمفتاح **Site currency**. ## الوظيفة {#what-it-does} يحتفظ NexCMP بالمحافظ والفواتير بعملة USD. وتُخزن أسعار خطط VM بالميكرو دولار لكل ساعة. وتتيح عملات العرض للعملاء قراءة مبالغ USD بعملتهم الخاصة وفق سعر منشور؛ وهي لا تغير رصيد المحفظة. تقبل بعض الخدمات الأسعار المدخلة بعملة VND، بما في ذلك إضافات النطاق الترددي، وS3، وPrivate Cloud، وخطط Bare Metal الحالية التي تحتفظ بالتسعير بعملة VND. وتُدفع التحويلات المصرفية عبر Sepay بعملة VND. يتم **نشر الأسعار بواسطة المسؤول**. لا يتم تحديث أي شيء تلقائياً، لذلك تظل الأسعار التي حفظتها كما هي تماماً حتى تضغط على زر التحديث. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | Internet access | يجب أن يتمكن خادم اللوحة من الوصول إلى `open.er-api.com` (من أجل USD/VND) وإلى `api.frankfurter.dev` (للعملات الأخرى) عند الضغط على **Update exchange rates**. | | الأذونات | مسؤول واحد للتغييرات؛ يطلب كل تغيير سبباً. | | يعتمد على | لاشيء. تستخدم [Plans](https://nexcmp.com/ar/docs/catalog/plans/) و [Bandwidth](https://nexcmp.com/ar/docs/catalog/bandwidth/) و [S3](https://nexcmp.com/ar/docs/infrastructure/s3/) والتحويلات البنكية بالدونغ الفيتنامي السعر. | ## تجهيز البنية التحتية {#prepare-the-infrastructure} غير مطلوب. إذا كان خادمك يفلتر حركة المرور الصادرة، فاسح بروتوكول HTTPS للخدمتين المذكورتين أعلاه. ## الربط في NexCMP {#connect-in-nexcmp} ### 1. اختر عملة الموقع {#_1-choose-the-site-currency} افتح **System › Settings › Brand** واضبط **Site currency**: | Choice | ما يراه العملاء | |---|---| | **حسب اللغة (auto)** (الافتراضي في التثبيت الجديد) | تحدد البوابة عملة العرض وفقاً للغة (الجدول أدناه). ويمكن للعميل اختيار USD بدلاً من ذلك. | | **USD** | الأسعار والأرصدة بالدولار الأمريكي فقط. لا يوجد تبديل للعملات ولا مبالغ محولة. | | **VND** | إعداد قديم؛ يتبع نفس قواعد العرض المستندة إلى اللغة مثل Auto. | حفظ. يتم تحديث صفحات العملاء في غضون دقيقة واحدة تقريباً. عندما يتبع الموقع لغة العميل: | Language | Display currency | |---|---| | English | USD | | Vietnamese | VND | | الصينية (المبسطة / التقليدية) | CNY / TWD | | Japanese, Korean | JPY, KRW | | French, German, Spanish, Italian | EUR | | Portuguese, Russian | BRL, RUB | | Arabic, Hindi | SAR, INR | | الإندونيسية، التايلاندية | IDR, THB | العملات التي لم يتم نشر سعرها لا يتم توفيرها، وتعود البوابة تلقائياً إلى USD. ### 2. نشر الأسعار {#_2-publish-the-rates} 1. افتح **Finance › Payment channels › Exchange rates**. 2. تُدرج بطاقة **Currency by language** عملات العرض الـ 11 مع سعرها لكل دولار أمريكي، والمصدر (Frankfurter)، ووقت آخر تحديث. انقر على **Update exchange rates**. يقوم هذا الزر بإجراءين في خطوة واحدة: يقرأ جدول السوق العام لـ **USD/VND** ويقرأ أسعار الصرف الـ 11 الأخرى. ويتم التحقق من كليهما قبل حفظ أي منهما. وإذا فشل أحدهما، فلن يتغير شيء وتظل الأسعار السابقة كما هي. 3. تعرض البطاقة **Active exchange rate** سعر صرف USD/VND المطبق، وعلامة مصدره (سوق عام أو ثابت)، والهامش، وأرقام السوق المرجعية مع طوابعها الزمنية. 4. بطاقة **Config** (الحفظ مع ذكر السبب): | الحقل | المعنى | النطاق | |---|---|---| | الهامش (بالنقطة، 100 = 1%) | تُضاف فوق السعر المرجعي للسوق. والسعر الفعلي هو السعر المرجعي مضافًا إليه الهامش، مقربًا للأعلى. | 0 إلى 1000 | | سعر ثابت (VND لكل USD، 0 = اتباع السوق) | سعر تحدده بنفسك، ويحل محل رقم السوق. | 0 أو 15,000 إلى 50,000 | | عتبة القفز (بالنقطة) | أي سعر سوق جديد يختلف عن السعر الحالي بأكثر من هذه القيمة يتم **تعليقه** حتى تؤكده. | 50 إلى 2000 (الافتراضي 500) | | خطوة تقريب VND | تقريب أسعار VND ومبالغ التحويل البنكي. | 1، 100، 1,000 (الافتراضي) أو 10,000 | 5. إذا قفز سعر السوق الجديد بأكثر من الحد المعين، تظهر البطاقة **Pending exchange rate** ويكون السعر **غير مطبق**. قارنه بالمرجع الذي اخترته وانقر على **Apply this rate**. يُرفض أي سعر سوقي خارج النطاق من 15,000 إلى 50,000 VND لكل USD لكونه غير معقول. يقتصر التحديث اليدوي على طلب واحد كل خمس دقائق، لذا قد يطلب منك الزر الانتظار. 6. يسرد جدول **Exchange rate history** كل سعر تم جلبه أو تأكيده مع وقته، والتعريفة الفعلية، والمرجع السوقي، والمصدر، وما إذا كان قد تم تطبيقه، ومن قام بذلك، مع ملاحظة (تُميز القفزات المعلقة بعلامة **held**). ## كيف يُستخدَم السعر {#how-a-rate-is-used} | المكان | القاعدة | |---|---| | المحفظة والفواتير | سنتات USD. لا يغير السعر الرصيد أبداً. | | خطط VM المُدخلة بعملة VND | تُحوَّل **مرة واحدة** وفق السعر الساري عند الحفظ، ثم تُخزَّن بعملة USD. لا تؤدي تغييرات الأسعار اللاحقة إلى إعادة تسعير خطط VM تلك. | | التحويل البنكي عبر Sepay | يدفع العميل `ceil(USD × rate)`، مقرباً للأعلى إلى خطوة التقريب. يتم **حظر** Sepay حتى يتوفر سعر USD/VND. | | خطط Bare Metal | تستخدم التثبيتات الجديدة عملة USD مباشرةً. تحتفظ خطط VND الحالية بوحدة التسعير الخاصة بها وتتطلب سعر صرف عند الخصم؛ راجع [Dedicated servers](https://nexcmp.com/ar/docs/infrastructure/dedicated/). | | المدفوعات الدولية الأخرى المدخلة بـ VND | يتم تقريبها لأقرب سنت. | | العرض في البوابة | USD مضروباً في السعر المنشور لعملة العرض، ومنسقاً حسب اللغة. | ## التحقق {#verify} 1. تُظهر **Active exchange rate** قيمة USD/VND مع وقت "تم جلبها" حديث. 2. تعرض شبكة **Currency by language** الأسعار غير الفارغة. 3. في بوابة العملاء، بدّل اللغة إلى الفيتنامية (مع ضبط عملة الموقع على Auto): تظهر الأسعار بالدونغ؛ بدّلها إلى اليابانية: بالين. وعند ضبط عملة الموقع على USD، تظهر الأسعار بالدولار فقط. 4. في نموذج الخطة (Plans & pricing)، تقدم قائمة **Enter price by** خيار **VND / month**. ## القيود والملاحظات {#limits-and-notes} - لا يوجد تحديث تلقائي. اضغط على **Update exchange rates** عندما تريد أسعاراً جديدة، واضبط تنبيهاً إذا كانت الأسعار مهمة بالنسبة لك. - يُستخدم سعر السوق العام لزوج USD/VND؛ وهو سعر مرجعي وليس سعر بيع أو شراء بنكي. تأتي عملات العرض الأخرى من Frankfurter؛ ويُرفض أي تاريخ أقدم من 14 يومًا أو أي جدول غير مكتمل. - الهامش والسعر الثابت يؤثران فقط على USD/VND. العملات ال11 المعروضة لا تحمل أي هامش. - لغة كل عميل لها عملة واحدة. يؤدي تغيير اللغة إلى إعادة تعيين عملة تلك اللغة ما لم يختار العميل USD لنفس اللغة. - مواقع الموزعين تتبع نفس الأسعار. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | "سعر الصرف الجديد ينحرف عن الحد المسموح - معلق، يتطلب تأكيداً يدويًا" | القفزة أكبر من الحد الأدنى | تحقق وانقر فوق **Apply this rate**، أو قم بتغيير الحد الأدنى. | | "الخادم رفض سعر الصرف الجديد" | القيمة السوقية خارج النطاق من 15,000 إلى 50,000 أو غير صالحة التنسيق | انتظر وحاول مرة أخرى، أو اضبط سعراً ثابتاً. | | عملية التحديث تطلب منك الانتظار قبل إعادة المحاولة | تحديثات متكررة جداً | انتظر وأعد المحاولة. | | "تعذر جلب سعر الصرف: …" | خادم اللوحة لا يمكنه الوصول إلى خدمات الأسعار | اسموح بـ HTTPS الصادر وأعد المحاولة. | | علامة **Sepay blocked** | لم يتم نشر سعر USD/VND بعد | اضغط على **Update exchange rates** أو اضبط سعراً ثابتاً. | | عملة مفقودة في البوابة | سعرها مفقود | اضغط على **Update exchange rates**. | | العملاء يرون الأسعار بالدولار الأمريكي USD فقط | عملة الموقع هي USD، أو السعر مفقود | اضبط **Site currency** على Auto وانشر الأسعار. | | "جدول أسعار الصرف غير مكتمل؛ تم الاحتفاظ بالأسعار السابقة" | أعاد Frankfurter أقل من 11 عملة | أعد المحاولة لاحقاً؛ لم يتم تغيير شيء. | | خيار VND مفقود في نموذج الخطة | لا يوجد سعر USD/VND | انشر سعراً أولاً. | --- # قنوات الدفع {#payment-channels} > **أين تجد ذلك في لوحة الإدارة:** Finance › Payment channels (`/payments`). المفاتيح والرسوم: Finance › Payment channels › Fees & limits (`/payments/fees`). تستخدم NexCMP **محفظة USD مسبقة الدفع**. يقوم العملاء بإضافة الأموال إلى المحفظة من خلال قناة دفع؛ يتم بعد ذلك دفع ثمن كل خدمة من المحفظة. لا يتم إظهار القناة للعملاء إلا عندما تكون **ممكنة** و**مكوّنة**. ## الوظيفة {#what-it-does} تربط قنوات الدفع حساباتك المالية (Stripe، PayPal، Binance، بنك فيتنامي) بمحفظة العميل. يتحول الدفع المؤكد بدقة إلى رصيد واحد في المحفظة — وكل رصيد مُعرّف بمعرف الدفع الخاص ببوابة الدفع، بحيث لا يمكن أبداً لعملية Webhook مكررة أن تضيف أموالاً مرتين. استخدم هذه الصفحة لمعرفة القنوات الجاهزة، وأدائها خلال آخر 30 يوماً، وتلك التي تحتاج إلى اهتمام. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | عنوان HTTPS العام | ترسل البوابات إشعارات الـ Webhook إلى `https:///v1/billing/...`، لذا يجب أن تكون لوحتك قابلة للوصول من الإنترنت عبر بروتوكول TLS صالح (انظر [DNS and Cloudflare](https://nexcmp.com/ar/docs/getting-started/dns-and-cloudflare/)). | | الحسابات | حسابك الخاص لدى كل مزود ترغب في استخدامه. تُدخل بيانات الاعتماد في لوحة الإدارة ولا تظهر مرة أخرى أبداً (يُعرض فقط آخر 4 أحرف). | | دور المشرف | حساب مسؤول. | | الاعتمادات | لا شيء. قناة البنك الفيتنامي تحتاج بشكل إضافي إلى [سعر صرف](https://nexcmp.com/ar/docs/catalog/currency-and-exchange-rates/). | ## القنوات {#the-channels} | القناة | ما يراه العميل | الإعداد في | المقالة | |---|---|---|---| | البطاقة (Stripe) | نموذج البطاقة، البطاقة المحفوظة | Payment channels › Stripe | [Stripe](https://nexcmp.com/ar/docs/billing/stripe/) | | Apple Pay, Google Pay, Link | أزرار المحفظة (Stripe Express Checkout) | Stripe، بالإضافة إلى تسجيل النطاق | [Stripe](https://nexcmp.com/ar/docs/billing/stripe/#apple-pay-google-pay-and-link) | | Alipay | إعادة التوجيه إلى Alipay (تتم المفوترة بالين الياباني بواسطة Stripe) | Stripe، بالإضافة إلى Fees & limits | [Stripe](https://nexcmp.com/ar/docs/billing/stripe/#alipay) | | PayPal | أزرار PayPal، حساب PayPal المحفوظ | Payment channels › PayPal | [PayPal](https://nexcmp.com/ar/docs/billing/paypal/) | | USDT | عنوان الإيداع والمبلغ المحدد | Payment channels › USDT | [USDT](https://nexcmp.com/ar/docs/billing/usdt/) | | تحويل بنكي فيتنامي | رمز الاستجابة السريعة وتفاصيل التحويل (الواجهة الفيتنامية فقط) | في Payment channels › VN bank transfer | [Bank transfer (Vietnam)](https://nexcmp.com/ar/docs/billing/bank-transfer-vn/) | ## تجهيز البنية التحتية {#prepare-the-infrastructure} غير مطلوب. كل شيء مُعد في لوحة الإدارة؛ ولا يوجد شيء لتثبيته على الخادم. ## الربط في NexCMP {#connect-in-nexcmp} 1. افتح **Finance › Payment channels** (`/payments`). يوضح جدول النظرة العامة كل قناة مع حالتها. 2. افتح علامة التبويب الخاصة بالقناة (**Stripe**، **PayPal**، **USDT**، **VN bank transfer**) واتبع مقالتها. تنتهي كل علامة تبويب بزر **Save**، وحيثما يتوفر، بزر **Test**. 3. افتح **Fees & limits** (`/payments/fees`)، وابحث عن بطاقة **Payment gateways & fees (wallet top-up)**، وفعل القناة بمفتاحها وانقر على **Save channels & fees**. ![نظرة عامة على قنوات الدفع توضح البوابات مع حالات تفعيلها وإعدادها وإحصاءات 30 يوماً](https://nexcmp.com/ar/docs/images/billing/payment-channels-01-overview.webp) ![صفحة الرسوم والحدود مع مفاتيح القنوات وحقول الرسوم](https://nexcmp.com/ar/docs/images/billing/payment-channels-02-fees.webp) ### المفاتيح والرسوم (Fees & limits) {#switches-and-fees-fees-limits} | الإعداد | القيمة الافتراضية | المعنى | |---|---|---| | البطاقة (Stripe) | On | نموذج البطاقة على شاشة الإيداع. مخفي حتى تتوفر مفتاح سري لـ Stripe. | | Apple Pay, Google Pay, Link | On | أزرار المحفظة. تظهر فقط عند التحقق من النطاق في Stripe. | | Alipay | معطل | يتطلب تفعيل Alipay في لوحة تحكم Stripe. | | PayPal | معطل | يُعرض فقط عند تكوين PayPal. | | USDT (Binance) | معطل | هذا المفتاح مقفل حتى يتم التحقق من عنوان الإيداع مقارنة بـ Binance. | | رسوم Stripe (نسبة % / مبلغ ثابت بالسنت) | 3.6 % و 0 | تُستخدم لعرض الرسوم للعميل وحساب المبلغ المضاف. قم تعيينها وفقاً لتعريفة Stripe الفعلية الخاصة بك. | | رسوم PayPal (نسبة % / مبلغ ثابت) | 4.4 % و 30 سنت | الشيء نفسه، بالنسبة لـ PayPal. | | رسوم USDT (%) | 1 % | الشيء نفسه، بالنسبة لـ USDT. | | العميل يدفع رسوم شحن الرصيد | معطل | **On**: يدفع العميل المبلغ + الرسوم وتتلقى المحفظة المبلغ بالكامل. **Off**: يتم خصم الرسوم وتتلقى المحفظة المبلغ ناقصاً الرسوم. | يرى العميل دائماً الرسوم ورصيد المحفظة النهائي قبل الدفع. يؤدي إيقاف تشغيل القناة إلى إخفاء الزر ورفض الخادم للمدفوعات الجديدة مع `method_disabled` (HTTP 403). ::: tip حدود شحن الرصيد الحد الأدنى والحد الأقصى للمبلغ في كل عملية شحن موجودان في نفس الصفحة — راجع [Minimum top-up](https://nexcmp.com/ar/docs/billing/minimum-top-up/). ::: ## التحقق {#verify} 1. في جدول النظرة العامة، تُظهر القناة **Enabled** و**Configured**؛ ويتم ملء عمود **Last test** بعد النقر فوق **Test** في علامة تبويب القناة. 2. قم بتسجيل الدخول إلى البوابة كعميل تجريبي وافتح **Billing › Deposit**. زر القناة موجود. 3. قم بإجراء دفعة صغيرة (راجع مقالة القناة للاطلاع على البطاقات التجريبية أو حسابات الـ sandbox). يرتفع الرصيد، وتظهر إشعار **Top-up received**، وتُدرج الدفعة في **Finance › Billing › Top-ups** (`/billing/deposits`). ## الحدود والملاحظات {#limits-notes} - **أعمدة النظرة العامة:** *30 days* (عدد المدفوعات، والعمليات الناجحة، والفاشلة، والحجم)، و*Stuck 24h* (المدفوعات التي لا تزال معلقة بعد يوم)، و*Unmatched* (عمليات تحويل USDT أو التحويلات المصرفية التي وصلت ولكنها لا تطابق أي طلب). يضيف صف مؤشرات الأداء الرئيسية (KPI) حجم ال30 يوماً، وعدد القنوات المعيبة (الممكّنة ولكن غير المُكوّنة، أو المدفوعات العالقة)، وإجمالي العمليات غير المطابقة. - **أحداث Webhook** مدرجة ضمن **Payment channels › Gateway events** (`/payments/events`). تمتلك Stripe علامة تبويب خاصة بها؛ بينما تتشارك كل من PayPal وUSDT في علامة تبويب واحدة. يمكن إعادة تشغيل الحدث الفاشل — دفتر حسابات المحفظة غير متأثر بالتكرار، لذا فإن إعادة التشغيل لا تُضيف رصيداً مرتين أبداً. - يمكن لـ **Resellers** امتلاك قنوات Stripe وPayPal وUSDT والتحويلات البنكية الخاصة بهم. تظهر صفوفهم هنا أيضاً، ويقوم محدد الموقع في رأس الصفحة بتفقدها. راجع [Resellers](https://nexcmp.com/ar/docs/customers/resellers/). - **المبالغ المستردة:** يمكن استرداد مدفوعات Stripe وPayPal من قائمة المدفوعات؛ أما مدفوعات USDT فلا يمكن استردادها إلى المصدر (يجيب الخادم بـ `usdt_no_refund`). - **وضع الصيانة** لا يزال يقبل طلبات Webhook الخاصة بـ Gateway، لذلك لافقدان لأي دفعة تمت قبل الصيانة مباشرة. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | القناة مفقودة على شاشة إيداع العميل | متوقفة، أو غير مُكوّنة، أو (بالنسبة للبنوك الفيتنامية VN) الواجهة ليست باللغة الفيتنامية | تحقق من **Fees & limits** وعلامة تبويب القناة؛ راجع [Bank transfer (Vietnam)](https://nexcmp.com/ar/docs/billing/bank-transfer-vn/). | | مؤشر الأداء الرئيسي **Faulty channels** أكبر من 0 | تم تمكين القناة بدون بيانات اعتماد، أو أن المدفوعات معلقة لأكثر من 24 ساعة | افتح الصف وانقر فوق **Configure**؛ بالنسبة للمدفوعات العالقة، افتح **Gateway events** وأعد تشغيلها. | | دفع العميل ولكن الرصيد لم يتغير | لم يصل طلب Webhook | تحقق من عنوان URL لـ Webhook في علامة تبويب القناة، ثم أعد تشغيل الحدث في **Gateway events**. | | يجيب الخادم بـ `method_disabled` | المفتاح متوقف | قم بتشغيله في **Fees & limits** واحفظ التغييرات. | | مفتاح USDT باهت وغير نشط | عنوان الإيداع غير مُتحقَّق منه | انقر على **Test & verify address** في تبويب USDT. | --- # Stripe > **المكان في لوحة التحكم:** Finance › Payment channels › Stripe (`/payments/stripe`). المفاتيح والرسوم: Finance › Payment channels › Fees & limits (`/payments/fees`). ## الوظيفة {#what-it-does} يقبل Stripe مدفوعات البطاقات لشحن المحفظة. وبنفس الحساب يمكنك أيضاً توفير **Apple Pay**، و**Google Pay**، و**Link**، و**Alipay**، والسماح للعملاء بـ **حفظ البطاقة** لـ [الشحن التلقائي](https://nexcmp.com/ar/docs/billing/auto-top-up/). استخدمه القناة الأساسية للعملاء الدوليين. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | حساب Stripe | حساب Stripe قادراً على قبول المدفوعات بـ **USD**. يتم خصم قيمة Alipay بالعملة JPY ويجب تفعيلها من قِبل Stripe لحسابك. | | المفاتيح | مفتاح سرّي (`sk_live_...` أو `sk_test_...`) ومفتاح قابل للنشر (`pk_live_...` أو `pk_test_...`). النموذج يقبل فقط المفاتيح التي تحمل هذه البادئات. | | الشبكة | يجب أن تكون لوحتك قابلة للوصول عبر HTTPS من الإنترنت (حيث يستدعي Stripe الـ webhook) ويجب أن تصل إلى `api.stripe.com` على المنفذ 443. | | النطاق (المحافظ فقط) | يجب أن يخدم النطاق المخصص للعملاء `/.well-known/apple-developer-merchantid-domain-association` — وتقوم NexCMP بذلك نيابة عنك. | | الاعتمادات | لا يوجد. | ::: info حسابات Stripe المشتركة تعالج NexCMP فقط أحداث الـ webhook للمدفوعات التي أنشأتها بنفسها، لذا يمكنك استخدام حساب Stripe يخدم تطبيقاً آخر أيضاً. ::: ## تجهيز البنية التحتية {#prepare-the-infrastructure} على جانب Stripe: 1. سجّل الدخول إلى [Stripe Dashboard](https://dashboard.stripe.com). قم بتشغيل أو إيقاف **Test mode** لتحديد ما إذا كنت تجري تشغيلاً تجريبياً أو تنتقل للإنتاج المباشر. مفاتيح أحد الوضعين لا تعمل أبداً مع الوضع الآخر. 2. افتح **Developers › API keys**. انسخ **Publishable key**، واكشف عن **Secret key** ثم انسخه. حافظ على سرية المفتاح السري. 3. (اختياري) افتح **Settings › Payment methods** وفعّل **Alipay** إذا كنت تريد توفيرها. 4. لا تحتاج إلى **إنشاء** الـ webhook يدوياً — يمكن لـ NexCMP إنشاؤه نيابة عنك (انظر الخطوة 5 أدناه). إذا كنت تفضل القيام بذلك يدوياً، أنشئ نقطة نهاية في **Developers › Webhooks** باستخدام عنوان URL والأحداث المدرجة في [Webhook](#webhook). ## الربط في NexCMP {#connect-in-nexcmp} 1. افتح **Finance › Payment channels › Stripe** (`/payments/stripe`). 2. في بطاقة **API keys**، اختر **Mode** (`live` أو `test`)، والصق **Secret key** و**Publishable key**. 3. انقر على **Save**. تُكتب المفاتيح في ملف تكوين على الخادم لا يمكن قراءته إلا بواسطة حساب خدمة NexCMP. ولا تُرسل أبداً مرة أخرى إلى المتصفح؛ وبعد ذلك تعرض الصفحة آخر 4 أحرف فقط. 4. انقر على **Check**. يعرض مربع الحوار الاتصال، والوضع، والرصيد المتاح والمعلق، ومعرف الحساب، وما إذا كانت عمليات الشخص مفعلة، وما إذا كان الـ webhook موجوداً وما إذا كانت Alipay متاحة. الخط الأحمر يعني أن هذا الجزء بحاجة إلى اهتمام. 5. في بطاقة **Webhook**، انقر على **Create webhook** وأكّد ذلك. تطلب NexCMP من Stripe إنشاء نقطة النهاية مع كل حدث مطلوب وتملأ حقل **Webhook signing secret** (`whsec_...`) تلقائياً. عنوان URL المملوء مسبقاً في الحقل هو `https:///v1/billing/stripe/webhook`، على سبيل المثال `https://cloud.example.com/v1/billing/stripe/webhook`. 6. افتح **Fees & limits** (`/payments/fees`)، واجعل **Card (Stripe)** مفعلاً، واضبط **Stripe fee %** و**Stripe fixed fee (cents)** على تعريفتك الحقيقية وانقر على **Save channels & fees**. راجع [Payment channels](https://nexcmp.com/ar/docs/billing/payment-channels/#switches-and-fees-fees-limits). ![صفحة Stripe مع تعبئة الوضع والمفتاح السري والمفتاح القابل للنشر بقيم تجريبية](https://nexcmp.com/ar/docs/images/billing/stripe-01-keys.webp) ### Webhook {#webhook} تبقى الراية الحمراء "Missing webhook_secret" ظاهرة حتى يتم حفظ سر التوقيع. وبدونها **لا يتم تسجيل** عمليات شحن المحفظة عبر Stripe، حتى لو تلقى Stripe الأموال. | العنصر | القيمة | |---|---| | URL | `https:///v1/billing/stripe/webhook` | | الأحداث | `checkout.session.completed`, `payment_intent.succeeded`, `payment_intent.payment_failed`, `charge.refunded`, `charge.dispute.created`, `charge.dispute.closed`, `radar.early_fraud_warning.created`, `refund.updated`, `refund.failed` | | التوقيع | Stripe `Stripe-Signature` رأس الصفحة، HMAC-SHA256، سماحية 300 ثانية. الطلبات ذات التوقيع غير الصحيح تتلقى HTTP 400. | | منع التكرار | يتم تخزين كل معرّف حدث مرة واحدة؛ ولن يؤدي التسليم المتكرر أبداً إلى إضافة رصيد مرتين. | إذا قمت بالتحديث من إصدار قام بتسجيل عدد أقل من الأحداث، فانقر فوق **Create webhook** مرة أخرى — يتم الاحتفاظ نقطة النهاية القديمة، لذا احذفها يدوياً في لوحة تحكم Stripe لاحقاً. يوضح صفوف **24h events** و**Latest event** في بطاقة Webhook ما إذا كانت Stripe تتصل باللوحة أم لا. يتم سرد الأحداث الفردية في **Payment channels › Gateway events** (`/payments/events`، علامة التبويب Stripe)، حيث يمكن عرض كل حدث (**Payload**) أو إعادة إرساله (**Replay**). ### Apple Pay وGoogle Pay وLink {#apple-pay-google-pay-and-link} 1. في بطاقة **Wallets (Apple Pay · Google Pay · Link) & Alipay**، يتم ملء حقل **Customer app Domain registered with Stripe** مسبقاً باسم مضيف موقعك (على سبيل المثال `cloud.example.com`). 2. انقر على **Register / verify domain** وأكد. تقوم NexCMP بتسجيل النطاق في نطاقات طرق الدفع الخاصة بـ Stripe وتطلب من Stripe التحقق منه. 3. تظهر النتيجة حالة **Apple Pay** و**Google Pay** و**Link**. يظهر Apple Pay فقط عندما تكون الحالة `active`. 4. في **Fees & limits** أبقِ خيار **Apple Pay · Google Pay · Link** مفعلاً. ![بطاقة المحفظة توضح النطاق المسجل وحالات Apple Pay وGoogle Pay وLink](https://nexcmp.com/ar/docs/images/billing/stripe-03-wallets.webp) ::: tip بقاء Apple Pay غير نشط يتطلب Apple Pay أن يستجيب ملف ارتباط النطاق برمز HTTP 200 على نطاقك العام. إذا وضعت Cloudflare أو وكيل آخر في المقدمة، فلا تقم بحظر `/.well-known/`. ::: ### Alipay {#alipay} خدمة Alipay اختيارية. قم بتفعيلها في **Stripe Dashboard › Settings › Payment methods**، وانقر على **Check** وانتظر حتى يظهر الحوار أن Alipay متاحة، ثم قم بتشغيل **Alipay (Stripe, JPY display)** في **Fees & limits**. اضبط **Alipay fee %**، و**Alipay fixed fee**، و**¥/USD rate** (50–500)، و**FX spread %** (0–20). قم بتحديث سعر الصرف ¥/USD بانتظام؛ حيث تحذر الصفحة عندما يكون أقدم من 7 أيام. ## التحقق {#verify} 1. في وضع الاختبار، سجّل الدخول إلى البوابة كعميل اختبار، وافتح **Billing**، وانقر على **Deposit**، واختر **Card** وقم بدفع الحد الأدنى باستخدام بطاقة اختبار Stripe `4242 4242 4242 4242` (أي تاريخ مستقبلي، وأي رمز CVC). 2. يرتفع الرصيد في غضون ثوانٍ ويظهر الدفع ضمن **Finance › Billing › Top-ups** بالحالة *Completed*. 3. افتح **Payment channels › Gateway events › Stripe**: يجب أن ترى `checkout.session.completed` أو `payment_intent.succeeded` مع وقت تمت معالجته. 4. بالعودة إلى صفحة Stripe، يكون حقل **24h events** أعلى من 0. قبل الإطلاق الفعلي، قم بتحويل **Mode** إلى `live`، والصق مفاتيح التشغيل الفعلي وانقر على **Create webhook** مرة أخرى (فإن ويب هوك وضعي الاختبار والتشغيل الفعلي منفصلان). ## الحدود والملاحظات {#limits-notes} - **المبالغ والعملات.** المحافظ بالدولار الأمريكي. تُخصم مدفوعات البطاقات والمحافظ والروابط بالدولار الأمريكي؛ بينما يُعرض Alipay للعميل بالين الياباني ويُحوَّل حسب سعرك. - **الرسوم.** لا يتم قراءة رسوم Stripe الفعلية تلقائياً؛ نسبة الرسوم التي تعينها تحدد ما يراه العميل وما يُضاف إلى المحافظ. اختر **Customer pays top-up fee** ضمن *Fees & limits* لتحميل الرسوم إضافياً. - **المرتجعات البطاقة.** عند تحديد العميل خيار *Save card for auto top-up*، تُحفظ البطاقة في Stripe وليس على خادرك. راجع [Saved payment methods](https://nexcmp.com/ar/docs/billing/saved-payment-methods/). - **الاستردادات.** الاسترداد إلى البطاقة هو عملية من خطوتين: ينشئ المسؤول طلب استرداد لدفعة مكتملة (**Finance › Billing › Top-ups**، إجراء الاسترداد على الدفعة) ثم يوافق عليه ضمن **Finance › Payouts › Card refunds** (`/billing/payouts`). استردادات Alipay غير متزامنة؛ والفاشلة منها (`refund.failed`) تعيد المبلغ المحتجز إلى المحافظ. - **النزاعات.** في حالة `charge.dispute.created` NexCMP، يقوم النظام بحظر حساب العميل، وإيقاف خدماته مدفوعة الأتاوة مسبقاً (دون حذف أي شيء) وإرسال تنبيه للمسؤول. إذا فزت بالنزاع (`charge.dispute.closed`)، يُعاد اعتماد المبلغ في المحافظ. - **المدفوعات المعلقة.** إذا لم يصل طلب Webhook أبدًا، يتحقق NexCMP من المدفوعات التي ظلت معلقة لأكثر من 10 دقائق مقابل Stripe من تلقاء نفسه ويقوم بإتمامها. يتم تجاهل المدفوعات الأقدم من 7 أيام. - يمكن لـ **Resellers** ربط حساب Stripe الخاص بهم (webhook `https:///v1/billing/stripe/webhook/r/`)؛ انظر [Resellers](https://nexcmp.com/ar/docs/customers/resellers/). ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | "يجب أن تبدأ المفتاح السري بـ sk_live_/sk_test_" | تم لصق مفتاح خاطئ | الصق المفتاح السري من **Developers › API keys**. | | "المفتاح السري لا يتطابق مع وضع البث المباشر/الاختبار" | وضع التشغيل والمفتاح غير متطابقين | اجعل **Mode** يطابق بادئة المفتاح. | | "يجب أن يبدأ المفتاح القابل للنشر بـ pk_" | مفتاح خاطئ | استخدم المفتاح القابل للنشر. | | يقول الفحص إن الاتصال فشل | مفتاح خاطئ، أو تم إلغاء المفتاح، أو لا يمكن للخادم الوصول إلى `api.stripe.com` | أعد لصق المفتاح؛ واختبره باستخدام `curl -I https://api.stripe.com` من الخادم. | | لافتة حمراء "Missing webhook_secret" | لم يتم حفظ سر التوقيع | انقر فوق **Create webhook** أو الصق سر `whsec_...` من لوحة تحكم Stripe وانقر فوق **Save**. | | تم خصم الأموال ولكن الرصيد لم يتغير | لم يتم تسليم Webhook أو فشل التوقيع | تحقق من أن عنوان URL ينتهي بـ `/v1/billing/stripe/webhook`، وأن السر يطابق نقطة النهاية، وأعد تشغيل الحدث في **Gateway events**. في Stripe، افتح نقطة النهاية وانظر في محاولات التسليم (HTTP 400 يعني وجود سر توقيع خاطئ). | | فشل "Create webhook" | عنوان URL ليس HTTPS أو لا يمكن الوصول إليه | استخدم نطاقك العام `https://`. | | حالة Apple Pay غير نشطة | النطاق غير مصادق عليه | انقر فوق **Register / verify domain** مرة أخرى بعد أن يستجيب ملف ربط النطاق برمز 200. | | Alipay غير متوفر في مربع حوار التحقق | غير مفعل في Stripe | قم بتفعيله في لوحة تحكم Stripe، ثم انقر فوق **Check**. | | لا يرى العميل نموذج البطاقة | **Card (Stripe)** معطل أو لا يوجد مفتاح سري | قم بتفعيله في **Fees & limits** واحفظ المفاتيح. | --- # PayPal > **المكان في لوحة التحكم:** Finance › Payment channels › PayPal (`/payments/paypal`). مفتاح التشغيل/الإيقاف والرسوم موجودة في Finance › Payment channels › Fees & limits (`/payments/fees`). ## الوظيفة {#what-it-does} يسمح للعملاء بشحن محفظتهم بالدولار الأمريكي باستخدام رصيد PayPal الخاص بهم أو حسابهم البنكي أو البطاقة المخزنة في PayPal. يمكن للعملاء أيضًا السماح لـ NexCMP بتذكر حساب PayPal الخاص بهم من أجل [automatic top-up](https://nexcmp.com/ar/docs/billing/auto-top-up/). استخدامه جنباً إلى جنب مع [Stripe](https://nexcmp.com/ar/docs/billing/stripe/) للعملاء الذين يفضلون PayPal. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | حساب PayPal | حساب **تجاري (Business)** على PayPal يمكنه استقبال الدولار الأمريكي. | | تطبيق REST | تطبيق REST واحد في لوحة تحكم مطوري PayPal (**Apps & Credentials**) يوفّر **Client ID** و **Client secret**. استخدم علامة التبويب **Sandbox** للاختبار، و **Live** للإنتاج. | | الشبكة | HTTPS يمكن الوصول إليه من الإنترنت (يستدعي PayPal خدمة webhook) ووصول صادر إلى `api-m.paypal.com` (مباشر) أو `api-m.sandbox.paypal.com` (تجريبي)، المنفذ 443. | | الأذونات | يحتاج تطبيق REST إلى صلاحيات استرداد الأموال و webhooks. يُظهر مربع حوار **Check** ما إذا كان كلا النطاقين موجودين. | | الاعتمادات | لا يوجد. | ## تجهيز البنية التحتية {#prepare-the-infrastructure} 1. قم بتسجيل الدخول إلى [developer.paypal.com](https://developer.paypal.com) باستخدام حساب الأعمال الخاص بك وافتح **Apps & Credentials**. 2. اختر **Sandbox** (للاختبار) أو **Live**، ثم **Create App**. قم بتسميته على سبيل المثال "NexCMP". 3. انسخ **Client ID** و **Secret** الخاصين بالتطبيق. 4. للاختبار، استخدم **Testing Tools › Sandbox Accounts** للعثور على حساب تجريبي *Personal* (مشتري) أو إنشاء حساب جديد. 5. لا تحتاج إلى إنشاء الويب هوك بنفسك؛ حيث ينشئه NexCMP باستخدام الزر **Create webhook**. ## الربط في NexCMP {#connect-in-nexcmp} 1. افتح **Finance › Payment channels › PayPal** (`/payments/paypal`). 2. في **API keys**، اختر **Mode**: `live` (أموال حقيقية، `api-m.paypal.com`) أو `sandbox` (`api-m.sandbox.paypal.com`). 3. الصق **Client ID** (ما لا يقل عن 20 حرفاً) و **Client secret**. 4. انقر فوق **Check**. تختبر هذه الوظيفة بيانات الاعتماد التي أدخلتها (الحفظ غير مطلوب) وتُبلغ عن الاتصال، ومعرف التطبيق، والوضع، وما إذا كانت نطاقات الاسترداد وويب هوك موجودة، ومدة صلاحية الرمز المميز. 5. انقر فوق **Save**. 6. في بطاقة **Webhook**، تأكد من أن عنوان URL هو `https:///v1/billing/paypal/webhook` (يجب أن يكون `https`)، ثم انقر فوق **Create webhook** وقم التأكيد. يطلب NexCMP من PayPal إنشاء أو تحديث الويب هوك بـ 11 حدثاً ويخزن **Webhook ID** المُعاد. يستخدم الزر المفاتيح **المحفوظة** — احفظ أولاً إذا قمت بتعديلها للتو. 7. انقر فوق **Check** مرة أخرى: يجب أن يُظهر صف **Webhook** "موجود، 11 حدثاً". 8. افتح **Fees & limits**، وقم بتفعيل **PayPal**، واضبط **PayPal fee %** (الافتراضي 4.4) و **PayPal fixed fee (cents)** (الافتراضي 30) لتعرفة الخاصة بك وانقر فوق **Save channels & fees**. ![صفحة PayPal مع وضع الحماية وبيانات الاعتماد التجريبية المُدخلة](https://nexcmp.com/ar/docs/images/billing/paypal-01-keys.webp) ### أحداث ويب هوك {#webhook-events} يسجل NexCMP هذه الأحداث الـ 11: `CHECKOUT.ORDER.APPROVED`، `PAYMENT.CAPTURE.COMPLETED`، `PAYMENT.CAPTURE.PENDING`، `PAYMENT.CAPTURE.DECLINED`، `PAYMENT.CAPTURE.REFUNDED`، `PAYMENT.CAPTURE.REVERSED`، `CUSTOMER.DISPUTE.CREATED`، `CUSTOMER.DISPUTE.UPDATED`، `CUSTOMER.DISPUTE.RESOLVED`، `RISK.DISPUTE.CREATED`، `CHECKOUT.PAYMENT-APPROVAL.REVERSED`. يتم التحقق من كل Webhook عن طريق استدعاء واجهة برمجة التطبيقات (API) الخاصة بالتحقق من التوقيع في PayPal، وتخزينها مرة واحدة ومعالجتها بشكل آمن. لا تثق NexCMP أبدًا في المبلغ الوارد في جسم Webhook: قبل تقييد أي عملية استلام، تقوم بجلب تفاصيلها مباشرة من PayPal. ## التحقق {#verify} 1. أبقِ **Mode** على `sandbox`. في البوابة، افتح **Billing › Deposit**، واختر **PayPal**، وانقر على **Continue on PayPal** (أو زر PayPal) وسجّل الدخول باستخدام حساب المشتري في sandbox. 2. وافق على الدفعة. ستعود إلى البوابة، ويزداد الرصيد وتظهر الدفعة ضمن **Finance › Billing › Top-ups** بالحالة *Completed*. 3. افتح **Payment channels › Gateway events › PayPal & USDT**: يتم سرد الحدث `PAYMENT.CAPTURE.COMPLETED`. 4. عندما يعمل كل شيء، قم بتحويل **Mode** إلى `live`، وأدخل بيانات الاعتماد الحية، و **Save**، ثم **Create webhook** مرة أخرى (ويب هوك وضع الحماية والوضع الحي منفصلان). ## الحدود والملاحظات {#limits-notes} - **كيف تتم الدفعة.** يتم إنشاء الطلب بالدولار الأمريكي؛ وبعد موافقة العميل عليه، يقوم **الخادم** بتحصيله (طلب بمعرف فريد لتجنب التكرار) وإضافة رصيد المحفظة مرة واحدة بالضبط. يُعد الويب هوك وظيفة مطابقة التسوية التي تعمل كل 10 دقائق شبكات أمان في حال أقام العميل بإغلاق المتصفح. - **الطلبات المعلقة والمهملة.** يمكن أن يظل الطلب مفتوحاً لمدة 12 ساعة. يمكن أن يكون لدى العميل 5 طلبات معلقة كحد أقصى (يستجيب الخادم بـ `too_many_pending`، HTTP 429). الطلب الذي لم يتم تحصيله بعد 24 ساعة يُعلم بأنه فاشل. - **لم يتم تكوين ويب هوك.** تُرجع لوحة التحكم HTTP 503 لكل ويب هوك خاص بـ PayPal حتى يتم حفظ معرف Webhook ID. التحصيلات التي تتم عبر البوابة وتسوية ال10 دقائق لا تزال تضيف رصيداً للمحفظة، ولكن لا يتم تطبيق أي شيء يبلغ عنه PayPal عبر الويب هوك (النزاعات، الاستردادات، التحصيلات المتأخرة) — انقر فوق **Create webhook**. - **حساب PayPal المحفوظ.** عندما يختار العميل حفظ PayPal (أو يُكمل أول إيداع، مما يؤدي إلى تفعيل [automatic top-up](https://nexcmp.com/ar/docs/billing/auto-top-up/)) يقوم PayPal بتخزين رمز الدفع في خزينة الأمان الخاصة به. يحتفظ NexCMP بمعرف فقط و بريد PayPal الإلكتروني. راجع [Saved payment methods](https://nexcmp.com/ar/docs/billing/saved-payment-methods/). - **Refunds and disputes** يتم التعامل معها مثل Stripe: يتم الموافقة على طلبات الاسترداد ضمن **Finance › Payouts › Card refunds**؛ النزاع يؤدي إلى حظر حساب العميل وإيقاف خدماته المدفوعة مسبقاً حتى تقوم بحله. - **Fees.** لا يتم قراءة رسوم PayPal تلقائياً؛ النسبة المئوية والرسوم الثابتة التي تقوم بإعدادها تحدد ما يراه العميل وما يتم إضافته لرصيده. التعريفة الحقيقية تعتمد على دولتك (النموذج يوضح 4.4 % لفيتنام و 3.49 % للولايات المتحدة). ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | "معرف العميل قصير جداً" | تم لصق أقل من 20 حرفاً | انسخ معرف العميل (Client ID) بالكامل. | | "يجب أن تبدأ رابط Webhook بـ https" | تم كتابة الرابط بـ `http://` | استخدم نطاقك العام `https://`. | | الفحص يُبلغ عن خطأ في الاتصال | وضع خاطئ (مفاتيح حية في بيئة التجربة أو العكس)، كلمة سر خاطئة، لا يوجد وصول للخارج | طابق **Mode** مع نوع المفتاح؛ اختبر `curl -I https://api-m.paypal.com` من الخادم. | | نطاق الاسترداد / الـ webhooks يُظهر "no" | تفتقر تطبيقات REST إلى هذه الميزات | قم بتفعيل الميزات على التطبيق في لوحة تحكم مطوري PayPal. | | لافتة "PayPal key set, NO webhook" | معرف الـ Webhook مفقود | انقر على **Create webhook**. | | "Webhook not found" في الفحص | تم حذف الـ Webhook في PayPal أو أنه ينتمي لتطبيق آخر | انقر على **Create webhook** مرة أخرى. | | يُقال للعميل أن PayPal رفض الدفع | رفض PayPal مصدر التمويل هذا | اطلب من العميل اختيار مصدر دفع آخر. | | العميل يرى "Too many pending requests" | 5 طلبات مفتوحة | انتظر حتى تنتهي صلاحيتها أو قم بإتمامها. | | زر PayPal مفقود | PayPal معطل في **Fees & limits** أو غير مُعَد | قم بتفعيله واحفظ بيانات الاعتماد. | --- # USDT (Binance) {#usdt-binance} > **أين في لوحة المشرف:** Finance › Payment channels › USDT (`/payments/usdt`). المفتاح والرسوم: Finance › Payment channels › Fees & limits (`/payments/fees`). الإيداعات غير المطابقة: Finance › Payment channels › Gateway events › PayPal & USDT (`/payments/events?tab=gateways`). ## الوظيفة {#what-it-does} يرسل العملاء USDT إلى **عنوان إيداع Binance الخاص بك**؛ تقرأ NexCMP سجل الإيداعات من خلال مفتاح API لـ Binance **للقراءة فقط** وتقوم بشحن المح عندما يتطابق الإيداع مع طلب مفتوح. لا توجد رسوم لمعالجة الدفع من جانبك بخلاف ما تفرضه Binance، ولا تحتفظ NexCMP بأي مفاتيح خاصة على الإطلاق. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | حساب Binance | حساب Binance مُحقق مع تفعيل إيداعات USDT على الشبكة التي تختارها. | | مفتاح API | مفتاح API لـ Binance مع خيار **Enable Reading** فقط. يجب أن يكون تفعيل عمليات السحب، النوال الداخلي، وتداول Spot/Margin في وضع **الإيقاف**. | | تقييد IP | يوصى بشدة: تقييد المفتاح على عنوان IP الصادر للخادم (يُظهره مربع الحوار **Test & verify address**). | | الشبكة | بروتوكول HTTPS الصادر إلى `api.binance.com`. لا حاجة لأي منفذ وارد. | | الشبكات المدعومة | `TRX` (Tron، TRC20)، `BSC` (BNB Smart Chain، BEP20)، `SOL` (Solana)، `ETH` (Ethereum، ERC20). العملة مثبتة على USDT. | | الاعتمادات | لا يوجد. | ::: warning اختر الشبكة مرة واحدة العملاء الذين يقومون بالتحويل على الشبكة الخطأ يفقدون أموالهم. اختر الشبكة ذات الرسوم المنخفضة التي تدعمها منصات تداول عملائك (عادة ما يتم اختيار TRX وBSC)، ولا تقم بتغييرها بشكل متكرر. ::: ## تجهيز البنية التحتية {#prepare-the-infrastructure} 1. في Binance، افتح **Account › API Management** وأنشئ مفتاح API جديداً (يتم إنشاؤه بواسطة النظام). امنحه تسمية مثل "NexCMP". 2. قم بتعديل الصلاحيات: اترك الخيار **Enable Reading** محددًا فقط. لا تقم بتفعيل عمليات السحب أو التحويلات أو التداول. 3. تحت قسم **Restrict access to trusted IPs only**، قم بإضافة عنوان IP العام لخادم NexCMP الخاص بك. إذا لم تكن تعرفه بعد، فأنشئ المفتاح بدون تقييد، ثم قم بتشغيل الاختبار الأول في NexCMP (سيقوم بعرض عنوان IP الصادر) وبعد ذلك أضف العنوان. 4. قم بنسخ **API key** و **Secret key** (يتم عرض المفتاح السري مرة واحدة فقط). 5. افتح **Wallet › Deposit › Crypto**، واختر **USDT** و **الشبكة** التي ستستخدمها، ثم انسخ **عنوان الإيداع** (على سبيل المثال عنوان يبدأ بـ `T...` على TRX أو `0x...` على BSC/ETH). ## الربط في NexCMP {#connect-in-nexcmp} 1. افتح **Finance › Payment channels › USDT** (`/payments/usdt`). 2. في حقل **API key (Binance › API Management)**، الصق **API key** بالإضافة إلى **مفتاح API السري (API secret)**. يجب إدخال كلاهما معاً. 3. في **Deposit address**، اختر **Network** والصق **عنوان إيداع USDT على الشبكة المحددة**. يتم التحقق من التنسيق مطابقةً مع الشبكة (`T` + 33 حرفاً لـ TRX، و `0x` + 40 حرفاً ست عشرياً لـ BSC و ETH، وتنسيق base58 لـ SOL). 4. انقر فوق **Save**. يؤدي تغيير العنوان أو الشبكة إلى إعادة تعيين التحقق وإيقاف القناة مؤقتاً حتى تقوم بالتحقق منها مرة أخرى؛ وستطلب منك الصفحة تأكيد ذلك. 5. انقر فوق **Test & verify address**. (يتم رفض التغييرات غير المحفوظة — حيث يتم إجراء التحقق على الإعدادات المحفوظة). يظهر في مربع الحوار: - صلاحيات المفتاح (القراءة، السحب، التحويل الداخلي، التداول، تقييد عنوان IP) — تحذيرات باللون الأحمر للصلاحيات الخطيرة؛ - عنوان IP الصادر الخاص بالخادم (لإدخاله في Binance)؛ - الشبكة (الإيداعات مفتوحة أو مغلقة، التأكيدات المطلوبة، المبالغ الضئيلة)؛ - العنوان الذي تصدره Binance لتلك الشبكة وما إذا كان **يتطابق** مع عنوانك. 6. عند تطابق العنوان، تسجل NexCMP وقت التحقق. وبعد ذلك فقط يمكنك فتح **Fees & limits**، وتفعيل **USDT (Binance)**، والتحقق من **USDT fee %** (الافتراضي هو 1) و **USDT request expires after (mins)** (5–180، الافتراضي 30)، ثم النقر فوق **Save channels & fees**. ## كيفية مطابقة المدفوعات {#how-a-payment-is-matched} 1. يدخل العميل مبلغاً في **Billing › Deposit › USDT** وينقر على **Get deposit address**. 2. ينشئ NexCMP طلباً ويعرض العنوان والشبكة و**مبلغاً دقيقاً** مع ستة منازل عشرية — على سبيل المثال `19.173742`. المنازل العشرية الأربعة الأخيرة هي رقم عشوائي (nonce) يجعل المبلغ فريداً لذلك الطلب. 3. يجب على العميل إرسال **المبلغ بالضبط** على تلك الشبكة. لا يمكن تعيين الدفعة التي لا تتطابق (مبلغ مقرب، شبكة خاطئة) تلقائياً. 4. كل 60 ثانية، يقرأ NexCMP آخر 24 ساعة من إيداعkات Binance. تؤدي الدفعة المتطابقة إلى نقل الطلب إلى حالة *confirming* (قيد التأكيد)، وبمجرد حصول Binance على التأكدات المطلوبة، يتم إيداع المبلغ في المحفظة. الطلب الذي يحتوي على أموال مرصودة لا ينتهي صلاحيته أبداً بينما تكون التأكيدات معلقة. 5. يُعلم الطلب الذي لم يُدفع خلال وقت انتهاء الصلاحية (الافتراضي 30 دقيقة) بأنه منتهي الصلاحية. ## التحقق {#verify} 1. بعد التحقق من العنوان وتشغيل USDT، قم بتسجيل الدخول كعميل تجريبي واطلب إيداعاً صغيراً (الحد الأدنى لعملية الشحن). 2. أرسل المبلغ المحدد من محفظة أو منصة تداول أخرى. انتظر بضع دقائق. 3. تعرض البوابة *Transfer seen — confirming*، ثم *USDT received — balance updated*. 4. تظهر صفحة USDT وقتاً حديثاً لـ **Last poll** وقيمة **Unmatched** عند 0. ## الحدود والملاحظات {#limits-notes} - **السعر.** 1 USDT يساوي 1.00 USD. تظهر الرسوم في **USDT fee %** للعميل، إما ليتم خصمها من المبلغ أو إضافتها إليه بناءً على خيار **Customer pays top-up fee**. - **بلا استرداد.** لا يقوم نظام NexCMP أبداً بإعادة مدفوعات USDT إلى المصدر (HTTP 409 `usdt_no_refund`). قم بالاسترداد يدويياً خارج النظام إذا لزم الأمر. - **حد الطلبات المعلقة.** لدى العميل عدد محدود من الطلبات المفتوحة؛ بعد تجاوز ذلك، يجيب الخادم بالرمز `too_many_pending` (HTTP 429). - يمكن لـ **Resellers** استخدام حساب Binance الخاص بهم؛ راجع قسم [Resellers](https://nexcmp.com/ar/docs/customers/resellers/). - **إذا كنت تشارك حساب Binance** مع نظام آخر، فمنح كل نظام شبكة مختلفة بحيث لا يرى مدققان نفس الإيداع أبداً. ### الإيداعات غير المطابقة {#unmatched-deposits} الإيداع الذي لا يطابق أي طلب (مبلغ خاطئ، شبكة خاطئة، طلب منتهي الصلاحية) ينشئ حدث `deposit.unmatched` وتنبيهًا للمسؤول. افتح **Payment channels › Gateway events › PayPal & USDT**، وابحث عن الحدث، وتحقق من المعاملة على Binance وانقر على إجراء التعيين لتقييد العميل الصحيح. ينخفض عداد **Unmatched** على صفحة USDT وعلى نظرة عامة على القنوات إلى 0 بعد ذلك. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | "يجب إدخال مفتاح API والرمز السري معاً" | تم تعبئة حقل واحد فقط | قم بتعبئة كلاهما. | | "العنوان ليس بالتنسيق الخاص بالشبكة ..." | العنوان لا يتطابق مع الشبكة المحددة | أعده نسخه من Binance لنفس الشبكة. | | "تغييرات غير محفوظة — احفظ أولاً ثم اختبر" | يتم تشغيل الاختبار على الإعدادات المحفوظة | انقر على **Save** ثم قم بالتجربة. | | تحذير "المفتاح يحتوي على تفعيل عمليات السحب (Enable Withdrawals)" | صلاحيات زائدة | قم بإزالتها من إدارة مفاتيح API في Binance. | | تحذير "المفتاح غير مقيد بعنوان IP" | `ipRestrict` متوقف | أضف عنوان IP الصادر للخادم الظاهر في نافذة الحوار. | | تحذير "المفتاح يفتقر إلى صلاحية القراءة (Enable Reading)" | الصلاحية مفقودة | قم بتفعيل القراءة (Enable Reading). | | تحذير "عطلت Binance الإيداعات لعملية USDT على الشبكة" | الشبكة معلقة | اختر شبكة أخرى أو انتظر. | | "خطر: العنوان المُكوّن يختلف عن العنوان الذي تصدره Binance" | عنوان أو شبكة خاطئة | انسخ العنوان مرة أخرى من Binance لتلك الشبكة. | | تم إلغاء تفعيل تبديل USDT في قسم الرسوم والحدود | العنوان غير محقق | قم بتشغيل **Test & verify address** حتى يتطابق. | | قام العميل بالدفع ولم يتم إضافة أي شيء | مبلغ مقرب أو شبكة خاطئة | ابحث عن الحدث في أحداث البوابة (Gateway events) وقم بتعيينه يدوياً. | | تمت رؤية الإيداع ولكن في انتظار طويل | لا توجد تأكيدات كافية بعد | انتظر؛ لا تنتهي صلاحية الطلب أثناء التأكيد. | --- # التحويل البنكي (فيتنام) {#bank-transfer-vietnam} > **أين في لوحة المسؤول:** Finance › Payment channels › VN bank transfer (`/payments/bank`). سعر الصرف: Finance › Payment channels › Exchange rates (`/payments/fx`). ## الوظيفة {#what-it-does} يتيح للعملاء شحن محفظة الدولار الأمريكي (USD) عبر تحويل بنكي عادي بالدونغ الفيتنامي. يعرض NexCMP رمز VietQR وتفاصيل الحساب و**رمز تحويل (transfer memo)** فريداً؛ يراقب [Sepay](https://sepay.vn) حسابك البنكي ويستدعي خطاف ويب (webhook) عند وصول الأموال، ليقوم NexCMP بعد ذلك بتقييد المبلغ في المحفظة. استخدم هذه الميزة إذا كنت تبيع للعملاء في فيتنام. ::: info يُعرض فقط في الواجهة الفيتنامية لا يُعرض خيار البنك الفيتنامي للعميل إلا عندما يتم عرض البوابة باللغة **Vietnamese**. فالعملاء الذين يستخدمون أي لغة أخرى لن يروه أبداً. ::: ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | الحساب البنكي | حساب بنكي فيتنامي (أو حساب افتراضي من Sepay، **VA**) متصل بحساب Sepay على [my.sepay.vn](https://my.sepay.vn). | | Sepay | حساب Sepay مع تفعيل تكامل خطاف الويب (webhook). | | سعر الصرف | يجب أن يتوفر سعر صرف بين الدولار الأمريكي والدونغ الفيتنامي: قم بتحديثه أولاً ضمن **Exchange rates**. بدون سعر الصرف، ستستجيب القناة بـ `fx_unavailable` ولن يتمكن العملاء من بدء عملية التحويل. | | الشبكة | يجب أن تكون لوحة التحكم الخاصة بك قابلة للوصول عبر بروتوكول HTTPS لكي يتمكن Sepay من استدعاء `https:///v1/billing/sepay/webhook`. | | الاعتمادات | [العملة أسعار الصرف](https://nexcmp.com/ar/docs/catalog/currency-and-exchange-rates/). | ## تجهيز البنية التحتية {#prepare-the-infrastructure} على جانب Sepay: 1. في موقع [my.sepay.vn](https://my.sepay.vn) قم بربط حسابك البنكي (أو أنشئ حساباً افتراضياً VA) وتأكد من ظهور المعاملات. 2. حدد **بادئة الرمز (memo prefix)** — من 2 إلى 5 أحرف لاتينية كبيرة، على سبيل المثال `PAY`. ينشئ NexCMP الرمز بحيث يتكون من البادئة متبوعة بـ 8 أرقام عشوائية (على سبيل المثال `PAY48210937`). يجب ألا تحتوي البادئة على `ORD`، ويجب عدم استخدامها من قبل أي نظام آخر يتلقى أموالاً في نفس الحساب. 3. إذا كان حساب Sepay الخاص بك يستخدم *هنية رمز الدفع (payment code structure)*، قم بتسجيل نفس البادئة هناك لكي يتعرف Sepay على الرمز. 4. أنشئ خطاف الويب (webhook) لاحقاً، بعد أن تمنحك صفحة NexCMP عنوان URL والمفتاح (الخطوة 7 أدناه). ## الربط في NexCMP {#connect-in-nexcmp} 1. افتح **Finance › Payment channels › Exchange rates** وانقر على **Update exchange rates** إذا لم يتم تخزين أي سعر صرف. 2. افتح **Finance › Payment channels › VN bank transfer** (`/payments/bank`). 3. في قسم **Receiving account** املأ ما يلي: | الحقل | مثال | القاعدة | |---|---|---| | البنك | `VCB` Vietcombank | اختر من القائمة؛ سيتم ملء رمز BIN تلقائياً. | | رقم الحساب | `0123456789` | 4–24 رقماً أو حرفاً لاتينياً كبيراً. | | الحساب الافتراضي (VA — اختياري) | | إذا تم تحديده، يقوم العملاء بالتحويل إلى الحساب الافتراضي ويظهر ذلك في رمز الاستجابة السريعة (QR). | | اسم صاحب الحساب | `NGUYEN VAN A` | بدون علامات تشكيل، أحرف لاتينية كبيرة UPPERCASE، من 2 إلى 60 حرفاً. | | بادئة رمز التحويل | `PAY` | 2–5 أحرف لاتينية كبيرة، بدون `ORD`. | 4. في قسم **Webhook authentication** اختر **Auth method**: **HMAC-SHA256** (موصى به) أو **API key**، وأدخل **Webhook key / HMAC secret** (من 8 إلى 200 حرف). اختياري، أدخل **userapi token** من Sepay؛ فهو يُستخدم فقط لتسوية التحويلات التي ضاع خطاف الويب الخاص بها. 5. في قسم **Channel & limits** اضبط الحدود (القيم الافتراضية بين قوسين): **Min / order** (10,000 VND)، **Max / order** (200,000,000 VND)، **Order expiry** (120 دقيقة، 15–1440)، **Max pending orders / account** (3، 1–10)، **Reconcile every** (10 دقائق)، واختيارياً، **Allowed webhook IPs** (مفصولة بفواصل؛ الفراغ يعني تسجيل عنوان IP فقط). 6. انقر فوق **Save**. تختفي لافتة التنبيه الحمراء "Sepay not configured" بمجرد أن تصبح بيانات الحساب والاسم والبادئة والمفتاح صحيحة. 7. انسخ **Webhook URL to paste into my.sepay.vn** (تظهر على شكل `https:///v1/billing/sepay/webhook`) باستخدام **Copy**. في Sepay، افتح تكامل webhook، والصق عنوان URL، واختر نفس نوع المصادقة والمفتاح، وفعّل حدث "money in". 8. انقر على **Test connection**. ثم قم بتفعيل **Enable Sepay for clients (main site)** وانقر على **Save**. ![صفحة التحويل المصرفي في فيتنام مع حساب الاستلام، وبادئة البيان، ومصادقة الويب هوك معبأة بقيم نموذجية](https://nexcmp.com/ar/docs/images/billing/bank-transfer-vn-01-config.webp) ![بطاقة القناة والحدود مع تفعيل مفتاح Sepay والحدود الافتراضية](https://nexcmp.com/ar/docs/images/billing/bank-transfer-vn-02-limits.webp) ### أمان الويب هوك {#webhook-security} | الطريقة | ما يجب أن يرسله Sepay | |---|---| | HMAC-SHA256 | الترويسة `X-SePay-Signature: sha256=`، المحسوبة عبر `"."`؛ قد تختلف الطابع الزمني بما لا يتجاوز 300 ثانية. | | مفتاح API | الترويسة `Authorization: Apikey `. | يتم التحقق من الترويسات فقط (وليس المتن أو نص الاستعلام أبداً) وتكون المقارنة في وقت ثابت. يتم استخدام الواردات فقط (`transferType = in`) للحساب أو الحساب الافتراضي (VA) المُكوَّن لديك. يتم تخزين كل معاملة Sepay مرة واحدة، لذا فإن طلب الويب هوك المُعاد لا يُقيد الرصيد مرتين أبداً. يجيب NexCMP بـ `200 {"success":true}` حتى عند تجاهل المعاملة عمداً، ويُرجع HTTP 5xx للأخطاء المؤقتة فقط لكي يقوم Sepay بإعادة المحاولة. ## كيف يدفع العميل {#how-the-customer-pays} 1. في **Billing › Deposit** (الواجهة الفيتنامية) يختار العميل خيار التحويل المصرفي الفيتنامي والمبلغ، ثم ينقر على زر إنشاء التحويل. 2. يقوم NexCMP بتحويل مبلغ الدولار الأمريكي بالسعر المخزّن (بما في ذلك الهامش وخطوة التقريب التي حددتها في **Exchange rates**) **ويقرب مبلغ الدونغ الفيتنامي للأعلى** إلى خطوة التقريب. 3. يرى العميل رمز الاستجابة السريعة (VietQR، يتم توليده محلياً) متضمناً رقم الحساب، والبنك، والمبلغ، وبيان التحويل. 4. بعد التحويل، يستدعي Sepay الويب هوك، ويقوم NexCMP بتقييد `floor(VND received × 100 / rate)` سنتاً. يتم تثبيت سعر الصرف عند إنشاء الطلب؛ وإذا وصلت الأموال بعد انتهاء صلاحية الطلب، يتم استخدام السعر الأعلى بين السعر المُثبّت والسعر الحالي. 5. تنتهي صلاحية الطلبات بعد **Order expiry**؛ وتعمل عملية المطابقة كل **Reconcile every** دقيقة كشبكة أمان (تتطلب رمز userapi). ## التحقق {#verify} 1. أنشئ طلباً تجريبياً كعميل على الواجهة الفيتنامية. وتأكد من أن المبلغ، والحساب، وبيان التحويل صحيحة. 2. قم بتحويل أصغر مبلغ مسموح به مع بيان التحويل الدقيق. 3. خلال دقيقة، تُظهر البوابة الإيداع كمكتمل ويرتفع رصيد المحفظة؛ وتُظهر بطاقة **State** في صفحة البنك وقت آخر ويب هوك. 4. افتح **Finance › Billing › Top-ups** وتأكد من إدراج الدفعة مع مبلغ الدونغ الفيتنامي المستلم. ## الحدود والملاحظات {#limits-notes} - **الحد الأدنى.** الحد الأدنى بالدونغ الفيتنامي الذي يراه العميل هو الأكبر بين **Min / order** والقيمة بالدونغ الفيتنامي لـ [minimum top-up](https://nexcmp.com/ar/docs/billing/minimum-top-up/). - **الطلبات المعلقة.** يمكن للعميل امتلاك **Max pending orders / account** من الطلبات المفتوحة كحد أقصى (الافتراضي 3). - **نفس بيان التحويل مرتين.** إجراء تحويل مرتين بنفس بيان التحويل ينشئ دفعة ثانية مكتملة بالسعر الحالي. - **لا يوجد استرداد تلقائي** إلى الحساب المصرفي. - **الرسوم.** لا تحتوي القناة على بند رسوم ثابتة في **Fees & limits**؛ ويعتبر هامش السعر هو التعديل الوحيد. - يمكن لـ **Resellers** تكوين حساباتهم الخاصة؛ وينتهي رابط الويب هوك الخاص بهم بـ `/v1/billing/sepay/webhook/r/`. ### التحويلات غير المطابقة {#unmatched-transfers} الأموال التي وصلت إلى الحساب ولكنها لا تحمل بيان تحويل صالح تظهر في **Unmatched transactions** في أسفل الصفحة (قم بالتصفية باستخدام *All channel owners* أو *Master*). تحقق من مرجع البنك مع العميل، ثم انقر على **Assign** وحدد الحساب. يتم إيداع المبلغ في المحفظة بالسعر الحالي. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | لافتة "Sepay not configured" | البنك، الحساب، اسم صاحب الحساب، البادئة، أو المفتاح مفقود أو غير صالح | أكمل بطاقتي **Receiving account** و **Webhook authentication**. | | لافتة "USD/VND rate blocked" (`fx_unavailable`) | لا يوجد سعر صرف مخزّن | من **Exchange rates › Update exchange rates**. | | `prefix: 2–5 capital letters, no ORD` | بادئة غير صالحة | استخدم 2–5 حروف كبيرة بدون `ORD`. | | خطأ `account_name` | علامات تشكيل أو حروف صغيرة | استخدم حروفاً كبيرة بدون علامات تشكيل، أو أرقاماً، أو مسافات، أو نقاط، أو شرطات. | | `webhook_secret: 8–200 characters` | المفتاح قصير جداً | استخدم 8 أحرف قابلة للطباعة على الأقل. | | العميل لا يرى الخيار | ليست بالواجهة الفيتنامية، أو الخيار معطل، أو لا توجد صسرة | تحقق من اللغة والمفتاح والصسرة. | | دفع العميل ولكن لم يتم إيداع أي شيء | لم يُستلم الويب هوك، أو تغيرت المذكرة، أو المبلغ خاطئ | تحقق من سجل الويب هوك الخاص بـ Sepay؛ ستكون النقلة ضمن **Unmatched transactions** إذا كانت المذكرة خاطئة. | | يُرجع الويب هوك 401 أو 403 | عدم تطابق طريقة المصادقة أو المفتاح | استخدم نفس الطريقة والمفتاح في Sepay وNexCMP. | | العميل يرى "Too many pending requests" | تم الوصول إلى حد الطلبات المعلقة | ينتهون أو ينتظرون انتهاء الصلاحية. | --- # الحد الأدنى للشحن {#minimum-top-up} > **أين في لوحة المشرف:** Finance › Payment channels › Fees & limits (`/payments/fees`)، بطاقة **Wallet & top-up (Billing › Policy)**. ## الوظيفة {#what-it-does} ترفض كل قناة دفع أي مبلغ يقل عن **الحد الأدنى للشحن** أو يزيد عن **الحد الأقصى للشحن لكل معاملة**. القيم الافتراضية هي **$10.00** و**$5,000.00**. استخدم الحد الأدنى لتجنب المدفوعات البسيطة التي تكلف رسوم بوابة أكثر مما تستحق. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | الدور | مسؤول. | | الاعتمادات | لا يوجد. | ## تعيين الحدود {#set-the-limits} 1. افتح **Finance › Payment channels › Fees & limits** (`/payments/fees`). 2. في بطاقة **Wallet & top-up (Billing › Policy)** قم بتعديل **Min top-up (USD)** و**Max top-up per transaction (USD)**. 3. انقر فوق **Save Wallet & top-up**. ![بطاقة المحفظة والشحن مع الحد الأدنى للشحن 10.00 والحد الأقصى 5000.00](https://nexcmp.com/ar/docs/images/billing/minimum-top-up-01-limits.webp) | الإعداد | القيمة الافتراضية | النطاق المسموح به | القاعدة | |---|---|---|---| | Min top-up (USD) | $10.00 | $0 إلى $10,000 | يجب أن يكون أقل من أو مساوياً للحد الأقصى. | | الحد الأقصى للشحن لكل معاملة (دولار أمريكي) | $5,000.00 | $1 إلى $1,000,000 | يجب أن يكون على الأقل الحد الأدنى. | يتم تخزين القيم بالسنت (`min_topup_cents`، `max_topup_cents`). ## أين تُطبق الحدود {#where-the-limits-apply} | المكان | السلوك | |---|---| | البطاقة، Apple/Google Pay، Link، Alipay، PayPal، USDT | تُرفض المبالغ خارج النطاق بواسطة الخادم. تُظهر البوابة "Enter an amount between {min} and {max}". | | تحويل بنكي فيتنامي | يجب أن يكون مبلغ VND داخل حدود Sepay **وقيمته** بـ USD (ما تتلقاه المحفظة) بين الحدين الأدنى والأقصى. تُظهر البوابة الحد الأدنى الأكبر لـ VND. راجع [Bank transfer (Vietnam)](https://nexcmp.com/ar/docs/billing/bank-transfer-vn/). | | [الشحن التلقائي](https://nexcmp.com/ar/docs/billing/auto-top-up/) | كل عملية خصم تلقائي تكون على الأقل بالحد الأدنى وعلى الأكثر بالحد الأقصى. في الوضع الثابت، يجب أن يكون مبلغ العميل بين الحد الأدنى و$1,000. | | رموز الشحن ([Vouchers](https://nexcmp.com/ar/docs/billing/promotions/)) | غير متأثر. | | رصيد / خصم المشرف | غير متأثر. | | شحن محفظة الموزع | حد أدنى مستقل (`rs_topup_min_cents`، الافتراضي $20) ضمن Resellers › Defaults. | ## الحدود المرتبطة {#related-floors} الحد الأدنى للشحن ليس قاعدة الرصيد الوحيدة. تجد هذه القواعد في **Services › Virtual Machines › Policy** (`/vm/policy`): | القاعدة | القيمة الافتراضية | المعنى | |---|---|---| | الحد الأدنى للرصيد (`min_balance_cents`) | $5.00 | أقل رصيد محفظة يحتاجه العميل لإنشاء جهاز افتراضي. | | الحصص | معطل | عند تفعيل **Quotas**، يتطلب إنشاء جهاز افتراضي أيضاً رصيداً يغطي عدداً معيناً من ساعات ذلك الجهاز. راجع [Quotas](https://nexcmp.com/ar/docs/billing/quotas/). | ## التحقق {#verify} 1. افتح **Billing › Deposit** في البوابة واكتب مبلغاً أقل بقليل من الحد الأدنى. سيتم إلغاء تفعيل زر الدفع وتظهر رسالة النطاق. 2. أدخل الحد الأدنى وأكد بدء عملية الدفع. ## الحدود والملاحظات {#limits-notes} - يسري أي تغيير على المدفوعات الجديدة. أما الطلبات المنشأة مسبقاً فتحتفظ بالمبالغ التي أنشئت بها. - تتبع التلميحات الموجهة للعملاء ("Minimum $10.00, maximum $5,000.00") وأزرار المبالغ السريعة الحدود الجديدة تلقائياً. - إذا كنت تعرض العملة VND (صفحة **Exchange rates**)، يتم تحويل الحد الأدنى بالسعر المخزن للعرض فقط؛ بينما تبقى المحفظة والحدود بالدولار الأمريكي. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | "يجب أن يكون الحد الأدنى للشحن أقل من أو يساوي الحد الأقصى" | قيم متداخلة | قم بتخفيض الحد الأدنى أو رفع الحد الأقصى. | | لا يمكن للعميل دفع مبلغ صغير عبر التحويل البنكي الفيتنامي | الحد الأدنى لـ Sepay VND أو الحد الأدنى بالدولار الأمريكي مرتفع | قم بتخفيض **Min / order** في صفحة البنك أو الحد الأدنى بالدولار الأمريكي. | | خطأ في الخادم `invalid_argument` أثناء عملية الشحن | المبلغ خارج النطاق | اطلب مبلغاً ضمن النطاق المعروض. | --- # طرق الدفع المحفوظة {#saved-payment-methods} > **Where in the portal:** Billing › Settings (`/billing?settings=1`). **Where in the admin:** Customers › List › a customer › Overview (`/customers/`)، بطاقة **Payment**، تعرض الطريقة المحفوظة وسجل الشحن التلقائي. ## الوظيفة {#what-it-does} تيح طريقة الدفع المحفوظة لـ NexCMP خصم الأموال من العميل **دون أن يكون حاضراً**، لكي لا تتوقف خدماته أبداً بسبب نفاد المحفظة. تُستخدم هذه الطريقة حصرياً بواسطة [الشحن التلقائي](https://nexcmp.com/ar/docs/billing/auto-top-up/). يوجد نوعان: **بطاقة** محفوظة لدى Stripe (بما في ذلك البطاقات المستخدمة عبر Apple Pay أو Google Pay أو Link عندما تُرجع Stripe بطاقة قابلة لإعادة الاستخدام) و**حساب PayPal** مخزن في خزنة PayPal. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | القنوات | إعداد وتفعيل [Stripe](https://nexcmp.com/ar/docs/billing/stripe/) و/أو [PayPal](https://nexcmp.com/ar/docs/billing/paypal/). | | الموقع | الموقع الرئيسي، أو موقع موزع تتم جباية قناة الدفع الخاصة به بواسطة المنصة. لا يمكن لموقع موزع يستخدم حساب Stripe الخاص به حفظ البطاقات. | | العميل | حساب عميل قام بعملية شحن باستخدام البطاقة أو PayPal. | ## كيفية حفظ طريقة الدفع {#how-a-method-gets-saved} 1. يفتح العميل **Billing**، وينقر فوق **Deposit** ويدفع باستخدام **Card** أو **PayPal**. 2. يتم إنشاء الدفعة بطريقة تسمح بإعادة استخدام الطريقة لاحقاً: تخزن Stripe البطاقة مع العميل لدى Stripe (للاستخدام خارج الجلسة)، بينما يخزن PayPal رمزا خزنيًا (vault token). تحتفظ NexCMP بالمراجع فقط (معرف طريقة الدفع ومعرف العميل في Stripe، أو معرف الخزنة في PayPal) وتسمية عرض مثل `visa •••• 4242` أو بريد PayPal الإلكتروني. **لا تلمس أرقام البطاقات خادمك أبداً.** 3. عند اكتمال الدفع، يتم تفعيل [التعبئة التلقائية](https://nexcmp.com/ar/docs/billing/auto-top-up/) لمرة واحدة إذا لم يقم العميل باختيار الإعدادات من قبل. لا توجد خانة اختيار إضافية أو رسالة على الشاشة. يسجل الخادم الوقت وعنوان IP الخاص بالعميل والطريقة كدليل. 4. في المرة القادمة، توفر شاشة الإيداع **Saved card ...** في القائمة المنسدلة للبطاقة، و **Saved PayPal ...** لـ PayPal. ## الإدارة والإزالة {#manage-and-remove} 1. في البوابة، انتقل إلى **Billing** وانقر على **Settings**. توضح اللوحة الطرق المحفوظة (بطاقة Stripe و/أو PayPal) وخيارات التعبئة التلقائية. 2. لإزالة بطاقة، انقر على **Remove card** وقم بالتأكيد. تقوم Stripe بفصل البطاقة **ويتم إيقاف تشغيل التعبئة التلقائية**. 3. لإزالة حساب PayPal، انقر على **Remove saved PayPal** وقم بالتأكيد. ### عرض المشرف {#admin-view} افتح العميل في **Customers › List**. تعرض بطاقة **Payment** في علامة التبويب **Overview** تسميات الطرق المحفوظة (**Saved cards**)، والبوابة المستخدمة للرسوم التلقائية، ودليل الموافقة المخزن (الوقت، عنوان IP، والطريقة)، بالإضافة إلى آخر 20 محاولة رسوم تلقائية مع حالتها والسبب (**Auto top-up history**). ## التحقق {#verify} 1. باعتبارك عميلاً للاختبار، قم بإيداع الحد الأدنى باستخدام البطاقة. بعد اكتمال الدفع، افتح **Billing › Settings**: ستكون البطاقة ومفتاح التعبئة التلقائية (في وضع التشغيل) مرئيين. 2. ابدأ عملية إيداع أخرى: توفر القائمة المنسدلة البطاقة المحفوظة. 3. في لوحة المشرف، تعرض بطاقة **Payment** الخاصة بالعميل نفس تسمية البطاقة. ## الحدود والملاحظات {#limits-notes} - **Stripe Link والمحافظ.** تعد Link وApple Pay وGoogle Pay ميزات خاصة بـ Stripe. لا تخزن NexCMP أي بيانات خاصة بـ Link؛ بل تحتفظ فقط بمرجع البطاقة الذي ترجعه Stripe. - **PayPal.** كل عملية تعبئة رصيد عبر PayPal يبدأها العميل تحتاج إلى نقرة؛ ويُستخدم حساب PayPal المحفوظ فقط بواسطة التعبئة التلقائية، ولا يُستخدم أبداً بواسطة ميزات أخرى. - **مواقع الموزعين.** إذا استخدم الموزع حساب Stripe أو PayPal الخاص به، يتم إخفاء الطرق المحفوظة وتكون التعبئة التلقائية غير متاحة لهذا الموقع. - **النزاعات.** يؤدي النزاع على أي عملية دفع إلى حظر الحساب وإيقاف خدماته مدفوعة الثمن مسبقاً؛ راجع [Stripe](https://nexcmp.com/ar/docs/billing/stripe/). - **إزالة الطريقة الأخيرة** تؤدي إلى إيقاف تشغيل التعبئة التلقائية؛ ويحتفظ العميل برصيد المحفظة. - **الدليل.** يتم تسجيل سجل الموافقة بواسطة الخادم (ولا يمكن للعميل تعديله) ويتم الاحتفاظ به لمعالجة النزاعات. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | لا يرى العميل زر الإعدادات أو البطاقة المحفوظة | يستخدم الموقع قناة دفع مملوكة لموزع، أو لم تتم أي عملية دفع بالبطاقة بعد | قم بإجراء إيداع عبر البطاقة أو PayPal من خلال قناة المنصة. | | اختفاء "Saved card" بعد عملية دفع عبر Stripe | تمت عملية الدفع باستخدام طريقة لا يمكن إعادة استخدامها (مثل Alipay على سبيل المثال) | ادفع مرة أخرى باستخدام البطاقة. | | PayPal: "لا يمكن حفظ هذا الحساب الان" | لم يُرجِع PayPal رمز خزنة (vault token) | تابع الدفع لمرة واحدة، أو جرب حساب PayPal آخر. | | توقفت التعبئة التلقائية بعد إزالة البطاقة | المتوقع: إزالة البطاقة تؤدي إلى تعطيلها | احفظ طريقة جديدة مع عملية الإيداع التالية. | --- # التعبئة التلقائية {#auto-top-up} > **المسار في لوحة الإدارة:** Finance › Payment channels › Fees & limits (`/payments/fees`)، البطاقة **Wallet & top-up (Billing › Policy)**، القسم **Auto top-up (Stripe / PayPal)**. **المسار في البوابة:** Billing › Settings (`/billing?settings=1`). ## الوظيفة {#what-it-does} عندما ينخفض رصيد محفظة العميل بشكل كبير، يقوم NexCMP بخصم المبلغ من [طريقة الدفع المحفوظة](https://nexcmp.com/ar/docs/billing/saved-payment-methods/) الخاصة به وشحن المحفظة، حتى لا تُعلق الخدمات قيد التشغيل بسبب نقص الأموال. تفحص مهمة في الخلفية جميع العملاء المفعلين **كل 5 دقائق**. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | القناة | تكوين [Stripe](https://nexcmp.com/ar/docs/billing/stripe/) و/أو [PayPal](https://nexcmp.com/ar/docs/billing/paypal/). | | Saved method | يمتلك العميل بطاقة محفوظة أو حساب PayPal. | | الموقع | الموقع الرئيسي، أو موقع الموزع الذي تُجمع قناة Stripe/PayPal الخاصة به بواسطة المنصة. | | Global switch | **Auto top-up enabled** قيد التشغيل (افتراضياً قيد التشغيل). | ## How it works {#how-it-works} بعد **أول عملية شحن عبر Stripe أو PayPal** للعميل، يحفظ الخادم طريقة الدفع ويفعل الشحن التلقائي في وضع **By usage** — فقط إذا لم يقم هذا العميل بضبط الشحن التلقائي بنفسه أبداً. لا يوجد مربع اختيار إضافي على شاشة الإيداع؛ يسجل الخادم الوقت وعنوان IP والطريقة كدليل. إذا أوقف العميل الشحن التلقائي لاحقاً، فلن يتم تشغيله تلقائياً مرة أخرى أبداً. | Mode | المشغل (عندما يكون الرصيد أقل من ...) | Amount charged | |---|---|---| | **By usage** (افتراضياً بعد الشحن الأول) | تكلفة الساعات الـ 24 القادمة للخدمات قيد التشغيل (الخوادم الافتراضية بالساعة مضافاً إليها التجديدات المدفوعة مقدماً المستحقة خلال 24 ساعة)، ولكن أبداً أقل من **$5** | تكلفة الـ 24 ساعة مقربة لأعلى إلى دولار صحيح، على الأقل [الحد الأدنى للشحن](https://nexcmp.com/ar/docs/billing/minimum-top-up/)، وعلى الأكثر الحد الأقصى للشحن والحد الأقصى اليومي | | **Fixed amount** | عتبة العميل الخاصة (من $1 إلى $500) | مبلغ العميل الخاص (من الحد الأدنى للشحن إلى $1,000، وأكبر من العتبة) | مع عدم وجود خدمة قيد التشغيل في وضع **By usage**، لا يتم خصم أي شيء. الرصيد مقارنة بالعتبة هو **المال الحقيقي في المحفظة**. تُحفظ رصيدات الخدمات من رموز العروض الترويجية بشكل منفصل ولا تُحتسب (انظر [Promotions](https://nexcmp.com/ar/docs/billing/promotions/)). يتم التعامل مع الرسوم مثل الشحن العادي: مع تفعيل **Customer pays top-up fee**، يتم خصم المبلغ مضافاً إليه الرسوم من البطاقة وتحصل المحفظة على المبلغ كاملاً؛ ومع إيقافها، تحصل المحفظة على المبلغ مطروحاً منه الرسوم. ## تكوين الحدود العامة {#configure-the-global-limits} 1. افتح **Finance › Payment channels › Fees & limits** (`/payments/fees`). 2. في **Auto top-up (Stripe / PayPal)**، قم بتعيين: | الإعداد | القيمة الافتراضية | النطاق | المعنى | |---|---|---|---| | Auto top-up enabled | On | on or off | إيقاف يوقف كل رسوم الخلفية فوراً. | | الحد الافتراضي للتعبئة التلقائية (بالدولار الأمريكي، الوضع الثابت الاحتياطي) | $5.00 | $0 إلى $10,000 | يُستخدم فقط كحد بدء في الوضع الثابت. | | الحد الأقصى للتعبئات التلقائية لكل 24 ساعة لكل عميل | 3 | 1 to 50 | يحسب المحاولات الناجحة والمعلقة. | | سقف مبلغ التعبئة التلقائية لكل 24 ساعة لكل عميل (بالدولار الأمريكي) | $500.00 | $0 to $1,000,000 | إجمالي الرسوم التلقائية في يوم متداول. | 3. انقر فوق **Save Wallet & top-up**. ![قسم التعبئة التلقائية في صفحة الرسوم والحدود مع المفتاح العام والحدود اليومية](https://nexcmp.com/ar/docs/images/billing/auto-top-up-01-limits.webp) ## ما يراه العميل {#what-the-customer-sees} 1. في البوابة، يفتح العميل **Billing** وينقر فوق **Settings**. 2. تعرض لوحة التحكم الطريقة (الطرق) المحفوظة، ومفتاح التشغيل/الإيقاف، والوضع (**By usage** أو **Fixed amount**)، والاستخدام الحالي المقدر والرسوم التالية، و**Recent automatic top-ups**. 3. التبديل إلى **Fixed amount** يتيح لهم إدخال الحد والمبلغ. إيقاف المفتاح يؤدي إلى وقف الرسوم. ![إعدادات الفواتير للعملاء مع التعبئة التلقائية في وضع حسب الاستخدام وعمليات التعبئة التلقائية الأخيرة](https://nexcmp.com/ar/docs/images/billing/auto-top-up-02-portal.webp) ## التحقق {#verify} 1. باعتبارك عميلاً تجريبياً، قم بإجراء أول عملية تعبئة بطاقة اختبار ([Stripe](https://nexcmp.com/ar/docs/billing/stripe/#verify)). افتح **Billing › Settings**: التعبئة التلقائية مفعلة. 2. قم بتشغيل جهاز افتراضي صغير ليكون هناك استخدام، واجعل الرصيد ينخفض دون الحد الأدنى (على سبيل المثال عبر **Customers › customer › Credit / debit**). 3. في غضون 5 دقائق تقريباً، يتم تنفيذ خصم. في بطاقة **Overview › Payment** الخاصة بالعميل، يوضح **Auto top-up history** المحاولة بحالة *Done*، ويتم إرسال إشعار *Top-up received*. ## الحدود والملاحظات {#limits-notes} - **خصم واحد لكل انخفاض.** بعد الخصم، تنتظر المهمة حتى يرتفع الرصيد مجدداً فوق الحد الأدنى أو ينتهي وقت الانتظار: 1 ساعة بعد العملية الناجحة، و24 ساعة بعد عملية معلقة، و30 دقيقة بعد خطأ في النظام. - **الحدود اليومية.** عند الوصول إلى أي من الحدين اليوميين، لا يتم إجراء أي خصم وتتم كتابة سطر *Daily limit reached* (مرة واحدة على الأكثر كل 6 ساعات). - **حالات الفشل.** تُعد البطاقة المرفوضة أو منتهية الصلاحية أو عدم كفاية الرصيد بمثابة فشل للبطاقة. تعيد المهمة المحاولة بعد 1 ساعة، ثم بعد 6 ساعات، ثم بعد 24 ساعة. **بعد 3 حالات فشل متتالية للبطاقة يتم إيقاف auto top-up** وإشعار العميل (*Auto top-up failed*). لا تُحتسب الدفعة التي تتطلب تأكيد العميل (على سبيل المثال 3-D Secure) كحالة فشل؛ بل يُطلب من العميل تأكيدها. - **لا توجد رسوم مزدوجة.** يتم طلب كل خصم بشكل ذرات لكل انخفاض تحت الحد الأدنى ويستخدم مفتاح تماثل في بوابة الدفع. - **إزالة البطاقة** تؤدي إلى إيقاف تشغيل التعبئة التلقائية. - **الموزعون.** إذا استخدم الموزع قناة الدفع الخاصة به، فلا يمكن للعميل تفعيل التعبئة التلقائية (HTTP 403 `feature_disabled`). ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | لا يمكن للعميل تشغيلها: "شحن مرة واحدة ببطاقة أو PayPal" | لا توجد طريقة محفوظة | قم بإجراء عملية شحن واحدة للبطاقة أو PayPal أولاً. | | خطأ `no_card` (422) | بوابة الدفع المختارة ليس لها طريقة محفوظة | اختر بوابة الدفع التي تحتوي على واحدة، أو احفظ طريقة. | | خطأ `invalid_argument` في المبلغ | الوضع الثابت خارج النطاقات المسموحة | الحد الأدنى $1 إلى $500، المبلغ بين الحد الأدنى للشحن و$1,000، والمبلغ أكبر من الحد الأدنى. | | لا يتم خصم أي شيء على الرغم من انخفاض الرصيد | المفتاح العام مغلق، لا توجد خدمة قيد التشغيل في وضع حسب الاستخدام، تم الوصول إلى الحد اليومي، أو الخصم السابق لا يزال قيد الانتظار | تحقق من المفتاح والسجل والحدود. | | "N محاولات فاشلة متتالية — تتوقف التعبئة التلقائية بعد 3 محاولات" | البطاقة تستمر في الفشل | يستبدل العميل البطاقة بإيداع جديد. | | الحالة *Needs your confirmation* | البنك يتطلب المصادقة 3-D Secure | يكمل العميل عملية الشحن العادية مرة واحدة. | --- # الفواتير دفتر الأستاذ {#invoices-and-ledger} > **أين في لوحة التحكم:** Finance › Billing (`/billing`) مع تبويبات Overview و Transactions (`/billing/ledger`) و Invoices (`/billing/invoices`) و Top-ups (`/billing/deposits`) و Payouts (`/billing/payouts`) و Vouchers (`/billing/vouchers`) و Reports (`/billing/reports`). **أين في بوابة العملاء:** Billing (`/billing`). ## الوظيفة {#what-it-does} يتم تخزين كل مبلغ في NexCMP كسنتاً بالدولار الأمريكي وتسجيله مرة واحدة. الفكرة الأساسية: **دفتر أستاذ المحفظة** هو مصدر الحقيقة للأرصدة؛ الفواتير ومدفوعات الشحن والتقارير هي عروض مبنية عليه. دفتر الأستاذ **يقتصر على الإضافة فقط** — يتم إصلاح الخطأ إضافة قيد عكسي، وليس عن طريق تعديل السجل أبداً. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | الدور | مسؤول. | | تفاصيل البائع | قم بتعيين الاسم القانوني، الرقم الضريبي، العنوان، بريد الاتصال و بادئة رقم الفاتورة في **System › Settings › General**، علامة التبويب **Seller & invoicing** (`/settings?tab=seller`)، بطاقة **Seller details (printed on invoices)**. | | الاعتمادات | [Payment channels](https://nexcmp.com/ar/docs/billing/payment-channels/) للأموال الواردة. | ## الأجزاء {#the-pieces} | علامة تبويب المشرف | ما تعرضه | الاستخدام النموذجي | |---|---|---| | **Overview** | الإيرادات اليوم وهذا الشهر، إجماليات دفتر الأستاذ حسب النوع (إيداع، رسوم، استرداد، تعديل، قسيمة)، الفواتير حسب الحالة، المبالغ المستردة المعلقة، الاختصارات، الإنفاق لكل خدمة في آخر 30 يوماً | فحص يومي | | **Transactions** | دفتر أستاذ المحفظة، سطر واحد لكل حركة | توضيح رصيد العميل | | **Invoices** | الفواتير، وعرض ثانٍ **Orders** مع كل عملية شراء لكل خدمة | البحث عن مستند، إعادة إرسال، تعيين كمدفوع | | **Top-ups** | المدفوعات المستلمة عبر البوابات | التحقق من الدفع واسترداده | | **Payouts** | استرداد البطاقات، مدفوعات الشركاء التابعين، مسحوبات الموزعين | الموافقة على الأموال الصادرة | | **Vouchers** | رموز الشحن | راجع [Promotions](https://nexcmp.com/ar/docs/billing/promotions/) | | **Reports** | الإيرادات، حسب الخدمة، حسب الموزع | المحاسبة | ### Transactions (ledger) {#transactions-ledger} الأعمدة: الوقت، العميل، **النوع**، الخدمة، المبلغ (موقع)، الجهاز الظاهري (VM)، المرجع، الفاعل، الملاحظة. المرشحات: النوع، الخدمة، معرف العميل، الموقع (عندما يكون لديك موزعون)، نطاق التاريخ، ورابط الجهاز الظاهري (VM). | النوع | المعنى | |---|---| | `deposit` | شحن من بوابة | | `charge` | الأموال المأخوذة مقابل خدمة (طلب، تجديد، استخدام بالساعة ...) | | `refund` | الأموال المعادة إلى المحفظة | | `adjust` | رصيد دائن أو مدين من المسؤول، وأيضاً رموز الشحن (المرجع يبدأ بـ `vch:`) — تعرض النظرة العامة القسائم كسطر خاص بها | كل صف له مرجع مثل `dep:stripe:`؛ ولا يمكن كتابة نفس المرجع مرتين أبداً، ولهذا السبب لا يمكن لخطأ الويب المتكرر (webhook) أن يمنح رصيداً مرتين. استخدم **Customers › List › customer › Credit / debit** لإضافة تعديل يدوي: السبب إلزامي، والمبلغ الموجب يحاول أيضاً إلغاء قفل الأجهزة الظاهرية (VMs) المقفلة لعدم وجود رصيد، ويتم تأكيد الإجراء في خطوتين. ![علام تبويب المعاملات تعرض صفوف دفتر الأستاذ للمحفظة مع النوع والخدمة والمبلغ والمرجع](https://nexcmp.com/ar/docs/images/billing/invoices-and-ledger-01-ledger.webp) ### Invoices {#invoices} يتم إنشاء الفاتورة تلقائياً عندما يقوم العميل بشراء أو تجديد شيء مدفوع من المحفظة، أو مقابل عملية شحن. تبدو الأرقام مثل `-<000001>` (على سبيل المثال `NX202610-000042`)؛ تستخدم مواقع الموزعين بادئة وتسلسلاً خاصين بها. لا تتغير الأرقام الموجودة أبداً عند تغيير البادئة. | الحقل | القيم | |---|---| | النوع | إيصال، تجديد، شحن، يدوي، استرداد | | Status | غير مدفوع، مدفوع، متأخر، ملغى، مسترد | الإجراءات على الصف: | الإجراء | التأثير | |---|---| | **View** / **Print** | يفتح الفاتورة؛ ويمكن للبوابة أيضاً طباعتها أو حفظها كملف PDF. | | **Mark paid** (غير مدفوع أو متأخر فقط) | يتم وضع علامة مدفوع **دون نقل أموال المحفظة** — يُستخدم عندما يدفع لك العميل خارج NexCMP. السبب مطلوب. بالنسبة لفاتورة التجديد، فإنها تمدد أيضاً الجهاز الوهمي المقفل وتلغي قفله. | | **إلغاء** (للغير مدفوعة أو المتأخرة فقط) | يلغي الفاتورة. السبب مطلوب. | | **إعادة إرسال** | يرسل الفاتورة بالبريد الإلكتروني مرة أخرى. | **إنشاء فاتورة يدوية** (زر في أعلى علامة التبويب): معرف العميل، من 1 إلى 50 بنداً (الوصف، الكمية، سعر الوحدة)، معرف الجهاز الوهمي الاختياري، أيام الاستحقاق الاختيارية (من 0 إلى 365، الافتراضي 7)، ملاحظة اختيارية. يتم إنشاؤها كغير مدفوعة؛ ويراها العميل في **Billing › Invoice History**. تُسدَّد فواتير الخدمات غير المدفوعة **تلقائياً من المحفظة** بمجرد توفر الأموال، لذا فإن إجراء العميل يقتصر ببساطة على إضافة رصيد. ### عمليات شحن الرصيد (المدفوعات) {#top-ups-payments} سطر واحد لكل محاولة: الوقت، العميل، **بوابة الدفع والطريقة**، النوع (شحن رصيد أو شحن تلقائي)، الحالة (معلقة، مكتملة، فاشلة، مستردة، متنازع عليها، ملغاة)، ما دفعه العميل، الرسوم، ما ذهب إلى المحفظة، مرجع البوابة ووقت الإكمال. تتمتع مدفوعات Stripe وPayPal المكتملة بإجراء **استرداد الأموال** (Refund). استخدم صفحات أحداث البوابة لمعرض شبكات الويب (webhooks) ([Payment channels](https://nexcmp.com/ar/docs/billing/payment-channels/)). ### عمليات الدفع والصرف {#payouts} ثلاث علامات تبويب فرعية: **استرداد البطاقات** (الموافقة على طلبات الاسترداد أو رفضها؛ يتم إنشاء الطلب من عملية دفع مكتملة)، **مدفوعات الشركاء التابعين** (سحب العمولات) و**مسحوبات الموزعين**. يتم تدقيق كل قرار. ### التقارير {#reports} **الإيرادات** (اتجاه 30 يوماً، شهراً بعد شهر، كبار العملاء)، **حسب الخدمة** و**حسب الموزع**. ![علامة تبويب التقارير التي تعرض مؤشرات الأداء الرئيسية للإيرادات واتجاه الثلاثين يوماً](https://nexcmp.com/ar/docs/images/billing/invoices-and-ledger-03-reports.webp) ## ما يراه العميل {#what-the-customer-sees} في **Billing**، يمتلك العميل **Balance**، و**Deposit**، و**Redeem code**، و**Settings** (الشحن التلقائي) وسجلًا يحتوي على علامات التبويب **Invoice History**، و**Payment Order**، و**Ledger**، و**Orders** (كل خدمة في قائمة واحدة مع عوامل تصفية حسب الخدمة والنوع). تحتوي كل فاتورة على **View**، و**Print**، و**Save as PDF**؛ المبالغ بالدولار الأمريكي، وتُعرض اختياريًّا بعملة العرض. ## التحقق {#verify} 1. قم بإجراء عملية شحن رصيد صغيرة كعميل اختبار. 2. **Transactions** يوضح `deposit` السطر، ويظهر **Top-ups** الدفع كـ *Completed*، وتزداد إيرادات **Overview**. 3. قم بشراء شيء ما: يظهر `charge` سطر، وتعرض **Invoices** فاتورة *Receipt* أو *Renewal* مع تفاصيل البائع التي قمت بتكوينها. ## الحدود والملاحظات {#limits-notes} - **الإضافة فقط.** لا توجد طريقة لتعديل أو حذف سطر دفتر الأستاذ؛ أضف تسوية مع ذكر السبب. - **العملة.** المبالغ بالدولار الأمريكي؛ عملة العرض تجميلية (انظر [Currency and exchange rates](https://nexcmp.com/ar/docs/catalog/currency-and-exchange-rates/)). - **الاسترداد إلى البطاقة** يتم على خطوتين (طلب، ثم موافقة ضمن عمليات الدفع والصرف)؛ ولا يتم استرداد عملات USDT والتحويلات المصرفية إلى المصدر. - **كل شيء خاضع للتدقيق** ضمن System › Logs › Admin actions مع السبب الذي أدخلته. - **الطلبات مقابل الفواتير.** لا يتم فوترة الاستخدام بالساعة لكل ساعة؛ تقوم طريقة عرض الطلبات بتجميعه حسب اليوم لكي تتمكن من رؤيته على أي حال. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | رصيد العميل يبدو غير صحيح | رسوم أو تسوية أو قسيمة لم تكن تتوقعها | قم بتصفية **Transactions** حسب معرف العميل واقرأ المراجع والملاحظات. | | "الفاتورة مدفوعة بالفعل" (409) | وضع علامة مدفوع على فاتورة مدفوعة بالأصل | لا شيء للقيام به. | | تعذر إلغاء الفاتورة | يمكن إلغاء الفواتير غير المدفوعة أو المتأخرة فقط | بالنسبة للفواتير المدفوعة، استخدم استرداد الأموال أو التسوية. | | تفاصيل البائع مفقودة على الفواتير | لم يتم تعبئتها | أكمل **Seller details** في System › Settings › General › Seller & invoicing. | | تم رفض بطاقة الائتمان / الخصم | المبلغ صفر أو يزيد عن $100,000 | استخدم مبلغاً يتراوح بين 1 سنت و $100,000. | | تظل حالة الدفع *Pending* لفترة طويلة | Webhook مفقود | راجع **Gateway events** وقدم إعادة تشغيل. | --- # العروض الترويجية {#promotions} > **أين في لوحة المشرف:** Finance › Billing › Vouchers (`/billing/vouchers`). **أين في البوابة:** Billing › Redeem code (أيضاً داخل درج الإيداع). ## الوظيفة {#what-it-does} **رمز تعبئة الرصيد** (القسيمة) هو رمز سري يُستخدم مرة واحدة ويُمنح للعملاء. وحسب طريقة إنشائه، يمكنه: | النوع | ما يحصل عليه العميل | أين تُضاف القيمة | |---|---|---| | **Bonus credit** لجميع الخدمات | أموال تضاف إلى المحفظة | رصيد المحفظة. قابل للاستخدام في أي شيء. | | **Bonus credit** للخدمات المحددة | رصيد خدمة | جيب منفصل لا يُستخدَم إلا لدفع ثمن تلك الخدمات. | | **Discount %** | نسبة خصم على الطلب الأول للخدمات المحددة | لا يتم إضافة رصيد؛ ويُطبق الخصم عند الدفع. | استخدمها للحملات الترويجية، أو أرصدة الاعتذار، أو صفقات الشركاء، أو خصم الطلب الأول. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | الدور | مسؤول. | | العملاء | يسترد العملاء الرموز أثناء تسجيل الدخول إلى البوابة (وليس كزوار). بشكل افتراضي، يجب أن يكون لدى العميل بريد إلكتروني مُتحقّق منه. | | رموز VND | الرمز الذي يتم إنشاؤه بـ VND يُحوَّل إلى USD عند الاسترداد باستخدام سعر الصرف المُخزَّن (راجع [Currency and exchange rates](https://nexcmp.com/ar/docs/catalog/currency-and-exchange-rates/)). | ## إنشاء دفعة {#create-a-batch} 1. افتح **Finance › Billing › Vouchers** وانقر على **Create vouchers**. 2. املأ النموذج. توجد أمثلة القيم بين قوسين. | الحقل | ملاحظات | |---|---| | اسم الدفعة | 1-80 حرفاً (`Spring welcome`). | | الهدف | **Main site clients**، **Single reseller's customers** (يتطلب قائمة بالعملاء) أو **Reseller wallet**. | | المستخدمون المؤهلون | **All in target audience** أو **Specified** — بريد إلكتروني واحد أو معرف عميل واحد في كل سطر، حتى 1,000. بالنسبة لعملاء الموزع، يجب أن يكون الخيار *Specified*. | | 1 رمز لكل هدف | مع الخيار *Specified*، يتم إنشاء رمز واحد لكل عميل مدرج. | | نوع الرمز | **Bonus credit** أو **Discount %**. | | ينطبق على | اختر خدمة واحدة أو أكثر؛ الحقل الفارغ يعني **All services**. | | العملة، القيمة الاسمية | USD ابتداءً من $1.00، أو VND ابتداءً من 10,000 بمضاعفات 1,000 (مكافأة الرصيد فقط). | | الخصم (%) | 1 إلى 100 (نسبة الخصم % فقط). | | الحد الأقصى لسقف الخصم (USD) | مطلوب لنسبة الخصم %، بدءاً من $1.00. وهو أيضاً الحد الأقصى لما يمكنك خسارته لكل عملية استرداد. | | الحد الأدنى للطلب (USD) | `0` = بلا. يجب ألا يقل الطلب الأول عن هذا المبلغ. | | عدد الرموز | من 1 إلى 1,000 رمز عشوائي. | | مرات الاستخدام لكل رمز | من 1 إلى 100,000. `1` تعني شخصاً واحداً لكل رمز؛ قم بزيادتها لرمز مشترك. | | الحد الأقصى للاستخدامات لكل حساب | 1 على الأقل. بالنسبة لنسبة الخصم % يجب أن يكون `1`. | | وقت البدء (اختياري)، تاريخ الانتهاء | يجب أن يكون تاريخ انتهاء الصلاحية بعد اليوم وبعد تاريخ البداية، وبحد أقصى 2 سنة في المستقبل. | | بادئة الرمز (0–6 أحرف) | أحرف فقط؛ الحترك الفارغ يستخدم بادئة الموقع. | | رمز مخصص (فقط عندما يكون العدد = 1) | من 6 إلى 32 حرفاً A–Z و0–9. سهلة المشاركة ولكنها سهلة التخمين: اجعل عدد الاستخدامات منخفضاً. | | يتطلب بريداً إلكترونياً متحققاً منه | مفعل افتراضياً. | | ملاحظة داخلية، السبب | السبب إلزامي ويتم تسجيله في سجل التدقيق. | 3. يعرض النموذج **التعرض الأقصى** (القيمة الاسمية × الرموز × الاستخدامات) لكي تدرك أسوأ سيناريو محتمل. انقر على **Generate codes**. 4. **انسخ الرموز الآن.** يتم عرضها مرة واحدة فقط: يخزن NexCMP الرمز المشفر (hash) وآخر 4 أحرف فقط. استخدم **Copy all** أو **Download CSV**، وحدد مربع التأكيد ثم أغلق النافذة. ## كيفية عمل كل نوع {#how-each-type-behaves} ### مكافأة المحفظة (بدون تحديد خدمة) {#wallet-bonus-no-service-selected} يتم إيداع رصيد في المحفظة كعملية **تعديل** (المرجع `vch:...`). وهو غير قابل للاسترداد بطاقة، ولا يربح عمولة إحالة، ولا ينشئ فاتورة، ويُحتسب كرصيد محفظة للأحصاص (quotas). تستخدم رموز VND سعر الصرف لحظة الاسترداد. ### رصيد الخدمة (الخدمات المحددة) {#service-credit-services-selected} - يستقر الرصيد في **جيب منفصل**، ويمكنه دفع رسوم الخدمات المختارة فقط (الطلبات الجديدة، التجديدات، الرسوم بالساعة أو اليومية، الترقيات) ويُصرف **قبل** المحفظة. - لا يمكن سحبه أو تحويله أو تحويله إلى أموال، ويهلك بانتهاء صلاحية الرمز. - يُظهر دفتر الأستاذ رسوم الإجمالي بالإضافة إلى سطر رصيد مطابق، بحيث تظل الإيرادات لكل خدمة صحيحة بينما تنخفض المحفظة فقط بما دفعه العميل حقاً. - إنه **لا** يرفع مستوى [quota](https://nexcmp.com/ar/docs/billing/quotas/) ويتم تجاهله بواسطة [auto top-up](https://nexcmp.com/ar/docs/billing/auto-top-up/). - إذا تم استرداد رسوم دُفعت برصيد أو خصم، فإن الجزء الذي دفعه الرمز يُسترد من استرداد المحفظة ويُعاد إلى جيب الرصيد. ### نسبة الخصم % {#discount} 1. يدخل العميل الرمز: ليصبح **مُفعلاً**. لا يمكن استخدام رمز النسبة المئوية إلا مرة واحدة لكل حساب. 2. يتم خصم النسبة المئوية من **الرسوم الأولى** للخدمة المحددة التي لا تكون رسوماً بالساعة، وبما لا يقل عن **الحد الأدنى للطلب**، على ألا يتجاوز ذلك أبداً **سقف الخصم الأقصى**. 3. يتم إعادة حساب الخصم بواسطة الخادم وقت الرسوم؛ ويتم تجاهل المبلغ الموجود في المتصفح. يتم كتابة صف الاسترداد عند استخدام الرمز فعلياً، مع الخصم الحقيقي. 4. رسوم الاستخدام بالساعة لا تستخدم الرمز أبداً. ## ما يفعله العميل {#what-the-customer-does} 1. افتح **Billing** في البوابة وانقر على **Redeem code**، أو استخدم **Have a top-up code?** في درج الإيداع. 2. اكتب الرمز (غير حساس لأسرف الحروف، والشرطات اختيارية) وانقر على **Check**. توضح البوابة ما يمنحه الرمز، على سبيل المثال *Valid code: +$5.00* أو *$5.00 credit for VPN* أو *20% off voucher for Virtual Machines (up to $5.00)*، بالإضافة إلى *Valid for orders from $10.00*. 3. انقر على **Redeem** وأكد العمليات. يمكن استخدام كل رمز مرة واحدة لكل حساب. الرموز مرتبطة بالموقع: الرمز الخاص بموقع ما يكون "غير صالح" في موقع آخر، دون أي إشارة إلى وجوده في مكان آخر. يتم تقييد المحاولات الخاطئة، وبعد عدة محاولات، يتم قفل الحساب لعدة دقائق ("N attempts left before a temporary lock"). ## المتابعة والإيقاف {#track-and-stop} - **Batches** تعرض كل دفعة مع حالتها (*active*، *disabled*، *expired*، *used up*)، وعدد مرات الاسترداد، ومقدار التعرض. افتح الدفعة للاطلاع على تبويبي **Codes** (المخفي) و**Redemptions**، بالإضافة إلى **Export CSV**. - **Redemptions** تعرض كل عملية استرداد عبر الدفعات؛ بينما توضح **Reseller quotas** مقدار ما تم استهلاكه من حد الإصدار الشهري لكل موزع؛ و**Settings** تتيح تفعيل أو تعطيل رموز الموزعين وتعيين الحد الشهري الافتراضي. - **Disable batch** تعمل على إيقاف جميع الرموز غير المستخدمة، بينما تظل عمليات الاسترداد التي تمت بالفعل سارية. يمكن أيضًا تعطيل رمز فردي. ## التحقق {#verify} 1. أنشئ دفعة من 1 رمز: Discount % 20، والحد الأقصى $5، والحد الأدنى للطلب $10، والخدمة Virtual Machines. 2. قم بالاسترداد كعميل تجريبي. ستعرض البوابة رسالة تفيد بأنه تم تفعيله. 3. اطلب جهاز افتراضي VM تكلفته $10 على الأقل (دورة شهرية): تظهر الفاتورة الخصم (بحد أقصى $5). 4. في الدفعة، يظهر الرمز 1 عملية استخدام بالخصم الحقيقي. ## الحدود والملاحظات {#limits-notes} - الرموز مرتبطة بـ **audience** و**site** عند الإنشاء؛ ولا يمكن نقلها لاحقًا. - يمكن للموزعين إصدار رموز لعملائهم ضمن حد تعرض شهري؛ راجع [Resellers](https://nexcmp.com/ar/docs/customers/resellers/). - شرائح العروض الترويجية للشريط الجانبي الخاصة بالعملاء (**Marketing › Promo slides**) هي ميزة مستقلة ولا تمنح أي خصم. - نظرًا لعدم تخزين الرمز بالنص الصريح أبدًا، لا يمكن استعادة الدفعة المفقودة: قم بتعطيلها وإنشاء دفعة جديدة. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | "أكواد النسبة المئوية: استخدام واحد لكل حساب" (`percent_one_per_account`) | الحد الأقصى للاستخدام لكل حساب أعلى من 1 للخصم النسبي Discount % | اضبطه على `1`. | | يشير النموذج إلى أن الحد الأقصى مطلوب | خصم نسبي % بدون تحديد حد أقصى للخصم Maximum discount cap | أدخل مبلغ $1.00 على الأقل. | | لم يتم العثور على العملاء | هناك بريد إلكتروني أو معرف في القائمة غير موجود | قم بتصحيح القائمة (يشير الخطأ إلى الإدخالات غير المعروفة). | | يقول العميل "invalid code" | الموقع خطأ، أو منتهي الصلاحية، أو معطل، أو مستنفد، أو ليس العميل المستهدف، أو البريد الإلكتروني غير مؤكد | تحقق من الدفعة والعميل. | | لم يتم استخدام الرصيد | الرسوم تخص خدمة أخرى | الرصيد يدفع فقط مقابل الخدمات المحددة في الدفعة. | | لم يتم تطبيق الخصم | الطلب أقل من الحد الأدنى، أو رسوم بالساعة، أو تم تفعيل الرمز لخدمة أخرى | قم بتقديم طلب أول مؤهل. | | تم قفل العميل عن الاسترداد | عدد كبير جداً من المحاولات الخاطئة | انتظر حتى تنتهي مدة القفل. | --- # الحصص {#quotas} > **الموقع في لوحة الإدارة:** Services › Virtual Machines › Policy › Quota tab (`/vm/policy?tab=quota`). لكل عميل: Customers › List › a customer › Overview (`/customers/`)، والبطاقة **Quota**. **الموقع في البوابة:** Client › Quotas (`/client/quotas`). ## الوظيفة {#what-it-does} تحميك الحصص من إساءة الاستخدام بواسطة الحسابات الجديدة: كلما زاد الأموال الحقيقية التي أودعها العميل في المحفظة، زادت الموارد التي يمكنه إنشاؤها. توجد طبقتان: - **موارد الأجهزة الافتراضية وKubernetes**: إجمالي vCPU، وRAM، والقرص، وعدد الأجهزة الافتراضية. المستويات هي خططك الثابتة. - **حصص الخدمات**: عدد عناوين IP، والمجموعات، وشبكات VPC، وغيغابايت التخزين وما إلى ذلك، عبر خمسة مستويات (من L0 إلى L4) مدفوعة بالأموال المودعة. يتم التحقق من الحصص **قبل** خصم أي شيء. يُرفض الطلب الذي يتجاوز الحد برمز HTTP 403 `quota_exceeded` مع رسالة تخبر العميل بالمبلغ المطلوب إيداعه. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | الدور | مسؤول. | | المفتاح | خيار **Enable quota** (`quota_enabled`) **معطل** افتراضياً. لا يُطبق أي مما يلي حتى تقوم بتفعيله. | | الخطط الثابتة | خطة واحدة غير مخصصة على الأقل (انظر [Plans](https://nexcmp.com/ar/docs/catalog/plans/)) — مستويات الموارد هي خططك الثابتة. بدون أي خطة، تسري قاعدة عدد الأجهزة الافتراضية فقط. | | الاعتمادات | توجد صفوف حصص الخدمة فقط للمنتجات المُمكّنة في تثبيتك (VPN، وكيل IPv6، Kubernetes، Private Cloud، Images، Object Storage، Dedicated). | ## كيفية احتساب الأساس {#how-the-basis-is-calculated} لا تنظر NexCMP إلى مدفوعات البطاقات وحدها. **الأساس** هو **رصيد المحفظة المرحل** للعميل: إيداعات بوابة الدفع، وأرصدة المشرف (**Credit / debit**)، وقسائم المحفظة المُستردة، كلها تحتسب مرة واحدة عبر دفتر حسابات المحفظة. لا تُعد خصومات الطلبات وأرصدة الخدمات الناتجة عن رموز العروض الترويجية أموالاً في المحفظة ولا يتم احتسابها. يتم **الاحتفاظ** بأعلى أساس وصل إليه العميل على الإطلاق (لكل موقع) — فالإنفاق أو الاسترداد لا يخفضان أبداً مستوىً تم فتحه مسبقاً. ### موارد الأجهزة الافتراضية وKubernetes {#vm-and-kubernetes-resources} 1. المستويات هي خطط الموقع الثابتة، مرتبة حسب تكلفة تشغيلها لمدة 24 ساعة. 2. يكون العميل على أعلى مستوى لا تتجاوز تكلفة تشغيله لمدة 24 ساعة أساسه. الحد الأقصى هو vCPU وRAM والقرص الخاص بتلك الخطة. العميل الذي لا يستطيع تحمل تكلفة أرخص خطة يحصل مع ذلك على موارد أرخص خطة. 3. الاستخدام المحسوب مقابل الحد يشمل كل جهاز افتراضي نشط (بما في ذلك المقفل منها)، وأحجام البيانات المشتراة (حتى لو كانت مفصولة)، وعمال ومراكز تحكم Kubernetes (يُحسب العمال أيضاً كأجهزة افتراضية). 4. **عدد الأجهزة الافتراضية:** يصل إلى **Max VMs at 24h tier** (الافتراضي 2). بدءاً من الجهاز الافتراضي التالي، يجب أن يغطي رصيد المحفظة *الحالي* للعميل **30 يوماً (720 ساعة)** لجميع أجهزتهم الافتراضية الحالية بالإضافة إلى الجهاز الجديد، حتى الحد الأقصى **Max VMs when meeting 30-day threshold** (الافتراضي 10). 5. **إنشاء جهاز افتراضي** يتطلب أيضاً رصيداً لا يقل عن **N ساعة** من ذلك الجهاز الافتراضي (**Create VM: balance ≥ N hours**، الافتراضي 2) والحد الأدنى لرصيد المنصة. 6. تصغير الجهاز الافتراضي لا يتم حظره أبداً. يتم التحقق من البعد المتنامي فقط، لذا يمكن للعميل الذي يتجاوز حد القرص إضافة vCPU إذا كان حد vCPU يسمح بذلك. ## التكوين {#configure} 1. افتح **Services › Virtual Machines › Policy** وحدد تبويب **Quota**. 2. قم بتشغيل خيار **Enable quota**. 3. راجع الأرقام الثلاثة (جميعها قابلة للتعديل): | الحقل | القيمة الافتراضية | النطاق | |---|---|---| | إنشاء جهاز افتراضي: الرصيد ≥ N ساعة | 2 | 1 إلى 720 | | Max VMs at 24h tier | 2 | 1 إلى 100 | | الحد الأقصى للأجهزة الافتراضية عند تحقيق عتبة 30 يومًا | 10 | 1 إلى 1000 (ليس أقل من الحقل السابق) | 4. في قسم **Tier-based service quotas** قم بتعديل الجدول (أسفله). 5. انقر على **Save**. تطلب NexCMP **سبباً** يتم تسجيله في سجل التدقيق (audit log) مع القريتين القديمة والجديدة. ينطبق التغيير على جميع العملاء. ![تبويب Quota مع مفتاح التمكين، وحدود الأجهزة الافتراضية، وجدول حصص الخدمة المستند إلى المستويات](https://nexcmp.com/ar/docs/images/billing/quotas-01-policy.webp) ### جدول حصص الخدمة {#service-quota-table} يحتوي الجدول على خمسة مستويات. تحتوي خلايا الرأس **L0** إلى **L4** على **عتبة الإيداع بالسنتات**: القيم الافتراضية `0, 1000, 5000, 20000, 100000` تعني L0 لحساب جديد، وL1 من $10، وL2 من $50، وL3 من $200، وL4 من $1,000. يجب أن تظل العتبة الأولى `0`. يحدد كل صف حصة مفتاح واحد لكل مستوى؛ **-1 تعني بلا حدود**. | المفتاح | المعنى | L0 | L1 | L2 | L3 | L4 | |---|---|---|---|---|---|---| | `vpn.ips` | عناوين IP لشبكة VPN | 2 | 10 | 30 | 100 | 500 | | `proxy6.ips` | عناوين IP لوكيل IPv6 | 500 | 2000 | 10000 | 50000 | -1 | | `dedicated.servers` | خوادم معدنية بالكامل | 1 | 2 | 5 | 20 | 50 | | `s3.storage_gb` | Object Storage GB allocated | 2048 | 4096 | 10240 | 51200 | -1 | | `k8s.clusters` | عناقيد Kubernetes | 1 | 2 | 5 | 10 | 30 | | `k8s.workers` | عقد عامل Kubernetes | 3 | 9 | 18 | 50 | 200 | | `vpc.count` | شبكات السحابة الخاصة | 1 | 2 | 5 | 10 | 30 | | `images.gb` | جيجابايت تخزين الصور المخصصة | 50 | 100 | 200 | 500 | 2000 | يسرد الجدول أيضًا بضع صفوف للمنتجات التي ليست جزءًا من هذا الإصدار؛ اتركها دون تغيير. المفتاح الذي يتم إيقاف تشغيله للمنتج مخفي ولا يتم فرضه أبدًا. يجب أن تكون القيمة `-1` أو بين `0` و`10,000,000`. تتبع حصص الخدمة **أساس الأموال**، مثل مستويات الأجهزة الافتراضية: أعلى رصيد محفظة تم بلوغه، وليس إجمالي مدفوعات البطاقات. يستخدم عملاء الموزعين نفس القيم الافتراضية ويمكن للموزع عرضها فقط. ## عمليات تجاوز لكل عميل {#per-customer-overrides} 1. افتح **Customers › List**، ثم العميل. وفي **Overview**، اعثر على بطاقة **Quota**. 2. **موارد الأجهزة الافتراضية:** انقر على **Quota override** واختر أحد الخيارات: - **حسب رصيد الشحن (إزالة التجاوز)** — السلوك الافتراضي؛ - **غير محدود (بما في ذلك عدد الأجهزة الافتراضية)** — يزيل كل القيود لهذا العميل؛ - **مستوى الباقة** — يثبت سقف الموارد على تلك الباقة؛ وتظل قاعدة عدد الأجهزة الافتراضية سارية. أدخل سبباً. يمكن لمسؤولي المنصة تعيين أي مستوى؛ ولا يمكن للتجاوز الذي يحدده المائع تجاوز الأساس المحتفظ به للعميل. 3. **الخدمات:** يوضح الجدول ضمن *Service quotas* كل مفتاح مع *In use*، والحد الفعلي و*Source* (المستوى أو التجاوز). انقر على **Edit** في أي صف، واكتب **New quota** (`-1` = غير محدود، فارغ = العودة إلى الوضع الافتراضي للباقة) وسبباً. ![بطاقة حصص العميل التي توضح المستوى، واستخدام الموارد، وجدول حصص الخدمات مع وجود تجاوز](https://nexcmp.com/ar/docs/images/billing/quotas-02-customer.webp) يتم تسجيل كل تجاوز في سجل التدقيق مع اسم المسؤول، والسبب، والقيم قبل وبعد. ## ما يراه العميل {#what-the-customer-sees} تظهر **Client › Quotas** (`/client/quotas`) **المستوى الحالي** للعميل، ووحدات vCPU والذاكرة العشوائية (RAM) والقرص وعدد الأجهزة الافتراضية المستخدمة والإجمالية (مقسمة بين الأجهزة الافتراضية وKubernetes)، و**رصيد المحفظة المؤهل**، و**أساس الموارد المحتجزة** (الذي لا ينخفض عند الإنفاق)، والمبلغ المطلوب شحنه للوصول إلى المستوى التالي. يتيح شريط التمرير للعميل اختيار المستوى المستهدف والانتقال مباشرة إلى شاشة الإيداع. تعرض بطاقة **Service Quotas** كل خدمة مع الحصة، والكمية المستخدمة، مستواهم (من L0 إلى L4)، والمبلغ الإضافي الواجب إيداعه للوصول إلى المستوى التالي، بالإضافة إلى زر **Request increase** الذي ينشئ مسودة تذكرة دعم. يشرح زر **Quota policy** القواعد المتبعة. ![صفحة حصص البوابة مع المستوى الحالي، واستخدام الموارد، وحصص الخدمات](https://nexcmp.com/ar/docs/images/billing/quotas-03-portal.webp) ## التحقق {#verify} 1. قم بتفعيل خيار **Enable quota** واستخدم عميل اختبار جديد برصيد $0. 2. حاول إنشاء جهاز افتراضي أكبر من أرخص باقة لديك. يتم رفض الطلب مع `quota_exceeded` والرسالة "Exceeds the resources of tier ... Top up $X more to unlock tier ...". 3. اشحن المبلغ المعروض. يتغير المستوى على الفور ويتم تنفيذ الطلب بنجاح. 4. شراء عناوين VPN التي تتجاوز حد L0: استجابة HTTP 403 `quota_exceeded` مع `"scope":"service"` ورابط إلى `/client/quotas`. 5. في بطاقة حصص العميل، يظهر الحقل **Source** القيمة *tier*؛ قم بتعيين تجاوز وراقب تحوله إلى *override*. ## الحدود والملاحظات {#limits-notes} - **تعني الإيقاف تماماً.** مع إيقاف `quota_enabled`، تحد القاعدة القديمة `new_account_max_vms` (**Services › Virtual Machines › Policy › Sales**) الحسابات الجديدة بـ 2 VMs حتى تصل إيداعاتها إلى $10. عندما تكون الحصة مفعلة، لا تطبق تلك القاعدة. - **الأجهزة الافتراضية التي ينشئها المسؤول غير مشمولة بالحظر.** - **الأخطاء تفشل في وضع الإغلاق.** إذا تعذر قراءة حالة الحصة، يتم رفض الطلب مع `quota_unavailable` بدلاً من السماح به. - تستخدم طلبات **API, CLI and MCP** نفس المعالجات، لذلك تنطبق نفس الحدود. - **رصيد العروض الترويجية** لا يرفع المستوى (راجع [Promotions](https://nexcmp.com/ar/docs/billing/promotions/)). - **حدود المستويات محسوبة بالسنتات** وليست بالدولارات. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | `quota_exceeded`، السبب `resources` | إجمالي وحدات vCPU/الذاكرة العشوائية/القرص الجديد يتجاوز المستوى | قم بشحن المبلغ الموضح في الرسالة أو قم بتعيين تجاوز. | | `quota_exceeded`، السبب `vm_30d` | عدد الأجهزة الافتراضية يتجاوز الحد المسموح به خلال 24 ساعة ولا تغطي المحفظة بعد 30 يوماً من تشغيل الأسطول | اشحن المبلغ المعروض. | | `quota_exceeded`، السبب `vm_max` | تم بلوغ الحد الأقصى المطلق لعدد الأجهزة الافتراضية | قم بزيادة خيار **Max VMs when meeting 30-day threshold** أو استخدم تجاوزاً. | | `quota_exceeded`, `scope: service` | تم بلوغ حد الخدمة الفردية | قم بزيادة قيمة الجدول أو تجاوز هذا المفتاح للعميل. | | `quota_unavailable` | تعذر التحقق من حالة الحصة | أعد المحاولة؛ وتحقق من سجل الخادم إذا استمرت المشكلة. | | "quota_max_vms_30d must be >= quota_max_vms_24h" عند الحفظ | القيم معكوسة | اجعل رقم الـ 30 يوماً على الأقل مساوياً لرقم الـ 24 ساعة. | | العميل يذكر أن المستوى انخفض | هو لا ينخفض؛ قارن **Held resource basis** بتكلفة الخطة | تحقق من قائمة أسعار الخطة: يمكن لزيادة سعر الخطة أن تحرك الحدود. | --- # إدارة العملاء {#managing-customers} > **أين في لوحة المشرف:** Customers › Customers › List (`/customers`)، Deletion requests (`/customers/requests`)، Service transfers (`/customers/transfers`) و API keys (`/customers/apikeys`). ## الوظيفة {#what-it-does} منطقة العملاء هي المكان الذي يبحث فيه موظفو الدعم عن الحساب، ويعرضون محفظته وخدماته وتذاكره وسجل تسجيل الدخول الخاص به، ويتخذون إجراءات بشأنه: القفل، إلغاء القفل، التحقق من البريد الإلكتروني، إعادة تعيين كلمة المرور، إضافة رصيد أو إزالته، انتحال الشخصية، إنشاء جهاز افتراضي أو إغلاق الحساب. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | الدور | مشرف. يطلب كل إجراء كتابة سبباً ويتم تسجيله في سجل التدقيق (System › Logs › Admin actions). | | البريد الإلكتروني | تتطلب رسائل البريد الإلكتروني لإعادة تعيين كلمة المرور والدعوات [SMTP configuration](https://nexcmp.com/ar/docs/administration/smtp-and-emails/) تعمل. | ## قائمة العملاء {#the-customer-list} افتح **Customers › List**. العملاء هم حسابات موقعك الرئيسي؛ وتظهر حسابات الموزعين أيضاً ويمكن تصفيتها حسب الموقع. ![قائمة العملاء مع عوامل التصفية وأعمدة الدولة ومصدر الإحالة والرصيد وعدد الأجهزة الافتراضية](https://nexcmp.com/ar/docs/images/customers/managing-customers-01-list.webp) | العمود | المعنى | |---|---| | **Email** (والاسم) | انقر لفتح العميل. | | **State** | *Active* (نشط)، أو *Locked* (مقفل)، أو *Deleted* (محذوف)، بالإضافة إلى بريد إلكتروني *verified* (موثق) أو *unverified* (غير موثق). مرر مؤشر الماوس فوق علامة القفل لقراءة السبب. | | **Login** | طرق تسجيل الدخول التي يمتلكها العميل: كلمة المرور، Google، GitHub، مفتاح المرور (passkey). | | **Country** | العلَم والاسم المستمدان من **عنوان IP**: دولة عنوان IP الخاص بالتسجيل، أو، عند عدم معرفتها، دولة عنوان IP لآخر تسجيل دخول. توضح تلميح الأدوات أيهما تم استخدامه. | | **مصدر الإحالة** | *الإحالة* مع رابط للمحيل ورمز الإحالة عندما قام العميل بالتسجيل من خلال رابط تسويقي؛ وإلافستظهر "غير مسجل". | | **Balance**، **الأجهزة الافتراضية** | رصيد المحفظة (القيم السلبية باللون الأحمر) وعدد الأجهزة الافتراضية النشطة. | | **IP المسجل / الأخير** | عنوان IP المستخدم عند التسجيل وفي آخر تسجيل دخول مع رمز دولة مكون من حرفين. استخدامه لرصد عدة حسابات من عنوان واحد. | | **المستأجر** | معرف المستأجر الداخلي للعميل. | | **تاريخ الإنشاء**، **آخر تسجيل دخول** | أوقات نسبية. | | **Site** | يظهر عندما يكون لديك شركاء إعادة بيع. | **البحث** يقبل البريد الإلكتروني أو الاسم أو عنوان IP. **عوامل التصفية:** الحالة (الكل، نشط، مقفل، محذوف)، طريقة تسجيل الدخول (أي، Google، GitHub، المفتاح الرئيسي، بدون كلمة مرور حتى الآن) والموقع. يتم الاحتفاظ بعوامل التصفية في عنوان URL، بحيث يمكن وضع علامة مرجعية على القائمة المصفاة أو مشاركتها مع زميل. **الفرز عالمي.** يؤدي النقر فوق رأس *البريد الإلكتروني* أو *الحالة* أو *الرصيد* أو *الأجهزة الافتراضية* أو *تاريخ الإنشاء* أو *آخر تسجيل دخول* إلى فرز **قاعدة العملاء بأكملها** على الخادم، وليس فقط الصفحة التي تنظر إليها، ويعود رقم الصفحة إلى 1. **تتحدث القائمة تلقائيًا.** يتم تحديثها كل بضع ثوانٍ أثناء استعراضها (وتتوقف مؤقتًا أثناء فتح نافذة حوارية أو أثناء الكتابة)، بحيث تظهر عمليات التسجيل الجديدة وتغييرات الأرصدة دون الحاجة لإعادة التحميل. تتحدث صفحة العميل كل 30 ثانية تقريبًا أثناء عرضها؛ وتحمّل كل علامة تبويب بياناتها الخاصة عند فتحها لأول مرة. ### إنشاء عميل {#create-a-customer} 1. انقر فوق **Create customer**. 2. أدخل **البريد الإلكتروني**، و**اسم العرض** الاختياري، و**كلمة المرور** الاختيارية (فارغة = يقوم العميل بتعيينها من خلال رابط الدعوة) واختر ما إذا كنت تريد **إرسال بريد الدعوة الإلكتروني**. 3. تأكيد. يُعتبر الحساب المُنشأ يدويًا مُتحققًا منه عند إرسال الدعوة. ## صفحة العميل {#a-customer-s-page} انقر على أحد الصفوف. تتضمن الصفحة ثماني علامات تبويب؛ ويتم الاحتفاظ بعلامة التبويب المحددة في الرابط (URL) لتتمكن من حفظها كإشارة مرجعية. تُحمَّل علامات التبويب عند فتحها لأول مرة وتحتفظ بحالتها عند الانتقال إلى غيرها. | علامة التبويب | المحتوى | |---|---| | **Overview** | بيانات الهوية والتسجيل وآخر تسجيل دخول، وملخص المحفظة والخدمات | | **Services** | جدول موحد لخدمات العميل، مع إمكانية التصفية حسب النوع والحالة، والبحث، والفرز والتصفح من جانب الخادم | | **Billing** | المحفظة والرصيد ودفتر الحسابات والفواتير والمدفوعات والاستردادات وطريقة الدفع المحفوظة والشحن التلقائي | | **Quota** | حدود الموارد وتجاوزاتها؛ راجع [Quotas](https://nexcmp.com/ar/docs/billing/quotas/) | | **الأمان** | الجلسات، والمصادقة، وطرق تسجيل الدخول، وسجل تسجيل الدخول، ومفاتيح API؛ راجع [API keys](https://nexcmp.com/ar/docs/developers/api-keys/) | | **Support** | التذاكر الأخيرة | | **الشركة التابعة** | حالة برنامج الإحالة | | **Log** | سجل التدقيق والنشاط | أزرار الإجراءات في رأس الصفحة (مخفية للحسابات المحذوفة): | الزر | الوظيفة | |---|---| | **Lock account** / **Unlock** | يحظر تسجيل الدخول ووصول API. يقوم اختياريًا أيضًا بإيقاف جميع الأجهزة الافتراضية (دون حذفها). يتم إيقاف الخدمات المدفوعة مسبقًا التي ليست أجهزة افتراضية (Kubernetes، والسحابية الخاصة، والشبكة الافتراضية الخاصة وما إلى ذلك) أيضًا. يجب فتح الأجهزة الافتراضية المقفلة من قبل المسؤول بشكل منفصل على صفحة الجهاز الافتراضي. | | **Verify email** | يقوم بتحديد البريد الإلكتروني كمعتمد دون الحاجة لأن ينقر العميل على أي رابط. | | **Send reset link** | يرسل رابط إعادة تعيين كلمة المرور عبر البريد الإلكتروني (صالح لمدة 1 ساعة، للاستخدام مرة واحدة). إذا لم يتم تكوين SMTP، يظهر الرابط مرة واحدة لتتمكن من إرساله بنفسك. لا يرى المشرف كلمة المرور أبداً. | | **Impersonate** | يقوم بتسجيل الدخول بصفتك العميل لمدة ساعة واحدة. راجع [Log in as a customer](https://nexcmp.com/ar/docs/customers/login-as/). | | **Credit / debit** | يضيف أو يخصم أموالاً من المحفظة عبر تعديل دفتر الأستاذ. راجع [Invoices and ledger](https://nexcmp.com/ar/docs/billing/invoices-and-ledger/). | | **Revoke sessions** | يقوم بتسجيل خروج العميل من جميع الأجهزة؛ وتتوقف رموز التطبيقات عن العمل. | | **Create VM** | ينشئ جهازاً افتراضياً (VM) للعميل. | | **Soft delete** | يغلق الحساب. يجب عليك كتابة البريد الإلكتروني للتأكيد. | ### إدارة خدمة مفردة {#manage-an-individual-service} افتح علامة التبويب **Services** الخاصة بالعميل، وابحث عن الخدمة بالاسم أو المعرف (ID) أو عنوان IP أو التكوين، واستخدم إجراءات الصف الخاصة بها. تتوفر نفس هذه الإجراءات في قائمة إدارة الخدمة نفسها. تعرض النافذة الحوارية فقط الإجراءات التي تدعمها تلك الخدمة وحالتها الحالية. | الإجراء | التأثير | |---|---| | **Lock** | يُوقف الخدمة مع الاحتفاظ ببياناتها. يراها العميل مقفلة ولا يمكنه تشغيلها. شحن الرصيد لا يزيل قفل المسؤول؛ ويتم حظر التجديد التلقائي أثناء القفل. | | **Unlock** | يلغي قفل المسؤول. لا يؤدي هذا إلى إزالة قفل الحماية أو قفل إساءة الاستخدام (abuse) غير المرتبط به. | | **Cancel without refund** | يلغي الخدمة دون إدراج قيد استرداد في دفتر الحسابات. يُحذر إشعار التأكيد من أنه لا يمكن التراجع عن الإلغاء. | | **Cancel and refund** | يعرض المدفوعات الأصلية، وتوزيعها بين المحفظة/الرصيد، وعمليات الاسترداد السابقة، والحد الأقصى للمبلغ القابل للاسترداد. راجع المبلغ قبل التأكيد. | أدخل سبباً لكل إجراء. هذا السبب مخصص للمسؤولين؛ بينما يتلقى العميل إشعاراً أو حدث خدمة محايداً. تعود أموال المحفظة المستردة إلى المحفظة، وتعود المخصصات الائتمانية أو الترويجية إلى الرصيد. لا يؤدي هذا الإجراء إلى إرجاع الأموال عبر Stripe أو التحويل المصرفي أو PayPal. بالنسبة لخدمات متعددة من النوع نفسه، حدد ما يصل إلى 50 صفاً واختر إجراءً مجمّعاً. تعرض النتيجة حالة النجاح أو الفشل لكل صف. تستخدم عمليات الاسترداد المجمّعة المبلغ المقترح لكل خدمة؛ ويتم تخطي الخدمات التي يكون المبلغ المقترح لاستردادها صفراً في وضع الاسترداد، وتتطلب مراجعة فردية أو إلغاءً دون استرداد. تُعد صفوف DDoS Shield وdisks وbackups للقراءة فقط هنا. وتتبع إضافات Bandwidth خدمتها الرئيسية. يمكن قفل الوصول إلى AI Models، ولكن ليس لديه اشتراك لإلغائه. لقفل خادم Bare Metal مستأجر، اتخذ الإجراء على اشتراكه بدلاً من طلبه. ### إغلاق الحساب (الحذف الناعم) {#closing-an-account-soft-delete} يتم تعيين الحساب على حالة *deleted* (محذوف)، وحظره، وإلغاء جلساته، وعكس عمولات الإحالة التي لم تُدفع بعد. تظل الفواتير ودفتر الأستاذ لأغراض المحاسبة. يُرفض الإجراء طالما أن لدى العميل **أي خدمة نشطة** (جهاز افتراضي VM، وKubernetes، وسحاب افتراضي خاص، ومخصص، وشשת VPN، ووكي IPv6)، أو حساب S3، أو استهلاك S3 غير مسوى. قم بحذف تلك أولاً. ## طلبات الحذف {#deletion-requests} يمكن للعميل طلب الحذف من صفحة حسابه. تظهر الطلبات ضمن **Customers › Deletion requests** (المرشح الافتراضي: معلق) مع العميل، والسبب، وعدد الأجهزة الافتراضية النشطة، والرصيد، ووقت الطلب. - **Approve deletion** متاح فقط عندما لا يكون لدى العميل أي جهاز افتراضي نشط. اكتب البريد الإلكتروني للتأكيد. يتم حذف الحساب حذفاً ناعماً؛ **ولا يتم استرداد رصيد المحفظة المتبقي تلقائياً** — أنشئ استرداداً أولاً إذا كنت مداناً به. - يتطلب **Reject** إبداء سبب. ## عمليات نقل الخدمات {#service-transfers} تعرض **Customers › Service transfers** الطلبات الخاصة بنقل **جهاز افتراضي VM أو اشتراك VPN** من حساب إلى آخر **على نفس الموقع**. - الشاشة مخصصة للقراءة والإنشاء فقط: يمكنك إنشاء طلب نيابة عن العميل أو إلغاؤه. تعمداً، **لا** توجد زر للموافقة عليه لصالح المالك أو المستلم. - آلية العمل: يؤكد المالك عبر رابط بريد إلكتروني صالح للاستخدام مرة واحدة (صالح لمدة 30 دقيقة، مع التحقق بخطوتين TOTP إن كان مفَعّلاً)، ثم يسجل المستلم الدخول ويقبل (يتحمل المستلم التزامات الدفع). ينتهي صلاحية الطلب الذي لم يُقبَل خلال 7 أيام. - القواعد: يجب أن تكون الخدمة نشطة، بدون فواتير غير مدفوعة وبدون مهام قيد التشغيل؛ ويجب أن يكون المستلم عميلاً نشطاً وله بريد إلكتروني معتمد على نفس الموقع. يؤدي نقل الجهاز الافتراضي (VM) إلى إزالة مفتاح SSH وإيقاف التجديد التلقائي؛ بينما يغيّر نقل VPN كلمات مرور الاتصال. - تظل الفواتير الصادرة مسبقاً مرتبطة بالمالك السابق؛ ويمكن للمالك الجديد قراءة تاريخ فواتير الخدمة مع إخفاء بيانات المالك السابق. - يمكن للعملاء إنشاء طلباتهم الخاصة ضمن **Transfers** في البوابة (5 طلبات في الساعة و3 طلبات مفتوحة في نفس الوقت). ## التحقق {#verify} 1. أنشئ عميلاً مع إرسال بريد دعوة إلكتروني. يظهر الحساب الجديد في أعلى القائمة في غضون ثوانٍ قليلة. 2. الفرز حسب **Balance**: يغطي الترتيب جميع العملاء. 3. قفل العميل: يتحول وسم الحالة إلى *Locked* ولا يعود بإمكان العميل تسجيل الدخول. يمكنك إلغاء قفله. ## الحدود والملاحظات {#limits-notes} - عمود البلد هو تقدير استرشادي مبني على عنوان IP وليس دليلاً قاطعاً على محل الإقامة. العناوين الخاصة أو غير المجهولة لا تُظهر أي بلد. - قفل الحساب لا يسترد أي أموال ولا يحذف الأجهزة الافتراضية إلا إذا اخترت إيقافها أيضاً. - إلغاء قفل الحساب لا يلغي قفل الأجهزة الافتراضية التي قفلها المسؤول؛ افتحها بشكل منفصل في صفحة الجهاز الافتراضي. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | "لا يزال لدى العميل خدمات نشطة ... قم بالإيقاف أو الحذف أولاً" | العميل لديه خدمات أو حساب S3 | قم بإزالتها، ثم قم بالحذف المؤقت. | | موافقة الحذف تقرأ "N VMs alive" | السبب نفسه | احذف الأجهزة الافتراضية أولاً. | | يظهر رابط إعادة التعيين بدلاً من "تم وضع البريد الإلكتروني في قائمة الانتظار" | لم يتم تكوين خادم SMTP | قم بتكوين البريد الإلكتروني، أو أرسل الرابط بنفسك. | | تعذر إزالة طريقة تسجيل الدخول (`last_login_method`) | إنها الطريقة الوحيدة للعميل لتسجيل الدخول | أضف طريقة أخرى أولاً. | | القفل لا يوقف الخدمات المدفوعة مسبقاً | تم الإبلاغ عن أخطاء في الإيقاف | اقرأ الرسالة بعد القفل؛ يعيد النظام محاولة الإيقاف تلقائياً. | | تعذر إنشاء عملية نقل | فاتورة غير مدفوعة، أو مهمة قيد التشغيل، أو المستلم على موقع آخر، أو غير متحقق منه | أصلح المشكلة وأعد المحاولة. | --- # تسجيل الدخول كعميل {#log-in-as-a-customer} > **أين في لوحة المشرف:** Customers › Customers › List › a customer › header button **Impersonate** (`/customers/`). ## الوظيفة {#what-it-does} تتيح لك **Impersonate** (تسجيل الدخول نيابة عن) لمسؤول الدعم رؤية البوابة تماماً كما يراها العميل، لإعادة إنتاج مشكلة أو المساعدة في طلب. تستمر الجلسة لمدة ساعة واحدة وتكون مفصولة بوضوح عن الجلسة العادية: يتم حظر أي شيء قد يمنح وصولاً دائمًا إلى الحساب، ويتم تسجيل كل استخدام. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | الدور | مسؤول مسجل الدخول إلى وحدة تحكم المسؤول. | | العميل | يجب أن يكون الحساب **نشطاً**. الحساب المقفل أو المحذف يرد بـ "الحساب ليس نشطاً" (HTTP 409). | | السبب | السبب إلزامي؛ يتم كتابته في سجل التدقيق. | | المتصفح | السماح بالنافذة المنبثقة لعنوان المسؤول: تفتح البوابة في نافذة جديدة. | ## الخطوات {#steps} 1. افتح **Customers › List** وانقر على العميل. 2. انقر على **Impersonate**. يوضح مربع الحوار أن موقع العميل يفتح كعميل لمدة ساعة واحدة وأن كل إجراء يخضع للتدقيق. 3. اكتب **السبب** (على سبيل المثال "التذكرة 1234 — تعذر إنشاء VM") وانقر على **Open app**. 4. تفتح نافذة جديدة على موقع العميل وتظهر لوحة المعلومات مع `?impersonated=1`. إذا حظر المتصفح النافذة، فاسمُح بالنوافذ المنبثقة وانقر مرة أخرى. ![نافذة Impersonate مع حقل السبب مملوءاً](https://nexcmp.com/ar/docs/images/customers/login-as-01-dialog.webp) بالنسبة لعميل الموزع، تفتح النافذة على **نطاق الموزع نفسه**، لأن الرابط يعمل فقط على موقع العميل نفسه. ## How it works {#how-it-works} 1. ينشئ إجراء المسؤول **رمزاً صالحاً للاستخدام مرة واحدة** لمدة ساعة واحدة ويكتب `customer.login_as` (المسؤول، عنوان IP، السبب، الموقع) في سجل التدقيق. 2. تفتح النافذة الجديدة `https:///v1/portal/impersonate/`. الطلب الأول يظهر فقط صفحة صغيرة ولا **يستهلك** الرمز (لذلك لا يمكن لجلب المتصفح المسبق حرقه)؛ ثم تؤكد الصفحة باستخدام POST. 3. يستهلك طلب POST الرمز. يؤدي الاستخدام للمرة الثانية، أو الاستخدام بعد مرور ساعة، إلى الرد "The impersonation link has expired or was already used". 4. تنشئ NexCMP جلسة عميل تستمر لمدة **ساعة واحدة** (تستمر الجلسة العادية 30 يوماً)، وتسجل إدخال تسجيل دخول باستخدام الطريقة `impersonate`، وتقوم بتسجيل `customer.login_as.used`. 5. يعمل الرمز فقط على موقع العميل نفسه؛ وعلى مضيف آخر يستجيب بالرمز 404. ## ما يتم حظره في الجلسة المنتحلة {#what-is-blocked-in-an-impersonated-session} أي شيء يمنح وصولاً يتجاوز الساعة، أو يغير أمان العميل نفسه، يُرجع الخطأ HTTP 403 `impersonate_forbidden`: | محظور | السبب | |---|---| | تغيير كلمة المرور، أو المصادقة الثنائية TOTP، أو ربط أو إلغاء ربط حسابات Google/GitHub، أو تعديل مفاتيح المرور | بيانات اعتماد العميل نفسه | | حذف الحساب | لا يمكن التراجع عنه | | إنشاء أو تعديل **API keys** | وصول طويل الأمد | | الموافقة على تسجيل دخول CLI أو سطح المكتب أو MCP (ربط الجهاز) | وصول طويل الأمد | | إنشاء وصول Kubernetes، أو مفاتيح S3، أو مفاتيح SSH، أو كلمات مرور الجذر، أو روابط مشاركة وحدة التحكم، أو بيانات اعتماد شبكة VPN أو الوكيل | أسرار تدوم لفترة أطول من الجلسة | | استرداد رموز تعبئة الرصيد | حملات الأموال | | سحب أو تغيير عمولة الإحالة | تغادر الأموال النظام | | تعديل مفاتيح الذكاء الاصطناعي، أو الميزانيات، أو رسائل البريد الإلكتروني للتنبيهات | إعدادات العميل | كل ما عدا ذلك يعمل: يمكنك قراءة الصفحات، أو إنشاء أو إدارة الأجهزة الافتراضية، أو تقديم الطلبات وما إلى ذلك. تُنفذ الإجراءات بهوية العميل وتُنفق أموال العميل؛ وتُظهر إدخال التدقيق أعلاه أن المشرف كان يقف خلف الجلسة. ## التحقق {#verify} 1. انتحل صفة عميل تجريبي. تفتح البوابة وتظهر بيانات ذلك العميل. 2. حاول تغيير كلمة المرور: تحصل على رسالة "ممنوع" (انتحال الشخصية). 3. في **System › Logs › Admin actions**، ابحث عن `customer.login_as` مع اسمك، والسبب، والموقع، متبوعاً بـ `customer.login_as.used`. 4. أغلق النافذة، وأعد فتح نفس الرابط: "انتهت صلاحية الرابط أو تم استخدامه مسبقاً". ## الحدود والملاحظات {#limits-notes} - حد الساعة الواحدة ثابت (3600 ثانية). للمتابعة، قم باانتحال الشخصية مرة أخرى. - فضل القراءة وإعادة الإنتاج؛ وتجنب الإجراءات التي تنفق الأموال ما لم يطلب منك العميل ذلك. - قم بإلغاء الجلسة مبكراً باستخدام **Revoke sessions** في صفحة العميل (هذا يؤدي إلى تسجيل خروج العميل أيضاً). - يتمتع الموزعون بخاصية انتحل الشخصية الخاصة بهم **Sign in to partner console** (60 دقيقة) من قسم الموزعين؛ راجع [Resellers](https://nexcmp.com/ar/docs/customers/resellers/). ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | "الحساب غير نشط" | الحساب مقفل أو محذوف | قم بإلغاء قفله أولاً، أو انظر إلى صفحة العميل بدلاً من ذلك. | | يحظر المتصفح النافذة | مانع النوافذ المنبثقة | اسمح بالنوافذ المنبثقة لعنوان المشرف وحاول مرة أخرى. | | "انتهت صلاحية الرابط أو تم استخدامه مسبقاً" | حد الساعة الواحدة أو إعادة الاستخدام | قم بانتحال الشخصية مرة أخرى. | | يفتح رسالة "غير موجود" | تم استخدام الرابط على المضيف الخطأ | استخدم النافذة التي فتحها مربع الحوار؛ ولا تلصق الرابط في مكان آخر. | | إجراء يقول "ممنوع" | محظور في الجلسات المنتحلة | اطلب من العميل القيام بذلك، أو استخدم شاشات المشرف. | --- # الموزعون (ذو العلامة البيضاء) {#resellers-white-label} > **المكان في لوحة التحكم:** Customers › Resellers › List (`/resellers`)، Domains & SSL (`/resellers/domains`)، Permissions & wholesale (`/resellers/entitlements`)، Defaults (`/resellers/settings`). فتحات الموزعين: System › Admin › License & updates (`/license`). ## الوظيفة {#what-it-does} يحصل **الموزع** على نسخة تحمل علامته التجارية من بوابة العملاء على **نطاقه الخاص**، مع عملائه، ومحفظته، وأسعاره، وقنوات الدفع (اختيارياً). وهم يشترون منك بسعر الجملة ويبيعون بسعرهم الخاص. ولا يرى عملاؤهم علامتك التجارية أبداً، ولا يمكن لنطاق الموزع فتح وحدة تحكم المشرف الخاصة بك. ويدير الموزع عملياته من **لوحة تحكم الشريك** على `https://partner.`. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | الترخيص | فتحة **نطاق موزع** واحدة على ترخيصك لكل نطاق موزع مخصص. تظهر صفحة الترخيص فتحات `used/max` ورابطاً لشراء المزيد. وبدون فتحة متوفرة، يفشل إضافة نطاق مع رسالة "Out of license reseller domain slots". | | DNS | يجب توجيه نطاق كل موزع نحو خادمك (انظر أدناه). | | خادم الويب وبروتوكول TLS | يجب أن يصل اسم الخادم إلى لوحة NexCMP عبر الوكيل العكسي (Reverse Proxy) مع شهادة صالحة لذلك الاسم. | | البريد الإلكتروني | تم تكوين SMTP لإرسال رسائل الدعوة والإشعارات. | | المفتاح الرئيسي | **Reseller settings › General › `rs_enabled`** قيد التشغيل افتراضياً. | ## تجهيز البنية التحتية {#prepare-the-infrastructure} 1. حدِّد العنوان العام للخادم: عنوان IPv4 الخاص به وإذا كنت تفضل استخدام أسماء CNAME، اسم خادم يشير إليه (على سبيل المثال `sites.cloud.example.com`). 2. افتح **Customers › Resellers › Defaults** (`/resellers/settings`)، والمجموعة **Domains & SSL**، واضبط: | المفتاح | المعنى | |---|---| | `rs_server_ipv4` | عنوان IPv4 العام الذي يجب أن تشير إليه سجلات A الخاصة بالموزعين. | | `rs_cname_target` | اسم الخادم الذي يجب أن تشير إليه سجلات CNAME الخاصة بالموزعين. | | `rs_master_hosts` | أسماء النطاقات التي تنتمي إلى موقعك الرئيسي الخاص (لا يمكن منحها للموزعين). | | `rs_platform_domain` | نطاق رئيسي اختياري **لنطاقات المنصة الفرعية** (على سبيل المثال `partners.cloud.example.com` لمنح الموزعين `acme.partners.cloud.example.com`). الإفراغ يعطل الخيار. | | `rs_sites_stale_minutes` | الدقائق التي تُعتبر بعدها خدمة الشهادة قديمة (الافتراضي 15). | | `rs_ssl_fail_hours` | ساعات المحاولات الفاشلة قبل إطلاق خطأ (الافتراضي 48). | ::: warning تحقق من هذه القيم قبل إرسال التعليمات تأتي `rs_server_ipv4` و `rs_cname_target` و `rs_master_hosts` محمّلة بقيم نموذجية. استبدلها بخادمك ونطاقك الخاص **قبل** إجادة تعليمات نظام أسعار النطاقات (DNS) للموزع، وإلا فإن التعليمات التي تظهر على الشاشة ستشير إلى المكان الخطأ. ::: 3. انقر فوق **Save** (يُطلب سبب لذلك). 4. تأكد من أن الوكيل العكسي (Reverse Proxy) يوجه أسماء نطاقات الموزعين إلى لوحة NexCMP ويقوم بخدمة شهادة لكل منها. يقوم المثبت بتكوين nginx و Let's Encrypt فقط للنطاق الرئيسي (وأسماء `admin.` و `partner.` التي يتم حلها). إذا كنت تستخدم Cloudflare، فوكِّل اسم النطاق واستخدم وضع Full SSL. ## الربط في NexCMP {#connect-in-nexcmp} ### إنشاء الموزع {#create-the-reseller} 1. افتح **Customers › Resellers › List** وانقر فوق **New reseller**. يحتوي المعالج على 8 خطوات ويقوم بتجهيز كل شيء في النهاية؛ ويمكن إعادة محاولة كل خطوة بأمان. | الخطوة | املأ | |---|---| | **الموزع** | الاسم القانوني أو التجاري، **الاسم المختصر (slug)** (4–31 حرفاً من a إلى z، أو من 0 إلى 9 أو `-`، تبدأ بحرف؛ وهي أيضاً بادئة الفاتورة)، اسم جهة الاتصال، البريد الإلكتروني ورقم الهاتف، اللغة الافتراضية، تفاصيل الفوترة الخاصة بالموزع (باعتباره مشترياً لعمليات شحن المحفظة). | | **حساب لوحة التحكم** | اسم المستخدم، البريد الإلكتروني للحساب، الاسم الكامل؛ **إرسال رابط دعوة لمرة واحدة عبر البريد الإلكتروني** (صالح لمدة 72 ساعة، وهو موصى به) أو عرض كلمة مرور مؤقتة لمرة واحدة. | | **Brand** | اسم العلامة التجارية، الاسم المختصر، العبارات التعريفية، الألوان الأساسية، بريد ودعم الهاتف، اسم البائع المطبوع على فواتير العملاء، الشعارات (الخلفية الفاتحة والداكنة)، العلامة المربعة وfavicon: بصيغة PNG أو JPEG أو WEBP أو ICO بحجم يصل إلى 256 كيلوبايت، **بدون SVG**. | | **Domains** | النطاق (النطاقات) للعميل مع **وجود www أيضاً**، وأيها هو الرئيسي، **نطاق الاختبار** (sslip.io) وخيار **التشغيل التجريبي** (dry-run)، أو نطاق فرعي للمنصة. يوضح المعالج حالتي **DNS OK / DNS not ready** والسجلات المراد إنشاؤها. | | **Pricing & wallet** | خصم الجملة (٪)، حد التجزئة الأدنى (٪ من القائمة)، هامش الربح الافتراضي (٪)، حد الائتمان، الرصيد الافتئي، تنبيه انخفاض الرصيد، القيود المفروضة على العملاء، الأجهزة الافتراضية والنطاقات، ميزات الموقع (تسجيل العملاء، حماية DDoS، تذاكر الدعم، الخطة المخصصة، تغيير الحجم، Auto Scaling). | | **Payment channels** | من يقوم بتحصيل مدفوعات العملاء (انظر أدناه) وحساب PayPal الخاص الاختياري والتحويل البنكي الفيتنامي الخاص. | | **Email** | اسم المرسل والرد إلى (Reply-To). يظل عنوان (From) هو عنوان المنصة حتى يتم إعداد DKIM لنطاق الموزع. | | **Review** | تحقق من كل شيء وانقر على **Provision everything**، أو **Save draft (provision later)**. | 2. يستمر التوفير في الخلفية (كل 30 ثانية). افتح الموزع لمعرفة التقدم واستخدم **Continue provisioning** أو **Retry** في حالة فشل أي خطوة. ![معالج الموزع الجديد في الخطوة الأولى مع قيم نموذجية](https://nexcmp.com/ar/docs/images/customers/resellers-01-wizard.webp) ### توجيه نظام أسماء النطاقات DNS (يقوم الموزع بذلك) {#point-dns-the-reseller-does-this} يقوم الموزع (أو أنت) بإنشاء السجلات المعروضة في علامة التبويب **Domains & SSL**: | السجل | الاسم | القيمة | |---|---|---| | TXT (الملكية، للمرة الأولى فقط) | `_site-verify.` | `sv=` تظهر على الشاشة | | A (النطاق الرئيسي مثل `shop.example.net`) | النطاق | `rs_server_ipv4` الخاص بك | | CNAME (نطاق فرعي مثل `cloud.example.net`) | النطاق | `rs_cname_target` الخاص بك (أو سجل A إلى `rs_server_ipv4`) | | CNAME (اختياري) | `www.` | `rs_cname_target` الخاص بك | أيضاً: - قم بإزالة أي سجل **AAAA** (IPv6) ما لم يكن خادمك يستجيب على عنوان IPv6 هذا. - قم **بإيقاف** وكيل شبكة توزيع的内容 CDN (السحاب الرمادي) أثناء التحقق من النطاق. - إذا كان النطاق يحتوي على سجلات **CAA**، فالرجاء السماح بـ `letsencrypt.org`. الرمز الموجود في سجل TXT يختلف لكل نطاق؛ انسخه من الشاشة. يعيد النظام التحقق من DNS كل 5 دقائق خلال أول 48 ساعة، ثم كل ساعة، ويحرر الاسم الذي يظل سجل TXT الخاص به مفقوداً بعد 72 ساعة. ### حالات النطاق {#domain-states} في **Customers › Resellers › Domains & SSL** (جميع الموزعين) وفي علامة تبويب **Domains & SSL** الخاصة بالموزع: | الحالة | المعنى | |---|---| | `pending_verify` | في انتظار سجل TXT. | | `pending_dns` / `verifying` | في انتظار إشارة A أو CNAME لتشير إليك. | | `issuing` | جارٍ إصدار الشهادة. | | `active` | يتم تقديم موقع الموزع. | | `cert_expiring` | الشهادة على وشك الانتهاء؛ والتجديد متوقع. | | `dns_lost` | توقف DNS عن الإشارة إليك؛ بعد 30 يوماً يتم إزالة النطاق. | | `error` | راجع رمز الخطأ؛ **Retry** بعد الإصلاح. | | `removing` / `removed` | جارٍ سحب الترخيص؛ تتم استعادة خانة الترخيص. | إجراءات الصف: **Check now**، **Retry**، **Make primary**، **Test mode** (لنطاق اختبار)، **Remove**. ## الصلاحيات والأسعار بالجملة {#permissions-wholesale} **Customers › Resellers › Permissions & wholesale** (`/resellers/entitlements`) عبارة عن مصفوفة: صف واحد لكل موزع، مع **خصم** و**هامش ربح** الجملة ومفتاح تبديل واحد لكل خدمة (مثل حماية DDoS وشبكة VPN). يكون مفتاح التبديل قابلاً للتعديل عندما تكون الميزة على مستوى المنصة مفعلة؛ وإلا فإن الخلية تصبح للقراءة فقط وترتبط بالإعداد. يحدد علامة التبويب الفرعية **Top-up codes** عدد الرموز التي يمكن لكل موزع إصدارها شهرياً (انظر [Promotions](https://nexcmp.com/ar/docs/billing/promotions/)). قواعد التسعير: - سعر الجملة = قائمة الأسعار × (1 - خصم)، ويمكن تجاوزه لكل خطة ولكل دورة فوترة في علامة التبويب **Wholesale pricing** الخاصة بالموزع. - يحدد الموزع أسعار التجزئة ولا يمكنه النزول عن **الحد الأدنى** (نسبة مئوية من السعر الأساسي). - تُدفع سعر الجملة من **محفظة** الموزع عندما يقوم عملاؤهم بالشراء. وتحتوي المحفظة على حد ائتماني، وفترة سماح، وسقف للسحب على المكشوف (انظر Defaults). ## الافتراضيات {#defaults} **Customers › Resellers › Defaults** (`/resellers/settings`) هي مفاتيح `rs_*` التي تُطبق على كل موزع. يتطلب كل تغيير سبباً ويخضع للمراجعة والتدقيق. | المجموعة | المفتاح | القيمة الافتراضية | المعنى | |---|---|---|---| | عام | `rs_enabled` | 1 | برنامج الموزعين مفعل. | | | `rs_platform_collect_enabled` | 0 | يسمح للمنصة بتحصيل مدفوعات العملاء نيابة عن الموزعين. **يُفعل فقط بعد المراجعة القانونية.** | | | `rs_totp_required` | 1 | يجب أن تستخدم حسابات وحدة تحكم الموزع المصادقة الثنائية. | | | `rs_agreement_version` | 1 | إصدار اتفاقية الموزع التي يجب عليهم قبولها. | | التسعير الافتراضي | `rs_default_discount_bp` | 2000 (20 %) | خصم الجملة للموزعين الجدد (نقاط أساس، من 0 إلى 9000). | | | `rs_default_markup_bp` | 2500 (25 %) | هامش الربح الافتراضي (من 0 إلى 50000). | | | `rs_default_floor_bp` | 9000 (90 %) | الحد الأدنى للتجزئة (من 0 إلى 20000). | | | `rs_default_max_domains` | 3 | النطاقات المسموح بها لكل موزع. | | المحفظة وعمليات الدفع | `rs_grace_hours` | 72 | فترة السماح قبل تأثر خدمات العملاء بخلو محفظة الموزع. | | | `rs_overdraft_cap_cents` | 5000 | السحب على المكشوف المسموح به في المحفظة. | | | `rs_retention_days` | 14 | الأيام قبل تدمير الأجهزة الافتراضية الخاصة بموزع مغلق. | | | `rs_payout_hold_days` | 30 | الأيام التي يُحتجز فيها العمولة قبل إمكانية سحبها. | | | `rs_payout_min_cents` | 5000 | أقل مبلغ سحب. | | | `rs_topup_min_cents` | 2000 | أقل عملية شحن للمحفظة يقوم بها الموزع. | | المدفوعات والبريد | `rs_webhook_base` | فارغ | عنوان URL الأساسي العام لخطافات ويب (webhooks) الخاصة ببوابة الموزع (فارغ = استخدام عنوان URL للموقع). | | | `rs_mail_from` | فارغ | عنوان المرسل لرسائل بريد الموزعين. | | | `rs_invoice_show_processor` | 1 | إظهار معالج الدفع على الفواتير. | | | `rs_gw_stripe_enabled`, `rs_gw_usdt_enabled` | 1 | ما إذا كان يُسمح للموزعين بتكوين Stripe أو USDT الخاص بهم. | ## من يقوم بتحصيل مدفوعات العملاء {#who-collects-customer-payments} | Mode | المعنى | |---|---| | **الموزع هو من يحصل (عبر قنواته الخاصة)** — افتراضي | يقوم الموزع بتوصيل حساب Stripe أو PayPal أو USDT أو الحساب المصرفي الخاص به. خطافات الويب الخاصة بهم هي `https:///v1/billing//webhook/r/`. البطاقات المحفوظة وميزة [auto top-up](https://nexcmp.com/ar/docs/billing/auto-top-up/) غير متاحتين لهذه المواقع. | | **المنصة تقوم بالتحصيل** | يتم عرض قنواتك على موقع الموزع. مقفلة حتى `rs_platform_collect_enabled = 1`. | | **مختلط** | مزيج يتم اختياره لكل قناة. | ## ما يراه الموزع {#what-the-reseller-sees} تتضمن وحدة تحكم الشريك في `https://partner.` خيارات Overview وReports وCustomers وVMs وTickets وOrders وPayments وPrices وBrand وLanding & legal وDomains & SSL وEmail وWallet وPayment channels. تحظى حسابات وحدة التحكم بدور *reseller* (بالكامل) أو *staff* (للقراءة فقط). لإلقاء نظرة بنفسك، افتح الموزع وانقر على **Sign in to partner console**: ستدخل لمدة 60 دقيقة، ويتم تسجيل كل عملية كتابة باسمك في كل من سجل المشرف وسجل الموزع، وتتطلب عمليات الأموال تأكيداً ثانياً. ## التحقق {#verify} 1. بعد التجهيز، يُظهر صف قائمة الموزع حالة *active* وعمود **Provisioning** أخضر. 2. افتح نطاق الموزع في متصفح: تظهر صفحة تسجيل الدخول الخاصة بالموزع مع علامته التجارية. يجيب `https:///admin` بـ 404. 3. قم بتسجيل عميل اختبار على هذا النطاق: يظهر العميل ضمن **Customers › List** مع وجود الموزع في عمود **Site**. 4. تظهر صفحة الترخيص خانة استخدام إضافية واحدة. ## الحدود والملاحظات {#limits-notes} - فتحة ترخيص واحدة لكل نطاق مخصص أو اختباري؛ النطاقات الفرعية للمنصة لا تستهلك فتحة. - تعليق الموزع يحتفظ بالبيانات؛ **Close reseller** يعيد جميع فتحات النطاقات، ولا يُسمح بحذف الأجهزة الافتراضية إلا بعد فترة الاحتفاظ. - يظهر عملاء الموزع في قائمة العملاء لديك ويمكن تقمص شخصياتهم كأي عميل آخر (يفتح الرابط على نطاق الموزع). - لا يمكن للموزعين رؤية أو تغيير قنوات الدفع الخاصة بك، أو القيم الافتراضية للحصص، أو الموزعين الآخرين. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | "نفدت فتحات نطاقات الموزع في الترخيص" | All slots used | حرر فتحة (احذف نطاقاً) أو اشترِ المزيد من صفحة الترخيص. | | Domain stuck in `pending_verify` | TXT record missing | أنشئ سجل TXT تماماً كما يظهر؛ استخدم **Check now**. | | Domain stuck in `pending_dns` | سجل A/CNAME لا يشير إليك، أو سجل AAAA، أو بروكسي CDN مفعل | أصلح نظام الأسماء النطاقية (DNS)، وأوقف تشغيل البروكسي، ثم انقر على **Check now**. | | `error` state | راجع الكود في السطر (على سبيل المثال، سجل CAA يحظر Let's Encrypt، حد معدل الطلبات) | أصلح المشكلة وانقر على **Retry**. | | يقول المتصفح إن المضيف غير معروف أو "421" | اسم المضيف غير موجود في الترخيص، أو غير موجه إلى اللوحة | أضف النطاق عبر الموزع (يستهلك فتحة) وأصلح البروكسي العكسي. | | التعليمات تظهر عنوان IP أو مضيفاً خاطئاً | `rs_server_ipv4` / `rs_cname_target` ما زالا يحتفظان بالقيم التجريبية | Set them in Defaults. | | لا يمكن للموزع تفعيل تحصيل المنصة | Locked | اضبط `rs_platform_collect_enabled` بعد المراجعة القانونية. | --- # Branding {#branding} > **أين تجد ذلك في لوحة المشرف:** System › Settings › Brand (`/settings/branding`). ذات صلة: System › Settings › General (`/settings`) لعناوين URLs وتفاصيل البائع المطبوعة على الفواتير. ## الوظيفة {#what-it-does} NexCMP يعتمد العلامة البيضاء: المنتج لا يحمل أي اسم للمورد، وكل ما يراه عملاؤك هو علامتك **الخاصة**. تُطبق إعدادات العلامة التجارية على صفحات تسجيل الدخول والتسجيل، والبوابة، ووحدة تحكم المشرف، ورسائل البريد الإلكتروني. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | الدور | مسؤول. | | Files | Logos: SVG, PNG, JPEG, WEBP or ICO, **up to 512 KB each**. | | الاعتمادات | لا يوجد. | ## الخطوات {#steps} 1. Open **System › Settings › Brand**. 2. في بطاقة **Identity** املأ ما يلي: | الحقل | ملاحظات | |---|---| | **Brand name** (required) | ما يصل إلى 60 حرفاً. يتم عرضها في البوابة، والبريد الإلكتروني، والفواتير، والصفحات القانونية. | | **اسم البائع على الفواتير** | ما يصل إلى 120 حرفاً. الفراغ يعني اسم العلامة التجارية. | | **لون العلامة التجارية** | رمز لون بصيغة `#rrggbb`؛ الزر الصغير بجوار الحقل يعيده إلى اللون المدمج. | | **Site currency** | **USD**: يتم عرض الأسعار والأرصدة بالدولار الأمريكي فقط، بدون تبديل العملات. **VND**: يعرض أيضاً المبلغ المُحوَّل بسعر الصرف المُخزَّن (راجع [Currency and exchange rates](https://nexcmp.com/ar/docs/catalog/currency-and-exchange-rates/)). | 3. انقر فوق **Save**. 4. في بطاقة **Logo & favicon** قم برفع الصور الثلاث — **الشعار (خلفية فاتحة)** و**الشعار (خلفية داكنة)** و**أيقونة المفضلة (Favicon)** — باستخدام **Upload** (أو **Replace**)؛ بينما تقوم **Remove** بحذف إحداها. ![صفحة العلامة التجارية مع حقول الهوية والصور الثلاث المرفوعة](https://nexcmp.com/ar/docs/images/customers/branding-01-brand.webp) ### الإعدادات ذات الصلة في العام {#related-settings-in-general} يحتوي قسم **System › Settings › General** على تبويبين يكملان الصورة: | علامة التبويب | الحقول | |---|---| | **العلامة التجارية والروابط** | اسم العلامة التجارية (البريد الإلكتروني، الفواتير)، اللغة الافتراضية (الإنجليزية أو الفيتنامية)، **Customer app URL**، **Console URL**، **Admin URL** (رابط انتحال شخصية الموزع) و**Partner console URL** (روابط الدعوة، رسائل البريد الإلكتروني للموزع). يملأ معالج الإعداد هذه الحقول بـ `https://` و`https:///admin` و`https:///console`. | | **Seller & invoicing** | اسم الكيان القانوني، والرقم الضريبي، والعنوان، وبريد الاتصال الإلكتروني، وبادئة رقم الفاتورة. راجع [Invoices and ledger](https://nexcmp.com/ar/docs/billing/invoices-and-ledger/). | يتم تعيين **From name** لرسائل البريد الإلكتروني في **System › Settings › Email** (قسّم [SMTP and e-mails](https://nexcmp.com/ar/docs/administration/smtp-and-emails/)). ## يتم فحص الملفات المرفوعة {#uploaded-files-are-checked} - يتم التعرف على الصور النقطية من محتواها (وليس من اسم الملف) وقياس أبعادها. - **يتم إعادة بناء ملفات SVG** من قائمة أمان للأشكال. الملف الذي يحتوي على نصوص برمجية، `foreignObject`، سمات أحداث، روابط خارجية، `url(...)` تشير إلى الخارج، أو مُحدد نوع المستند DOCTYPE، أو كيانات يتم **رفضه** (`svg_unsafe`). - يُرفض الملف كبير الحجم جداً باستخدام `asset_too_large`، والنوع الخاطئ باستخدام `asset_type`، والأبعاد غير الصحيحة باستخدام `asset_dimensions`. - يتم تقديم الملفات من نطاقك الخاص مع تفعيل ترويسات الأمان الصارمة. ## التحقق {#verify} 1. افتح صفحة تسجيل الدخول إلى البوابة في نافذة خاصّة: يظهر الشعار والاسم واللون. 2. تحقق من علامة تبويب المتصفح الخاصة بأيقونة المفضلة (تقوم المتصفحات التخزين المؤقت للأيقونات؛ أعد التحميل مع مسح التخزين المؤقت إذا كنت لا تزال ترى القديمة). 3. قم بتشغيل بريد إلكتروني تجريبي (على سبيل المثال **Send reset link** لعميل تجريبي) وتحقق من اسم العلامة التجارية في الموضوع والتذيل. ## الحدود والملاحظات {#limits-notes} - يتم استخدام شعار الخلفية الداكنة عندما ينتقل العميل أو المسؤول إلى المظهر الداكن. - يتمتع الموزعون بعلامتهم التجارية الخاصة؛ حيث يقومون برفع ملفات PNG أو JPEG أو WEBP أو ICO بحجم يصل إلى 256 كيلوبايت (بدون SVG). راجع [Resellers](https://nexcmp.com/ar/docs/customers/resellers/). - يظهر التغيير في لون العلامة التجارية أو الشعار عند تحميل الصفحة التالية؛ ولا تتأثر رسائل البريد الإلكتروني التي تم إرسالها بالفعل. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | تم رفض الرفع: `svg_unsafe` | يحتوي ملف SVG على نصوص برمجية أو روابط أو مراجع خارجية | قم بتصدير ملف SVG عادي (بدون نصوص برمجية، وبدون صور خارجية) أو استخدم صيغة PNG. | | `asset_too_large` | الملف أكبر من 512 كيلوبايت | قم ضغط الصورة أو تغيير حجمها. | | `asset_type` | الملف ليس بصيغة SVG أو PNG أو JPEG أو WEBP أو ICO | قم بتحويل الملف. | | `invalid_argument: primary` | اللون ليس بصيغة `#rrggbb` | استخدم قيمة سداسية عشرية مكونة من ستة أرقام. | | الشعار القديم لا يزال ظاهراً | ذاكرة التخزين المؤقت للمتصفح | قم بإعادة التحميل الشامل؛ فقد تستغرق أيقونات المفضلة وقتاً أطول. | | الأسعار تظهر بالدولار الأمريكي فقط | عملة الموقع هي USD | التحويل إلى VND والتأكد من حفظ سعر الصرف. | --- # الصفحات القانونية {#legal-pages} > **أين في لوحة التحكم:** System › Settings › Legal (`/settings/legal`). **أين يراها العملاء:** `https:///terms` و `/privacy`، مع روابط من صفحة التسجيل والدفع. ## الوظيفة {#what-it-does} يتم تنشيط صفحتين في تثبيتك: **Terms of Service** و **Privacy Policy**. إلى أن تكتب صفحتك الخاصة، يعرض NexCMP **نصاً افتراضياً محايداً** لا يذكر جهة البرمجيات ولا يتعهد بأي خدمة محددة. استبدله بنص تمت مراجعته بواسطة محاميك قبل بدء البيع. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | الدور | مسؤول. | | المحتوى | نص عادي (Markdown)، حتى **50 كيلوبايت** لكل صفحة ولغة. | | الاعتمادات | اسم العلامة التجارية وتفاصيل البائع ([Branding](https://nexcmp.com/ar/docs/customers/branding/)) تُدرج في النص الافتراضي. | ## الخطوات {#steps} 1. افتح **System › Settings › Legal**. تحتوي كل صفحة من الصفحتين على بطاقة خاصة بها تحمل الوسم *Using the default text* أو *Using your text*. 2. اختر تبويب اللغة، **English** أو **Tiếng Việt**. 3. اكتب النص الخاص بك. طالما أن الحقل فارغ، يظهر النص الافتراضي بشكل باهت كعنصر نائب. للبدء منه، انقر على **Start from the default text**، ثم قم بالتعديل. 4. انقر على **Save**. يظهر عداد الحجم `used / 50 KB`. 5. انقر على **View on the customer site** لفتح `/terms` أو `/privacy`. 6. للهبوط بالعودة إلى النص الافتراضي للغة واحدة، انقر على **Clear, back to default** واحفظ. ![الإعدادات القانونية مع بطاقة شروط الخدمة التي تظهر النص الافتراضي كبداية](https://nexcmp.com/ar/docs/images/customers/legal-01-terms.webp) ## ما تحتويه الصفحات الافتراضية {#what-the-default-pages-contain} يتم تخزين النص الافتراضي في المنتج باسم `legal_default.json` وملؤه باسم علامتك التجارية، اسم البائع، رابط الموقع والبريد الإلكتروني للدعم (من **Seller & invoicing** تحت System › Settings › General؛ إذا لم يتم تعيين بريد إلكتروني فإنه يشير إلى فريق الدعم الخاص بك). | الصفحة | الأقسام | |---|---| | **Terms of Service** | 1 الخدمة · 2 الحسابات والتحقق · 3 الأسعار والفواتير · 4 الاسترداد · 5 بياناتك · 6 الاستخدام المقبول · 7 التوافر والدعم · 8 التعليق والإنهاء · 9 المسؤولية · 10 التغييرات والقانون الحاكم (قانون مقر عمل البائع) | | **Privacy Policy** | 1 ما نجمعه · 2 لماذا نستخدمه · 3 ملفات تعريف الارتباط والتخزين المحلي · 4 من يراه غيرنا · 5 الاحتفاظ بالبيانات · 6 حقوقك · 7 الاتصال | ::: warning لا يعد استشارة قانونية النص الافتراضي هو قالب محايد. يُرجى مراجعته قبل استخدامه مع العملاء الحقيقيين، خاصة الأقسام المتعلقة بالاسترداد والمسؤولية والقانون الحاكم. ::: ## قواعد Markdown {#markdown-rules} - المدعوم: العناوين (`# 1. Title`)، الفقرات، القوائم النقطية والمرقمة، **الخط العريض**، والروابط `[text](https://example.com)`. - يجب أن تبدأ الروابط بـ `http://` أو `https://`. - **يتم رفض HTML الخام** (أي ``، ` # نظرة عامة على بوابة العملاء {#customer-portal-overview} > **أين في البوابة:** `https:///` — يسجل العملاء دخولهم في `/login`. يستخدم المسؤولون `/admin`؛ يفتح نفس تسجيل الدخول كلاهما عندما يكون الحساب مسؤولاً. البوابة هي ما يستخدمه عملاؤك كل يوم. وهي تحمل علامتك التجارية واسمك وشعارك وألوانك ([Branding](https://nexcmp.com/ar/docs/customers/branding/)) ولا تعرض سوى الخدمات التي قمت بتفعيلها ([Modules](https://nexcmp.com/ar/docs/infrastructure/modules/)). ## لوحة التحكم {#the-dashboard} بعد تسجيل الدخول، تظهر **Dashboard**: | الكتلة | المعنى | |---|---| | رصيد المحفظة | الرصيد الحالي وتقدير للمدة التي سيستغرقها بناءً على معدل الاستهلاك الحالي | | المبلغ المنفق هذا الشهر | الرسوم حتى الآن وتوقع لنهاية الشهر | | الأجهزة الافتراضية | كل جهاز افتراضي مع حالته، وعنوان IP، ووحدة المعالجة المركزية، وذاكرة الوصول العشوائي (RAM)، والإجراءات السريعة (وحدة التحكم، إعادة التشغيل) | | عرض النطاق الترددي | حركة المرور الواردة والصادرة لمدة 1 س، 6 س، 24 س، 7 ي، 30 ي | | النشاط الأخير | أحدث الأحداث على الحساب | | البدء السريع | قائمة تحقق: إنشاء جهاز افتراضي، إضافة مفتاح SSH، تعبئة الرصيد، تمكين تعبئة الرصيد التلقائي، التحقق من البريد الإلكتروني | ![لوحة تحكم العميل مع رصيد المحفظة، وتوقع الإنفاق، وجهاز افتراضي قيد التشغيل، وقائمة تحقق البدء السريع](https://nexcmp.com/ar/docs/images/portal/overview-01-dashboard.webp) ## التنقل {#navigation} تقسم القائمة الخدمات حسب النوع. الخدمة التي قمت بتعطيلها (أو التي لم يتم توصيل مصدرها) لا تظهر. | المجال | الصفحة | |---|---| | Instances | [Virtual machines](https://nexcmp.com/ar/docs/portal/virtual-machines/) صفحات التفاصيل الخاصة بها | | النشر | [Ordering](https://nexcmp.com/ar/docs/portal/ordering/) — إنتاج مورد | | التخزين | اللقطات، والنسخ الاحتياطية، وحدات التخزين عند تمكينها — [Snapshots](https://nexcmp.com/ar/docs/portal/snapshots/) | | الفوترة | [Wallet and top-ups](https://nexcmp.com/ar/docs/portal/sign-up-and-wallet/)، الفواتير، الطلبات، الحصص | | الحساب | الملف الشخصي، تسجيل الدخول والأمان، التفضيلات، الشحن التلقائي | | الدعم | أداة المحادثة والتذاكر — [Support](https://nexcmp.com/ar/docs/portal/support/) | | مستندات API | `/apidoc` — [API](https://nexcmp.com/ar/docs/developers/api/) | ## الحساب {#account} **الحساب** يحتوي على أربعة تبويبات: **Profile** (الاسم، البريد الإلكتروني، معرف العميل، طلب حذف الحساب)، **Sign-in & security** (كلمة المرور، مفاتيح المرور، حسابات Google/GitHub المرتبطة)، **Preferences** (اللغة، عملة العرض) و **Auto top-up** ([Auto top-up](https://nexcmp.com/ar/docs/billing/auto-top-up/)). لا يمكن للعميل حذف الحساب مباشرة: بل يضغط على **Request account deletion**؛ وبعد حذف جميع الأجهزة الافتراضية، يراجع المشرف الطلب (Customers › Deletion requests) ويمكن للعميل إلغاء الطلب طالما أنه قيد الانتظار. ## اللغة والعملة {#language-and-currency} البوابة متاحة بـ 16 لغة وتُظهر الأسعار بعملة العرض المحددة حسب اللغة؛ انظر [Currency and exchange rates](https://nexcmp.com/ar/docs/catalog/currency-and-exchange-rates/). يمكن للعملاء تبديل كليهما في **Preferences**. ## حصص العملاء {#customer-quotas} **Billing › Quotas** يوضح مقدار كل مورد (وحدة المعالجة المركزية، الذاكرة، التخزين، عناوين IP، الجهاز الافتراضي) الذي يجوز للعميل استخدامه، بناءً على ما دفع ثمنه — انظر [Quotas](https://nexcmp.com/ar/docs/billing/quotas/). --- # التسجيل، المحفظة والشحن {#sign-up-wallet-and-top-up} > **أين في البوابة:** `/register`، `/login`، الفوترة (`/billing`). ## إنشاء حساب {#create-an-account} 1. يفتح العميل `https:///register` ويدخل البريد الإلكتروني وكلمة المرور (10 أحرف على الأقل تحتوي على حروف وأرقام)، أو يستخدم **Google** أو **GitHub** أو **passkey** عند تمكينها — راجع [Security](https://nexcmp.com/ar/docs/administration/security/#customer-sign-in). 2. إذا تم تمكين التحقق البشري (captcha)، يقوم العميل بإكماله. 3. يتم إرسال بريد إلكتروني للتحقق عبر [SMTP](https://nexcmp.com/ar/docs/administration/smtp-and-emails/) الخاص بك. التحقق مطلوب قبل إنشاء جهاز افتراضي إذا كانت إعدادات المبيعات لديك تتطلب ذلك. ![صفحة التسجيل مع حقول البريد الإلكتروني وكلمة المرور](https://nexcmp.com/ar/docs/images/portal/sign-up-and-wallet-01-register.webp) ::: tip بدون خادم SMTP يعمل بشكل صحيح، لا يمكن للعملاء التحقق من بريدهم الإلكتروني أو إعادة تعيين كلمة المرور. قم بتكوين [SMTP](https://nexcmp.com/ar/docs/administration/smtp-and-emails/) أولاً. ::: ## المحفظة {#the-wallet} يتم دفع كل شيء من رصيد **المحفظة** بعملة الفوترة الخاصة بك. تعرض صفحة **Billing** ما يلي: | القسم | المعنى | |---|---| | القدرة الشرائية | الرصيد بالإضافة إلى عمليات الشحن المعلقة | | الرسوم المتراكمة | الخدمات بالساعة المستهلكة في الدورة الحالية والتي لم يتم تسويتها بعد | | الرصيد المستحق | أي مبلغ مستحق الدفع | | سجل الفوترة | علامات التبويب **Invoice History** و **Payment Order** و **Ledger** و **Orders** | ![صفحة الفوترة مع القدرة الشرائية والرسوم المتراكمة وعلامات تبويب السجل](https://nexcmp.com/ar/docs/images/portal/sign-up-and-wallet-02-billing.webp) ## إضافة رصيد {#add-credit} 1. انقر فوق **Deposit**. 2. أدخل المبلغ. الحد الأدنى هو [minimum top-up](https://nexcmp.com/ar/docs/billing/minimum-top-up/) الخاص بك. 3. اختر قناة دفع (بطاقة، PayPal، USDT، أو تحويل بنكي عندما تكون الواجهة بالفيتنامية) — القنوات هي تلك التي قمت بتمكينها في [Payment channels](https://nexcmp.com/ar/docs/billing/payment-channels/). 4. ادفع. يتم تحديث الرصيد عندما يؤكد مزود الدفع المعاملة. يمكن إعادة استخدام البطاقات المحفوظة و Stripe Link و PayPal واستخدامها في [auto top-up](https://nexcmp.com/ar/docs/billing/auto-top-up/)؛ راجع [Saved payment methods](https://nexcmp.com/ar/docs/billing/saved-payment-methods/). ## استرداد رمز {#redeem-a-code} يؤدي **Redeem code** إلى إضافة رصيد من قسيمة أصدرتها (Finance › Billing › Vouchers) أو تطبيق رمز ترويجي — راجع [Promotions](https://nexcmp.com/ar/docs/billing/promotions/). ## Invoices {#invoices} تنتج كل مدفوعات الطلب فاتورة تعرض تفاصيل البائع الخاصة بك ([General settings](https://nexcmp.com/ar/docs/administration/general-settings/)). يفتحها العملاء من **Invoice History** لطباعتها أو حفظها بصيغة PDF من المتصفح. ## الرسوم بالساعة {#hourly-charges} يتم احتساب الرسوم بالساعة لكل ساعة يبقى فيها المورد موجوداً؛ تتراكم المبالغ وقد يتم تقريب الساعة الواحدة إلى $0.00. عندما لا يكون الرصيد كافياً، يتم تعليق الخدمات وفقاً لقواعد الفوترة الخاصة بك ويتم إخطار العميل عبر البريد الإلكتروني (`low_balance`). --- # طلب خدمة {#ordering-a-service} > **أين في البوابة:** Deploy (`/deploy/vm`). **أين في لوحة التحكم** تتحكم فيما يظهر هنا: Services (الخطط، الأسعار) و System › Admin › License & updates (الوحدات النمطية). صفحة الطلب هي نموذج تمرير واحد بخطوات مرقمة. يؤدي اختيار خدمة أخرى في الخطوة 1 إلى الحفاظ على الصفحة وتغيير الخطوات أدناه. ## الخطوات {#steps} 1. **Service** — خوادم السحابة، والخدمات الأخرى التي قمت بتفعيلها (Kubernetes، Object Storage، الصور، السحابة الخاصة، VPN …). 2. **Location** — [zone](https://nexcmp.com/ar/docs/infrastructure/zones/). قد تختلف الأسعار وحركة المرور المشمولة حسب الموقع. 3. **Plan** — خطة ثابتة (vCPU، وRAM، وقرص NVMe، والسعر بالساعة) أو **Custom** (يختار العميل وحدات vCPU، وRAM، والقرص؛ وتُسعَّر حسب المورد). تأتي الخطط من [Plans](https://nexcmp.com/ar/docs/catalog/plans/). 4. **Billing cycle** — دورات **Hourly** أو دورات شهرية/سنوية مسبقة الدفع مع خصم (على سبيل المثال 1 سنة −10%، 2 سنة −15%، 3 سنوات −20%). 5. **Operating system** — قائمة بالنماذج، و**My Images** (تحميلات العميل الخاصة)، والإصدار. 6. **Hostname & quantity** — الاسم (أو **Randomize**) وعدد الخوادم. ![صفحة الطلب التي تظهر خطوات الخدمة والموقع والخطة](https://nexcmp.com/ar/docs/images/portal/ordering-01-plan.webp) ![خطوات دورة الفوترة ونظام التشغيل لصفحة الطلب](https://nexcmp.com/ar/docs/images/portal/ordering-02-cycle-os.webp) ## إرسال الطلب {#placing-the-order} يوضح الملخص السعر. يتم خصم قيمة الطلب من المحفظة **قبل** التجهيز، وبعد قواعد [quota check](https://nexcmp.com/ar/docs/billing/quotas/) و[minimum balance](https://nexcmp.com/ar/docs/billing/minimum-top-up/). عادةً ما يصل الجهاز الافتراضي إلى حالة *Running* في غضون دقيقة واحدة تقريباً؛ ويرى العميل خطوات النشر في علامة التبويب **Activity** الخاصة بالجهاز الافتراضي ويتلقى بريد "VM ready" الإلكتروني مع كلمة المرور الأولية (التي تظهر مرة واحدة لمدة 10 دقائق). ## ما الذي يمكن أن يوقف الطلب {#what-can-stop-an-order} | الرسالة / السبب | الحل | |---|---| | لا يوجد رصيد كافٍ | شحن الرصيد — [Sign-up, wallet and top-up](https://nexcmp.com/ar/docs/portal/sign-up-and-wallet/) | | تم تجاوز الحصة | زيادة الحصة — [Quotas](https://nexcmp.com/ar/docs/billing/quotas/) | | البريد الإلكتروني غير مؤكد | يقوم العميل بتأكيد البريد الإلكتروني | | لا توجد خطة للموقع المختار | إتاحة خطة في تلك المنطقة — [Plans](https://nexcmp.com/ar/docs/catalog/plans/) | | الترخيص غير صالح | لا يمكن للعملاء إنشاء خدمات جديدة — [License](https://nexcmp.com/ar/docs/getting-started/license-and-purchase/#if-the-license-is-not-valid) | --- # الأجهزة الافتراضية {#virtual-machines} > **أين في البوابة:** Instances (`/vms`) وصفحة الجهاز الافتراضي (`/vms/`). **Instances** تعرض قائمة بأجهزة العملاء الافتراضية مع الاسم، ونظام التشغيل، والحالة، وعنوان IP، والمواصفات، والتكلفة. انقر فوق أحدهما لفتح صفحته. ## صفحة الجهاز الافتراضي {#the-vm-page} علامات التبويب: **Overview**، **Console**، **AI SSH Agent** (عند تشغيل وحدة الذكاء الاصطناعي)، **Monitoring**، **Storage**، **Network**، **Configuration**، **Billing**، **Activity**. ![نظرة عامة على الجهاز الافتراضي مع الحالة، والمواصفات، وعنوان IP، ومخطط نطاق التردد، وسجل الإجراءات](https://nexcmp.com/ar/docs/images/portal/virtual-machines-01-overview.webp) ### الإجراءات {#actions} | الإجراء | التأثير | |---|---| | وحدة التحكم | يفتح وحدة تحكم المتصفح — [Console](https://nexcmp.com/ar/docs/portal/console/) | | إعادة تشغيل / إيقاف / إيقاف اجباري | التحكم في الطاقة | | إعادة تعيين كلمة المرور | ينشئ كلمة مرور جديدة، تظهر مرة واحدة | | إعادة تثبيت نظام التشغيل | يعيد البناء من قالب؛ تُفقد البيانات | | تغيير عنوان IP | يستبدل عنوان IP العام (حيثما يدعمه المصدر) | | تفعيل Auto Scaling | يقوم بتحجيم وحدة المعالجة المركزية / الذاكرة العشوائية تحت الحمل عند التفعيل | | حذف | يدمر الجهاز الافتراضي؛ ويتوقف الفوترة بالساعة | ### المعلومات المعروضة {#information-shown} وقت التشغيل، التكلفة هذا الشهر، وحدة المعالجة المركزية / الذاكرة العشوائية / القرص مع الاستخدام المباشر، عنوان IP العام والخاص، اسم المستخدم، مخطط النطاق الترددي، سجل الإجراءات، وملخص الفوترة (الخطة، دورة الفوترة، الساعات، المتبقي). ::: info الحقول تعتمد على المصدر تظهر صفحة الجهاز الافتراضي فقط ما يدعمه مصدره. على سبيل المثال، لا يحتوي جهاز Proxmox VE الافتراضي على إعادة توجيه المنافذ أو تغيير عنوان IP، وتتبع قائمة أنظمة التشغيل الخاصة به مجموعة قوالب الكتلة الخاصة به. راجع جدول الإمكانيات في [Proxmox VE](https://nexcmp.com/ar/docs/infrastructure/proxmox/). ::: ## علامة تبويب الفوترة {#billing-tab} تُظهر الخطة، دورة الفوترة، إجمالي الساعات، الوقت المتبقي وسجل الفوترة. تستمر الأجهزة الافتراضية بالساعة في تراكم التكلفة حتى يتم حذفها. يمكن للعميل **تغيير دورة الفوترة** للدفع مسبقاً لفترة أطول بخصم. ## للمسؤولين {#for-administrators} يكون الجهاز الافتراضي نفسه مرئياً ضمن Services › Virtual Machines في وحدة تحكم المسؤول، حيث يمكنك التصرف نيابة عن العميل أو [تسجيل الدخول كـ](https://nexcmp.com/ar/docs/customers/login-as/) عميل. --- # وحدة التحكم {#console} > **أين في البوابة:** صفحة الجهاز الافتراضي ← علامة تبويب **Console**. **أين في لوحة المسؤول:** System › Admin › License & updates ← الوحدات النمطية (SSH للويب). ## الوظيفة {#what-it-does} تفتح علامة تبويب **Console** جلسة رسومية (VNC) إلى الجهاز الافتراضي في المتصفح، حتى عندما تكون الشبكة داخل الجهاز الافتراضي معطلة. تتوفر طرفية **web SSH** كخيار ثانٍ عند تمكين وحدة SSH النمطية. ## المتطلبات {#requirements} | العنصر | وحدة تحكم VNC | SSH للويب | |---|---|---| | CloudStack | جهاز افتراضي لوكيل وحدة التحكم (CPVM) يمكن للوحة الوصول إليه — راجع [CloudStack](https://nexcmp.com/ar/docs/infrastructure/cloudstack/) | منفذ SSH قابل للوصول على الجهاز الافتراضي | | Proxmox VE | يعمل عبر اللوحة (noVNC عبر Proxmox API؛ بصمة TLS مثبتة) — انظر [Proxmox VE](https://nexcmp.com/ar/docs/infrastructure/proxmox/) | نفس الشيء | | اللوحة | عنوان URL لوحدة التحكم المعين في [General settings](https://nexcmp.com/ar/docs/administration/general-settings/) | خدمة `ssh-proxy` وعلامة وحدة النمطية `feature_ssh_web`؛ معطلة افتراضياً — راجع [Modules](https://nexcmp.com/ar/docs/infrastructure/modules/) | إذا كانت وحدة SSH للويب معطلة، تظهر علامة التبويب **VNC only**. ## استخدامه {#use-it} 1. افتح الجهاز الافتراضي ← **Console**. 2. انقر فوق **Console** (أو **Open in new window**). يتم إصدار تذكرة قصيرة الأجل وتفتتح وحدة التحكم في `https:///console`. 3. قم بتسجيل الدخول باستخدام اسم مستخدم الجهاز الافتراضي وكلمة المرور (الظاهرة في علامة تبويب Overview؛ قم بإعادة تعيينها إذا ضاعت). ![علامة تبويب وحدة التحكم لجهاز افتراضي](https://nexcmp.com/ar/docs/images/portal/console-01-tab.webp) ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | "Disconnected" فوراً | احتفظ المتصفح بمسار وحدة تحكم قديم | امسح بيانات الموقع للنطاق وأعد المحاولة | | شاشة سوداء | الجهاز الافتراضي متوقف عن العمل أو قيد الإقلاع | قم بتشغيل الجهاز الافتراضي وانتظر | | لا تفتح وحدة التحكم على CloudStack | جهاز Proximity VM الوكيل لوحدة التحكم لا يعمل أو تعذر الوصول إليه | تحقق من الأجهزة الافتراضية للنظام في CloudStack | | لا توجد خيارات SSH | وحدة SSH عبر الويب معطلة | قم بتفعيلها فقط بعد تثبيت `ssh-proxy` | --- # Snapshots و Backups {#snapshots-and-backups} > **أين في البوابة:** Snapshots (`/snapshots`)، وSnapshot schedules (`/snapshots/schedules`)، وBackups (`/backups`). تظهر فقط عند تفعيل الميزة في لوحة التحكم. ## الوظيفة {#what-it-does} تحفظ لقطة Snapshots حالة قرص الجهاز الافتراضي ليتمكن العميل من التراجع عن التغييرات الخاطئة. يمكن إنشاؤها يدويًا أو وفق جدول زمني. ## التوفر {#availability} | Source | Snapshots | ملاحظات | |---|---|---| | CloudStack | نعم | لقطات الوحدات التخزينية؛ وتتم محاسبة التخزين حسب الإعدادات | | Proxmox VE | نعم | حتى **5 لكل جهاز افتراضي**؛ إنشاء وعرض واستعادة وحذف | يظهر عنصر القائمة فقط عند تفعيل ميزة اللقطات وامتلاك العميل لجهاز افتراضي تدعمه بيئة التشغيل الخاصة به. ## استخدامه {#use-it} 1. افتح **Snapshots**، انقر فوق **Create**، واختر الجهاز الافتراضي وحدد اسمًا. 2. انتظر حتى تصبح الحالة *ready*. 3. للرجوع، اختر **Restore** على اللقطة وقم التأكيد — يعود الجهاز الافتراضي إلى تلك الحالة (ويتم إعادة تشغيله عند الضرورة). 4. احذف اللقطات التي لم تعد بحاجة إليها. ::: warning تؤدي الاستعادة إلى تجاهل كل ما تم كتابته بعد اللقطة. لا يمكن استعادة الأجهزة الافتراضية المحمية أو حذفها من البوابة. ::: --- # دعم العملاء {#support-for-customers} > **المكان في البوابة:** فقاعة الدردشة في كل صفحة، `/chat`، وتذاكر الدعم. **المكان في لوحة المشرف:** Customers › Support › Tickets (`/support/tickets`)، علامة التبويب **Settings**. ## للعملاء {#for-customers} - **فقاعة الدردشة** (في الزاوية السفلية لكل صفحة): اطرح سؤالاً؛ تجيب [AI Chat](https://nexcmp.com/ar/docs/ai/ai-chat/) باستخدام وثائقك وبيانات حساب العميل نفسه. يؤدي الزر **Expand** إلى فتح المحادثة نفسها على `/chat`. - **التحدث إلى الموظفين**: يجهّز المحادثة لفريقك (عبر مجموعة Telegram الخاصة بالمشرفين). - **أزرار Telegram / Zalo**: تظهر فقط بعد ضبط الروابط في إعدادات الدعم. - **التذاكر**: للمشكلات طويلة الأجل؛ يتم إرسال الردود عبر البريد الإلكتروني (`ticket_reply`). ## لك {#for-you} 1. افتح **Customers › Support › Tickets**؛ تظهر التذاكر والدردشات الجديدة هنا مع سجل المحادثة. 2. قم بالرد ضمن الموضوع. يتم إرسال بريد إلكتروني للعميل عبر خادم [SMTP](https://nexcmp.com/ar/docs/administration/smtp-and-emails/) الخاص بك. 3. في علامة التبويب **Settings**، قم بتشغيل أو إيقاف أداة الدردشة، وقم بتعيين رابط Telegram ورابط Zalo (يُشترط استخدام HTTPS)، واختر ما إذا كان الذكاء الاصطناعي يجيب تلقائيًا — راجع [AI Chat](https://nexcmp.com/ar/docs/ai/ai-chat/). 4. قم بتوصيل [Telegram alerts](https://nexcmp.com/ar/docs/administration/telegram-notifications/) حتى يتم إشعار فريقك بالمحادثات الجديدة. --- # مزود الذكاء الاصطناعي {#ai-provider} > **المكان في لوحة المشرف:** System › Settings › AI provider (`/settings/ai`). مفتاح وحدة الذكاء الاصطناعي موجود هناك وأيضاً في System › Admin › License & updates (`/license`)، في بطاقة **Module**. ## الوظيفة {#what-it-does} إن ميزة AI Chat (دردشة الدعم التلقائي) وAI Agent (إدارة الأجهزة الافتراضية بلغة بسيطة) لا تأتيان مع نموذج مدمج. أنت تختار **مزودك الخاص**: أي خدمة توفر واجهة `chat/completions` API متوافقة مع **OpenAI** — مثل OpenAI أو OpenRouter أو بوابة LiteLLM أو خادم vLLM الخاص بك. يقوم نظام NexCMP بتخزين نقطة النهاية ومفتاح API (مشفرين) واستخدامهما لكل ميزة ذكاء اصطناعي. أنت تدفع للمزود مباشرة. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | نقطة النهاية | عنوان URL أساسي متوافق مع OpenAI (`https://api.openai.com/v1`، `https://ai.example.com/v1`). يضيف NexCMP `/chat/completions` إلى عنوان URL ينتهي بـ `/v1`؛ ولأي عنوان URL آخر يضيف `/v1/chat/completions`؛ بينما يُستخدم عنوان URL الذي ينتهي بالفعل بـ `/chat/completions` كما هو. | | Model | نموذج يدعم **استدعاء الأدوات (الوظائف)**. يعتمد كل من AI Chat و Agent عليه. | | مفتاح API | مفتاح لتلك النقطة النهائية. يُفضل مفتاح ذو **حد إنفاق** من جانب المزود (مثل مفتاح افتراضي لـ LiteLLM بميزانية شهرية). | | الشبكة | يجب أن يتمكن خادم اللوحة من الوصول إلى نقطة النهاية عبر HTTP(S). يُسمح للعنوان المدخل في النموذج بالإشارة إلى الإنترنت فقط عبر المنافذ 80 أو 443 أو 8080 أو 8443؛ ولاستخدام عنوان داخلي، احفظ المزود أولاً ثم اختبره. | | الاعتمادات | وحدة **AI** مفعلة. بالنسبة لـ Agent، راجع [AI Agent](https://nexcmp.com/ar/docs/ai/ai-agent/#requirements). | ## تجهيز البنية التحتية {#prepare-the-infrastructure} 1. قم بالتسجيل لدى المزود وإنشاء مفتاح API. إذا كان المزود يدعم الميزانية أو حدود المعدل، فقم بتعيين حد شهري. 2. لاحظ **عنوان URL الأساسي** و**اسم النموذج** بدقة (واختيارياً، ما يصل إلى أربعة نماذج احتياطية). 3. قم باختباره من خادم NexCMP قبل إدخاله: ```bash curl -s https://ai.example.com/v1/chat/completions \ -H "Authorization: Bearer XXXX" -H "Content-Type: application/json" \ -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Reply with one word: OK"}]}' ``` إجابة بتنسيق JSON مع `choices[0].message.content` تعني أن نقطة النهاية تعمل. ## الربط في NexCMP {#connect-in-nexcmp} 1. Open **System › Settings › AI provider**. 2. في بطاقة **Module AI**، قم بتبديل الوحدة إلى وضع **الـتشغيل** (on). إلى أن يتم تفعيلها، لن يرى العملاء ميزة AI Chat أو AI Agent في البوابة. (يمكنك أيضاً تبديلها في **License & updates**.) 3. في بطاقة **Connection**، املأ الآتي: | الحقل | مثال | ملاحظات | |---|---|---| | Use this provider | مفعّل | يتطلب عنوان URL أساسياً ونموذجاً ومفتاحاً لكي يتم تفعيله. | | الاسم المعروض | `LiteLLM` | Up to 60 characters. | | Base URL (OpenAI-compatible) | `https://ai.example.com/v1` | `http://` أو `https://`، بحد أقصى 300 حرف، بدون مسافات. | | Provider API key | `sk-XXXX` | يتم تخزينه مشفراً؛ وبعد ذلك يتم عرض آخر 4 أحرف فقط. اتركه فارغاً للحفاظ على المفتاح المخزن. | | Default model | `gpt-4o-mini` | حروف وأرقام و`- _ . / : @`. | | Fallback models | `gemini-2.5-flash` | مفصولة بفاصلة، بحد أقصى 4. تُستخدم عندما يفشل النموذج الافتراضي. | | Reasoning effort | Default (not sent) | `Minimal` أو `Low` أو `Medium` أو `High`. بالنسبة لنماذج الاستدلال (Gemini و o-series)، يجيب المستوى المنخفض بشكل أسرع بكثير. اتركه على Default للنماذج العادية. | 4. انقر فوق **Save**، ثم **Test connection**. يرسل الاختبار سؤالاً قصيراً واحداً ويعرض `Connected — , ms` أو الخطأ الذي أرجعه المزود. ![صفحة مزود الذكاء الاصطناعي مع تفعيل وحدة الذكاء الاصطناعي وملء نموذج الاتصال بقيم تجريبية](https://nexcmp.com/ar/docs/images/ai/ai-providers-01-connection.webp) ### What saving does {#what-saving-does} - يتم حفظ إعدادات المزود كعنصر تكوين واحد ويتم تشفير المفتاح باستخدام AES-256-GCM، المرتبط بهذا الغرض، باستخدام المفتاح الرئيسي للتثبيت. - تم تعيين إعدادات الدعم **Primary model** و **Fallback model** (التي تستخدمها AI Chat) إلى نموذجك الافتراضي ونموذجك الاحتياطي الأول تلقائياً. - يتم تسجيل التغيير في سجل التدقيق (نقطة النهاية، النموذج، وما إذا كان المفتاح قد تغير — ولكن ليس المفتاح أبداً). ## التحقق {#verify} 1. يظهر **Test connection** باللون الأخضر. 2. سجل الدخول إلى البوابة كعميل تجريبي: تعرض القائمة الآن **AI Chat** (أو فقاعة الدردشة) و **AI Agent**. 3. اسأل AI Chat "ما هو رصيدي؟". الإجابة التي تذكر رصيدك الحقيقي تُظهر أن المزود يتعامل مع استدعاءات الأدوات بشكل صحيح. ## الحدود والملاحظات {#limits-notes} - **مزود واحد.** يستخدم NexCMP مزوداً واحداً مهيئاً للدردشة، والوكيل، والتحقيق في التذاكر. توفر نماذج الاحتياط مرونة ضمن هذا المزود. - **أمان المفتاح.** يُرسل المفتاح المحفوظ إلى نقطة النهاية المحفوظة فقط. إذا قمت بتغيير عنوان Base URL، فيجب عليك كتابة المفتاح مرة أخرى قبل الاختبار. - **الحدود لكل عميل.** مخصصة للعملاء المسجلين الدخول فقط، مع حدود رسائل لكل دقيقة ولكل دردشة. يمتلك الوكيل حد استدعاء يومي لكل حساب. راجع [AI Chat](https://nexcmp.com/ar/docs/ai/ai-chat/) و [AI Agent](https://nexcmp.com/ar/docs/ai/ai-agent/). - **الخصوصية.** تُرسل أسئلة العميل والبيانات التي تقرؤها الذكاء الاصطناعي لذلك العميل (للعرض فقط) إلى مزودك. اذكر ذلك في [privacy policy](https://nexcmp.com/ar/docs/customers/legal/) الخاص بك. - **التحكم في التكاليف.** لا يقوم NexCMP بقياس تكلفة الذكاء الاصطناعي؛ استخدِم ميزات الميزانية الخاصة بالمزود. - يمكن إيقاف تشغيل الوحدة في أي وقت: تختفي عناصر قائمة الذكاء الاصطناعي وتستجيب مسارات الذكاء الاصطناعي بالرمز 404 `module_disabled`. تلتقط بعض مهام الخلفية الخاصة بـ AI Chat (التحقيق في التذاكر، الردود المؤجلة) التغيير عند إعادة تشغيل اللوحة التالية. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | `base_url must be an http(s) URL` | مخطط مفقود أو مسافات | استخدم `https://host/v1`. | | `api_key is required to enable the provider` | No key stored | أدخل المفتاح واحفظ. | | `base_url and model are required to enable the provider` | Empty field | قم بتعبئة كلاهما. | | "تم حظر Base URL: بروتوكول http(s) العام فقط، والمنافذ 80/443/8080/8443" | اختبار عنوان داخلي غير محفوظ أو منفذ آخر | احفظ المزود أولاً ثم اختبره. | | `api_key is required (enter the key again when you change the endpoint)` | عنوان Base URL يختلف عن العنوان المحفوظ | Retype the key. | | `model: letters, digits and - _ . / : @` | Invalid character | استخدم معرف النموذج الدقيق للمزود. | | `fallback_models: up to 4 model names` | Too many | احتفظ بأربعة أو أقل. | | فشل الاختبار بالرمز 401 | مفتاح خاطئ | تحقق من المفتاح ونقطة النهاية. | | فشل الاختبار بالرمز 404 أو "model not found" | مسار أو نموذج خاطئ | تحقق من عنوان الأساس (`/v1`) ومعرف النموذج. | | `Too many tests — wait a minute` (429) | أكثر من 10 اختبارات في الدقيقة | Wait. | | لا تزال البوابة لا تظهر أي قائمة ذكاء اصطناعي | الوحدة متوقفة، أو المزود ليس "in use" | قم بتشغيل الوحدة وتفعيل المزود. | --- # AI Chat {#ai-chat} > **أين يوجد في لوحة الإدارة:** Customers › Support › Ticket، علامة التبويب **AI settings** (`/support/tickets?tab=settings`). المزود والوحدة: System › Settings › AI provider (`/settings/ai`). **أين يوجد في البوابة:** زر الدردشة العائم وصفحة `/chat` (الوضع **Ask AI**). ## الوظيفة {#what-it-does} يجيب AI Chat على أسئلة العملاء في أي ساعة، ويستعلم عن بيانات حسابهم *الخاصة* (الرصيد، الخدمات، المدفوعات، الأخطاء الأخيرة)، ويمكنه التصرف نيابة عنهم — إنشاء جهاز افتراضي، تغيير خطة — بعد تأكيد العميل. عندما تعجز المساعدة، ينقر العميل على **Talk to a human**: تنتقل الدردشة إلى فريقك على تيليجرام، وإذا لم يرد أحد في الوقت المحدد، تصبح تذكرة. تتيح إعدادات الذكاء الاصطناعي نفسها أيضاً للنظام **التحقيق في التذاكر** نيابة عن فريقك. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | Module and provider | تشغيل وحدة **AI** وحفظ [AI provider](https://nexcmp.com/ar/docs/ai/ai-providers/) واستخدامه. بدون مزود، سيخبر المساعد بأنه غير مهيأ. | | العملاء | **العملاء المسجلون فقط.** في نظام NexCMP المثبت، لا يوجد موقع عام، لذا فإن الزائر غير المسجل يرى رسالة "Sign in to use AI Chat". | | قناة طاقم العمل (اختياري) | بوت ودردشة على Telegram لتنبيهات المشرفين (انظر [Telegram notifications](https://nexcmp.com/ar/docs/administration/telegram-notifications/)). تتلقى نفس القناة عمليات تحويل الدردشة ومسودات التذاكر. | | الاعتمادات | [AI provider](https://nexcmp.com/ar/docs/ai/ai-providers/). | ## تجهيز البنية التحتية {#prepare-the-infrastructure} غير مطلوب بخلاف مزود الذكاء الاصطناعي. إذا كنت تريد تحويل المحادثات إلى طاقم العمل: 1. أنشئ بوت Telegram باستخدام @BotFather وسجل الرمز (token). 2. أنشئ مجموعة أو استخدم محادثتك الخاصة مع البوت، وسجل معرف الدردشة (chat ID). 3. أدخل كليهما ضمن System › Settings › Admin alerts (انظر [Telegram notifications](https://nexcmp.com/ar/docs/administration/telegram-notifications/)). تعيد ميزات الدعم استخدام هذا البوت والدردشة. ## الربط في NexCMP {#connect-in-nexcmp} 1. تأكد من تشغيل وحدة الذكاء الاصطناعي وأن اختبار المزود ينجح باللون الأخضر ([AI provider](https://nexcmp.com/ar/docs/ai/ai-providers/)). 2. افتح **Customers › Support › Ticket** وحدد علامة التبويب **AI settings**. يُظهر أعلى البطاقة اليسرى ثلاثة وسوم: *AI provider: configured*، و*Telegram: channel present*، و*On shift* أو *Off shift*. 3. البطاقة اليسرى **AI + Telegram**: | المفتاح أو الحقل | القيمة الافتراضية | المعنى | |---|---|---| | الذكاء الاصطناعي يفحص التذاكر تلقائياً | On | بالنسبة للتذكرة أو الرسالة الجديدة، يقرأ الذكاء الاصطناعي بيانات العميل (للقراءة فقط) ويكتب السبب المحتمل وردا مقترحا **كملاحظة داخلية**. ولا يرسل شيئاً أبداً للعميل. | | تنبيهات Telegram للمشرف | On | تصل الملاحظة على Telegram مع أزرار Send و Edit و Skip. | | الرد الآلي بالذكاء الاصطناعي | معطل | يرسل إجابات إرشادية بسيطة أو متعلقة بالمبيعات بنفسه عندما تتحقق جميع شروط الأمان (مستوى ثقة 85% أو أكثر، وعدم وجود تحذيرات)؛ ويتم الإرسال بعد 3 دقائق مع إمكانية الإلغاء على Telegram. | | التصنيفات المسموح لها بالرد الآلي | `how_to`, `sales` | هذه فقط. | | النموذج الأساسي، نموذج الاحتياط | يتم تعيينه من المزود | اتركه عادة كما تم حفظه بواسطة صفحة مزود الذكاء الاصطناعي. | | معرف مستخدم Telegram المسموح له بالتصرف | فارغ | الحقل الفارغ يعني دردشة قناة التنبيهات. | 4. البطاقة اليمنى **Live chat (customer widget)**: | الحقل | القيمة الافتراضية | المعنى | |---|---|---| | تفعيل أداة الدردشة | On | فقاعة الدردشة و صفحة `/chat`. | | ساعات الدعم (توقيت فيتنام) | `08:00-22:00` | الوقت المتوقع أن يجيب فيه طاقم العمل على Telegram. خارج هذه الأوقات، أو عندما لا توجد قناة Telegram، يقوم خيار **Talk to a human** بتحويل الدردشة إلى تذكرة فوراً. | | الحد الأقصى لانتظار طاقم العمل (بالدقائق)، ثم التحويل إلى تذكرة | 10 | من 1 إلى 240. | | عمليات الذكاء الاصطناعي / يوم / عميل | 40 | من 1 إلى 1000. بعد تجاوز الحد، يدعو المساعد العميل للتحدث إلى بشري. | | الدردشات الجديدة / ساعة / IP | 20 | من 1 إلى 1000. | | **رابط Zalo OA** | فارغ | `https://zalo.me/...` يعرض الزر **Chat on Zalo** (مع رمز الاستجابة السريعة QR code) في الدردشة. إبقاؤه فارغاً يخفيه. | | **رابط Telegram** | فارغ | `https://t.me/...` يعرض زر **Telegram**. إبقاؤه فارغاً يخفيه. | | الحد الأقصى اليومي لعمليات الذكاء الاصطناعي على مستوى النظام للعملاء المسجلين | 2000 | | | الحد الأقصى اليومي على مستوى النظام للضيوف | 500 | مجموعة خاصة؛ لا تُستخدم عندما يتعذر على الضيوف الدردشة. | | الحد الأقصى اليومي على مستوى النظام لتحقيقات التذاكر التلقائية | 200 | | | مسار المسؤول (زر Telegram "فتح المسؤول") | فارغ | رابط المسؤول الخاص بك، على سبيل المثال `https://cloud.example.com/admin`. | يتم حفظ كل تبديل أو حقل عند تغييره. 5. **Reply templates** (العنوان، اللغة VI/EN/ZH، النص حتى 4,000 حرف) في الأسفل تمنح الموظفين ردوداً جاهزة. ![علامة تبويب إعدادات AI مع مفاتيح AI وTelegram وحدود الدردشة المباشرة وروابط الاختصارات](https://nexcmp.com/ar/docs/images/ai/ai-chat-01-settings.webp) ![صفحة دردشة العميل مع المساعد وأزرار اختصارات Zalo وTelegram وخيار التحدث إلى موظف بشري](https://nexcmp.com/ar/docs/images/ai/ai-chat-02-portal.webp) ## ما يمكن للمساعد فعله وما لا يمكنه فعله {#what-the-assistant-can-and-cannot-do} - **القراءة:** يبحث في قاعدة المعارف والوثائق العامة الخاصة بك، ويقرأ بيانات العميل المسجل الدخول نفسه عبر أدوات للقراءة فقط. ولا يمكنه رؤية عميل آخر. - **التنفيذ:** يستخدم أذونات API الخاصة بالعميل نفسه. يتم تشغيل طلب *القراءة* فوراً. أي شيء يغير أو يكلف أموالاً ينشأ عنه **بطاقة تأكيد** ("تحتاج إلى تأكيدك"، مع وسوم *تكلفة مالية* أو *حذف*)؛ ولا يحدث شيء حتى ينقر العميل على **Confirm**. يمكن أن تحتوي الدردشة على 3 بطاقات معلقة كحد أقصى والحساب على 10 إجراءات كتابة مؤكدة كحد أقصى في الساعة. - **أبداً:** لا يمكنه فتح وحدات التحكم، أو إنشاء رموز SSH أو وحدة التحكم، أو تنزيل ملفات وصول Kubernetes، أو إعادة تعيين كلمات المرور، أو عرض الأسرار مثل كلمات مرور الوكيل أو أسرار S3. لا يتم وضع الأسرار أبداً في سياق النموذج أو سجل الدردشة. - **الأمان:** تمر إجاباته عبر مرشح مخرجات؛ ويتم التعامل مع نص العميل ونتائج الأدوات كبيانات وليس كتعليمات. - **لافتة الأمان:** تظهر في الدردشة عبارة "تمت الإجابة بواسطة مساعد ذكاء اصطناعي — قد يكون غير دقيق. تحدث إلى موظف بشري لأي أمر حرج." ## التحويل إلى الموظفين {#staff-hand-off} 1. ينقر العميل على **Talk to a human** وقد يترك بريداً إلكترونياً. 2. تصل رسالة تحتوي على المحادثة إلى دردشة Telegram الخاصة بالموظفين. يجيب الموظفون بالرد على تلك الرسالة؛ ويظهر الرد في دردشة العميل كـ "[brand] Support". 3. إذا لم يجب أحد خلال وقت الانتظار (الافتراضي 10 دقائق)، تصبح الدردشة تذكرة ضمن **Customers › Support › Ticket**. ويحدث الشيء نفسه فوراً خارج ساعات الدعم أو عند عدم تكوين Telegram، ويتم إعلام العميل بفتحتذكرة. 4. يرى المسؤولون أيضاً الدردشة الجارية في علامة التبويب **Live chat**. ## التحقق {#verify} 1. سجّل الدخول كعميل اختبار، وافتح الدردشة واطرح سؤالاً حول خدماتك. سيجيب المساعد. 2. اطلب منه إنشاء شيء يتكلف مالاً: تظهر بطاقة تأكيد ولا يتم إنشاء أي شيء حتى تنقر على **Confirm**. 3. انقر على **Talk to a human**. تصل الرسالة إلى دردشة Telegram الخاصة بك (إذا تم تكوينها) أو تظهر تذكرة بعد وقت الانتظار. 4. مع إدخال روابط Zalo وTelegram، يظهر كلا زرّي الاختصار في الدردشة. ## الحدود والملاحظات {#limits-notes} - **حدود المعدل (لكل عنوان IP):** 20 رسالة في الدقيقة وعدد قليل من عمليات التحويل في الساعة؛ **40 رسالة لكل محادثة**. هذه الحدود ثابتة. - **التكلفة:** كل تفاعل مع AI يستפיد مزود الخدمة الخاص بك. قم بتخفيض **AI turns / day / customer** لتقييد الإنفاق. - **الرد التلقائي معطل افتراضياً.** قم بتفعيله فقط بعد مراقبة المسودات لفترة من الوقت. - **اللغات:** يجيب المساعد بلغة العميل؛ ويتم اكتشاف اللغة الفيتنامية من النص. - **الموزعون:** تستخدم مواقع الموزعين التذاكر بدلاً من أداة العرض (Widget). ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | العملاء لا يرون الدردشة | وحدة AI معطلة، أو خيار **Enable chat widget** معطل | قم بتفعيل الاثنين معاً. | | "Sign in to use AI Chat" | الvisitor غير مسجل الدخول | متوقع في NexCMP: سجل الدخول أولاً. | | يقول المساعد أنه لم يتم تكوين أي مزود AI | المزود مفقود، غير قيد الاستخدام، أو المفتاح مفقود | أكمل [AI provider](https://nexcmp.com/ar/docs/ai/ai-providers/). | | يرد الـ AI بـ "talk to a human" بعد أسئلة قليلة | تم الوصول إلى الحد اليومي لكل عميل | ارفع **AI turns / day / customer**. | | علامة Telegram تعرض "no channel" | معرّف البوت أو الدردشة غير مُكوّن | قم بإعداد [Telegram notifications](https://nexcmp.com/ar/docs/administration/telegram-notifications/). | | زر Zalo أو Telegram مفقود | حقل الرابط فارغ | املأ الرابط. | | "Too many requests" في المحادثة | أكثر من 20 رسالة في الدقيقة من عنوان IP واحد | انتظر دقيقة واحدة. | | محادثة الدردشة ممتلئة | تم الوصول إلى 40 رسالة | ابدأ محادثة جديدة. | --- # AI Agent {#ai-agent} > **أين في لوحة التحكم:** System › Settings › AI provider (`/settings/ai`) — مفتاح الوحدة والمزود؛ System › Admin › License & updates (`/license`) — مفتاح الوحدة. **أين في البوابة:** AI Agent (`/ai/agent`) والصفحة `/chat/agent`، أو وضع **Agent** داخل المحادثة. ## الوظيفة {#what-it-does} يتصل AI Agent بـ Linux VM الخاص بالعميل عبر SSH ويقوم بتنفيذ المهام الموصوفة بلغة بسيطة: "check system health"، "install Docker"، "find recent errors"، "free up disk space". يعرض كل أمر يقترحه ونتيجته. يمكن تشغيل الأوامر التي للقراءة فقط تلقائيًا؛ أي شيء يغير الخادم ينتظر العميل للضغط على **Run**. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | وحدة ومزود الـ AI | وحدة **AI** قيد التشغيل و[AI provider](https://nexcmp.com/ar/docs/ai/ai-providers/) فعال. يحتاج Agent أيضًا إلى نموذج يدعم استدعاء الأدوات. | | `openssh-client` على خادم اللوحة | يقوم Agent بتنفيذ الأوامر باستخدام برنامج اللوحة الخاص `ssh` (`/usr/bin/ssh`). يقوم المثبت بتثبيت `openssh-client`؛ تحقق باستخدام `ssh -V`. بدون ذلك، يبلغ Agent بأن "ssh client is not installed on the panel server". | | لا توجد بوابة SSH منفصلة | في التثبيت الافتراضي، يتم استخدام SSH المدمج ولا يلزم استخدام طرفية الويب `ssh-proxy` **أبدًا**. فقط عندما يتم تمكين ميزة *web SSH* الاختيارية (`feature_ssh_web`) وتثبيت خدمة `ssh-proxy`، يمر Agent عبر `ssh-proxy` بدلاً من ذلك. | | الشبكة | يجب أن يتمكن خادم اللوحة من الوصول إلى عنوان IP الخاص بـ VM على منفذ SSH الخاص به (22 افتراضيًا). تحقق من جدران الحماية ومجموعات الأمان بين اللوحة وشبكة الضيف. | | VM | مملوك للعميل، **قيد التشغيل**، غير مقفل، **Linux** (يتم رفض أجهزة Windows VMs)، مع عنوان IP عام أو قابل للوصول. | | بيانات اعتماد SSH | اسم مستخدم وكلمة مرور تسجيل الدخول لـ VM المخزنة بواسطة NexCMP (تم حفظها عند إنشاء VM أو إعادة تعيين كلمة المرور الخاصة بها، مشفرة)، أو مفتاح عمليات اللوحة إذا كان مثبتًا. إذا لم يتوفر أي منهما، يقول Agent إنه لا يمكنه تسجيل الدخول. | ## تجهيز البنية التحتية {#prepare-the-infrastructure} 1. تحقق من عميل SSH على خادم اللوحة: ```bash ssh -V sudo apt-get install -y openssh-client # only if missing ``` 2. تحقق من قدرة خادم اللوحة على فتح SSH إلى جهاز ضيف VM: ```bash nc -vz 198.51.100.10 22 ``` استبدل العنوان بعنوان IP الخاص بـ VM تجريبي. إذا فشل ذلك، قم بإصلاح التوجيه أو جدار الحماية أولاً. 3. تأكد من أن الجهاز الضيف يسمح بتسجيل الدخول بكلمة المرور للمستخدم الذي خزنه NexCMP (بعض صور السحاب تعطل ذلك)، أو من تثبيت مفتاح عمليات اللوحة على الجهاز الضيف. ## الربط في NexCMP {#connect-in-nexcmp} 1. أكمل [AI provider](https://nexcmp.com/ar/docs/ai/ai-providers/): تم تشغيل الوحدة، وحفظ المزود، وظهرت **Test connection** باللون الأخضر. 2. لا شيء آخر يتم إعداده من جانب المشرف. مفتاح الوحدة يجعل إدخالات **AI Agent** تظهر في بوابة العميل. 3. بصفة عميل: افتح **AI Agent**، واختر خادماً قيد التشغيل وانقر على **Choose server**. تختبر الصفحة أولاً اتصال SSH باستخدام أمر ثابت غير ضار (دون استخدام استدعاء الذكاء الاصطناعي) وتظهر عبارة *SSH connected* أو سبب الفشل. 4. اكتب مهمة أو اختر بداية سريعة (*Check system health*، *Install Docker*، *Install Nginx*، *Find recent errors*، *Security check*، *Free up disk space*). ## كيف تُنفّذ الأوامر {#how-it-runs-commands} - **من أين:** خادم اللوحة، باستخدام عميل النظام `ssh`، بأمر واحد غير تفاعلي في كل مرة. الهدف هو دائماً عنوان IP الخاص بالجهاز الافتراضي **من قاعدة البيانات**، وليس أبداً من الطلب؛ ولا يمكن الوصول إلا إلى الجهاز الافتراضي الخاص بالمالك والذي يعمل وغير مقفل. - **المصادقة:** تُمرَّر كلمة المرور المخزنة عبر مساعد أحادي التشغيل `SSH_ASKPASS` في بيئة العملية — ولا يُكتب على القرص أو يوضع في سطر الأوامر. مفاتيح المضيف غير مثبتة (يتم إعادة تثبيت الأجهزة الافتراضية بمفاتيح جديدة). يقتصر الناتج لكل أمر على 200 كيلوبايت ولكل أمر حد زمني (60 ثانية). - **حلقة الوكيل:** يقترح الذكاء الاصطناعي الأوامر ويقرأ المخرجات؛ وتنتهي الجولة الواحدة بعد **10 خطوات** على الأكثر. - **الوضعيات:** | Mode | السلوك | |---|---| | **Confirm** | كل أمر ينتظر **Run**. | | **Auto** | فقط الأوامر التي تجتاز قائمة سماح صارمة للقراءة فقط هي التي تُنفَّذ تلقائياً (على سبيل المثال `df -h` و`ps` و`journalctl`). أي شيء آخر، وأي شيء لا يستطيع المحلل التحقق منه بيقين (المتغيرات، استبدال الأوامر، إعادة التوجيه إلى الملفات)، ينتظر **Run**. | - **تصنيفات المخاطر:** الأوامر التي تستبدل الملفات أو تحذفها، أو تكتب على الأقراص، أو تغيّر الحسابات أو مفاتيح SSH، أو ترسل بيانات إلى خادم خارجي، أو تفتح اتصالات شبكة خام، أو تشغل تعليمة برمجية مبهمة، أو تنزل نص برمجي وتشغله، أو توقف تشغيل الجهاز أو تعيد تشغيله، أو تصل إلى خوادم أخرى، تُظهر دائماً **Needs confirmation**، حتى في وضع Auto. - **المخرجات غير الموثوقة:** يتم عرض مخرجات الأوامر للنموذج كبيانات غير موثوقة؛ ولا يتم اتباع التعليمات الموجودة بداخلها. ## التحقق {#verify} 1. اختر خادم اختبار قيد التشغيل. تعرض الصفحة *SSH connected*. 2. اطلب "Check CPU, RAM and disk". في وضع Auto، تُنفَّذ أوامر القراءة فقط وتلخص الإجابة نتائجها. 3. اطلب "Install Nginx". يظهر أمر التثبيت مع **Run** و**Skip**؛ ولا يُنفَّذ أي شيء حتى تضغط على **Run**. 4. يُظهر العداد في الأعلى عدد استدعاءات الذكاء الاصطناعي المستخدمة اليوم (على سبيل المثال `3/300`). ## الحدود والملاحظات {#limits-notes} - **الحد اليومي:** 300 استدعاء ذكاء اصطناعي لكل عميل يومياً (التوقيت العالمي المنسق UTC)؛ ويتم إعادة تعيينه عند 00:00 بالتوقيت العالمي المنسق. عند استنفاده، يجيب الوكيل بـ "Daily AI quota reached". - **التزامن:** حد أقصى لتشغيل 2 Agent لكل عميل في نفس الوقت؛ وتنفذ الجلسة خطوة واحدة في كل مرة. - **الجلسات:** حتى 100 رسالة لكل جلسة، 4,000 حرف لكل رسالة. تنتمي الجلسة إلى جهاز افتراضي واحد؛ وفي حال حذف الجهاز الافتراضي أو نقله، تصبح الجلسة القديمة للقراءة فقط. - **جهاز افتراضي مقفل أو متوقف، أو ويندوز:** يظهر الجهاز الافتراضي كـ *Locked* أو *Stopped* أو *Windows* أو *No address* ولا يمكن اختياره. - **انتحال الشخصية:** لا يمكن للمشرف الذي ينتحل صفة عميل استخدام ميزات بيانات اعتماد الوكيل (انظر [Log in as a customer](https://nexcmp.com/ar/docs/customers/login-as/)). - **المسؤولية:** يمكن للوكيل ارتكاب الأخطاء. تخبر البوابة العملاء بمراجعة الأوامر قبل تشغيلها. أبلغ العملاء في الشروط والأحكام الخاصة بك بأنهم مسؤولون عن الأوامر التي يوافقون عليها. - إيقاف تشغيل وحدة الذكاء الاصطناعي يزيل إدخالات الوكيل وترجع المسارات الخطأ 404 `module_disabled`. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | "عميل ssh غير مثبت على خادم اللوحة (apt install openssh-client)" | No `ssh` binary | `sudo apt-get install -y openssh-client`. | | "تعذر على الوكيل تسجيل الدخول" / `ssh: no saved credentials for this VM` | لا توجد كلمة مرور مخزنة ولا مفتاح عمليات | أعد تعيين كلمة مرور الجهاز الافتراضي في البوابة لكي يتم حفظها مرة أخرى، أو ثبّت مفتاح العمليات. | | "لم يستجب الخادم في الوقت المناسب" | جدار الحماية، أو SSH لا يستمع، أو الجهاز الافتراضي مشغول | اختبر `nc -vz 22` من خادم اللوحة؛ وابدأ `sshd` في الجهاز الافتراضي. | | "تعذر الوصول إلى SSH على هذا الخادم" | التوجيه أو مجموعة الأمان | اسمح لخادم اللوحة بالوصول إلى الجهاز الافتراضي عبر المنفذ 22. | | "الجهاز الافتراضي لا يعمل" / "ممنوع" | الجهاز الافتراضي متوقف، أو مقفل، أو محذوف، أو لا ينتمي للعميل | قم بتشغيله، أو إلغاء قفله، أو اختر جهاظاً آخر. | | "غير متوفر: N (متوقف، مقفل أو ويندوز)" | Reasons listed above | يجب أن يكون الجهاز الافتراضي يعمل بنظام Linux وفي حالة تشغيل. | | "بوابة SSH غير متوفرة مؤقتاً" | ميزة ويب SSH ممكنة ولكن `ssh-proxy` متوقف عن العمل | قم بتشغيل `ssh-proxy`، أو عطل ميزة ويب SSH لاستخدام SSH المدمج. | | "الذكاء الاصطناعي يستجيب ببطء شديد (أكثر من 90 ثانية)" | Provider slow | استخدم نموذجاً أسرع أو **Reasoning effort** أقل. | | "تم بلوغ حصة الذكاء الاصطناعي اليومية" | 300 calls used | Wait until 00:00 UTC. | | "هذه الجلسة لا تزال قيد التشغيل" | دورة أخرى قيد التنفيذ | Wait or press **Stop**. | --- # REST API > **أين في البوابة:** مرجع API في `https:///apidoc` (عام) ومفاتيح API في `/api-keys`. **أين في لوحة المشرف:** Customers › API keys (`/customers/apikeys`) يعرض المفاتيح التي أنشأها العملاء. ## الوظيفة {#what-it-does} كل إجراء يمكن للعميل القيام به في البوابة — سرد الأجهزة الظртуаية والتحكم بها، قراءة الفواتير، إدارة SSH Keys، Kubernetes، التخزين، تذاكر الدعم — متاح عبر REST API مُوَصَّل بالإصدارات تحت `https:///v1/`. يستدعي العملاء ذلك من النصوص البرمجية وCI باستخدام **API key** بنطاق محدد. نفس الـ API يغذي [`cmp` command-line tool](https://nexcmp.com/ar/docs/developers/cmp-cli/) و[MCP server](https://nexcmp.com/ar/docs/developers/mcp/)، ويتم إنشاء المرجع من التثبيت قيد التشغيل، لذا فهو يعرض دائماً بدقة الميزات التي قمت بتفعيلها. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | عنوان HTTPS العام | يتم تقديم API على نطاقك الرئيسي (وعلى نطاق كل موزع خاص به). | | An API key | تم إنشاؤها بواسطة العميل في البوابة؛ راجع [API keys](https://nexcmp.com/ar/docs/developers/api-keys/). | | الاعتمادات | لا شيء. نقاط النهاية لوحدة لم تقم بتفعيلها (مثل Kubernetes أو Object Storage) مخفية من المرجع ومرفوضة. | ## تجهيز البنية التحتية {#prepare-the-infrastructure} لا شيء لتثبيته. إذا كان هناك خادم وكيل عكسي (reverse proxy) أمام NexCMP، فقم بتوجيه `/v1/` و`/mcp` و`/cli/` و`/apidoc` إلى لوحة التحكم (تكوين nginx الخاص بالمثبت يقوم بذلك بالفعل). ## الربط في NexCMP {#connect-in-nexcmp} ### The interactive reference {#the-interactive-reference} افتح `https://cloud.example.com/apidoc` (استبدل المضيف بنطاقك؛ ويرى عملاء الموزع المرجع على نطاق الموزع، مع اسم الموزع). يحتوي على توثيق لنقاط النهاية مع أمثلة للطلب والاستجابة بلغة curl، و`cmp` CLI، وJavaScript، وPython، وGo، ومربع بحث (Ctrl أو Cmd + K)، ولوحة **Try it**. ترسل ميزة Try it الطلبات إلى نفس الموقع فقط، باستخدام مفتاح يلسقه الزيارة (يُحفظ في جلسة المتجر)؛ وهي للقراءة فقط افتراضياً، وتتطلب استدعاءات الكتابة أو المدفوعة مفتاح تبديل إضافياً وتأكيداً. ### التنزيلات والمستندات القابلة للقراءة آلياً {#downloads-and-machine-readable-documents} جميعها عامة ولا تحتاج إلى مفتاح ويتم إنشاؤها لكل موقع: | URL | المحتوى | |---|---| | `/apidoc` | المرجع التفاعلي. | | `/v1/public/openapi.json` | مستند OpenAPI 3.1. | | `/v1/public/openapi.yaml` | نفسه، بصيغة YAML. | | `/v1/public/postman.json` | مجموعة Postman. | | `/v1/public/insomnia.json` | تصدير Insomnia. | | `/v1/public/api.md` | المرجع في ملف Markdown واحد. | | `/v1/public/api-catalog` | JSON خفيف: العلامة التجارية، عنوان URL الأساسي، بادئة المفتاح، كل نطاق (scope) وكل نقطة نهاية مع طريقة الاتصال، والمسار، والنطاق، وما إذا كانت تتطلب `Idempotency-Key`. | ```bash curl -s https://cloud.example.com/v1/public/api-catalog | python3 -m json.tool | head -40 curl -sO https://cloud.example.com/v1/public/openapi.yaml ``` في Postman، اختر **Import › Link** والصق `https://cloud.example.com/v1/public/postman.json`. توفر صفحة المرجع أيضاً عملاء API بملف واحد לـ JavaScript وPython. ### المصادقة {#authentication} أرسل المفتاح في ترويسة `Authorization`: ```bash curl -s https://cloud.example.com/v1/billing/wallet \ -H "Authorization: Bearer vk_XXXX" ``` - تبدأ مفاتيح العملاء بـ `vk_`. المفاتيح **مرتبطة بالموقع**: المفتاح الذي يتم إنشاؤه على `cloud.example.com` لا يعمل على نطاق الموزع. - رموز جلسات المتصفح (`pt_...`) مخصصة للوحة التحكم فقط؛ استخدم مفتاحاً للأتمتة. - تحدد **نطاقات** (scopes) المفتاح ما يُسمح له باستدعائه؛ ويُرجع النطاق المفقود خطأ HTTP 403 `scope_required`. راجع [API keys](https://nexcmp.com/ar/docs/developers/api-keys/). - تحقق من المفتاح باستخدام `GET /v1/apikeys/self`: فهو يُرجع اسم المفتاح المستدعي ونطاقاته وتاريخ انتهاء صلاحيته ومعدل الطلبات المتبقي المسموح به (يمكن لكل مفتاح استدعاؤه). ### الأمثلة {#examples} ```bash # List virtual machines curl -s "https://cloud.example.com/v1/vm?page=1" -H "Authorization: Bearer vk_XXXX" # Start one (needs vm:write) curl -s -X POST https://cloud.example.com/v1/vm/3f2a1c9e-0000-4000-8000-000000000000/start \ -H "Authorization: Bearer vk_XXXX" # Create a VM (paid: needs vm:create and an Idempotency-Key) curl -s -X POST https://cloud.example.com/v1/vm \ -H "Authorization: Bearer vk_XXXX" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d @vm.json ``` خذ حقول الطلب الدقيقة لكل عملية من `/apidoc`. ### الأخطاء {#errors} كل خطأ هو بتنسيق JSON مع قيمة `code` ثابتة و`message` مقروءة بشرياً: ```json {"error": {"code": "scope_required", "message": "Key lacks scope vm:write"}} ``` | HTTP | الرمز النموذجي `code` | المعنى | |---|---|---| | 401 | `unauthenticated`, `key_invalid`, `key_revoked`, `key_expired`, `key_ip_denied`, `site_mismatch`, `api_keys_disabled` | مفتاح مفقود أو غير معروف، مُلغى، منتهي الصلاحية، عنوان IP للمستدعي خارج قائمة السماح الخاصة بالمفتاح، مفتاح من موقع آخر، أو مفاتيح API معطلة. | | 403 | `scope_required`, `endpoint_not_public`, `account_blocked`, `quota_exceeded`, `impersonate_forbidden` | المفتاح يفتقر إلى النطاق؛ نقطة النهاية غير متوفرة للمفاتيح؛ الحساب مقفل؛ تم بلوغ [quota](https://nexcmp.com/ar/docs/billing/quotas/)؛ إجراء غير مسموح به في جلسة منتحلة. | | 404 | `not_found` | غير موجود — يُعاد أيضاً للموارد التي تملكها جهة أخرى. | | 422 | `invalid_argument` | خطأ تحقق (الحقل المُسمَّى في الاستجابة). | | 429 | `rate_limited` | طلبات كثيرة جداً؛ انتظر حتى `Retry-After`. | | 503 | `maintenance` | وضع الصيانة مفعل: عمليات القراءة تعمل، وعمليات الكتابة مرفوضة. | ### حدود المعدل {#rate-limits} | الحد | القيمة الافتراضية | |---|---| | لكل مفتاح | 120 طلباً في الدقيقة | | لكل حساب (جميع المفاتيح معاً) | 300 طلب في الدقيقة | تحمل كل استجابة `X-RateLimit-Limit`، و`X-RateLimit-Remaining`، و`X-RateLimit-Reset`؛ وتضيف استجابة 429 الحقل `Retry-After`. ### منع التكرار {#idempotency} الأوامر التي تكلف مالاً أو لا يمكن تكرارها (إنشاء، تغيير الخطة، شراء، حذف ...) **تتطلب** ترويسة `Idempotency-Key` (أي سلسلة نصية تصل إلى 200 حرف؛ يعد معرف UUID خياراً جيداً). أرسل نفس المفتاح مرة أخرى بعد انتهاء المهلة وسيعيد الخادم النتيجة **الأصلية** (مع `Idempotency-Replayed: 1`) بدلاً من تكرار العملية. إعادة استخدام المفتاح لأمر مختلف يُرجع 422؛ والطلب الذي لا يزال قيد التنفيذ يُرجع 409/`Retry-After`. بدون هذه الترويسة، يتم رفض الطلب المدفوع. ## التحقق {#verify} 1. أنشئ مفتاحاً بنطاق `vm:read` في لوحة التحكم (**API keys › Create key**). 2. تنفيذ: ```bash curl -i https://cloud.example.com/v1/apikeys/self -H "Authorization: Bearer vk_XXXX" ``` ستحصل على HTTP 200 وترويسات الحد الأقصى للمعدل. 3. `curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"` يعرض الأجهزة الوهمية للحساب. في البوابة، يظهر عمود **Last used** للمفتاح و**Key usage log** الاستدعاءات. ## الحدود والملاحظات {#limits-notes} - **غير متاح للمفتاح أبداً:** تعبئة الرصيد، السحب، تغيير البطاقات أو التعبئة التلقائية، تغيير كلمة المرور، البريد الإلكتروني أو المصادقة الثنائية (2FA)، حذف الحساب، أو إنشاء أو تعديل أو إلغاء مفاتيح أخرى. تتطلب هذه الإجراءات جلسة متصفح مسجلة الدخول. - **الوحدات المخفية:** يعرض المرجع ومستند OpenAPI فقط الميزات المُفعّلة على ذلك الموقع. - **حجم الاستجابة والتقسيم إلى صفحات:** نقاط نهاية القوائم مُقسمة إلى صفحات (`page`، `per_page`)؛ اقرأ مستند OpenAPI لكل نقطة نهاية. - **الوقت والمال:** المبالغ المالية تكون بسنتات USD ما لم يُذكر اسم الحقل بخلاف ذلك. - **واجهة برمجة تطبيقات المشرف:** وحدة تحكم المشرف لها صفحة **System › Admin › API** الخاصة بها ومفاتيح المشرف (`ofw_...`) للإدارة؛ وهي منفصلة عن واجهة برمجة تطبيقات العملاء الموضحة هنا. - **إصدار النسخ:** بادئة المسار `/v1` ثابتة؛ وقد تُضاف حقول جديدة إلى الاستجابات. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | 401 على مفتاح جديد | المفتاح من نطاق آخر، أو منتهي الصلاحية، أو مُدخَل بمسافات | أنشئ المفتاح على النطاق الذي تستدعيه؛ وتحقق من رأس `Authorization: Bearer vk_...`. | | 403 `scope_required` | نطاق مفقود | عدّل المفتاح في البوابة وأضف النطاق. | | 401 `key_ip_denied` أو `site_mismatch` | المفتاح مقصور على عناوين IP أخرى ("allowed IPs") أو مُنشأ على نطاق آخر | أضف عنوان IP الخاص بخادمك إلى عناوين IP المسموح بها للمفتاح، أو استدعِ النطاق الذي أُنشئ فيه المفتاح. | | 404 على جهاز وهمي موجود | الجهاز الوهمي ينتمي إلى حساب آخر | استخدم مفتاح المالك. | | 400/422 تطلب `Idempotency-Key` | عملية مدفوعة بدون الرأس المطلوب | أضف `Idempotency-Key: `. | | 429 | تجاوز الحد المسموح به | تراجع؛ واستخدم `Retry-After`. | | `/apidoc` يعرض أقل من المتوقع | الوحدة مُعطّلة | فَعِّل الوحدة في License & updates. | --- # مفاتيح API والنطاقات {#api-keys-and-scopes} > **أين تجدها في البوابة:** مفاتيح API (`/api-keys`). **أين تجدها في لوحة المشرف:** Customers › Customers › API keys (`/customers/apikeys`). ## الوظيفة {#what-it-does} يتيح **API key** لأي نص برمجي، أو مهمة تكامل مستمر (CI)، أو [`cmp` CLI](https://nexcmp.com/ar/docs/developers/cmp-cli/)، أو مساعد ذكاء اصطناعي ([MCP](https://nexcmp.com/ar/docs/developers/mcp/)) استدعاء [REST API](https://nexcmp.com/ar/docs/developers/api/) نيابةً عن عميل واحد، مع الصلاحيات (**النطاقات**) الممنوحة فقط. تبدأ مفاتيح العملاء بـ `vk_`. يمكنها قراءة الخدمات وإدارتها ولكن لا يمكنها **أبدًا** المساس بالمال أو الحساب نفسه. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | العميل | جلسة بوابة مسجلة الدخول (لا يمكن لمفتاح إنشاء أو تعديل مفاتيح أخرى، ولا يمكن للمشرف انتحال صفة عميل فعل ذلك أيضاً). | | المفتاح | مفاتيح API مُفعّلة افتراضياً. إذا تم إيقافها، ستستجيب الاستدعاءات برمز 401 `api_keys_disabled`. | | الاعتمادات | لا تظهر نطاقات المنتج إلا عندما يكون هذا المنتج مُفعّلاً على الموقع. | ## إنشاء مفتاح (للعميل) {#create-a-key-customer} 1. سجّل الدخول إلى البوابة وافتح **API keys**. 2. انقر على **Create key**. 3. املأ النموذج: | الحقل | القاعدة | |---|---| | **Key name** | مطلوب، بحد أقصى 60 حرفاً ("deploy server"، "backup script"). | | **ما يمكن أن فعله هذا المفتاح** | حدد النطاقات التي تحتاجها — نطاق واحد على الأقل. يجب ألا يحصل مفتاح القراءة فقط على أي نطاق كتابة. توخ الحذر مع النطاقات التي تكلف مالاً أو تحذف بيانات. | | **Expiry** | أبداً، أو 30 يوماً، أو 90 يوماً، أو 1 سنة (يقبل API من 1 إلى 3650 يوماً). | | **السماح بالاتصالات من هذه عناوين IP فقط** | عنوان IP واحد أو نطاق CIDR في كل سطر، حتى 20 (IPv4 أو IPv6). الحقل الفارغ يعني أي عنوان IP. ثبت عنوان IP الخاص بخادومك كلما استطعت. | 4. أكد النموذج. يظهر المفتاح **مرة واحدة** في نافذة "تم إنشاء المفتاح — يتم إظهاره مرة واحدة". انسخه وانقر على **I saved the key**. يتم تخزين تجزئة SHA-256 فقط، لذا لا يمكن حتى للمشرف قراءته مرة أخرى؛ وإذا فقدته، فالغِ مفتاحك وأنشئ مفتاحاً جديداً. 5. تظهر البوابة أيضاً أمر `curl` جاهزاً لاختبار المفتاح. يبدو المفتاح كـ `vk_` يليه سلسلة عشوائية طويلة. تظهر القائمة الأحرف الأولى فقط (على سبيل المثال `vk_a1b2c3d4`)، والنطاقات، وواريخ الانتهاء، وتاريخ اخر استخدام، وعدد الطلبات، والحالة (*Active*، *Expired*، *Revoked*). ### التعديل، الإلغاء، التدقيق {#edit-revoke-audit} - **Edit** يغير الاسم، النطاقات، عناوين IP المسموح بها وتاريخ الانتهاء. لا يُسمح بذلك خلال الجلسة المنتحلة. - **Revoke** يوقف المفتاح على الفور ولا يمكن التراجع عن ذلك. يُحتفظ بالصف لتبقى سجلات استخدامه متاحة. - **Key usage log** يوضح أوامر الكتابة وكل خطأ خلال الـ 60 يوماً الماضية: الوقت، الطلب، المفتاح، النتيجة وعنوان IP المصدر. - يمكن أن يحتوي الحساب على **10 مفاتيح نشطة** كحد أقصى افتراضياً. - تظهر المفاتيح المُنشأة عبر سطر الأوامر CLI أو تسجيل دخول MCP تحت **Connected apps & devices** ويمكن إبطالها من هناك. ## النطاقات {#scopes} أسماء النطاقات لها الشكل `area:action`. النطاقات المعروضة تعتمد على المنتجات التي قمت بتفعيلها. | النطاق | يسمح بـ | |---|---| | `catalog:read` | قراءة الخطط والكتالوج. | | `vm:read` | قراءة الأجهزة الافتراضية، المقاييس وفواتير الأجهزة الافتراضية. | | `vm:write` | إجراءات الطاقة، التغييرات البسيطة، جدار الحماية، اللقطات السريعة. | | `vm:create` | **إنشاء الأجهزة الافتراضية (يكلف مالاً).** | | `vm:plan` | **تغيير الخطة أو تغيير الحجم (يكلف مالاً).** | | `vm:destroy` | **حذف الأجهزة الافتراضية.** | | `vm:restore` | **استعادة جهاز افتراضي من لقطة (يكتب فوق القرص).** | | `vm:console` | فتح تذاكر وحدة تحكم VNC. | | `sshkey:read`, `sshkey:write` | قراءة، إضافة وإزالة مفاتيح SSH. | | `volume:read`, `volume:write`, `volume:create`, `volume:destroy` | مجلدات البيانات (الإنشاء والتوسيع يكلفان مالاً؛ الحذف يفقد البيانات). | | `backup:read`, `backup:write`, `backup:restore` | Backups (الاستعادة تكتب فوق القرص). | | `billing:read` | المحفظة، الفواتير، سجل الدفع — **قراءة فقط**. | | `bandwidth:buy` | **شراء ملحق نطاق التردد (يكلف مالاً).** | | `account:read`, `account:write` | الملف الشخصي، النظرة العامة، النشاط، الإشعارات؛ `account:write` يحدد الإشعارات كمقروءة فقط. | | `apikey:read` | سرد مفاتيح الحساب وسجل الاستخدام (لا يمكن الإنشاء، التعديل أو الإلغاء). | | `apikey:self` | ضمني على كل مفتاح: فحص المفتاح المتصل (`GET /v1/apikeys/self`). | | `ticket:read`, `ticket:write` | تذاكر الدعم. | | `aff:read`, `transfer:read` | برنامج الشركاء التابعين وعمليات نقل الخدمة — قراءة فقط. | | `k8s:read`, `k8s:write`, `k8s:create`, `k8s:scale`, `k8s:destroy`, `k8s:kubeconfig` | Kubernetes (الإنشاء والتوسيع يكلفان مالاً؛ ملف kubeconfig بصلاحية مسؤول المجموعة cluster-admin). | | `vpc:read`, `vpc:write`, `vpc:create`, `vpc:destroy` | السحاب الخاص. | | `image:read`, `image:write` | صور نظام التشغيل و ISO (يتم احتساب التخزين بالساعة). | | `s3:read`, `s3:write`, `s3:create`, `s3:destroy`, `s3:keys` | Object Storage (يتم إظهار مفتاح الـ S3 السري مرة واحدة). | | `vpn:read`, `vpn:detail`, `vpn:write`, `vpn:create`, `vpn:destroy` | شبكة VPN ووكيل IPv6 (تتضمن تفاصيل الاتصال كلمات سر الوكيل). | | `dedicated:read`, `dedicated:write`, `dedicated:console`, `dedicated:create`, `dedicated:destroy` | الخوادم المخصصة (إنشاء الطلبات من المحفظة؛ الحذف يعيد تثبيت نظام التشغيل). | | `shield:read`, `shield:write`, `shield:agent` | درع DDoS، فقط عند تفعيل تلك الوحدة. | الطلب الذي يتجاوز نطاقات المفتاح يرد بـ **403 `scope_required`**؛ أما المسار الذي لا يحق لأي مفتاح طلبه فيرد بـ **403 `endpoint_not_public`**. ### ما لا يفعله المفتاح أبداً {#what-a-key-can-never-do} لا يمكن لأي نطاق فتح ما يلي: شحن الرصيد أو سحب الأموال، تغيير البطاقات أو الشحن التلقائي، تغيير كلمة المرور أو البريد الإلكتروني أو المصادقة الثنائية 2FA، حذف الحساب، أو إنشاء أو تعديل أو إلغاء مفاتيح أخرى. تتطلب هذه العمليات دائماً متصفحاً مسجلاً للدخول. حتى لو تسرب المفتاح، فلن يتمكن من الوصول إلى أموال العميل أو حسابه. ## قواعد يمكنك الاعتماد عليها {#rules-you-can-rely-on} | القاعدة | التفاصيل | |---|---| | مرتبط بالموقع | يعمل المفتاح فقط على الموقع (النطاق) الذي تم إنشاؤه فيه. | | حدود المعدل | لكل مفتاح ولكل حساب: 120 و300 طلب في الدقيقة افتراضياً. | | منع التكرار | العمليات التي تكلف أموالاً أو لا يمكن تكرارها تتطلب ترويسة `Idempotency-Key`. | | الحصص | يخضع المفتاح لنفس [حصص الاستخدام](https://nexcmp.com/ar/docs/billing/quotas/) الخاصة بالعميل. | | حساب مقفل | تتوقف مفاتيح العميل المقفل عن العمل (403 `account_blocked`). | | تدقيق | يتم تسجيل عمليات إلغاء المفاتيح من قبل المسؤول في سجل تدقيق المسؤول. | ## عرض المسؤول {#administrator-view} 1. افتح **Customers › API keys** (`/customers/apikeys`). يعرض الجدول اسم المفتاح والحروف الأولى منه، والمالك، والنطاقات، والحالة، وآخر استخدام (الوقت، عدد الطلبات، عنوان IP)، وتاريخ انتهاء الصلاحية. 2. قم بالتصفية حسب الموقع إذا كان لديك شركاء إعادة بيع. ابحث بالاسم أو المعرف أو بداية المفتاح. 3. انقر فوق **Revoke** لإيقاف مفتاح نشط، أو **Log** لعرض سجل استخدامه. 4. يمكن للمسؤولين **عرض وإلغاء** المفاتيح ولكن لا يمكنهم قراءتها أو إنشائها نيابة عن العملاء. ![قائمة المشرف لمفاتيح API الخاصة بالعملاء مع النطاقات، الحالة، الاستخدام الأخير وزر Revoke](https://nexcmp.com/ar/docs/images/developers/api-keys-02-admin.webp) ## التحقق {#verify} 1. أنشئ مفتاحاً بالنطاق `vm:read` فقط. 2. تُرجع `curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"` قائمة الأجهزة الافتراضية. 3. ترد `curl -s -X POST .../v1/vm//start -H "Authorization: Bearer vk_XXXX"` بالرمز 403 `scope_required`. 4. قم بإلغاء المفتاح؛ سيُرجع الطلب الأول الآن 401 `key_revoked`. ## الحدود والملاحظات {#limits-notes} - لا يتم عرض المفتاح مرة أخرى أبداً. تعامل معه ككلمة مرور وخزنه في مدير كلمات سر أو في أسرار نظام التكامل المستمر CI. - يفضل تخصيص مفتاح واحد لكل سكريبت، بأضيق نطاقات ممكنة، مع صلاحية قصيرة وقائمة سماح لعناوين IP؛ قم بتدوير المفاتيح عن طريق إنشاء مفتاح جديد وإلغاء القديم. - تكون صلاحية مفاتيح تسجيل الدخول للأجهزة (CLI، MCP) 90 يوماً افتراضياً. - الموارد المحذوفة أو المنقولة لا تأثر بإلغاء المفتاح. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | خطأ `too_many_keys` (422) | تم الوصول إلى الحد الأقصى للمفاتيح النشطة (10 مفاتيح افتراضياً) | قم بإلغاء مفتاح قديم. | | خطأ `invalid_argument`: لم يتم اختيار أي نطاق | لم يتم تحديد أي نطاق | حدد نطاقاً واحداً على الأقل. | | خطأ `invalid_argument` في عناوين IP المسموحة | العنصر المدخل ليس عنوان IP أو نطاقاً صحيحاً، أو طول بادئة خاطئ، أو يتجاوز 20 عنصراً | عنوان IP واحد أو نطاق CIDR في كل سطر، على سبيل المثال `203.0.113.0/24`. | | تم رفض الإنشاء أثناء وضع تقمص الشخصية (Impersonation) | `impersonate_forbidden` | اطلب من العميل إنشاء المفتاح. | | 401 `key_expired` | انقضى تاريخ انتهاء الصلاحية | أنشئ مفتاحاً جديداً. | | 401 `key_ip_denied` | عنوان IP الخاص بالمرسل غير موجود في قائمة السماح | أضف عنوان IP أو أفرغ القائمة. | | 401 `api_keys_disabled` | الميزة معطلة | استشر المسؤول لديك (إعداد `api_keys_enabled`). | --- # `cmp` أداة سطر الأوامر {#cmp-command-line-tool} > **أين في البوابة:** أوامر التثبيت موجودة في مرجع الAPI (`https:///apidoc`، قسم Command-line interface). الموافقة على تسجيل الدخول: `https:///link`. الأجهزة المتصلة: API keys (`/api-keys`) › Connected apps & devices. ## الوظيفة {#what-it-does} `cmp` هو برنامج صغير بسطر الأوامر لعملائك (ولك) والذي يحول **كل عملية API إلى أمر**: `cmp vm list`، `cmp vm start `، `cmp billing invoice list`. تم بناؤه من مستند OpenAPI الخاص بتثبيتك **الخاص** في وقت الإصدار، لذا تتطابق الأوامر مع الميزات التي قمت بتفعيلها. إنه ملف ثنائي ثابت واحد لنظام Linux وmacOS وWindows (amd64 وarm64) مع عدم وجود أي شيء آخر لتثبيته. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | الخادم | لا شيء إضافي. حزم الإصدار موجودة داخل إصدار NexCMP ويتم تقديمها بواسطة اللوحة في `https:///cli/`. | | جهاز العميل | Linux أو macOS أو Windows (PowerShell 5.1+). يلزم وجود `ssh-keygen` (OpenSSH 8.0+) فقط للتحقق من التوقيع. | | بيانات الاعتماد | تسجيل دخول عبر المتصفح برمز لمرة واحدة، أو [مفتاح API](https://nexcmp.com/ar/docs/developers/api-keys/). | | الشبكة | بروتوكول HTTPS للوحتك. ترفض أداة CLI إرسال مفتاح عبر بروتوكول `http://` العادي إلا إلى `localhost`. | ## تجهيز البنية التحتية {#prepare-the-infrastructure} لا شيء. تقوم اللوحة بتقديم هذه الملفات من `/cli/` (لا يلزم بناء أو رفع): | الملف | الغرض | |---|---| | `install.sh`, `install.ps1` | برامج التثبيت لنظام Linux/macOS وWindows؛ وهي تحتوي على عنوان لوحتك. | | `latest.json` | الإصدار الحالي، قائمة الملفات، الأحجام، وsha256. | | `v/cmp___.tar.gz` أو `.zip` | البرامج: linux amd64/arm64، darwin amd64/arm64/universal، windows amd64/arm64. | | `v/SHA256SUMS`, `SHA256SUMS.sig` | المجاميع الاختبارية وتوقيع ed25519 الخاص بها. | | `cmp-cli.pub` | المفتاح العام للإصدار. | ## التثبيت (للعميل) {#install-customer} أنظمة macOS وLinux: ```bash curl -fsSL https://cloud.example.com/cli/install.sh | sh ``` برنامج PowerShell لنظام Windows: ```powershell irm https://cloud.example.com/cli/install.ps1 | iex ``` يختار برنامج التثبيت الحزمة الخاصة بنظام التشغيل وحدة المعالجة المركزية، ويقوم بتنزيل `SHA256SUMS` وتوقيعه، والتحقق من التوقيع باستخدام المفتاح المضمن في البرنامج النصي، والتحقق من تجزئة الحزمة، وتثبيت `cmp` في `/usr/local/bin` (بصفتك root) أو `~/.local/bin`؛ وعلى نظام Windows في `%LOCALAPPDATA%\cmp\bin` (المضاف إلى `PATH` للمستخدم). إذا فشل أي تحقق فللن يتم تثبيت أي شيء. | المتغير | المعنى | |---|---| | `CMP_VERSION` | تثبيت هذا الإصدار بدلاً من أحدث إصدار. | | `CMP_INSTALL_DIR` | مجلد التثبيت. | | `CMP_REQUIRE_SIGNATURE` | `1` = الإلغاء عندما تعذر التحقق من التوقيع. | | `CMP_BASE_URL` | قاعدة التنزيل (للمرايا). | التنزيل اليدوي والتحقق: ```bash curl -fsSLO https://cloud.example.com/cli/latest.json sha256sum --check --ignore-missing SHA256SUMS ``` ![قسم مرجع الAPI الذي يحتوي على أمر تثبيت cmp لنظامي macOS وLinux](https://nexcmp.com/ar/docs/images/developers/cmp-cli-01-install.webp) ## تسجيل الدخول {#log-in} ```bash cmp login ``` 1. تطبع أداة CLI **رمْزاً** لمرة واحدة ورابطاً (`https://cloud.example.com/link?code=WDJB-MJHT`)، وتفتح المتصفح وتنتظر. 2. في المتصفح، قم بتسجيل الدخول إلى البوابة، وافحص اسم العميل، والجهاز، وعنوان IP والبلد، وحدد الأذونات (النطاقات) واتركه يحدد مدة صلاحية المفتاح (الافتراضي 90 يوماً). الأذونات التي تكلف أموالاً أو تحذف بيانات تبدأ بدون تحديد. انقر فوق موافق. 3. تتلقى أداة CLI **مفتاحها الخاص**، منفصلاً عن المفاتيح التي أنشأها العميل يدويًا، وتقوم بتخزينه في `~/.config/cmp/config.json` (الوضع `0600`؛ `%APPDATA%\cmp` على نظام Windows). يظهر تحت **API keys › Connected apps & devices** ويمكن إلغاؤه من هناك. ينتهي صلاحية الرمز بعد 10 دقائق. تتطلب الموافقة جلسة بوابة حقيقية مسجلة الدخول مع بريد إلكتروني متحقق منه — وليس مفتاحًا آخر وليست جلسة منتحلة. شارات مفيدة: `--scopes vm:read,billing:read`، `--name "build server"`، `--no-browser`، `--profile`، `--api-url`. بالنسبة لـ CI أو الخوادم التي ليس لها متصفح، استخدم مفتاحاً من البوابة: ```bash printf %s "$KEY" | cmp login --with-token export CMP_TOKEN=vk_XXXX # nothing is written to disk cmp whoami ``` ## استخدام الأوامر {#using-commands} ```text cmp [subgroup] [ ...] [flags] ``` - معلمات المسار هي وسائط موضعية؛ وتصبح معلمات الاستعلام وحقول الجسم شارات بصيغة kebab-case (`--start-port 443`). - ترسل `--data '{"a":1}'` أو `--data @file.json` أو `--data -` محتوى JSON كاملاً؛ وتتجاوز الخيارات (flags) حقوله. - يعرض `cmp help vm firewall add` (أو `--help`) تفاصيل أي أمر. ```bash cmp catalog plans cmp vm list --state active --per-page 50 cmp vm get 3f2a1c9e-0000-4000-8000-000000000000 cmp vm start 3f2a1c9e-0000-4000-8000-000000000000 cmp vm firewall add 3f2a1c9e-... --protocol tcp --start-port 22 --cidr-list 203.0.113.0/24 cmp billing wallet cmp api GET /v1/vm --query page=2 # raw call to any endpoint ``` الأوامر المضمنة: `login` و`logout` و`whoami` و`config` و`api` و`completion` و`version` و`update` و`help`. وكل ما عدا ذلك يأتي من مستند API. الخيارات العامة: | الخيار | المعنى | |---|---| | `-o, --output json\|table\|yaml` | التنسيق. القيمة الافتراضية هي `table` على الطرفية و`json` عند التوجيه (piped). | | `--profile`, `--api-url` | تسجيل الدخول المخزن والموقع المحدد. | | `-y, --yes` | تخطي التأكيد للأوامر المدفوعة أو التي تترتب عليها إجراءات هامة. | | `--idempotency-key ` | اختيار مفتاح لأمر مدفوع. | | `--retry ` | عند استلام رمز HTTP 429، يتم الانتظار لمدة `Retry-After` وإعادة المحاولة حتى n مرات. | | `--timeout ` | عدد الثواني للانتظار حتى استلام ترويسات الاستجابة (الافتراضي 60). | | `--debug` | عرض تبادل بيانات HTTP على مخرج الأخطاء المعياري (stderr) مع إخفاء المفاتيح. | الأوامر التي **تقتطع من الرصيد أو تحذف بيانات** تطلب تأكيداً، وإذا كانت مدفوعة، فإنها ترسل رمز `Idempotency-Key` مُنشأ تلقائياً (يتم طباعته على stderr ليتسنى لك إعادة المحاولة بأمان باستخدام `--idempotency-key`). وفي حال عدم وجود طرفية، يتم رفض التنفيذ ما لم يتم تمرير `--yes`. ### رموز الخروج {#exit-codes} | الرمز | المعنى | |---|---| | 0 | نجاح | | 1 | خطأ آخر (شبكة، أو خطأ HTTP 4xx/5xx غير مدرج) | | 2 | خطأ في الاستخدام | | 3 | غير مسموح (401/403) | | 4 | غير موجود (404) | | 5 | تجاوز حد الاستخدام (429) | | 6 | التأكيد مطلوب أو تم رفضه | | 130 | تم المقاطعة | ### الملفات الشخصية والبيئة {#profiles-and-environment} يعرض `cmp config` الملفات الشخصية، ويقوم `cmp config use ` بالتبديل بينها؛ ويستخدم عملاء الموزع نطاقهم الخاص: `cmp login --api-url https://shop.example.net --profile shop`. الأولوية: الخيار، البيئة، ملف التكوين. المتغيرات: `CMP_TOKEN` و`CMP_PROFILE` و`CMP_API_URL` و`CMP_OUTPUT` و`CMP_CONFIG_DIR` و`CMP_ALLOW_HTTP` و`CMP_UPDATE_URL`. GitHub Actions: ```yaml - name: Install cmp run: | curl -fsSL https://cloud.example.com/cli/install.sh | CMP_INSTALL_DIR="$RUNNER_TEMP/bin" sh echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH" - name: List running VMs env: CMP_TOKEN: ${{ secrets.CMP_TOKEN }} # a read-only key run: cmp vm list -o json | jq -r '.items[] | select(.cs_state=="Running") | .hostname' ``` إكمال الأوامر في الصدفة (Shell completion): `cmp completion bash|zsh|fish|powershell`. ## التحديث وإلغاء التثبيت {#update-and-uninstall} ```bash cmp version cmp update --check cmp update ``` يقوم `cmp update` بتنزيل `latest.json` و`SHA256SUMS` والتوقيع الرقمي، ويتحقق من صحة التوقيع باستخدام المفتاح العام **المدمج في الملف الثنائي قيد التشغيل**، ثم يتحقق من تجزئة الحزمة (hash) وبعدها فقط يستبدل نفسه. يتطلب التراجع إلى إصدار سابق استخدام `--force`. عند تحديث NexCMP، تفرِّم اللوحة إصدار CLI الذي يتماشى مع الإصدار الجديد. لإلغاء التثبيت، احذف الملف الثنائي `cmp` ومجلد التكوين (يعرضه `cmp config path`). قم بإلغاء تنشيط المفتاح ضمن **API keys** في حال ضياع الجهاز. ## التحقق {#verify} 1. يطبع `cmp version` الإصدار وإصدار مستند API. 2. `cmp login`، ثم الموافقة في المتصفح، وبعدها يعرض `cmp whoami` الملف الشخصي ورابط لوحتك. 3. يعرض `cmp vm list` الأجهزة الافتراضية الخاصة بك؛ ويعرض `cmp vm list -o json | jq .` بيانات JSON الخام. ## الحدود والملاحظات {#limits-notes} - تعتمد قائمة الأوامر على النسخة المبنية لديك: يتم إنشاء الحزم من مستند OpenAPI الخاص بالتثبيت عند بناء الإصدار، لذا فإن أي منتج معطل في نسختك لن يكون له أمر مقابل. استخدم `cmp api` للوصول إلى مسار لا يتعرف عليه CLI. - أداة CLI تخضع لرخصة MIT. - كل حزمة موقعة بمفتاح ed25519؛ ومفتاح التوقيع مثبت داخل المثبت والملف الثنائي، ولا يتم جلبه وقت التحديث. - المفاتيح محدودة لكل مفتاح ولكل حساب (راجع [REST API](https://nexcmp.com/ar/docs/developers/api/#rate-limits)). ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | يعيد `curl .../cli/install.sh` الرمز 404 | إصدار الخادم لا يحتوي على مجلد CLI، أو أن المضيف لا يمتلك ترخيصاً صالحاً | تحقق من `https:///cli/latest.json` والنطاق؛ ثم قم بتحديث NexCMP. | | "لم يتم التحقق من صحة التوقيع" | `ssh-keygen` مفقود أو قديم جداً | قم بتثبيت OpenSSH 8.0+، أو اضبط `CMP_REQUIRE_SIGNATURE=0` فقط إذا كنت تقبل المخاطرة. | | `cmp login` يشير إلى انتهاء صلاحية الرمز | انقضاء 10 دقائق | قم بتشغيل `cmp login` مرة أخرى. | | رمز الخروج 3 | المفتاح يفتقر إلى نطاق، أو انتهت صلاحيته، أو تم إلغاؤه | `cmp whoami`؛ أنشئ المفتاح أو أعد اعتماده بنطاقات أكثر. | | رمز الخروج 6 في برنامج نصي | أمر مدفوع أو مدمر بدون وحدة طرفية | أضف `--yes` (بالإضافة إلى `--idempotency-key` الخاص بك). | | "يرفض إرسال مفتاح عبر http" | رابط API بصيغة http عادي | استخدم `https://`، أو استخدم `CMP_ALLOW_HTTP=1` للمختبر فقط. | | المتصفح يفتح الموقع الخطأ | `--api-url` غير معين للموزع | `cmp login --api-url https://`. | --- # خادم MCP {#mcp-server} > **أين في البوابة:** API reference › Tools (`https:///apidoc`) يظهر نقطة النهاية ومقتطفات العميل؛ ويتم إنشاء المفاتيح في API keys (`/api-keys`). لا توجد إعدادات في لوحة المشرف: نقطة النهاية هي جزء من اللوحة. ## الوظيفة {#what-it-does} يسمح **Model Context Protocol (MCP)** لمساعد الذكاء الاصطناعي باستدعاء الأدوات. توفر NexCMP نقطة نهاية MCP على `https:///mcp`. تصبح كل عملية API عامة عبارة عن **أداة** (`vm_list` و `vm_start` و `billing_wallet`، ...)، بحيث يمكن للعميل أن يسأل مساعده "أي من أجهزتي الافتراضية تعمل؟" أو "أوقف الجهاز الافتراضي للتجربة". يعمل المساعد باستخدام مفتاح الـ API وصلاحيات العميل وحده. ::: tip هل تريد تكوين NexCMP نفسه باستخدام الذكاء الاصطناعي؟ هذه الصفحة مخصصة لنقطة نهاية MCP لل**عميل** (`/mcp`). للسماح لمساعد الذكاء الاصطناعي بتكوين لوحتك الخاصة كمسؤول، راجع [تكوين باستخدام الذكاء الاصطناعي](https://nexcmp.com/ar/docs/configure-with-ai/mcp-admin/) (نقطة النهاية `/mcp/admin`، مفاتيح المسؤول `ak_`). ::: ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | الخادم | لا شيء للتثبيت: يتم خدمة نقطة النهاية بواسطة اللوحة ويمكن الوصول إليها أينما كانت اللوحة. يجب أن يقوم الوكيل العكسي الخاص بك بتوجيه `/mcp` إلى اللوحة. | | العميل | [مفتاح API](https://nexcmp.com/ar/docs/developers/api-keys/) (`vk_...`) يتضمن النطاقات التي يحتاجها المساعد. | | العميل | عميل MCP يدعم نقل **Streamable HTTP** وترويسة `Authorization` مخصصة: Claude Code، وClaude Desktop (من خلال جسر `mcp-remote`)، وCursor، وVS Code مع وضع وكيل Copilot وما شابه ذلك. | | إصدارات البروتوكول | 2025-11-25 و2025-06-18 و2025-03-26. | ## تجهيز البنية التحتية {#prepare-the-infrastructure} لا شيء، سوى التأكد من أن `https:///mcp` غير محظور بواسطة جدار حماية أو قاعدة وكيل. يتم رفض عميل MCP المستند إلى المتصفح من أصل آخر ما لم يتم السماح بهذا الأصل؛ بينما لا ترسل عميلات سطر الأوامر وتطبيقات سطح المكتب رأس `Origin` وتعمل كما هي. ## الاتصال (جانب العميل) {#connect-customer-side} 1. أنشئ مفتاح واجهة برمجة تطبيقات في البوابة (**API keys › Create key**) مع النطاقات التي تريد أن يستخدمها المساعد فقط، وفترة صلاحية قصيرة، وتقييد عنوان IP إن أمكن. 2. أضف الخادم إلى عميلك. استبدل `cloud.example.com` والمفتاح. **Claude Code** ```bash claude mcp add --transport http cloud https://cloud.example.com/mcp \ --header "Authorization: Bearer vk_XXXX" ``` **Cursor** (`~/.cursor/mcp.json` أو `.cursor/mcp.json`؛ اضبط `CLOUD_API_KEY` في بيئة التشغيل التي يبدأ منها Cursor): ```json { "mcpServers": { "cloud": { "url": "https://cloud.example.com/mcp", "headers": { "Authorization": "Bearer ${env:CLOUD_API_KEY}" } } } } ``` **Claude Desktop** (يحتاج Node.js 18+؛ `claude_desktop_config.json`)، من خلال جسر `mcp-remote`: ```json { "mcpServers": { "cloud": { "command": "npx", "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp", "--header", "Authorization:${CLOUD_AUTH_HEADER}"], "env": { "CLOUD_AUTH_HEADER": "Bearer vk_XXXX" } } } } ``` اكتب الرأس بدون مسافة بعد النقطتين واضع القيمة بأكملها في متغيّر البيئة، كما هو موضح أعلاه. 3. أعد تشغيل العميل واطلب منه سرد أدواتك. تحقق من الاتصال بدون عميل: ```bash curl -s https://cloud.example.com/mcp \ -H "Authorization: Bearer vk_XXXX" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` ## How it works {#how-it-works} | العنصر | التفاصيل | |---|---| | نقطة النهاية | `POST /mcp` مع رسالة JSON-RPC 2.0؛ الإجابة هي `application/json`. `GET /mcp` يرد بـ 405 (لا يوجد تدفق من الخادم إلى العميل)؛ `DELETE /mcp` ينهي الجلسة. | | المصادقة | فقط `Authorization: Bearer vk_...` (يتم رفض رموز الجلسة وملفات تعريف الارتباط ومفاتيح المسؤول باستخدام الرمز 401 مع رأس `WWW-Authenticate: Bearer`). | | الجلسة | يتم إصدار `Mcp-Session-Id` بواسطة `initialize`، وهو مرتبط بهذا المفتاح وصالح لمدة 24 ساعة؛ وبحد أقصى 16 جلسة لكل مفتاح. | | الأدوات | واحدة لكل عملية في API العام مرئية للمفتاح. اسم الأداة هو أمر CLI مع استخدام `_` بدلاً من المسافات والشرطات (يصبح `vm firewall add` هو `vm_firewall_add`) ويطابق OpenAPI `operationId`. يتم إدراج الأداة فقط عندما يمتلك المفتاح نطاقها وتكون الوحدة مفعلة. | | القدرات | الأدوات فقط (بدون موارد أو مطالبات). | | الحجم | حجم طلب الجسم يصل إلى 1 ميجابايت؛ ونص نتيجة الأداة يصل إلى حوالي 100 كيلوبايت (يتم اقتطاع الباقي مع ملاحظة)؛ وتستغرق المكالمة بحد أقصى 55 ثانية. | ### قواعد الأمان {#safety-rules} - **نفس بوابة REST.** يمر كل `tools/call` عبر خط أنابيب الطلبات الخاص باللوحة نفسها: النطاق، والموقع، وتقييد عنوان IP، وحد معدل الطلبات، وعدم التكرار، وفقرات التحقق من الملكية (الرمز 404 لموارد الأشخاص الآخرين) وحصص الاستخدام كلها مطبقة. لا يمكن لـ MCP منح أي شيء لا يملكه المفتاح. - **التأكيد.** الأدوات التي تكلف أموالاً أو تحذف أو تعيد بيانات الاعتماد (تذاكر وحدة التحكم، أو kubeconfig، أو أسرار S3 أو SSH، أو إعادة تعيين كلمة المرور، أو المفاتيح الجديدة) تتطلب وسيطة `confirm: true`. يخبر وصف الأداة المساعد بتمريرها فقط بعد موافقة المستخدم، لذا لا يمكن لأي تعليمة مخفية في صفحة ويب أو سجل تشغيلها من تلقاء نفسها. - **عدم التكرار (Idempotency).** تقبل الأدوات مدفوعة الثمن `idempotency_key`؛ وإذا تم حذفه، يتم اشتقاق مفتاح ثابت من اسم الأداة والوسيطات، بحيث لا يمكن لإعادة محاولة متطابقة أن تخصم المبلغ مرتين. - **غير معروضة كأدوات:** نقاط نهاية البث (دردشة AI Agent)، وتذاكر SSH أو وحدة التحكم لمرة واحدة عبر WebSocket، والتنزيلات الثنائية، وننقاط نهاية تطبيق VPN (`/v1/ext/*`). - **غير ممكن أبداً:** لا يسمح API أبداً بعمليات شحن الرصيد، أو تغيير كلمات المرور، أو حذف الحساب أو إنشاء مفاتيح، لذلك لا يمكن لأي مساعد القيام بذلك. ### الحدود {#limits} | الحد | القيمة الافتراضية | |---|---| | استدعاءات الأدوات لكل مفتاح | 60 في الدقيقة | | طلبات MCP لكل مفتاح | 240 في الدقيقة | | بالإضافة إلى حدود المفتاح والحساب العادية | راجع [REST API](https://nexcmp.com/ar/docs/developers/api/#rate-limits) | عند تجاوز الحد، يستجيب نقطة النهاية برمز HTTP 429 مع خطأ JSON-RPC و`Retry-After`. ## التحقق {#verify} 1. يقوم أمر `curl` أعلاه بإرجاع نتيجة JSON-RPC مع قائمة `tools`. تظهر فقط الأدوات التي تتطابق مع نطاقات المفتاح. 2. اسأل العميل لديك "list my VMs": يقوم المساعد باستدعاء `vm_list` وعرض النتيجة. 3. في البوابة يتحرك وقت **Last used** الخاص بالمفتاح، وتظهر عمليات الكتابة في **Key usage log**. ## الحدود والملاحظات {#limits-notes} - **تسجيل الدخول عبر المتصفح (OAuth).** تصف صفحة المرجع أيضاً تسجيل الدخول عبر المتصفح للعملاء الذين يدعمون مصادقة MCP OAuth. في نسخة NexCMP المثبتة، الطريقة المدعومة والمختبرة هي مفتاح API (أو `cmp login` لـ CLI). - **مواقع الموزعين** لا تعرض قسم MCP؛ ويستخدم عملاؤهم نطاق الموزع لـ API. - **أقل امتياز.** أنشئ مفتاحاً مخصصاً لكل مساعد مع نطاقات القراءة أولاً؛ وأضف نطاقات الكتابة فقط عند الحاجة. - قم بإلغاء المفتاح في **API keys** لقطع وصول المساعد على الفور. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | 401 مع `WWW-Authenticate: Bearer` | لا يوجد مفتاح، أو مفتاح خاطئ، أو رمز جلسة | أرسل `Authorization: Bearer vk_...`. | | 403 حول `Origin` | صفحة متصفح على أصل (Origin) آخر | استخدم جهاز سطح مكتب أو عميل CLI؛ أو اطلب من المسؤول السماح بالأصل (`mcp_allowed_origins`). | | 404 في طلب يحتوي على `Mcp-Session-Id` | الجلسة تنتمي إلى مفتاح آخر أو انتهت صلاحيتها | قم بتشغيل `initialize` مرة أخرى. | | 405 على `GET /mcp` | المتوقع: الخادم لا يحتوي على تدفق أحداث | استخدم POST فقط (تقوم العناوين بهذا تلقائياً). | | قائمة الأدوات قصيرة | نطاقات المفاتيح أو الوحدات النمطية | أضف نطاقات إلى المفتاح؛ وقم بتفعيل الوحدة النمطية. | | تستجيب الأداة بأنها تحتاج `confirm: true` | أداة مدفوعة، أو محذوفة، أو حساسة | يجب على المساعد تعيين `confirm` بعد موافقتك. | | 429 | حد معدل MCP أو المفتاح | انتظر حتى `Retry-After`. | | العميل غير قادر على الاتصال برأس (header) | العميل بدون دعم الرؤوس المخصصة | استخدم جسر `mcp-remote`. | --- # التهيئة باستخدام الذكاء الاصطناعي {#configure-with-ai} > **أين في لوحة المشرف:** AI Chat (`/agent`) و System › Settings › API & AI agents (`/agent/keys`). كل ما في هذه الصفحات مخصص للمشرفين فقط. ## الوظيفة {#what-it-does} بدءاً من الإصدار NexCMP 1.4.0، يمكنك أن تطلب من مساعد الذكاء الاصطناعي إعداد اللوحة نيابةً عنك: ربط Proxmox VE أو CloudStack، أو إنشاء منطقة، أو بناء جدول خطط بناءً على التكاليف الخاصة بك، أو إعداد البريد الإلكتروني والمدفوعات والعلامة التجارية، أو البحث عن عميل، أو تصدير التكوين بالكامل. يعمل المساعد من خلال مجموعة ثابتة من **أدوات المشرف**. فهو لا يحصل أبداً على صدفة (shell)، ولا يقرأ الملفات على الخادم، ولا يرى أبداً كلمة مرور مخزنة أو مفتاح API. استخدمه عندما تريد إعداداً اولياً في دقائق بدلاً من النقر عبر عشرات الصفحات، أو عندما تدير عدة تثبيتات وترغب في الاحتفاظ بتكوينها في ملف. ## ثلاث طرق لاستخدامه {#three-ways-to-use-it} | الطريقة | من يتحدث إلى الذكاء الاصطناعي | أين يعمل | ابدأ من هنا | |---|---|---|---| | **AI Chat في لوحة المشرف** | أنت، في لوحة مشرف NexCMP | مصدر الذكاء الاصطناعي الذي تختاره: مفتاح API من OpenAI أو Anthropic أو Gemini أو OpenRouter، أو مزود الذكاء الاصطناعي الخاص بلوحتك، أو واجهة سطر أوامر (CLI) رسمية للذكاء الاصطناعي قمت بتسجيل الدخول إليها | [AI Chat في لوحة المشرف](https://nexcmp.com/ar/docs/configure-with-ai/ai-chat-in-admin/) | | **عميل الذكاء الاصطناعي الخاص بك عبر MCP** | أنت، في Claude Code أو Codex CLI أو Gemini CLI أو Cursor أو Claude Desktop أو claude.ai أو ChatGPT | على جهازك أو في تطبيق المزود، متصلاً بلوحتك على `https://cloud.example.com/mcp/admin` | [وصّل عميل ذكاء اصطناعي](https://nexcmp.com/ar/docs/configure-with-ai/mcp-admin/) | | **التكوين كتعليمات برمجية (Configuration as code)** | أنت أو برنامج نصي | ملف YAML وأمر `nexcmp config` على الخادم (أو صفحة الاستيراد/التصدير) | [التكوين كتعليمات برمجية](https://nexcmp.com/ar/docs/configure-with-ai/config-as-code/) | تستدعي الطرق الثلاث نفس الأدوات وتمر عبر طبقة الأمان نفسها، لذا يمكنك دمجها: صغ تكوينًا بمساعدة مساعد، وقم بتصديره كملف YAML، وراجعه في محرر النصوص الخاص بك ثم قم تطبيقه لاحقاً. ## نموذج الأمان {#safety-model} | القاعدة | ماذا يعني ذلك بالنسبة لك | |---|---| | **النطاقات** | يقتصر المفتاح أو الاتصال على النطاقات التي تحددها (`admin:read`، `catalog:write`، `infra:write`، `billing:write`، `customers:write`، `settings:write`، `ai:write`، `secrets:write`). بدون نطاق، يتم رفض المكالمة. راجع [Admin API keys](https://nexcmp.com/ar/docs/configure-with-ai/admin-api-keys/#scopes). | | **Expiry** | تنصرم صلاحية كل مفتاح وكل اتصال: من 1 إلى 90 يوماً للمفاتيح التي تنشئها، و30 يوماً بشكل افتراضي. تستمر رمز وصول OAuth لمدة ساعة واحدة. | | **تقييد عناوين IP وحد المعدل** | يمكن تقييد المفتاح بنطاقات عناوين IP وعدد محدد من الاتصالات في الدقيقة (120 افتراضياً). | | **التأكيد على خطوتين** | الإجراءات التي تنقل أموالاً، أو تحذف بيانات، أو تغير بيانات اعتماد الدفع، أو تغير أمان تسجيل الدخول تعرض معاينة أولاً ولا تفعل شيئاً حتى توافق عليها. داخل AI Chat، كل تغيير هو بطاقة تأكيد تضغط عليها بنفسك. | | **أمور لا تستطيع المفاتيح فعلها أبداً** | إنشاء مسؤولين، أو تغيير المصادقة الثنائية (2FA)، أو إنشاء مفاتيح أو إلغاؤها، أو تسجيل الدخول كعميل، أو النسخ الاحتياطي، أو الاستعادة، أو تحديث لوحة التحكم، وما شابه. تتطلب هذه العمليات وجودك كمسؤول. | | **سجل النشاطات** | يتم تسجيل كل مكالمة، سواء سمح بها أو رفضها، مع المفتاح، العميل، الأداة، عنوان IP والنتيجة. راجع System › Settings › API & AI agents › Activity. | | **لا يتم إرجاع الأسرار أبداً** | يمكن تعيين كلمات المرور ومفاتيح API والرموز المميزة ولكن لا يمكن قراءتها مرة أخرى أبداً. الإجابات التي تراها الذكاء الاصطناعي تظهر فيها مخفية. | | **تثبيتات التجربة للقراءة فقط** | في لوحة تجريبية، يتم رفض كل عملية كتابة باستخدام `demo_read_only`. | ::: important ما يمكن للذكاء الاصطناعي قراءته باستخدام `admin:read`، يمكن للمساعد قراءة أسماء العملاء، وعناوين البريد الإلكتروني، والأرصدة، وسجلات الفوترة. عندما تستخدم مصدر ذكاء اصطناعي يعمل لدى مزود (OpenAI، Anthropic، Google، OpenRouter)، تُرسل تلك البيانات إلى ذلك المزود للإجابة عن سؤالك. امنح المساعد أقل مجموعة ممكنة من الصلاحيات التي يحتاجها، واختر مصدراً تثق به في التعامل مع تلك البيانات. ::: ## البدء السريع {#quick-start} 1. سجل الدخول إلى لوحة التحكم وافتح **AI Chat**. إذا لم يكن هناك أي مصدر ذكاء اصطناعي متصلاً بعد، فافتح **System › Settings › AI accounts** وقم بربط واحد (انظر [AI accounts and subscriptions](https://nexcmp.com/ar/docs/configure-with-ai/ai-accounts-and-subscriptions/)). 2. اكتب "Check my setup progress" واضغط على Enter. يقرأ المساعد [Setup progress checklist](https://nexcmp.com/ar/docs/configure-with-ai/setup-checklist/) ويخبرك بما تبقى. 3. اطلب منه تنفيذ الخطوة التالية. راجع كل بطاقة تأكيد واضغط على **Confirm** لتطبيقها. لإلقاء نظرة أوليّة على ما يمكنك طلبه، راجع [Example prompts](https://nexcmp.com/ar/docs/configure-with-ai/example-prompts/). ![صفحة AI Chat مع محادثة، ونتيجة أداة، وبطاقة تأكيد](https://nexcmp.com/ar/docs/images/configure-with-ai/overview-01-ai-chat.webp) ## الحدود والملاحظات {#limits-notes} - **العرض التجريبي وللقراءة فقط.** الصفحات مرئية على اللوحة التجريبية، ولكن لا يمكن حفظ أي شيء هناك. - **لا يوجد غلاف للأوامر (Shell).** يمكن للمساعد فقط استدعاء أدوات الإدارة المدرجة في [Connect an AI client](https://nexcmp.com/ar/docs/configure-with-ai/mcp-admin/#tools). ولا يمكنه تشغيل الأوامر على الخادم. - **وحدات الشبكة والتوجيه** (BGP وXDP والواجهات وNAT وما شابه) هي للقراءة فقط بالنسبة للذكاء الاصطناعي، والمناطق الحساسة مثل حسابات المسؤولين والنسخ الاحتياطي والتحديثات مغلقة تماماً أمام المفاتيح. - **الأسعار** بالدولار الأمريكي: أسعار الخُطط بالدولار في الساعة، والأرصدة بالسنت. - **التكلفة.** تُدفع تكلفة إجابات الذكاء الاصطناعي لمصدر الذكاء الاصطناعي الذي تتصل به (استخدام API، أو اشتراكك الخاص). يمكنك في AI Chat تعيين حد أقصى للإنفاق اليومي. بالنسبة لنموذج ترخيص NexCMP راجع https://nexcmp.com/pricing. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | يقول AI Chat إنه لم يتم توصيل أي مصدر ذكاء اصطناعي | لم يتم إعداد أي مصدر لحساب المسؤول الخاص بك | افتح System › Settings › AI accounts وقم بتوصيل مصدر. | | يجيب المساعد بـ `insufficient_scope` | يفتقر المفتاح أو الاتصال إلى الصلاحية اللازمة لتلك الأداة | أنشئ مفتاحاً بالصلاحية المطلوبة، أو أعد الاتصال وحددها في شاشة الموافقة. راجع [Admin API keys](https://nexcmp.com/ar/docs/configure-with-ai/admin-api-keys/#errors). | | يعرض كل تغيير بطاقة تأكيد | متوقع في AI Chat | اضغط على **Confirm** للتطبيق أو **Reject** للإلغاء. | | تفشل عمليات الكتابة مع `demo_read_only` | اللوحة في وضع التجربة | استخدم تثبيتاً غير تجريبي. | --- # AI Chat في لوحة التحكم {#ai-chat-in-the-admin} > **أين في لوحة المشرف:** AI Chat (`/agent`، عنصر القائمة الخاص به) وزر **Ask AI** العائم في كل صفحة من صفحات المشرف. يتم إعداد مصادر الإجابات في System › Settings › AI accounts (`/agent/accounts`). ## الوظيفة {#what-it-does} AI Chat هو مساعد مدمج في لوحة المشرف. تصف ما تريده ("ربط مجموعة Proxmox الخاصة بي"، "إعداد البريد الإلكتروني")، ليقوم المساعد بقراءة الحالة الحالية باستخدام أدوات المشرف، واقتراح التغييرات وعرض كل منها على شكل **بطاقة تأكيد**. لا يتم تطبيق أي شيء حتى تضغط على **Confirm**. لوحة **Ask AI** هي نفس الدردشة في لوحة جانبية ضيقة، بحيث يمكنك طرح الأسئلة أثناء تصفح الصفحة. الأزرار مثل **Do it for me** (في [Setup progress checklist](https://nexcmp.com/ar/docs/configure-with-ai/setup-checklist/) وفي القوائم الفارغة) تفتحها بسؤال جاهز. هذه ليست [AI Chat](https://nexcmp.com/ar/docs/ai/ai-chat/) و [AI Agent](https://nexcmp.com/ar/docs/ai/ai-agent/) المخصصتين للعملاء، والتي تخدم عملاءك. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | الدور | مشرف مسجل الدخول. تنتمي الدردشة والمفاتيح والتفضيلات إلى حساب المشرف الخاص بك؛ ولا يراها المشرفون الآخرون. | | مصدر للإجابة | واحد على الأقل متصل: مفتاح API، أو تسجيل دخول، أو مزود الذكاء الاصطناعي الخاص باللوحة، أو واجهة CLI للذكاء الاصطناعي قمت بتسجيل الدخول إليها. راجع [AI accounts and subscriptions](https://nexcmp.com/ar/docs/configure-with-ai/ai-accounts-and-subscriptions/). | | عرض تجريبي | في لوحة تجريبية، يمكنك قراءة الدردشات القديمة ولكن لا يمكنك إرسال رسائل. | ## اختر مصدر الإجابات {#choose-where-answers-come-from} اختر المصدر من القائمة المنسدلة أسفل حقل الإدخال (فهي تعرض المصادر التي قمت بتوصيلها). يتيح لك قسم **System › Settings › AI accounts** أيضاً تعيين مصدر افتراضي، ونمودج افتراضي، والحد اليومي. | Source | كيفية الاتصال | ملاحظات | |---|---|---| | OpenAI (نماذج ChatGPT) | الصق مفتاح API من platform.openai.com | يتم الفوترة بواسطة OpenAI حسب الاستخدام. | | Anthropic (Claude) | الصق مفتاح API من console.anthropic.com | يتم الفوترة بواسطة Anthropic حسب الاستخدام. | | Google Gemini | الصق مفتاح API من aistudio.google.com، أو **Sign in with Google** | يتطلب تسجيل الدخول بحساب Google عميل OAuth تقوم **أنت** بإنشائه في مشروع Google Cloud الخاص بك. | | OpenRouter | الصق مفتاحاً، أو **Sign in with OpenRouter** | حساب واحد للعديد من النماذج. | | مزود الذكاء الاصطناعي للوحة | تم تعيينه مسبقاً في System › Settings › AI provider | نفس المزوِّد الذي يستخدمه AI Chat الخاص بعملائك. [AI provider](https://nexcmp.com/ar/docs/ai/ai-providers/). | | اشتراك Claude أو ChatGPT أو Gemini | واجهة CLI الرسمية مثبتة ومسجل الدخول إليها على خادم اللوحة | راجع [AI accounts and subscriptions](https://nexcmp.com/ar/docs/configure-with-ai/ai-accounts-and-subscriptions/). | يتم تخزين المفاتيح التي تلصقها مشفرة لحساب المشرف الخاص بك فقط. ولا يتم عرضها مرة أخرى ولا يمكن لأي مشرف آخر فك تشفيرها. ## استخدام الدردشة {#use-the-chat} 1. افتح **AI Chat** (أو انقر على **Ask AI**). 2. انقر على **New chat**، أو افتح دردشة سابقة من القائمة الموجودة على اليسار. 3. اكتب طلبك واضغط على Enter (مفتاح Shift+Enter يبدأ سطرًا جديدًا). يمكنك إرفاق صور أو ملفات نصية (بحد أقصى 4 لكل رسالة، و3 ميجابايت لكل منها) لعرض خطأ أو لصق مستند. 4. راقب تدفق الإجابة. تظهر كل أداة يستدعيها المساعد كبطاقة قابلة للطي تحتوي على اسم الأداة ومعarguments الخاصة بها ونتيجة مختصرة. 5. اضغط على **Stop** لإلغاء إجابة قيد التنفيذ. يتم تشغيل إجابة واحدة فقط في كل مرة لكل مشرف. ![AI Chat مع قائمة المحادثات، وإجابة تحتوي على بطاقات الأدوات، وحقل الإدخال مع محدد المصدر وحقل Secret](https://nexcmp.com/ar/docs/images/configure-with-ai/ai-chat-in-admin-01-chat.webp) تحدث ما يصل إلى 10 جولات أدوات لكل رسالة. يتذكر المساعد آخر 30 رسالة في المحادثة. يتم تمرير نتائج الأدوات إلى النموذج كبيانات وليست تعليمات. ## بطاقات التأكيد {#confirmation-cards} في AI Chat، **كل تغيير هو عبارة عن بطاقة**، وليس فقط العمليات المتعلقة بالأموال. المساعد يقترح وأنت تقرر. توضح البطقة: - عنوان يوضح سبب الحاجة إلى الانتباه، على سبيل المثال "يغير رصيد العميل". - الاستدعاء: الطريقة والمسار. - جدول بالحقول التي تتغير: القيمة الحالية والقيمة الجديدة. تظهر القيم السرية كـ `••••`. - عد تنازلي (تنتهي صلاحية البطاقات بعد 5 دقائق). - **Confirm** و **Reject**. **Confirm** تجعل اللوحة نفسها تطبق التغيير، ثم تخبر المساعد بما حدث. لا يمكن للمساعد الضغط على الزر، أو الموافقة عبر API، ويتم إخباره بألا يدعي أبداً أنه تم تطبيق أي تغيير قبل تأكيده. إذا أُعادت تحميل الصفحة، ستعود البطاقات التي لا تزال سارية. كما تظهر في أعلى **System › Settings › API & AI agents** تحت قسم "Waiting for your confirmation". ![بطاقة تأكيد توضح تغيير الرصيد، والعد التنازلي، وزري التأكيد والرفض](https://nexcmp.com/ar/docs/images/configure-with-ai/ai-chat-in-admin-02-confirm.webp) ## Secrets {#secrets} يجب عدم تمرير كلمات المرور ومفاتيح API عبر نص الدردشة. استخدم حقل **Secret** (رمز القفل) بجوار حقل الإدخال: 1. انقر على رمز القفل وأدخل **اسمًا** (أحرف، وأرقام، وشرطة سفلى، على سبيل المثال `smtp_password`) و**القيمة**. 2. في رسالتك، أشر إلى الاسم: "use the secret smtp_password as the SMTP password". 3. لا يرى المساعد سوى عنصر نائب يمثل السر، مكتوباً بهذا الشكل: ```text {{secret:smtp_password}} ``` تستبدل اللوحة هذا العنصر بالقيمة الحقيقية في اللحظة التي تُنفذ فيها الأداة. لا يتم حفظ القيمة في سجل الدردشة ولا تُرسل إلى مصدر الذكاء الاصطناعي. إذا قمت بلصق شيء يشبه المفتاح في الرسالة عن طريق الخطأ، تنقله اللوحة إلى نفس المخزن المحمي وتخفيه في السجل، ولكن تعامل مع ذلك كشبكة أمان وليس كطريقة معتمدة. تبقى الأسرار في ذاكرة اللوحة فقط، للمحادثة التي أُدخلت فيها ولمدة تصل إلى ساعة واحدة بعد رسالتها الأخيرة؛ كما يؤدي إعادة تشغيل اللوحة إلى مسحها أيضاً. أَدخلها مرة أخرى إذا طلب المساعد ذلك. تعيين سر يتطلب أيضاً إذن `secrets:write` لجلسة الدردشة (انظر أدناه). ## أذونات الدردشة {#permissions-of-the-chat} تعمل كل رسالة بمفتاح مؤقت موجود طوال مدة الإجابة (15 دقيقة على الأكثر)، ويعمل فقط من خادم اللوحة ولا يمكن استخدامه إلا من خلال بطاقات التأكيد. نطاقاته هي تلك التي تم تحديدها في **System › Settings › AI accounts › Chat session permissions**. `admin:read` مفعل دائمًا. جميع النطاقات باستثناء `secrets:write` مفعلة افتراضيًا؛ حدد `secrets:write` إذا كنت تريد أن يتمكن المساعد من تعيين كلمات المرور والمفاتيح (عبر حقل Secret). في لوحة تجريبية، تكون الدردشة للقراءة فقط. ## حد الإنفاق اليومي {#daily-spending-cap} يقوم AI Chat بجمع التكلفة المقدرة للإجابات من مصادر API. الحد الافتراضي هو **5 دولار أمريكي لكل مسؤول في اليوم**. قم بتعيين مبلغ آخر (0 يعني بلا حدود) ضمن **AI accounts › Defaults for AI Chat**. تظهر الصفحة "used today". عند الوصول إلى الحد الأقصى، ترفض الدردشة الرسائل الجديدة (`daily_cap`) حتى اليوم التالي أو حتى تقوم برفع الحد. المصادر التي تمثل اشتراكات AI CLI لا يتم احتسابها، لأنها تُفوترة بواسطة اشتراكك. ## التحقق {#verify} 1. في **AI accounts** انقر فوق **Test** على المصدر. يجيب باسم النموذج والوقت بالمللي ثانية. 2. في AI Chat، اطلب "Check my setup progress". تعرض الإجابة الخطوات من [checklist](https://nexcmp.com/ar/docs/configure-with-ai/setup-checklist/) وتظهر `setup_checklist` بطاقة أداة. 3. اطلب تغييرًا صغيرًا، على سبيل المثال "Set the brand name to Example Cloud". تظهر بطاقة تأكيد؛ اضغط على **Confirm** وتحقق من صفحة العلامة التجارية. 4. **API & AI agents › Activity** تسرد الاستدعاءات مع القناة `chat`. ## الحدود والملاحظات {#limits-notes} - لا يمتلك المساعد غلاف أوامر (shell) ولا يمكنه قراءة الملفات الموجودة على الخادم. إنه يستدعي فقط [admin tools](https://nexcmp.com/ar/docs/configure-with-ai/mcp-admin/#tools). - التغييرات التي لا يمكن للمفاتيح إجراؤها أبداً ([list](https://nexcmp.com/ar/docs/configure-with-ai/admin-api-keys/#what-a-key-can-never-do)) لا يمكن إجراؤها من AI Chat أيضًا. - تحقق من عمل النموذج. توضح بطاقة التأكيد بدقة ما سيتم إرساله؛ اقرأها، وخاصة الأسعار والمبالغ. - تُفوترة إجابات API بواسطة موفر الذكاء الاصطناعي. الحد الأقصى هو تقدير؛ قم بتعيين حد للإنفاق لدى الموفر أيضًا. - يتوقف رد CLI بعد 5 دقائق. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | "تم بلوغ الحد الأقصى للإنفاق على الذكاء الاصطناعي اليوم" (`daily_cap`) | لقد استهلكت الحد اليومي | ارفعه في حسابات الذكاء الاصطناعي، أو انتظر حتى الغد. | | "إجابة أخرى قيد التنفيذ حالياً - يرجى الانتظار أو الضغط على إيقاف" (`busy`) | إجابة واحدة في كل مرة لكل مسؤول | اضغط على **Stop** أو انتظر. | | المصدر غير ظاهر في القائمة المنسدلة | غير متصل، أو (Claude CLI) مفتاح "I understand" مغلق | قم بتوصيله في حسابات الذكاء الاصطناعي. | | "لا يبدو هذا كِمفتاح API" | المفتاح المنسوخ يحتوي على مسافات أو طويل جداً | الصق المفتاح فقط. | | فشل الاختبار | مفتاح خاطئ، أو لا توجد رصيد، أو المزود متوقف | تحقق من المفتاح والفواتير لدى المزود. | | يقول المساعد إنه لا يمكنه فعل شيء ما | جلسة الدردشة تفتقر إلى النطاق، أو الإجراء مغلق أمام الذكاء الاصطناعي | حدد النطاق في حسابات الذكاء الاصطناعي أو نفذه في لوحة الإدارة. | | تظهر بطاقة تفيد بأنها منتهية الصلاحية | انقضت أكثر من 5 دقائق | اطلب من المساعد اقتراح التغيير مرة أخرى. | | يبلغ مصدر CLI عن "حد الاستخدام" أو "غير مسجل الدخول" | حد اشتراكك أو جلستك | سجل الدخول مرة أخرى أو انتظر؛ راجع [AI accounts and subscriptions](https://nexcmp.com/ar/docs/configure-with-ai/ai-accounts-and-subscriptions/). | --- # حسابات واشتراكات الذكاء الاصطناعي {#ai-accounts-and-subscriptions} > **أين في لوحة الإدارة:** System › Settings › AI accounts (`/agent/accounts`)، التبويبات **Accounts** و **Use your own AI subscription**. الطرفية الاختيارية هي AI Console (`/agent/console`)، والتي تظهر ضمن AI Chat فقط عند تفعيلها. ## الوظيفة {#what-it-does} تحتاج دردشة AI Chat إلى شيء تجيب من خلاله. تتيح لك هذه الصفحة توصيل هذا المصدر لحساب المسؤول الخاص بك: - **مصادر API**: OpenAI، وAnthropic (Claude)، وGoogle Gemini، وOpenRouter، باستخدام مفتاح API أو تسجيل الدخول. - **مزود الذكاء الاصطناعي للوحة**، إذا كنت قد حددت واحداً بالفعل ضمن System › Settings › AI provider. - **اشتراكك الخاص في الذكاء الاصطناعي** (Claude، وChatGPT، وGemini) عبر **أداة سطر الأوامر الرسمية** الخاصة بالمزود، إما على خادم اللوحة أو على جهاز الكمبيوتر الخاص بك. كل ما تقوم بتوصيله ينتمي إلى حساب المسؤول الخاص بك. يتم تخزين المفاتيح والرموز مشفرة لك وحدك؛ ولا يمكن لمسؤول آخر استخدامها. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | الدور | مشرف مسجل الدخول. في لوحة تجريبية، لا يمكن توصيل أو إزالة أي شيء. | | مصادر API | حساب ومفتاح API لدى المزوّد (تحتوي البطاقة على رابط **Get API key** يفتح صفحة المزوّد). | | واجهة CLI على خادم اللوحة | تشغيل وحدة التحكم بالذكاء الاصطناعي AI Console (انظر أدناه)، وتفعيل اتصالات HTTPS الصادرة من الخادم إلى المزوّد وإلى `nodejs.org` وسجل npm، و**2 غيغابايت من ذاكرة الوصول العشوائي RAM أو أكثر** (تتطلب واجهة CLI حوالي 1 غيغابايت فارغة أثناء عملها؛ ويحذّر المثبّت إذا كانت الذاكرة أقل من 2 غيغابايت). يتم استخدام Node.js 20 أو أحدث إن وجد، وإلا يقوم المثبّت بتنزيل Node.js 22 مع التحقق من المجموع التداعي (checksum). | | واجهة CLI على حاسوبك | إصدار Node.js 20 أو أحدث لتثبيت واجهة CLI، واشتراكك الخاص. | ## توصيل مصدر API {#connect-an-api-source} 1. افتح **System › Settings › AI accounts** وابقَ في تبويب **Accounts**. 2. انقر على **Connect** في بطاقة المصدر. ستفتح صفحة المفاتيح الخاصة بالمزوّد في علامة تبويب جديدة؛ قم بتنشئة مفتاح هناك. 3. الصق المفتاح في الحقل واحفظه. ستعرض البطاقة حالة الاتصال مع عرض الأحرف الأربعة الأخيرة. 4. اختر **default model** إذا كنت تريد نموذجاً مختلفاً، ثم انقر على **Test**. تبدو النتيجة الجيدة هكذا: "Connected - example-model, 850 ms". ![صفحة حسابات الذكاء الاصطناعي AI accounts مع بطاقات مصادر API، وبطاقة OpenAI متصلة، وبطاقة مزود الذكاء الاصطناعي للوحة Panel AI provider](https://nexcmp.com/ar/docs/images/configure-with-ai/ai-accounts-and-subscriptions-01-accounts.webp) | Source | طريقة بديلة لتسجيل الدخول | |---|---| | OpenRouter | يؤدي النقر على **Sign in with OpenRouter** إلى فتح OpenRouter في نافذة منبثقة أو علامة تبويب جديدة؛ قم بالموافقة لتتم العودة إلى هذه الصفحة وأنت متصل. | | Google Gemini | يظهر الخيار **Sign in with Google** بعد الحفظ، تحت قسم **Set up Google sign-in (optional)** على البطاقة، وذلك باستخدام عميل OAuth مُنشأ في مشروع Google Cloud **الخاص بك** (معرف العميل ينتهي بـ `.apps.googleusercontent.com`، بالإضافة إلى السر الخاص به). لا ترفق NexCMP أي عميل Google مشترك مسبقاً. | | مزود الذكاء الاصطناعي للوحة | يستخدم المزود المُكوّن مسبقاً ضمن System › Settings › AI provider ([AI provider](https://nexcmp.com/ar/docs/ai/ai-providers/)). لا شيء ليتم لصقه. | لإلغاء توصيل أي مصدر، انقر على **Remove** في بطاقته. سيؤدي هذا إلى حذف المفتاح المخزن لحسابك. ### القيم الافتراضية، الحد اليومي والصلاحيات {#defaults-daily-cap-and-permissions} في أسفل تبويب **Accounts**، يحتوي قسم **Defaults for AI Chat** على ثلاثة إعدادات: | الإعداد | المعنى | |---|---| | المصدر والنموذج الافتراضيان | الإعدادات التي تستخدمها المحادثات الجديدة. لا يزال بإمكانك تغيير المصدر لكل رسالة. | | الحد اليومي للإنفاق (بالدولار الأمريكي، 0 = بلا حدود) | القيمة الافتراضية هي 5. تظهر الصفحة عبارة "مستخدم اليوم". راجع [AI Chat in the admin](https://nexcmp.com/ar/docs/configure-with-ai/ai-chat-in-admin/#daily-spending-cap). | | صلاحيات جلسة المحادثة | النطاقات التي يجوز للمساعد استخدامها. `admin:read` مفعل دائماً؛ بينما `secrets:write` معطل افتراضياً. راجع [Admin API keys](https://nexcmp.com/ar/docs/configure-with-ai/admin-api-keys/#scopes). | انقر على **Save defaults**. ## استخدم اشتراكك الخاص في الذكاء الاصطناعي {#use-your-own-ai-subscription} يمكنك تشغيل NexCMP باستخدام خطة Claude أو ChatGPT أو Gemini التي تدفع ثمنها بالفعل، دون الحاجة إلى مفتاح API منفصل. توجد طريقتان للقيام بذلك. ### الطريقة 1 (موصى بها): واجهة CLI على حاسوبك الشخصي {#way-1-recommended-the-cli-on-your-own-computer} أنت تستخدم أداة المزوّد الخاصة على حاسوبك وتسجل الدخول بحسابك بالطريقة الاعتيادية للمزوّد. تتلقى NexCMP فقط طلبات MCP موقّعة بمفتاح قصير الأجل. افتح **AI accounts › Use your own AI subscription**؛ حيث ستعرض ثلاث خطوات لكل أداة. 1. انقر على **Create a 7-day key** واختر المستوى: **Read only** (`admin:read`) أو **Read + configuration** (`admin:read`، `catalog:write`، `infra:write`، `settings:write`). ستتضمن الأوامر أدناه المفتاح الحقيقي بعد ذلك. 2. قم بتثبيت واجهة CLI وتسجيل الدخول. يُعرض المفتاح في هذه الصفحة مرة واحدة فقط. | الأداة | التثبيت | تسجيل الدخول | |---|---|---| | Claude Code | `npm install -g @anthropic-ai/claude-code` | قم بتشغيل `claude`، ثم `/login` | | Codex CLI | `npm install -g @openai/codex` | `codex login` | | Gemini CLI | `npm install -g @google/gemini-cli` | قم بتشغيل `gemini`، واختر "Login with Google" | 3. قم بتوصيله باللوحة باستخدام أمر واحد أو كتلة واحدة، يتم نسخهما من الصفحة: ```bash # Claude Code claude mcp add --transport http nexcmp https://cloud.example.com/mcp/admin \ --header "Authorization: Bearer ak_XXXX" ``` ```toml # Codex CLI: ~/.codex/config.toml, then: export NEXCMP_KEY=ak_XXXX [mcp_servers.nexcmp] url = "https://cloud.example.com/mcp/admin" bearer_token_env_var = "NEXCMP_KEY" ``` ```json // Gemini CLI: ~/.gemini/settings.json { "mcpServers": { "nexcmp": { "httpUrl": "https://cloud.example.com/mcp/admin", "headers": { "Authorization": "Bearer ak_XXXX" } } } } ``` 4. ابدأ الأداة واسأل مثلاً: "what is left to set up in nexcmp?". جميع تفاصيل اتصال MCP موجودة في [Connect an AI client](https://nexcmp.com/ar/docs/configure-with-ai/mcp-admin/). تُظهر نفس العلامة التبويب عنوان URL لموصلات **claude.ai** و**ChatGPT**، والتي تسجل الدخول باستخدام OAuth ولا تحتاج إلى مفتاح: [OAuth connectors](https://nexcmp.com/ar/docs/configure-with-ai/oauth-connectors/). ![استخدم علامة تبويب اشتراك الذكاء الاصطناعي الخاص بك مع زر المفتاح لمدة 7 أيام وأوامر التثبيت وتسجيل الدخول والاتصال لثلاثة CLIs](https://nexcmp.com/ar/docs/images/configure-with-ai/ai-accounts-and-subscriptions-02-subscription.webp) ### الطريقة 2: واجهة CLI على خادم اللوحة (أزرار التثبيت / تسجيل الدخول) {#way-2-the-cli-on-the-panel-server-install-login-buttons} تتيح البطاقات الموجودة ضمن قسم "Subscription through a CLI (Claude, ChatGPT, Gemini)" لـ NexCMP تثبيت واجهة الأوامر الرسمية (CLI) على خادم اللوحة وفتح تدفق تسجيل الدخول الخاص بها، حتى يتمكن **AI Chat** من الرد باستخدام اشتراكك. **كيف يتم العزل.** تعمل أدوات CLI في عملية منفصلة (`nexcmp-ai.service`) كمستخدم نظام خاص بها `nexcmp-ai`، بدون الصلاحيات الجذرية (sudo)، ودون أي وصول إلى بيانات NexCMP ومجلدات التكوين ومع حد للذاكرة. بالنسبة لكل رسالة في AI Chat، يتم تشغيل CLI مع السماح بأدوات NexCMP MCP فقط (أدوات الشปล والملفات مغلقة) ومفتاح يعمل من الخادم فقط. لا تقرأ NexCMP أو تنسخ عملية تسجيل الدخول الخاصة بـ CLI: بل تحافظ عليها في مجلد خاص لحساب المسؤول الخاص بك. لا يوجد شيء لتفعيله: تقوم اللوحة بإعداد مستخدم وخدمة `nexcmp-ai` عند تثبيتها أو تحديثها إلى الإصدار 1.4.0، بحيث تكون البطاقات جاهزة للاستخدام. **التثبيت وتسجيل الدخول (لكل مسؤول):** 1. في بطاقة CLI، انقر على **Login**. إذا لم تكن أداة CLI مثبتة بعد، تقوم اللوحة بتثبيتها أولاً: يظهر شريط تقدم وسجل قصير لعملية التنزيل (Node.js إذا لزم الأمر، ثم CLI). يظهر تحذير عندما يكون الخادم يحتوي على ذاكرة وصول عشوائي (RAM) أقل من 2 جيجابايت. 2. توضح البطاقة ما تطلبه أداة CLI: - **Codex CLI**: انقر على **Open the sign-in page** واكتب الرمز لمرة واحدة الذي تعرضه البطاقة. (يجب تمكين تسجيل الدخول للأجهزة في إعدادات الأمان الخاصة بـ ChatGPT في OpenAI). - **Claude Code and Gemini CLI**: انقر على **Open the sign-in page**، وسجل الدخول، ثم الصق رمز التحقق الذي تعرضه صفحة المزود في **Paste the verification code here** وانقر على **Send code**. 3. تحولت البطاقة إلى "Signed in" مع الحساب والإصدار. يتم إلغاء تسجيل الدخول الذي لم ينتهي خلال 10 دقائق؛ انقر فوق **Login** مرة أخرى. 4. في **AI Chat** يظهر المصدر الآن في محدد (على سبيل المثال "ChatGPT (via Codex CLI)"). 5. يؤدي **Sign out** إلى إزالة تسجيل الدخول الخاص بـ CLI لحسابك. بالنسبة لـ Claude، تحتوي البطاقة على مفتاح إضافي، **I understand and accept the vendor's terms for using a subscription this way**، وهو معطل افتراضياً. لا يتم تقديم المصدر في AI Chat حتى يتم تشغيله. ![بطاقات اشتراك CLI مع خيار التثبيت وتسجيل الدخول، ورمز لمرة واحدة على بطاقة Codex، ومفتاح أفهم على بطاقة Claude](https://nexcmp.com/ar/docs/images/configure-with-ai/ai-accounts-and-subscriptions-03-cli.webp) ### شروط مزودي الذكاء الاصطناعي {#terms-of-the-ai-vendors} إن تسجيل الدخول باستخدام اشتراك المستهلك يحكمه شروط كل مزود والتي تتغير. الملاحظات أدناه هي ملخص لما ينشره المزودون اعتباراً من أكتوبر 2026، وليست استشارة قانونية وليست بياناً نيابة عن المزود. اقرأ الصفحات الحالية قبل تشغيل هذا. | المورّد | ما تغطيه صفحة المورّد | Source | |---|---|---| | Anthropic (Claude) | يتم تغطية تسجيل الدخول إلى Claude Code غير المعدل باستخدام خطتك الخاصة. أما استخدام اشتراك عبر منتجات أخرى، أو قيام منتج بجمع أو تمرير عملية تسجيل الدخول، فيتم التعامل معه بشكل مختلف، وتفترض حدود الخطة الاستخدام الفردي العادي. ولهذا السبب تحمل بطاقة Claude ملاحظة ومفتاح **I understand**، ولهذا تعد الطريقة 1 الخيار الأفضل. | https://code.claude.com/docs/en/legal-and-compliance | | OpenAI (Codex) | يدعم Codex تسجيل الدخول بحساب ChatGPT أو مفتاح API. توصي OpenAI بمفاتيح API للأتمتة وتحذر من تعريض Codex في بيئات غير موثوقة أو عامة. استخدم البطاقة لنفسك فقط. | https://developers.openai.com/codex/auth | | Google (Gemini CLI) | يدعم تسجيل الدخول بحساب Google، ومفتاح API، وVertex AI؛ وتعتمد الشروط على طريقة تسجيل الدخول، وتُطبق حصص خطتك. | https://geminicli.com/docs/get-started/authentication | إذا كنت تريد تجنب الأمر تماماً، فاستخدم مصدر **API key**، أو الطريقة 1 على حاسوبك الشخصي. ## وحدة تحكم الذكاء الاصطناعي {#ai-console} وحدة تحكم الذكاء الاصطناعي هي صفحة طرفية اختيارية لتشغيل إحدى واجهات CLI المسجلة على خادم اللوحة. وهي **معطلة افتراضياً**. - قم بتفعيلها أو تعطيلها، وأدر واجهات CLI على الخادم: ```bash sudo nexcmp ai-console enable # turn on (also creates the nexcmp-ai user and service) sudo nexcmp ai-console disable # turn off sudo nexcmp ai-console status # runner, console state and installed CLIs sudo nexcmp ai-console install claude # or codex, or gemini ``` تطبع `status` ما إذا كانت مقبس مشغل الذكاء الاصطناعي جاهزة، وما إذا كانت وحدة تحكم الذكاء الاصطناعي مفعلة أو معطلة، ولكل CLI حالة "مثبت" أو "غير مثبت". وتظهر `sudo nexcmp status` أيضاً "مشغل الذكاء الاصطناعي: نشط". - بمجرد التفعيل، تظهر علامة تبويب **AI Console** أسفل AI Chat. اختر واجهة CLI مسجلة الدخول، وأعد إدخال كلمة مرور المشرف الخاصة بك (ورمز التحقق الثنائي 2FA إذا كنت تستخدمه) وافتح جلسة. يذكرك شعار بأن الأوامر هنا لا يمكنها إدارة NexCMP إلا من خلال أدوات MCP الخاصة بها؛ حيث يتم تعطيل أدوات الصدفة (shell) والملفات. - لا تنشئ عمليات التثبيت التجريبية مستخدم `nexcmp-ai` أبداً. ![شاشة بدء وحدة تحكم الذكاء الاصطناعي مع محدد CLI، وحقل كلمة المرور، وشعار التحذير الخاص بـ MCP فقط](https://nexcmp.com/ar/docs/images/configure-with-ai/ai-accounts-and-subscriptions-04-console.webp) ## التحقق {#verify} 1. يُرجع **Test** على مصدر API اسم النموذج. 2. على بطاقة CLI، تظهر الحالة "تم تسجيل الدخول" مع الحساب. 3. على الخادم: تسرد `sudo nexcmp ai-console status` واجهة CLI كمدعومة، وتطبع `systemctl is-active nexcmp-ai` النتيجة `active`. 4. في AI Chat، اختر المصدر، واسأل "Check my setup progress"، وستظهر بطاقة أداة. ## الحدود والملاحظات {#limits-notes} - تقتصر إجابة CLI على 5 دقائق وإجابة واحدة في كل مرة لكل مشرف. ولا يحتسب الحد اليومي إجابات CLI. - يظل كل تغيير صادر عن مصدر CLI عبارة عن بطاقة تأكيد في AI Chat؛ ولا يمكن لـ CLI تطبيق التغييرات بمفرده. - تخضع خطط الاشتراكات لحدود استخدام خاصة بها. وعندما يقول المورّد "حد الاستخدام" أو "لم تقم بتسجيل الدخول"، تعرض الدردشة تلك الرسالة. - إزالة المصدر لا تؤدي إلى حذف المحادثات. - احافظ على تحديث الخادم: يتم تثبيت واجهات CLI من حزم المورّدين العامة في وقت النقر فوق تثبيت. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | تم تعطيل تسجيل الدخول وتقول البطاقة "أدوات الذكاء الاصطناعي غير جاهزة على الخادم بعد" | خدمة `nexcmp-ai` لا تعمل | قم بتحديث اللوحة إلى أحدث إصدار، ثم تحقق من `sudo nexcmp status`. يُعد هذا متوقعاً في النسخة التجريبية للقراءة فقط. | | "أدوات الذكاء الاصطناعي غير مثبتة على هذا الخادم بعد" | خدمة `nexcmp-ai` لا تعمل (لوحة قديمة، أو لوحة تجريبية) | قم بتحديث اللوحة، ثم `sudo nexcmp ai-console install claude` (أو `codex`، `gemini`). | | تحذير بشأن ذاكرة الوصول العشوائي (RAM) التي تقل عن 2 جيجابايت | الخادم صغير | قد يكون التثبيت بطيئاً أو يفشل؛ أضف ذاكرة أو استخدم الطريقة 1. | | "عدم تطابق مجموع الاختباري لتنزيل Node.js" أو "فشل التنزيل" | لا يمكن للخادم الوصول إلى nodejs.org، أو قام وكيل (proxy) بتعديل التنزيل | اسموح بـ HTTPS الصادر وأعد المحاولة. | | ينتهي التثبيت بحدوث خطأ | لم يتمكن npm من تثبيت الحزمة | اقرأ السجل الموجود على البطاقة، وتحقق من الوصول الصادر إلى سجل npm، ثم أعد المحاولة. | | تنتهي عملية تسجيل الدخول بخطأ أو تنتهي مهلتها | انقضت نافذة الـ 10 دقائق، أو كان الرمز غير صحيح | انقر فوق **Login** مرة أخرى وأكملها بشكل أسرع. | | مصدر Claude مفقود في AI Chat | مفتاح **I understand** معطل، أو لم يتم تسجيل الدخول إلى CLI | قم بتشغيل المفتاح بعد قراءة صفحة المورد، ثم سجل الدخول. | | خيار "Sign in with Google" مفقود في Gemini | لم يتم حفظ عميل Google OAuth بعد | أنشئ العميل في مشروع Google Cloud الخاص بك واحفظه ضمن **Set up Google sign-in (optional)** على البطاقة، أو الصق مفتاح API بدلاً من ذلك. | | إرجاع خطأ عند استخدام "Sign in with OpenRouter" | لقد قیت بالإلغاء، أو تم حظر النافذة المنبثقة | اسمح بالنافذة المنبثقة وحاول مرة أخرى. | | إجابة CLI تقول "usage limit" | تم استنفاد حصة الخطة | انتظر، أو قم بتبديل المصدر. | --- # مفاتيح Admin API {#admin-api-keys} > **أين تجد ذلك في لوحة المشرف:** System › Settings › API & AI agents (`/agent/keys`)، علامة التبويب **API keys**. تحتوي نفس الصفحة على علامات التبويب **Connect an AI** و **Connected apps** و **Activity**. ## الوظيفة {#what-it-does} يسمح مفتاح Admin API (البادئة `ak_`) لعميل ذكاء اصطناعي أو برنامج نصي بإدارة لوحتك بالصلاحيات الدقيقة التي تمنحها إياه. وهو يعمل على Admin API ضمن `/v1/admin/` وعلى نقطة نهاية Admin MCP ضمن `/mcp/admin`. وهو لا يعمل في أي مكان آخر. ::: info ليس هو نفسه مفاتيح العملاء ينشئ العملاء مفاتيح تبدأ بـ `vk_` في بوابة العملاء ([API keys and scopes](https://nexcmp.com/ar/docs/developers/api-keys/)). تصل هذه المفاتيح فقط إلى Customer API و `/mcp`. يتم رفض مفتاح `ak_` على Customer API، ويتم رفض مفتاح `vk_` على Admin API. ::: ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | الدور | يجب عليك تسجيل الدخول بصفتك مشرفاً. لا يمكن للمفاتيح إنشاء مفاتيح أخرى. | | عرض تجريبي | في لوحة تجريبية، تكون الصفحة للقراءة فقط: لا يمكن إنشاء أو إلغاء أي مفتاح. | | إمكانية الوصول | يجب أن يتمكن العميل من الوصول إلى `https://cloud.example.com/mcp/admin` أو `/v1/admin/...` على لوحتك (تحقق من جدار الحماية الخاص بك إذا كنت تستخدم تقييد عناوين IP). | ## إنشاء مفتاح {#create-a-key} 1. افتح **System › Settings › API & AI agents** وابقَ في علامة التبويب **API keys**. 2. انقر فوق **Create new key**. 3. املأ النموذج: | الحقل | القواعد | |---|---| | الاسم | حتى 60 حرفاً، على سبيل المثال "Claude Code on my laptop". | | النطاقات | حدد واحداً على الأقل. راجع [Scopes](#scopes). ابدأ بـ `admin:read` فقط. | | تاريخ الانتهاء | 1، 7، 30، 60 أو 90 يوماً. الافتراضي هو 30. الحد الأقصى 90. لا يمكن إنشاء مفتاح بدون تاريخ انتهاء. | | نطاقات عناوين IP (اختياري) | عنوان IPv4 أو IPv6 واحد أو CIDR في كل سطر، على سبيل المثال `203.0.113.0/24` أو `2001:db8::/48`. بحد أقصى 32. اترك الحقل فارغاً للسماح بأي عنوان IP. | | المكالمات في الدقيقة | من 1 إلى 6000. الافتراضي هو 120. | 4. انقر فوق **Create key**. يعرض المربع المفتاح مرة واحدة، على سبيل المثال `ak_XXXX`. **انسخه الآن**: لا تخزن NexCMP سوى تجزئة (hash) ولا يمكنها إظهاره مرة أخرى أبداً. 5. انقر فوق **I have saved the key**. افتح علامة التبويب **Connect an AI** للحصول على أوامر جاهزة للصق تحتوي مسبقاً على المفتاح الذي أنشأته للتو (فقط على هذه الصفحة، حتى تقوم بتحديثها). ![نافذة المفتاح الجديد مع الاسم، خانات النطاق، تاريخ انتهاء الصلاحية ونطاق IP المعبأة](https://nexcmp.com/ar/docs/images/configure-with-ai/admin-api-keys-01-create.webp) ![نافذة تعرض المفتاح الجديد مرة واحدة مع زر نسخ وتحذير](https://nexcmp.com/ar/docs/images/configure-with-ai/admin-api-keys-02-shown-once.webp) ## النطاقات {#scopes} لا يمكن لأي مفتاح استخدام سوى الأدوات ونقاط النهاية التي تسمح بها نطاقاتُه. لا تتضمن نطاقات الكتابة صلاحية القراءة: لذا يحتاج المفتاح الذي يجب أن يقرأ ويكتب إلى `admin:read` أيضاً. | النطاق | ما تسمح به | |---|---| | `admin:read` | قراءة الإعدادات، الكتالوج، العملاء، الفوترة والسجلات. لا يتم إرجاع الأسرار مطلقاً. | | `catalog:write` | الخطط، قوالب نظام التشغيل، حصص الاستخدام، رموز الخصم. | | `infra:write` | مصادر البنية التحتية (CloudStack، Proxmox)، المناطق، الخوادم. | | `billing:write` | بوابات الدفع، العملة، الفواتير، الأرصدة. تتطلب العمليات المالية تأكيداً. | | `customers:write` | العملاء والموزعون. | | `settings:write` | الإعدادات العامة، العلامة التجارية، البريد الإلكتروني، الصفحات القانونية، الوحدات النمطية، الإشعارات. | | `ai:write` | مزود الذكاء الاصطناعي وميزات الذكاء الاصطناعي. | | `secrets:write` | كتابة كلمات المرور ومفاتيح API. يمكن تعيينها ولكن لا يمكن قراءتها مرة أخرى مطلقاً. | ::: tip تعيين سر يتطلب نطاقين أي طلب يحمل كلمة مرور أو مفتاح API أو قيمة رمز (كلمة مرور SMTP، مفتاح دفع، رمز بوت Telegram، مفتاح مزود الذكاء الاصطناعي، بيانات اعتماد CloudStack أو Proxmox) يحتاج إلى `secrets:write` **بالإضافة إلى** نطاق المنطقة (على سبيل المثال `settings:write` لـ SMTP). إذا كنت تفضل كتابة الأسرار بنفسك، فاترك `secrets:write` متوقفاً وأدخلها في لوحة الإدارة. ::: ## إلغاء مفتاح {#revoke-a-key} 1. ابحث عن المفتاح في الجدول (الحالة **Active**، **Expired** أو **Revoked**؛ يعرض **Last used** الوقت والعميل). 2. انقر على **Revoke** وأكد العملية. يتوقف المفتاح عن العمل فوراً. عملية الإلغاء نهائية؛ أنشئ مفتاحاً جديداً إذا كنت بحاجة إليه مرة أخرى. ## ما لا يفعله المفتاح أبداً {#what-a-key-can-never-do} لا يمكن لمفتاح الوصول إلى هذه المناطق مطلقاً، بغض النظر عن نطاقاته. تتطلب هذه المناطق تسجيل دخولك كمدير. - إنشاء أو تغيير مستخدمي الإدارة، المصادقة الثنائية (2FA) وأمان تسجيل الدخول، جلسات المشرف، ورموز API الخاصة بالإدارة. - إنشاء أو سرد أو إلغاء مفاتيح المشرف، اتصالات OAuth وحسابات الذكاء الاصطناعي، أو استخدام وحدة تحكم الذكاء الاصطناعي. - نسخ لوحة التحكم احتياطياً أو استعادتها، تحديثها، أو تغيير ترخيصها. - تسجيل الدخول كعميل أو موزّع، فتح وحدة تحكم العميل، قراءة بيانات اعتماد الجهاز الافتراضي أو ملف kubeconfig، تعيين مفاتيح SSH، أو إرسال كلمات المرور أو إعادة تعيينها. - تغيير وحدات الشبكة والتوجيه (BGP، FRR، RTBH، XDP، الواجهات، المسارات الثابتة ومسارات السياسة، NAT) أو الوكلاء الخارجيين وتكامل البوابة. هذه للقراءة فقط. - تغيير الإعدادات مثل `demo_*`، `admin_*`، قوائم المضيفين، مفتاح المرور، إعادة المصادقة وأسرار اختبار التحقق (captcha). أي شيء لا تغطيه قاعدة ما يكون مغلقاً افتراضياً للكتابة، وقابلاً للقراءة باستخدام `admin:read` للقراءة. ### الإجراءات التي تتطلب تأكيدك {#actions-that-need-your-confirmation} تنجح هذه الإجراءات فقط بعد موافقتك على معاينة (انظر [Two-step confirmation](#two-step-confirmation)): - تغيير رصيد العميل أو محفظة الموزع، دفع الأموال، سجلات الفوترة، سعر الصرف. - تغيير الأسعار (أسعار الخطط، إنشاء الخطط المجمعة، تسعير الصور والتخزين) وإنشاء رموز الخصم أو الأموال. - حفظ بيانات اعتماد بوابة الدفع أو اتصال CloudStack. - حذف أي شيء، حظر عميل أو حذفه، تغيير حدود العميل، تعليق موزّع أو إغلاقه. - التفاعل مع خوادم العملاء، أو إنشاء خادم مدفوع لعميل. - تغيير المفاتيح العامة للموقع، إعدادات أمان تسجيل الدخول أو إعدادات الدفع من خلال الإعدادات العامة. ## التأكيد على خطوتين {#two-step-confirmation} عندما تحتاج عملية استدعاء إلى تأكيد، فلن يتغير شيء بعد. الرد هو HTTP **428** مع `confirm_required`، و`confirm_token`، و`preview` (الطريقة، المسار، السبب، القيم الجديدة، وعند توفرها، القيم الحالية) و`expires_in: 300`. 1. يعرض لك العميل معاينة التغيير. 2. بعد الموافقة، يتم تكرار **نفس** الطلب (نفس الطريقة والمسار وbody) مع الترويسة `X-Confirm-Token: `. تأخذ أدوات MCP الوسيط `confirm_token` بدلاً من ذلك. 3. الرمز يعمل لمرة واحدة وينتهي صلاحيته بعد 5 دقائق. المفاتيح التي يتم إنشاؤها داخل لوحة المشرف لأجل AI Chat لا يمكن تأكيدها إلا على الشاشة: يقول الرد `confirm_in: "ui"` وتظهر بطاقة تأكيد في لوحة المشرف. لا يمكن للذكاء الاصطناعي الموافقة عليها. ## قواعد الحد الأقصى للمعدل وعناوين IP {#rate-limit-and-ip-rules} - عند تجاوز الحد المسموح به في الدقيقة، يُرجع الاستدعاء `rate_limited` (HTTP 429) مع `Retry-After: 60`. - عند ضبط نطاقات IP، فإن الاستدعاءات الواردة من أي عنوان آخر تُرجع `ip_not_allowed` (HTTP 403). ## سجل النشاطات {#activity-log} تُدرج تبويب **Activity** كل عملية استدعاء تتم باستخدام المفتاح، والأحدث أولاً: الوقت، المفتاح، العميل، طريقة الوصول (`http`، `mcp`، `chat`، `cli`، `confirm`، `preview`)، الطريقة والمسار، الأداة، حالة HTTP، عنوان IP والتفاصيل (المخفية). يمكنك البحث حسب المسار أو الأداة أو اسم المفتاح، أو إظهار الأخطاء فقط (HTTP 400 وما فوق) أو الاستدعاءات التي تنتظر التأكيد فقط (428 وما فوق)، وتحديد الفترة الزمنية لتشمل الساعة الأخيرة أو 24 ساعة أو 7 أيام. تحتفظ NexCMP بآخر 200,000 إدخال. تظهر التغييرات التي يتم إجراؤها عبر مفتاح أيضاً في Logs › Admin actions تحت اسم `ak:/`. ![تبويب Activity يعرض الاستدعاءات مع الحالة، العميل، الأداة وعنوان IP](https://nexcmp.com/ar/docs/images/configure-with-ai/admin-api-keys-03-activity.webp) ## التحقق {#verify} اختبر مفتاح القراءة فقط من أي جهاز يقع داخل نطاق IP: ```bash curl -s https://cloud.example.com/v1/admin/agent/tools \ -H "Authorization: Bearer ak_XXXX" ``` ستحصل على قائمة بتنسيق JSON بالأدوات التي تسمح بها نطاقات صلاحياتك. قم بتشغيل إحداها: ```bash curl -s -X POST https://cloud.example.com/v1/admin/agent/tools/system_health \ -H "Authorization: Bearer ak_XXXX" \ -H "Content-Type: application/json" -d '{}' ``` يتحدث وقت **Last used** الخاص بالمفتاح ويظهر الاستدعاء في **Activity**. يتم وصف قائمة الأدوات الكاملة ووصف OpenAPI (`/v1/admin/openapi.json`) في [Connect an AI client](https://nexcmp.com/ar/docs/configure-with-ai/mcp-admin/). ## الأخطاء {#errors} تأتي الأخطاء بتنسيق JSON: `{"error": {"code": "...", "message": "..."}}`. | HTTP | `code` | المعنى | الحل | |---|---|---|---| | 401 | `invalid_key` | المفتاح مفقود، أو غير مصاغ بشكل صحيح، أو غير معروف. يُعاد هذا الرد أيضاً عند استخدام مفتاح `ak_` على مسار غير خاص بالمشرف. | تحقق من المفتاح؛ واستخدمه فقط على `/v1/admin/` و`/mcp/admin`. | | 401 | `key_expired` | انتهت صلاحية المفتاح. | أنشئ مفتاحاً جديداً. | | 401 | `key_revoked` | تم إبطال المفتاح. | أنشئ مفتاحاً جديداً. | | 403 | `ip_not_allowed` | عنوان IP الخاص بالمرسل خارج نطاقات IP المسموحة للمفتاح. | قم بالاستدعاء من عنوان IP مسموح به، أو أنشئ مفتاحاً بالنطاق الصحيح. | | 403 | `local_only_key` | تم استخدام مفتاح مخصص لـ AI Chat أو لـ server CLI من جهاز آخر. | هذه المفتاح تعمل فقط على خادم لوحة التحكم نفسه. | | 403 | `insufficient_scope` | المفتاح يفتقر إلى نطاق صلاحية (scope)؛ ويتضمن الرد `required_scope`. | أنشئ مفتاحاً يحتوي على هذا النطاق. | | 403 | `forbidden_for_keys` | نقطة النهاية، أو الإعداد الذي حاولت تغييره، مغلقة أمام المفاتيح. | قم بذلك من خلال لوحة المشرف. | | 403 | `demo_read_only` | لوحة التحكم في وضع التجربة (demo mode) والاستدعاء يحاول إجراء كتابة. | استخدم لوحة تحكم لا تعمل في وضع التجربة. | | 403 | `confirm_in_ui` | يجب تأكيد هذا الإجراء على الشاشة في لوحة المشرف. | قم بالموافقة على بطاقة التأكيد. | | 428 | `confirm_required` | المعايِنة جاهزة؛ لم يتغير شيء. تتضمن `confirm_token`. | اعرض المعاينة، ثم كرّر الطلب باستخدام `X-Confirm-Token`. | | 409 | `confirm_expired` | الرمز أقدم من 5 دقائق. | أرسل الطلب مرة أخرى للحصول على معاينة جديدة. | | 409 | `confirm_mismatch` | الرمز ينتمي إلى طلب مختلف (يختلف في الطريقة أو المسار أو body). | كرر الطلب المطابق تماماً. | | 409 | `confirm_invalid` | رمز غير معروف أو تم استخدامه مسبقاً. | أرسل الطلب مرة أخرى للحصول على معاينة جديدة. | | 429 | `rate_limited` | عدد كبير جداً من الاستدعاءات في هذه الدقيقة. | انتظر حتى `Retry-After`. | | 400 | `invalid_path` | يحتوي المسار على تسلسلات محظورة. | استخدم مساراً بسيطاً. | | 413 | `too_large` | النَتْل (الجسم) يتجاوز 10 ميغابايت. | أرسل بيانات أقل. | | 400 | `invalid_argument` | معامل الأداة مفقود، أو غير معروف، أو ذو نوع خاطئ؛ وتسميه الرسالة. | أصلح المعامل. | ## الحدود والملاحظات {#limits-notes} - اجعل المفاتيح قصيرة الأجل ومحدودة النطاق. يفضل مفتاح واحد لكل عميل لكي تتمكن من إبطال مفتاح واحد بشكل منفصل. - المفتاح بقوة نطاقاته. `secrets:write` زائد `billing:write` هو التجميعة الأكثر حساسية؛ وتتوقف إجراءات الأموال عند المعاينة دائماً. - المفاتيح المنشأة تلقائياً (لـ AI Chat و CLI الخادم) تعيش لدقائق معدودة وتعمل حصرياً من خادم اللوحة. - لقطع اتصال عميل ذكاء اصطناعي فوراً، أبطل مفتاحه. يتم إبطال اتصالات OAuth من تبويب **Connected apps** ([OAuth connectors](https://nexcmp.com/ar/docs/configure-with-ai/oauth-connectors/)). --- # توصيل عميل ذكاء اصطناعي (MCP) {#connect-an-ai-client-mcp} > **أين تجد ذلك في لوحة المشرف:** System › Settings › API & AI agents (`/agent/keys`)، ويُظهر تبويب **Connect an AI** عنوان URL لنقطة النهاية وقصاصة جاهزة للنسخ لكل عميل، معبأة بمفتاح أنشأته للتو. ## الوظيفة {#what-it-does} يتيح بروتوكول **Model Context Protocol (MCP)** لعميل الذكاء الاصطناعي استدعاء الأدوات. تخدم لوحتك خادم MCP للمشرف على `https://cloud.example.com/mcp/admin`. قم بتوصيل أداة الذكاء الاصطناعي الخاصة بك به واسأل بلغة واضحة: "ما الذي تبقى لإعداده؟"، "أضف مجموعة Proxmox الخاصة بي"، "أنشئ خططاً بهامش 40%". يستدعي العميل أدوات المشرف أدناه؛ وتتحقق اللوحة من النطاقات، وتسألك قبل أي إجراء محفوف بالمخاطر، وتسجل كل عملية استدعاء. ::: info نقطتا نهاية MCP `/mcp` هي نقطة نهاية **العميل** (مفاتيح API الخاصة بالعملاء، `vk_`؛ راجع [خادم MCP](https://nexcmp.com/ar/docs/developers/mcp/)). `/mcp/admin` هي نقطة نهاية **المسؤول** الموضحة هنا (مفاتيح المسؤول `ak_` أو OAuth). لا تختلط الجهتان أبداً: أدوات المسؤول غير مرئية على `/mcp`، وتقبل `/mcp/admin` مفاتيح المسؤول فقط. ::: ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | نقطة النهاية | `https://cloud.example.com/mcp/admin` على نطاق لوحتك الخاص. انسخ عنوان URL الدقيق من تبويب **Connect an AI**. تعرض نفس الصفحة عنوان URL محلي (`http://127.0.0.1:/mcp/admin`) للأدوات التي تعمل على الخادم نفسه. | | بيانات الاعتماد | [مفتاح مسؤول API](https://nexcmp.com/ar/docs/configure-with-ai/admin-api-keys/) (`ak_...`) مع النطاقات التي تريدها، **أو** تسجيل الدخول عبر OAuth لموصلات الويب ([موصلات OAuth](https://nexcmp.com/ar/docs/configure-with-ai/oauth-connectors/)). | | العميل | أي عميل MCP يدعم نقل **Streamable HTTP** وترويسة `Authorization` مخصصة. إصدارات البروتوكول 2025-11-25 و 2025-06-18 و 2025-03-26. | | الشبكة | إذا وضعت وكيل عكسي (reverse proxy) خاص بك أمام اللوحة، فيجب عليه إعادة توجيه `/mcp/admin`. تتصل موصلات الويب (claude.ai و ChatGPT) من خوادم المزود، لذا يجب أن يكون عنوان URL قابلاً للوصول من الإنترنت. | ## تجهيز البنية التحتية {#prepare-the-infrastructure} لا شيء لتثبيته على الخادم. إذا قمت بتقييد المفتاح حسب عنوان IP، فتأكد من أن العنوان الذي يتصل منه عميلك يقع ضمن النطاق. اختبر إمكانية الوصول أولاً: ```bash curl -i -X POST https://cloud.example.com/mcp/admin ``` استجابة `401` مع ترويسة `WWW-Authenticate: Bearer ... resource_metadata=...` تعني أن نقطة النهاية تعمل وتريد بيانات الاعتماد. ## الربط في NexCMP {#connect-in-nexcmp} 1. إنشاء مفتاح: **System › Settings › API & AI agents › API keys › New key**. للاستخدام الأول، استخدم `admin:read` فقط؛ وأضف نطاقات الكتابة عندما تحتاج إليها. راجع [Admin API keys](https://nexcmp.com/ar/docs/configure-with-ai/admin-api-keys/). 2. افتح تبويب **Connect an AI**. بينما لا يزال مربع حوار "تم إنشاء المفتاح" حديثاً، تحتوي كل قصاصة أدناه بالفعل على مفتاحك الحقيقي. وإلا فستعرض العنصر النائب `ak_YOUR_KEY`. 3. انسخ القصاصة الخاصة بعميلك وقم بتشغيلها أو لصقها كما هو موضح لاحقاً. ![تبويب Connect an AI مع عنوان URL لـ MCP وبطاقة واحدة بها زر نسخ لكل عميل](https://nexcmp.com/ar/docs/images/configure-with-ai/mcp-admin-01-connect.webp) ### Claude Code {#claude-code} ```bash claude mcp add --transport http nexcmp https://cloud.example.com/mcp/admin \ --header "Authorization: Bearer ak_XXXX" ``` ثم ابدأ `claude` واسأل "list the tools from nexcmp" أو "what is left to set up?". تم التحقق في 30/10/2026 باستخدام Claude Code 2.1: تكتب `claude mcp add --transport http …` الخادم (أضف `-s project` للاحتفاظ به في `.mcp.json` الخاص بالمشروع — يطلب منك Claude Code الموافقة على خوادم المشروع في المرة الأولى). بالنسبة للبرامج النصية، يعمل `claude -p "…" --mcp-config .mcp.json --strict-mcp-config --allowedTools "mcp__nexcmp__*"` بدون موجه الموافقة ويسمح لـ Claude باستخدام أدوات اللوحة فقط. ### Claude Desktop {#claude-desktop} يتطلب Node.js 18 أو أحدث. أضف هذا إلى `claude_desktop_config.json` (يستخدم جسر `mcp-remote`) وأعد تشغيل Claude Desktop: ```json { "mcpServers": { "nexcmp": { "command": "npx", "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp/admin", "--header", "Authorization:Bearer ak_XXXX"] } } } ``` إذا كان نظامك يعبث بالمسافة في وسيطة الترويسة، ضع القيمة بأكملها في متغيّر بيئي بدلاً من ذلك، تماماً كما هو الحال مع نقطة نهاية العملاء: `"args": [..., "--header", "Authorization:${NEXCMP_AUTH_HEADER}"]` مع `"env": { "NEXCMP_AUTH_HEADER": "Bearer ak_XXXX" }`. ### claude.ai (custom connector) {#claude-ai-custom-connector} لا حاجة لمفتاح: فهو يسجل الدخول عبر OAuth. في موقع claude.ai افتح إعدادات الموصلات، وأضف موصلاً مخصصاً، والصق `https://cloud.example.com/mcp/admin`، ثم سجل الدخول بحساب مسؤول NexCMP الخاص بك واختر الأذونات على شاشة الموافقة. التفاصيل: [موصلات OAuth](https://nexcmp.com/ar/docs/configure-with-ai/oauth-connectors/). ### ChatGPT (developer mode) {#chatgpt-developer-mode} لا حاجة لمفتاح. في ChatGPT قم بتشغيل وضع المطور، وأضف موصل MCP مع عنوان URL `https://cloud.example.com/mcp/admin`، واختر OAuth وسجل الدخول بحساب مسؤول NexCMP الخاص بك. التفاصيل: [موصلات OAuth](https://nexcmp.com/ar/docs/configure-with-ai/oauth-connectors/). ### Codex CLI {#codex-cli} Add to `~/.codex/config.toml`: ```toml [mcp_servers.nexcmp] url = "https://cloud.example.com/mcp/admin" bearer_token_env_var = "NEXCMP_KEY" ``` ثم قم بتصدير المفتاح في الصدفة (shell) التي تبدأ تشغيل Codex: ```bash export NEXCMP_KEY=ak_XXXX codex codex mcp list # shows nexcmp with "Bearer token" auth ``` ::: tip Non-interactive `codex exec` في `codex exec` (البرامج النصية، وCI) لا يسأل Codex قبل استدعاء الأدوات، ويتخطى الأدوات التي تغير البيانات. أضف `default_tools_approval_mode = "approve"` تحت `[mcp_servers.nexcmp]` للسماح له باستدعائها؛ لا تزال لوحة التحكم تُعيد معاينة وتطلب التأكيد لعمليات الأموال والأمان والحذف. تم التحقق من ذلك باستخدام Codex CLI 0.166 بتاريخ 30/10/2026. ::: ### Gemini CLI {#gemini-cli} Add to `~/.gemini/settings.json`: ```json { "mcpServers": { "nexcmp": { "httpUrl": "https://cloud.example.com/mcp/admin", "headers": { "Authorization": "Bearer ak_XXXX" } } } } ``` يقوم Gemini CLI بإيقاف تشغيل خوادم MCP في المجلدات التي لا يثق بها. ابدأ تشغيله في مجلد تثق به (أو ثق بالمجلد عندما يطلب ذلك)، ثم تحقق باستخدام `gemini mcp list` — فهو يعرض `nexcmp … Connected`. يمكنك إبقاء المفتاح خارج الملف باستخدام `"Authorization": "Bearer $NEXCMP_KEY"`. تم التحقق باستخدام Gemini CLI 0.66 بتاريخ 30/10/2026. ### Cursor {#cursor} Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project): ```json { "mcpServers": { "nexcmp": { "url": "https://cloud.example.com/mcp/admin", "headers": { "Authorization": "Bearer ak_XXXX" } } } } ``` ::: tip إبقاء المفتاح خارج ملفات التكوين حيثما يدعم العميل ذلك، اقرأ المفتاح من متغيّر بيئي بدلاً من كتابته في الملف: يقوم Codex بذلك افتراضياً (`bearer_token_env_var`)، ويقبل Cursor `"Bearer ${env:NEXCMP_KEY}"`. لا تقم أبداً بإيداع ملف يحتوي على مفتاح. ::: ### OpenAI Agents SDK (Python) {#openai-agents-sdk-python} ```python from agents.mcp import MCPServerStreamableHttp nexcmp = MCPServerStreamableHttp( params={"url": "https://cloud.example.com/mcp/admin", "headers": {"Authorization": "Bearer ak_XXXX"}}, name="nexcmp", ) ``` تشغيل كامل (تم التحقق باستخدام `openai-agents` 0.24 بتاريخ 30/10/2026 — أداة قراءة، تليها تغيير في الرصيد أعاد معاينة التأكيد وتم تطبيقه عند الاستدعاء الثاني باستخدام `confirm_token`): ```python import asyncio from agents import Agent, Runner from agents.mcp import MCPServerStreamableHttp async def main(): async with MCPServerStreamableHttp(params={"url": "https://cloud.example.com/mcp/admin", "headers": {"Authorization": "Bearer ak_XXXX"}}, name="nexcmp") as nexcmp: agent = Agent(name="admin", model="gpt-5", mcp_servers=[nexcmp], instructions="You operate a hosting panel through the nexcmp tools. Ask me before confirming money actions.") result = await Runner.run(agent, "Run system_health and summarise it in one line.") print(result.final_output) asyncio.run(main()) ``` ### OpenAI Responses API {#openai-responses-api} مرّر الخادم كأداة من النوع `mcp`. حافظ على `require_approval` في `always` لكي يسألك برنامجك قبل كل استدعاء: ```json { "type": "mcp", "server_label": "nexcmp", "server_url": "https://cloud.example.com/mcp/admin", "headers": { "Authorization": "Bearer ak_XXXX" }, "require_approval": "always" } ``` ### أي شيء آخر (HTTP عادي) {#anything-else-plain-http} يمكن للعميل الذي لا يحتوي على MCP استدعاء نفس الأدوات عبر HTTP. تسردها `GET /v1/admin/agent/tools`، وتنفذ `POST /v1/admin/agent/tools/` واحدة منها مع نص JSON للوسيطات، وتُعيد `GET /v1/admin/openapi.json` وصف OpenAPI 3.1 (كل أداة هي عملية واحدة). تحتاج جميعها إلى `Authorization: Bearer ak_...`. ## التحقق {#verify} 1. بدون عميل، اسرد الأدوات: ```bash curl -s https://cloud.example.com/mcp/admin \ -H "Authorization: Bearer ak_XXXX" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` النتيجة هي رد JSON-RPC مع الأدوات التي تسمح بها نطاقاتك. 2. اطلب من عميلك "run system_health". فهو يُعيد التنبيهات، وحالة البنية التحتية المتصلة، والمدفوعات، والبريد الإلكتروني، والذكاء الاصطناعي، وحالة الترخيص. 3. افتح **API & AI agents › Activity**: يتم سرد الاستدعاءات مع اسم العميل و`mcp`. 4. على الخادم، يطبع `sudo nexcmp status` سطر "MCP admin" الذي يوضح `ready` عندما تستجيب نقطة النهاية (HTTP 401 بدون مفتاح هو الحالة السليمة). ## الأدوات {#tools} يوفر الخادم 58 أداة. لا يرى العميل سوى الأدوات التي تسمح بها نطاقات مفتاحه: تحتاج أدوات القراءة إلى `admin:read`، وتحتاج أدوات الكتابة إلى نطاقها الخاص. تحصل أدوات الكتابة أيضاً على وسيطة اختياريّة `confirm_token` (راجع [Confirmation](#confirmation-confirm-token)). يتم التحقق من الوسيطات مقابل مخطط كل أداة: تُرفض الوسيطات غير المعروفة أو التي بها خطأ إملائي مع رسالة تذكر أسماءها. الأسعار بالدولار الأمريكي: أسعار الخطط بالدولار في الساعة (`hourly_usd`)، والأرصدة بالسنتات. يمكن تعيين الأسرار ولكن لا يتم إرجاعها مطلقاً. ### Overview and logs {#overview-and-logs} | الأداة | الوظيفة | النطاق | Changes data | Asks you | |---|---|---|---|---| | `system_health` | التنبيهات التي تحتاج إلى اهتمام، وحالة البنية التحتية، والمدفوعات، والبريد الإلكتروني، والذكاء الاصطناعي، والترخيص، وحالة التحديث. | `admin:read` | No | No | | `setup_checklist` | ما تم تكوينه وما تبقى: الترخيص، البنية التحتية، المنطقة، قوالب نظام التشغيل، الخطط، المدفوعات، البريد الإلكتروني، العلامة التجارية، الجوانب القانونية، الطلب التجريبي. | `admin:read` | No | No | | `license_status` | حالة الترخيص وما إذا كان هناك إصدار أحدث من NexCMP متوفر. | `admin:read` | No | No | | `audit_search` | البحث في سجل التدقيق الخاص بالمشرف وسجل مفاتيح API. | `admin:read` | No | No | ### الإعدادات، العلامة التجارية، النواحي القانونية، والوحدات النمطية {#settings-branding-legal-modules} | الأداة | الوظيفة | النطاق | Changes data | Asks you | |---|---|---|---|---| | `settings_get` | قراءة الإعدادات العامة (`keys` عوامل التصفح؛ اللاحقة `*` تطابق بادئة). | `admin:read` | No | No | | `settings_update` | تغيير الإعدادات العامة من كائن `values` مسطح. يتم قبول المفاتيح المذكورة بواسطة `settings_get` فقط. | `settings:write` | نعم | عندما يمس مفتاح المدفوعات، أمان تسجيل الدخول، مفاتيح التحكم على مستوى الموقع أو الأسعار | | `branding_get` | اسم العلامة التجارية، اللون، عملة العرض، اسم البائع، وشعارات الموقع ورمز المفضلة (Favicon). | `admin:read` | No | No | | `branding_update` | تعيين اسم العلامة التجارية (حتى 60 حرفاً)، اللون (`#rrggbb`)، عملة العرض (`usd` أو `vnd`) واسم البائع. | `settings:write` | نعم | No | | `branding_logo_set` | تحميل شعار فاتح أو داكن أو رمز مفضلة من رابط https أو base64 (بصيغة PNG أو JPEG أو WEBP أو ICO أو SVG، بحجم يصل إلى 512 كيلوبايت). | `settings:write` | نعم | No | | `legal_get` | شروط الخدمة وسياسة الخصوصية (باللغتين الإنجليزية والvietnamية) والإعدادات الافتراضية المحايدة. | `admin:read` | No | No | | `legal_update` | تعيين نص الشروط والخصوصية (markdown بسيط، بدون HTML، بحد أقصى 50 كيلوبايت لكل منهما). السلسلة الفارغة تعيد القيمة الافتراضية. | `settings:write` | نعم | No | | `modules_get` | الوحدات النمطية الاختيارية المفعّلة وتلك التي يمكن تبديلها. | `admin:read` | No | No | | `module_set` | تبديل وحدة نمطية اختيارية بين التشغيل والإيقاف (يجب أن يكون `key` واحداً من `settable`). | `settings:write` | نعم | No | ### البريد الإلكتروني والتنبيهات {#email-and-alerts} | الأداة | الوظيفة | النطاق | Changes data | Asks you | |---|---|---|---|---| | `smtp_get` | إعدادات البريد الإلكتروني الصادر (مع إخفاء كلمة المرور) وحالة قائمة الانتظار. | `admin:read` | No | No | | `smtp_configure` | تعيين خادم SMTP. يتطلب تغيير المضيف أو المنفذ أو الأمان إعادة إدخال كلمة المرور. | `settings:write` (+ `secrets:write` لكلمة المرور) | نعم | No | | `smtp_test` | إرسال بريد إلكتروني تجريبي حقيقي باستخدام الإعدادات المحفوظة. | `settings:write` | يرسل بريداً إلكترونياً | No | | `telegram_get` | قنوات إشعارات المشرفين (معرفات المحادثات؛ رموز البوت لا تُعاد أبداً). | `admin:read` | No | No | | `telegram_configure` | إضافة أو تحديث قناة تنبيهات Telegram (رمز البوت ومعرف المحادثة) وتبديل تنبيهات المشرفين بين التشغيل والإيقاف. | `settings:write` (+ `secrets:write` للرمز) | نعم | No | | `telegram_test` | إرسال رسالة تجريبية إلى قناة Telegram. | `settings:write` | يرسل رسالة | No | ### المدفوعات والعملة {#payments-and-currency} | الأداة | الوظيفة | النطاق | Changes data | Asks you | |---|---|---|---|---| | `payments_get` | حالة Stripe وPayPal والعملات المشفرة (USDT) والتحويل البنكي، بالإضافة إلى القنوات المفعّلة والرسوم. | `admin:read` | No | No | | `payment_configure` | تعيين بيانات اعتماد إحدى بوابات الدفع (`stripe` أو `paypal` أو `crypto` أو `bank`). | `billing:write` (+ `secrets:write`) | نعم | دائماً | | `payment_test` | التحقق من بيانات اعتماد بوابة الدفع المحفوظة لدى المزود. | `billing:write` | No | No | | `currency_get` | عملة العرض وسعر صرف USD إلى VND (تلقائي أو يدوي). | `admin:read` | No | No | | `currency_set` | تعيين عملة العرض و/أو سعر الصرف اليدوي (0 يعني تلقائي، وإلا من 15000 إلى 50000). | `billing:write` | نعم | عندما تغير سعر الصرف اليدوي | ### البنية التحتية والمناطق {#infrastructure-and-zones} | الأداة | الوظيفة | النطاق | Changes data | Asks you | |---|---|---|---|---| | `cloudstack_get` | نقطة نهاية CloudStack المحفوظة ومعرفات المناطق والشبكات (مع إخفاء المفاتيح). | `admin:read` | No | No | | `cloudstack_test` | اختبار نقطة نهاية باستخدام مفتاح API وسر دون حفظ؛ يعرض قائمة المناطق. | `infra:write` (+ `secrets:write`، لأنك تمرر المفاتيح) | No | No | | `cloudstack_connect` | حفظ اتصال CloudStack. | `infra:write` (+ `secrets:write`) | نعم | دائماً | | `proxmox_list` | مجموعات Proxmox VE المضافة كمصادر، مع حالتها الصحية. | `admin:read` | No | No | | `proxmox_add` | إضافة مجموعة Proxmox VE باستخدام رمز API (`user@realm!tokenid`) وسره. | `infra:write` (+ `secrets:write`) | نعم | No | | `proxmox_test` | الاتصال بمجموعة عن طريق المعرف؛ أول عملية ناجحة تثبت شهادة TLS الخاصة بها. | `infra:write` | نعم | No | | `proxmox_attach_zone` | بيع مجموعة Proxmox في منطقة موجودة، اختيارياً مع عقدة كنطاق. | `infra:write` | نعم | No | | `zones_list` | المناطق (المواقع) التي يمكن للعملاء اختيارها. | `admin:read` | No | No | | `zone_create` | إنشاء منطقة. | `infra:write` | نعم | No | ### الكتالوج والخطط {#catalog-and-plans} | الأداة | الوظيفة | النطاق | Changes data | Asks you | |---|---|---|---|---| | `templates_list` | قوالب نظام التشغيل التي يمكن للعملاء تثبيتها. | `admin:read` | No | No | | `templates_sync` | استيراد قوالب نظام التشغيل من CloudStack. | `catalog:write` | نعم | No | | `template_update` | تفعيل أو إخفاء قالب، أو إعادة تسميته، أو تعيين مستخدم تسجيل الدخول أو الترتيب. | `catalog:write` | نعم | No | | `offerings_list` | عروض خدمات CloudStack (وحدة المعالجة المركزية، والذاكرة، القرص الجذر) لبناء الخطط منها. | `admin:read` | No | No | | `plans_list` | خطط بسعر لكل ساعة وكل شهر، الحجم، والمنطقة، وعدد الخوادم التي تستخدمها. | `admin:read` | No | No | | `plan_create` | إنشاء خطة. السعر كـ `hourly_usd`. تحتاج خطط CloudStack إلى `cs_offering_id`؛ بينما تحتاج خطط Proxmox إلى `backend_id`. | `catalog:write` | نعم | No | | `plan_update` | إعادة تسمية، أو إظهار أو إخفاء، أو تفعيل أو تعطيل، أو إعادة تسعير خططة. تغييرات الحجم على خطة قيد الاستخدام تتطلب نسخة. | `catalog:write` | نعم | عند تغيير السعر | | `plans_from_offerings` | بناء جدول خطط بداية من العروض (أو أحجام Proxmox) باستخدام تكلفتك ونسبة هامش الربح. يعيد معاينة؛ اطلب مرة أخرى مع `apply=true` لإنشاء الخطط. | `catalog:write` | مع `apply=true` | دائم التشغيل عند التطبيق | | `quota_defaults_get` | حدود العملاء الافتراضية. | `admin:read` | No | No | | `quota_defaults_set` | تغيير إعدادات `quota_*`. | `catalog:write` | نعم | No | | `coupons_list` | دفعات أكواد الخصم والهدايا. | `admin:read` | No | No | | `coupon_create` | إنشاء دفعة من الأكواد: النوع `money` (القيمة الاسمية بالسنت الأمريكي) أو `percent` (من 1 إلى 100، مع خصم أقصى). | `catalog:write` | نعم | دائماً | ### العملاء والشركاء {#customers-and-resellers} | الأداة | الوظيفة | النطاق | Changes data | Asks you | |---|---|---|---|---| | `customers_search` | البحث عن العملاء بالبريد الإلكتروني، أو الاسم، أو عنوان IP. | `admin:read` | No | No | | `customer_get` | حساب العميل، ورصيده، وخوادمه، وفواتيره الأخيرة. | `admin:read` | No | No | | `customer_adjust_balance` | إضافة رصيد (موجب) أو إزالته (سالب) بالسنت الأمريكي. السبب مطلوب. | `billing:write` | نعم | دائماً | | `customer_block` | حظر عميل، مع إيقاف خوادمه اختيارياً. السبب مطلوب. | `customers:write` | نعم | دائماً | | `customer_unblock` | إلغاء حظر عميل. | `customers:write` | نعم | No | | `resellers_list` | الشركاء مع المحفظة والحالة. | `admin:read` | No | No | | `reseller_get` | موقع الشريك، ومحفظته، ومستخدموه، وبوابات الدفع الخاصة به. | `admin:read` | No | No | ### مزود الذكاء الاصطناعي {#ai-provider} | الأداة | الوظيفة | النطاق | Changes data | Asks you | |---|---|---|---|---| | `ai_provider_get` | المزود المتوافق مع OpenAI المستخدم بواسطة AI Chat للعملاء و AI Agent (المفتاح مخفي). | `admin:read` | No | No | | `ai_provider_set` | تعيين المزود: عنوان URL الأساسي، النموذج، مفتاح API، النماذج البديلة، جهد الاستدلال، والتفعيل. | `ai:write` (+ `secrets:write` للمفتاح) | نعم | No | | `ai_provider_test` | طرح سؤال واحد على المزود المحفوظ للتحقق من عمله. | `ai:write` | No | No | ### ملفات التكوين {#configuration-files} | الأداة | الوظيفة | النطاق | Changes data | Asks you | |---|---|---|---|---| | `config_export` | تصدير التكوين بتنسيق YAML (تصبح الأسرار مراجع `secret://`). | `admin:read` | No | No | | `config_plan` | مقارنة تكوين YAML مع اللوحة النشطة وسرد ما سيتم تغييره. | `admin:read` | No | No | | `config_apply` | تطبيق تكوين YAML قسمًا بقسم. يتبع كل تغيير قواعد النطاق والتأكيد العادية. | `admin:read` + نطاق كل تغيير | نعم | لكل تغيير | راجع [Configuration as code](https://nexcmp.com/ar/docs/configure-with-ai/config-as-code/) لمعرفة تنسيق الملف. ## الموجهات {#prompts} يوفر الخادم أيضاً ثلاثة موجهات جاهزة يمكن للعملاء عرضها كاختصارات: | الموجه | الوسيط | ما يطلب من الذكاء الاصطناعي فعله | |---|---|---| | `initial-setup` | لا يوجد | استدعاء `setup_checklist`، وشرح كل خطوة مفتوحة في جملة واحدة، وطلب المعلومات التي يحتاجها منك، وتنفيذ الخطوة باستخدام الأداة المطابقة، ومعاينة تغييرات الأموال أو الأمان، والإنهاء بـ `system_health`. | | `add-proxmox` | `endpoint` (اختياري، `https://host:8006`) | طلب رمز API، ثم `proxmox_add`، و`proxmox_test`، وأدوات المنطقة، و`proxmox_attach_zone`؛ ثم اقتراح الخطط باستخدام `plans_from_offerings` وانتظار موافقتك. | | `launch-pricing` | `margin_pct` (اختياري، الافتراضي 40) | اطلب تكلفك الشهرية لكل vCPU، ولكل غيغابايت من ذاكرة الوصول العشوائي (RAM)، ولكل غيغابايت من القرص، وأظهر جدول معاينة بالتكلفة، والسعر شهرياً، والسعر بالساعة، وأنشئ الخطط بعد موافقتك. | ## التأكيد (`confirm_token`) {#confirmation-confirm-token} الإجراءات التي تنقل الأموال، أو تحذف البيانات، أو تغيّر بيانات اعتماد الدفع، أو أمان تسجيل الدخول تتطلب خطوتين: 1. الاستدعاء الأول لا يغير شيئاً. تبدأ نتيجة الأداة بعبارة "CONFIRMATION REQUIRED" وتتضمن **معاينة** (ما سيتم استدعاؤه، ولماذا يعتبر حساساً، والقيم الجديدة والحالية) و `confirm_token`. 2. يجب أن يعرض لك العميل المعاينة. وفقط بعد موافقتك، يقوم باستدعاء نفس الأداة مرة أخرى مع نفس الوسائط بالإضافة إلى `confirm_token`. 3. الرمز صالح لمرة واحدة، ولذلك الطلب المحدد فقط، وتنتهي صلاحيته بعد 5 دقائق. تخبر تعليمات الخادم الذكاء الاصطناعي بمعاملة نتائج الأدوات كبيانات وليس كتعليمات، وألا يكرر الاستدعاء أبداً باستخدام رمز لم تقم بالموافقة عليه. أنت خط الدفاع: اقرأ المعاينة. ::: warning لا تقم بالموافقة التلقائية يمكن لبعض العملاء الموافقة على كل استدعاء للأداة تلقائياً. بالنسبة لأدوات الكتابة، حافظ على تفعيل الموافقة لكل استدعاء، أو استخدم مفتاحاً للقراءة فقط، حتى لا يتمكن خطأ من الذكاء الاصطناعي من الوصول إلى لوحتك دون ملاحظة. ::: ## How it works {#how-it-works} | العنصر | التفاصيل | |---|---| | النقل | `POST /mcp/admin` مع رسالة JSON-RPC 2.0؛ الإجابة هي `application/json`. ما يصل إلى 20 رسالة في الدفعة الواحدة. `GET /mcp/admin` تعيد الخطأ 405 (لا يوجد تدفق للخادم)؛ `DELETE /mcp/admin` تنهي الجلسة. | | المصادقة | `Authorization: Bearer ak_...` (مفتاح يدوي أو رمز وصول OAuth). بيانات الاعتماد المفقودة أو الخاطئة تعطي الرمز 401 مع `WWW-Authenticate: Bearer ... resource_metadata=...`، مما يسمح لعملاء OAuth بدء تسجيل الدخول بأنفسهم. | | الجلسات | `Mcp-Session-Id` يتم إصدارها بواسطة `initialize`، ومرتبطة بهذا المفتاح وصالحة لمدة 24 ساعة. | | القدرات | الأدوات والتعليمات. لا توجد موارد. | | الحجم | جسم الطلب حتى 1 ميجابايت؛ ويتم قطع نتيجة الأداة بعد حوالي 100 كيلوبايت. | | المصدر | يتم رفض الطلب الذي يحمل رأس `Origin` من موقع آخر (`origin_not_allowed`). لا يرسل عملاء سطر الأوامر وتطبيقات سطح المكتب أي شيء. | | نفس بوابة REST | يتم إعادة إرسال كل استدعاء للأداة عبر خط أنابيب الطلبات الخاص باللوحة باستخدام مفتاحك، بحيث يتم تطبيق النطاقات، ونطاقات IP، ومعدل الحدود، والتؤكيد، وسجل النشاط تماماً كما هو الحال في طلبات API المباشرة. | ## الحدود والملاحظات {#limits-notes} - الأداة التي لا يمكنك رؤيتها هي نطاق لم تقم بمنحه. أضف النطاق إلى مفتاح جديد. - تعيين كلمة مرور أو مفتاح API من خلال عميل ذكاء اصطناعي يعني أن السر يمر عبر ذلك الذكاء الاصطناعي. إذا كنت تفضل ذلك، فاترك `secrets:write` معطلاً وأدخل الأسرار بنفسك في لوحة المشرف، أو استخدم حقل **Secret** في AI Chat (انظر [AI Chat in the admin](https://nexcmp.com/ar/docs/configure-with-ai/ai-chat-in-admin/#secrets)) أو مراجع `secret://` (انظر [Configuration as code](https://nexcmp.com/ar/docs/configure-with-ai/config-as-code/#secrets)). - لا يتشارك العملاء الجلسات: تبدأ كل عملية اتصال بـ `initialize`. - قم بإلغاء المفتاح في قسم **API & AI agents** لقطع الاتصال عن عميل الذكاء الاصطناعي فوراً. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | 401 `invalid_key` | مفتاح خاطئ أو مقتطع أو ليس لصلاحيات المشرف (على سبيل المثال مفتاح `vk_`) | استخدم مفتاح `ak_`. | | 401 `key_expired` أو `key_revoked` | انتهت صلاحية المفتاح أو تم إلغاؤه | أنشئ مفتاحاً جديداً. | | 403 `ip_not_allowed` | عنوان IP الخاص بك خارج نطاقات IP الخاصة بالمفتاح | اتصل من عنوان IP مسموح به. | | 403 `origin_not_allowed` | استدعت صفحة متصفح على مصدر آخر نقطة النهاية | استخدم عميل سطح مكتب أو CLI. | | 404 في طلب يحتوي على `Mcp-Session-Id` | الجلسة تنتمي إلى مفتاح آخر أو انتهت صلاحيتها | أرسل `initialize` مرة أخرى. | | 400 `MCP-Protocol-Version` غير مدعوم | يستخدم العميل إصداراً لا يتعرف عليه الخادم | قم بتحديث العميل؛ المدعومة: 2025-11-25، 2025-06-18، 2025-03-26. | | قائمة الأدوات قصيرة | نطاقات المفاتيح | أنشئ مفتاحاً بنطاقات أكثر. | | `insufficient_scope` أثناء المكالمة | الأداة تحتاج إلى نطاق (scope) ثانٍ، على سبيل المثال `secrets:write` | أضف النطاق إلى مفتاح جديد. | | 429 `rate_limited` | عدد مكالمات في الدقيقة أكبر مما يسمح به المفتاح | انتظر لمدة `Retry-After` أو ارفع الحد على مفتاح جديد. | | claude.ai أو ChatGPT لا يمكنهما الاتصال | عنوان URL غير قابل للوصول من الإنترنت، أو أن وكيلًا (proxy) يحظر `/mcp/admin` أو `/oauth-admin/` | تحقق من نظام الأسماء النطاقية (DNS) و TLS والوكيل العكسي (reverse proxy). | لجميع رموز الأخطاء، راجع [Admin API keys](https://nexcmp.com/ar/docs/configure-with-ai/admin-api-keys/#errors). --- # موصلات claude.ai و ChatGPT {#claude-ai-and-chatgpt-connectors} > **أين تجد ذلك في لوحة المشرف:** System › Settings › API & AI agents (`/agent/keys`)، علامة التبويب **Connected apps**. تفتح شاشة الموافقة في `/agent/consent` عندما يطلب موصل الوصول (وهي ليست في القائمة). ## الوظيفة {#what-it-does} لا تستطيع تطبيقات الذكاء الاصطناعي الوبوية قراءة مفتاح من قرصك. تتصل عبر **OAuth**: تضيف عنوان MCP الخاص باللوحة، فيرسلك التطبيق إلى مشرفك الخاص لتسجيل الدخول، وتختار ما يسمح للتطبق فعله ومدة ذلك، ويتلقى التطبيق رموزاً قصيرة العمر. لا يتم نسخ أو لصق أي مفتاح. يمكنك قطع الاتصال بالتطبيق في أي وقت. استخدم هذا لموصلات claude.ai المخصصة، وموصلات وضع المطورين في ChatGPT، وأي عميل MCP آخر يدعم OAuth مع التسجيل الديناميكي للعملاء. يمكن لأدوات سطر الأوامر استخدام التدفق نفسه، ولكن [admin API key](https://nexcmp.com/ar/docs/configure-with-ai/admin-api-keys/) يُعد أبسط بالنسبة لها. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | URL | `https://cloud.example.com/mcp/admin`، ويمكن الوصول إليه عبر الإنترنت (تتصل خوادم المورد به). | | الوكيل العكسي (Reverse proxy) | إذا وضعت الوكيل الخاص بك أمام اللوحة، فيجب عليه إعادة توجيه `/mcp/admin` و `/oauth-admin/` ومسارات `/.well-known/` إلى اللوحة. | | أنت | مسجل الدخول كمسؤول NexCMP **في المتصفح نفسه** الذي تستخدمه لشاشة الموافقة. | | العميل | يدعم بروتوكول MCP عبر Streamable HTTP، و OAuth 2.1 مع PKCE (S256)، والتسجيل الديناميكي للعملاء. | ## الاتصال {#connect} 1. في تطبيق الذكاء الاصطناعي، أضف موصل MCP مخصصاً والصق `https://cloud.example.com/mcp/admin`. في claude.ai يوجد هذا ضمن إعدادات الموصلات (إضافة موصل مخصص)؛ وفي ChatGPT يوجد ضمن وضع المطورين (إضافة موصل MCP، مع المصادقة OAuth). 2. اختر **Sign in** (أو "Connect") في التطبيق. يفتح متصفحك شاشة موافقة مسؤول NexCMP. إذا لم تكن مسجلاً للدخول، فيرجى تسجيل الدخول أولاً؛ وستستمر الشاشة بعد ذلك. 3. اقرأ البطاقة: "**Example AI app** يريد إدارة مسؤول NexCMP هذا" (اسم التطبيق الذي يطلب ذلك)، مع العنوان الذي سيتم إعادتك إليه. 4. حدد مربعات النطاقات المراد منحها. النطاقات التي طلبها التطبيق محددة مسبقاً؛ وإذا لم يطلب أي نطاق، فلن يتم تحديد سوى `admin:read`. راجع [Scopes](https://nexcmp.com/ar/docs/configure-with-ai/admin-api-keys/#scopes). 5. اختر مدة استمرار الاتصال: **7** أو **30** أو **90** يوماً (الافتراضي هو 30). 6. انقر على **Allow**. يعود المتصفح إلى التطبيق، والذي أصبح متصلاً الآن. انقر على **Deny** للرفض. ![شاشة موافقة تطلب السماح لتطبيق ذكاء اصطناعي، مع مربعات اختيار للنطاقات، واختيار المدة، وزري السماح والرفض](https://nexcmp.com/ar/docs/images/configure-with-ai/oauth-connectors-01-consent.webp) ::: important اختر النطاقات كما تفعل مع أي مفتاح امنح الحد الأدنى الذي يؤدي الغرض. لا تزال إجراءات الأموال والحذف والأمان تتوقف عند المعاينة وتتطلب موافقتك، ولكن الاتصال الذي يحتوي على `settings:write` لا يزال بإمكانه تغيير علامتك التجارية وبريدك الإلكتروني. ::: ## الإدارة والإلغاء {#manage-and-revoke} افتح **System › Settings › API & AI agents › Connected apps**. يسرد الجدول كل تطبيق قمت بوصله: التطبيق، والنطاقات، ووقت الاتصال، ووقت انتهاء الصلاحية، ووقت آخر استخدام. لقطع الاتصال بتطبيق ما، انقر فوق **Revoke** وقم بالتأكيد. تتوقف رموزه عن العمل فوراً؛ ويجب على التطبيق المرور عبر شاشة الموافقة مرة أخرى لإعادة الاتصال. ![علامة تبويب التطبيقات المتصلة تعرض تطبيق ذكاء اصطناعي واحداً مع نطاقاته وتاريخ انتهاء صلاحيته وزر إبطال](https://nexcmp.com/ar/docs/images/configure-with-ai/oauth-connectors-02-connected-apps.webp) ## كيفية عمل التدفق {#how-the-flow-works} | الخطوة | التفاصيل | |---|---| | الاكتشاف | يقرأ التطبيق `/.well-known/oauth-protected-resource/mcp/admin` ثم `/.well-known/oauth-authorization-server/oauth-admin`. جهة الإصدار هي `https://cloud.example.com/oauth-admin`. | | التسجيل | يقوم التطبيق بتسجيل نفسه (`POST /oauth-admin/register`، RFC 7591). العملاء العامون فقط هم المدعومون (بدون سر العميل). يجب أن يكون عنوان إعادة التوجيه هو `https` أو `http` على نفس الجهاز (حلقة محلية). | | المنح | `GET /oauth-admin/authorize` باستخدام طريقة PKCE `S256`. معامل `resource`، عند إرساله، يجب أن يكون عنوان URL الخاص بهذه اللوحة `/mcp/admin`. الطلب صالح لمدة 10 دقائق ومقترن بالمتصفح الذي بدأه. | | الموافقة | أنت تختار النطاقات والمدة (أعلاه). رمز التفويض صالح لمدة 60 ثانية ويعمل مرة واحدة. | | الرموز المميزة | يُرجع `POST /oauth-admin/token` **رمز وصول** (مفتاح `ak_o...`، صالح لمدة 1 ساعة أو حتى انتهاء الاتصال، أيهما أقرب) و**رمز تحديث** (`akr_...`). يُرجع كل تحديث رمز تحديث جديدًا؛ ويتوقف الرمز القديم عن العمل. ينتهي الاتصال بعد الأيام التي اخترتها. | | الإبطال | **Revoke** في التطبيقات المتصلة، أو يستدعي التطبيق `POST /oauth-admin/revoke` (RFC 7009). | يتصرف رمز الوصول مثل مفتاح المسؤول مع النطاقات التي منحته إياها: نفس قواعد النطاق، والتأكيد، وحد المعدل، وسجل النشاط. تظهر استدعاءاته في علامة تبويب **Activity**. ## التحقق {#verify} 1. في التطبيق، اسأل "run system_health" (أو "what tools do you have?"). يعرض التطبيق الأدوات التي تسمح بها نطاقاتك ([قائمة الأدوات](https://nexcmp.com/ar/docs/configure-with-ai/mcp-admin/#tools)). 2. افتح **Connected apps**: يتحرك **Last used**. 3. افتح **Activity**: يتم سرد الاستدعاءات مع اسم التطبيق و`mcp`. ## الحدود والملاحظات {#limits-notes} - إذا طلب التطبيق تسجيل الدخول مرة أخرى بعد ساعة، فهذا أمر طبيعي عندما لا يقوم العميل بالتحديث؛ أعد الاتصال. - رمز التحديث الذي يُستخدَم مرتين يتم التعامل معه كأنه مسروق: يتم إبطال الاتصال بالكامل. أعد الاتصال من التطبيق. - رمز التفويض المستخدَم مرتين يُرفض (`invalid_grant`) ويتم إبطال الرموز الصادرة عنه بالفعل. - وصول OAuth لا يمنح أبداً أكثر مما تسمح به قواعد النطاق: [ما لا يستطيع المفتاح فعله أبداً](https://nexcmp.com/ar/docs/configure-with-ai/admin-api-keys/#what-a-key-can-never-do) ينطبق على التطبيقات المتصلة أيضاً. - يغير الموردون قوائمهم وما يدعمونه. إذا كان تطبيق المورد لا يقدم موصلات مخصصة في خطتك، فاستخدم [admin API key](https://nexcmp.com/ar/docs/configure-with-ai/admin-api-keys/) مع عميل سطح مكتب أو سطر أوامر بدلاً من ذلك. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | شاشة الموافقة تقول "متصفح خاطئ" | بدأ الطلب في متصفح يختلف عن المتصفح الذي مسجل دخولك إليه | ابدأ الاتصال مرة أخرى من تطبيق الذكاء الاصطناعي في نفس المتصفح. | | شاشة الموافقة تقول إن الطلب انتهت صلاحيته أو مفقود | مرت أكثر من 10 دقائق، أو تم فتح الرابط مرتين | ابدأ الاتصال مرة أخرى من تطبيق الذكاء الاصطناعي. | | صفحة "عميل غير معروف" أو "عنوان إعادة التوجيه غير متطابق" | تسجيل التطبيق قديم، أو أنه يستخدم عنوان إعادة توجيه لم يسجله | أزل الموصل في التطبيق وأضفه مرة أخرى. | | `invalid_target` | الـ `resource` المرسل ليس عنوان URL الخاص بهذه اللوحة `/mcp/admin` | استخدم عنوان URL الدقيق المعروض في علامة تبويب **Connect an AI**. | | `invalid_request` حول PKCE | العميل لا يُرسل `code_challenge_method=S256` | استخدم عميلاً يدعم OAuth 2.1 مع PKCE. | | يتصل التطبيق ولكن أحد الاستدعاءات يُرجع `insufficient_scope` | لم تقم بتحديد ذلك النطاق | قم بإبطال الاتصال ثم أعد الاتصال مع تحديد النطاق. | | لا يمكن للتطبيق الوصول إلى عنوان URL | تعمل أنظمة DNS أو TLS أو الوظيفة العكسية الوسيطة (reverse proxy) على حظر `/mcp/admin` أو `/oauth-admin/` أو `/.well-known/` | تحقق من قواعد الوسيط (proxy). | --- # التكوين كشفرة برمجية {#configuration-as-code} > **أين تجد ذلك في لوحة المشرف:** System › Settings › Import/Export (`/agent/config`). على الخادم: الأمر `nexcmp config export` و `plan` و `apply` و `nexcmp admin `. ## الوظيفة {#what-it-does} يمكن حفظ تكوين لوحة التحكم الخاصة بك (العلامة التجارية، الإعدادات العامة، البريد الإلكتروني، تنبيهات تيليجرام، الوحدات، العملة، بوابات الدفع، الحدود، المناطق، الخطط، موزع الذكاء الاصطناعي والصفحات القانونية) كملف YAML واحد. يمكنك تحرير الملف بنفسك، أو طلب مساعد ذكاء اصطناعي لتعديله، أو الاحتفاظ به في نظام التحكم بالإصدار، وتطبيقه على نفس اللوحة أو لوحة أخرى. يمكنك دائماً رؤية قائمة التغييرات قبل حدوث أي شيء. ولا يتم كتابة الأسرار في الملف مطلقا. استخدمه لاستنسخ إعدادات إلى تثبيت ثانٍ، أو لمراجعة التغييرات قبل طرحها مباشرة، أو لاستعادة الإعدادات بعد ارتكاب خطأ، أو للسماح للذكاء الاصطناعي باقتراح تكوين كامل تقرأه كمستند واحد. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | NexCMP | 1.4.0 أو أحدث. | | سطر الأوامر | أنت `root` على خادم لوحة التحكم (استخدم `sudo`). يطلب الأمر من لوحة التحكم مفتاحاً مؤقتاً (15 دقيقة، لكافة النطاقات) من تلقاء نفسه. لاستخدام مفتاح أضيق نطاقاً بدلاً من ذلك، قم بتعيين `NEXCMP_KEY` إلى [admin API key](https://nexcmp.com/ar/docs/configure-with-ai/admin-api-keys/) واحتفظ به عبر sudo، على سبيل المثال `sudo --preserve-env=NEXCMP_KEY nexcmp config plan -f nexcmp.yaml`. | | صفحة المشرف | تم تسجيل الدخول بصفتك مشرفاً. هذه الصفحة للقراءة فقط على لوحة تجريبية. | | Secrets | القيم المقدمة وقت التطبيق (انظر [Secrets](#secrets))؛ وليست موجودة داخل الملف أبداً. | ## تصدير، تعديل، معاينة، تطبيق {#export-edit-preview-apply} 1. تصدير التكوين الحالي: ```bash sudo nexcmp config export -o nexcmp.yaml ``` بدون `-o`، تتم طباعة ملف YAML على الشاشة. 2. قم بتعديل `nexcmp.yaml` (راجع [example](#example-file) أدناه). حافظ على `version: 1` في الأعلى. 3. معاينة ما سيتم تغييره. لا يؤدي هذا إلى تغيير أي شيء: ```bash sudo nexcmp config plan -f nexcmp.yaml ``` يعرض كل سطر القسم والعنصر والحقل و `old → new`. تنتمي الأسطر التي تحمل العلامة `$` إلى أقسام الفوترة (انظر [Billing sections](#billing-sections)). إذا كانت لوحة التحكم تتطابق بالفعل مع الملف، سترى "No changes". 4. تطبيق. بدون `--yes`، يكون الأمر **تشغيلاً تجريبياً (dry run)** ويطبع القائمة نفسها فقط: ```bash sudo nexcmp config apply -f nexcmp.yaml --yes ``` 5. قراءة النتيجة: `applied`، و `pending` (في انتظار تأكيدك)، و `skipped`، و `errors`. | الخيار | المعنى | |---|---| | `-f ` | ملف YAML (مطلوب لـ `plan` و `apply`). | | `--yes` | التطبيق الفعلي. بدونه، يكون `apply` تشغيلاً تجريبياً. | | `--confirm-billing` | تطبيق أقسام الفوترة أيضاً (`payments`، `currency`، `plans`). بدون ذلك يتم تخطيها. | | `--section ` | تطبيق هذا القسم فقط. كرر الخيار لعدة أقسام. | | `-o ` | مع `export`: كتابة ملف YAML في ملف. | رمز الخروج هو 0 عند تطبيق كل شيء أو عدم تغير شيء، و1 عند إرجاع خطأ، و2 في حالة وجود خطأ في الاستخدام أو المفتاح. ### Secrets {#secrets} يحتوي الملف على مراجع بدلاً من الأسرار، مثل `password: secret://smtp_password`. وقت التطبيق، تأتي القيمة من متغير بيئة يُسمى `NEXCMP_SECRET_` مضافاً إليه اسم المرجع بأحرف كبيرة: ```bash sudo -i read -rs NEXCMP_SECRET_SMTP_PASSWORD && export NEXCMP_SECRET_SMTP_PASSWORD read -rs NEXCMP_SECRET_STRIPE_SECRET_KEY && export NEXCMP_SECRET_STRIPE_SECRET_KEY nexcmp config apply -f nexcmp.yaml --yes --confirm-billing ``` إذا لم تكن للمرجع قيمة، فسيتم **الاحتفاظ** بالسر المحفوظ مسبقاً في لوحة التحكم. أما السر الذي لم يُحفظ قط ولم يتم توفيره فسيبقى فارغاً. | اسم المرجع | أين يذهب | |---|---| | `smtp_password` | `email.smtp.password` | | `telegram_bot_token` | `telegram.bot_token` | | `stripe_secret_key`, `stripe_webhook_secret` | `payments.stripe` | | `paypal_client_secret` | `payments.paypal.client_secret` | | `binance_api_key`, `binance_api_secret` | `payments.crypto` | | `sepay_api_token`, `sepay_webhook_secret` | `payments.bank` | | `ai_provider_key` | `ai_provider.api_key` | ## ملف تجريبي {#example-file} ```yaml # NexCMP configuration. Preview: nexcmp config plan -f nexcmp.yaml version: 1 branding: name: Example Cloud primary: "#1677ff" currency: usd seller_name: Example Cloud LLC settings: brand_name: Example Cloud support_email: support@example.com default_lang: en invoice_prefix: EX company_name: Example Cloud LLC company_address: "1 Example Street, New York, NY" min_topup_cents: 500 email: smtp: host: smtp.example.com port: 587 security: starttls username: mailer@example.com password: secret://smtp_password from_email: no-reply@example.com from_name: Example Cloud reply_to: support@example.com telegram: enabled: true chat_id: "123456789" bot_token: secret://telegram_bot_token modules: s3: true k8s: false currency: site_currency: usd manual_rate_vnd: 0 # 0 = automatic payments: stripe: mode: test publishable_key: pk_test_XXXX secret_key: secret://stripe_secret_key webhook_secret: secret://stripe_webhook_secret bank: bank_code: BANK account_number: "0000000000" account_name: EXAMPLE CLOUD LLC prefix: EX api_token: secret://sepay_api_token channels: pay_card_enabled: true quotas: quota_enabled: true quota_max_vms_24h: 5 quota_max_vms_30d: 30 zones: - slug: new-york name: New York country: US city: New York enabled: true is_default: true plans: - slug: vps-1c-1g name: 1 vCPU, 1 GB RAM, 25 GB cpu: 1 ram_mb: 1024 disk_gb: 25 hourly_usd: 0.0112 cs_offering_id: OFFERING_ID enabled: true visible: true ai_provider: enabled: true name: Example AI base_url: https://api.example.com/v1 model: example-model fallback_models: [example-model-mini] reasoning_effort: low api_key: secret://ai_provider_key legal: terms: en: | # Terms of service Your terms in simple markdown (no HTML). privacy: en: | # Privacy policy Your policy in simple markdown (no HTML). ``` قد يحتوي الملف على أي مجموعة فرعية من الأقسام. القسم الذي تتركه دون تحديد لا يتم المساس به. يتم رفض أي ملف يزيد حجمه عن 1 ميجابايت، أو في حال غياب `version: 1`، أو اختلاف رقم الإصدار، أو وجود قسم غير معروف قبل تشغيل أي شيء. ## الأقسام {#sections} | القسم | ما تتحكم فيه | ملاحظات | |---|---|---| | `branding` | اسم العلامة التجارية (حتى 60 حرفاً)، اللون الأساسي، عملة العرض (`usd` أو `vnd`)، اسم البائع. | الشعارات ليست جزءاً من الملف؛ استخدم [صفحة العلامة التجارية](https://nexcmp.com/ar/docs/customers/branding/). | | `settings` | قائمة ثابتة من الإعدادات العامة: `brand_name`، `support_email`، `support_telegram_url`، `default_lang`، `require_email_verified`، `min_topup_cents`، `max_topup_cents`، `invoice_prefix`، `company_name`، `company_address`، `company_tax_id`، `auto_destroy_days`، `low_balance_cents`. | يتم تجاهل المفاتيح الأخرى. | | `email.smtp` | مضيف SMTP، المنفذ، الأمان (`starttls`، `tls`، `none`)، المستخدم، كلمة المرور، اسم المرسل وعنوانه، وعنوان الرد. | [قوالب SMTP والبريد الإلكتروني](https://nexcmp.com/ar/docs/administration/smtp-and-emails/). يتطلب تغيير المضيف أو المنفذ أو الأمان إعادة إدخال كلمة المرور. | | `telegram` | قناة التنبيه مفعلة أو معطلة، معرف الدردشة، رميز البوت. | [إشعارات تيليجرام](https://nexcmp.com/ar/docs/administration/telegram-notifications/). | | `modules` | الوحدات الإضافية مفعلة أو معطلة (`key: true/false`). | فقط المفاتيح التي تتيح لك اللوحة تبديلها. راجع [الوحدات](https://nexcmp.com/ar/docs/infrastructure/modules/). | | `currency` | عملة العرض ومعدل يدوي من USD إلى VND (`0` تلقائي، وإلا من 15000 إلى 50000). | قسم الفوترة. راجع [العملة ومسارات الصرف](https://nexcmp.com/ar/docs/catalog/currency-and-exchange-rates/). | | `payments` | بيانات اعتماد `stripe`، `paypal`، `crypto`، `bank` ومفاتيح `channels` (`pay_card_enabled`، `pay_wallets_enabled`، `pay_alipay_enabled`، `pay_paypal_enabled`، `pay_usdt_enabled`، `pay_sepay_enabled`). | قسم الفوترة. راجع [قنوات الدفع](https://nexcmp.com/ar/docs/billing/payment-channels/). | | `quotas` | حدود `quota_*`. | راجع [الحصص](https://nexcmp.com/ar/docs/billing/quotas/). | | `zones` | المناطق بواسطة `slug` (مطلوبة: `slug`، `name`، `country`؛ اختيارية `city`، `enabled`، `is_default`). | يتم إنشاء مناطق جديدة. المنطقة الموجودة مسبقاً **لا تُعدل** بواسطة الملف. راجع [المناطق](https://nexcmp.com/ar/docs/infrastructure/zones/). | | `plans` | الخطط بواسطة `slug` (مطلوبة: `slug`، `name`، `cpu`، `ram_mb`، `disk_gb`، `hourly_usd`؛ اختيارية `cs_offering_id`، `backend_id`، `zone_id`، `enabled`، `visible`، `sort`، `description`). | قسم الفوترة. يتم إنشاء خطط جديدة، وتحديث الخطط الحالية عبر الـ slug. الأسعار بالدولار الأمريكي لكل ساعة. راجع [الخطط](https://nexcmp.com/ar/docs/catalog/plans/). | | `ai_provider` | مزود الذكاء الاصطناعي في اللوحة المستخدم من قِبل AI Chat وAI Agent للعملاء. | [AI provider](https://nexcmp.com/ar/docs/ai/ai-providers/). | | `legal` | نصوص الشروط والخصوصية لكل لغة (`en`، `vi`). | [الصفحات القانونية](https://nexcmp.com/ar/docs/customers/legal/). | ترتيب التطبيق هو نفس الترتيب أعلاه: العناصر التي تشبه البنية التحتية قبل الخطط. ## قواعد يجب تذكرها {#rules-to-remember} - **متطابق وظيفياً (Idempotent).** تطبيق نفس الملف مرتين لا يغير شيئاً في المرة الثانية. يعرض `plan` عبارة "No changes". - **لا عمليات حذف.** لا يقوم الملف أبداً بإزالة أي منطقة أو خطة أو إعداد. إزالة إدخال من الملف تبقي اللوحة كما هي. - **تظل قواعد الأمان العادية سارية.** من سطر Commands، يتم إرسال كل تغيير عبر نفس فحوصات تغيير API: النطاقات وقواعد IP. التغيير الذي يتطلب تأكيداً (مثل مفتاح على مستوى الموقع) يتم الإبلاغ عنه تحت `pending` مع معاينة بدلاً من تطبيقه، ما لم تمرر `--confirm-billing`، والتي تؤكدها جميعاً. - **لا يمكن لعملاء الذكاء الاصطناعي إلغاء قفل الفوترة.** عند استدعاء `config_apply` بواسطة عميل MCP، يتم تجاهل `confirm_billing`؛ وتنتظر تغييرات الأموال تدخلك. - **تحقق قبل التطبيق.** يصف مخطط JSON كل حقل. وجه محررك إليه، أو امنحه لذكاء اصطناعي ليكتب ملف YAML صالحاً: `https://cloud.example.com/v1/admin/agent/config/schema.json` (قابل للقراءة العامة). ### أقسام الفوترة {#billing-sections} تؤدي `payments`، `currency` و`plans` إلى تغيير الأسعار أو مسارات الأموال. تتخلى `nexcmp config apply --yes` **عنها** ما لم تقم بإضافة `--confirm-billing`؛ يتم بعد ذلك إدراجها تحت `skipped` ("billing section - pass confirm_billing"). العلامة هي تأكيدك: معها، يتم تطبيق كل تغيير فوترة في الملف (وأي تغيير آخر يتطلب تأكيداً) دون مطالبة ثانية. قم بتشغيل `plan` أولاً واقرأ كل سطر محدد بـ `$`. عند تطبيق نفس الملف بواسطة ذكاء اصطناعي (أداة `config_apply` في عميل MCP أو AI Chat)، يتم تجاهل العلامة، وبدلاً من ذلك تنتظر التغييرات المالية موافقتك. ## استخدام صفحة الاستيراد/التصدير {#use-the-import-export-page} 1. افتح **System › Settings › Import/Export**. 2. ضمن **Export** انقر فوق **Get current configuration**، ثم **Download .yaml** للحفظ `nexcmp.yaml`. تظهر البيانات السرية كعناصر نائبة. 3. ضمن **Import** اختر ملفاً، أو اسحبه إلى داخل المربع، أو الصق ملف YAML. 4. اختياري: افتح **Secrets that come with it (not in the file)** وأضف اسمًا وقيمة لكل مرجع، على سبيل المثال `smtp_password`. 5. انقر فوق **Preview changes**. يعرض الجدول التغييرات مجمعة حسب القسم؛ وتحمل الأقسام المتعلقة بالمال علامة "Money-related". قم إلغاء تحديد الأقسام التي لا ترغب بها. 6. إذا كانت الأقسام المتعلقة بالمال مدرجة، فحدد **Also apply money-related changes (prices, payment gateways, balances)**. بدون تحديد هذا الخيار، سيتم تخطيها. 7. انقر فوق **Apply selected**. توضح النتيجة ما تم تطبيقه أو تخطيه أو فشله. التغيير الذي يتم إرجاعه كمعلق في انتظار التأكيد يظهر بطاقة تأكيد؛ اضغط على **Confirm** عليها. زر **JSON Schema** في الأعلى إلى اليمين يفتح مخطط البيانات. ![صفحة الاستيراد والتصدير مع بطاقة التصدير وبطاقة الاستيراد التي تحتوي على ملف YAML المصدر](https://nexcmp.com/ar/docs/images/configure-with-ai/config-as-code-01-import-export.webp) ![جدول معاينة التغييرات مجمعاً حسب القسم مع علامة الفوترة وزر تطبيق المحدد](https://nexcmp.com/ar/docs/images/configure-with-ai/config-as-code-02-preview.webp) ## تشغيل أي أداة من سطر الأوامر {#run-any-tool-from-the-command-line} `nexcmp admin` تشغيل نفس الأدوات الخاصة بمساعدي الذكاء الاصطناعي ([قائمة الأدوات](https://nexcmp.com/ar/docs/configure-with-ai/mcp-admin/#tools)) وطباعة بتنسيق JSON: ```bash sudo nexcmp admin tools # name, scope and title of every tool sudo nexcmp admin system_health sudo nexcmp admin customers_search q=customer@example.com sudo nexcmp admin settings_update --json '{"values":{"support_email":"support@example.com"}}' ``` المعلمات هي أزواج `key=value` (تتم قراءة القيم كـ JSON عند تحليلها، وإلا كنص) أو كائن واحد `--json '{...}'`. إذا كان الإجراء يتطلب تأكيداً، يقوم الأمر بطاعة المعاينة ويتوقف برمز الخروج 3 مع رسالة "Nothing changed". اقرأ المعاينة، ثم شغّل نفس الأمر مرة أخرى مع `--yes` لتطبيقه. عند التشغيل بصلاحية الجذر (root)، يحصل الأمر على مفتاح لمدة 15 دقيقة بكافة النطاقات، لذا فإن خطوة التأكيد هي إجراء الأمان الخاص بك؛ ومع `NEXCMP_KEY` تُطبق نطاقات المفتاح الخاصة به. ## التحقق {#verify} 1. `sudo nexcmp config plan -f nexcmp.yaml` مباشرة بعد `apply --yes` تطبع "No changes". 2. في لوحة الإدارة، تُظهر الصفحات التي قمت بتغييرها القيم الجديدة، وتقوم **Logs › Admin actions** بإدراج التغييرات. 3. تطبيق نفس الملف مرة أخرى لا يغير شيئاً. ## الحدود والملاحظات {#limits-notes} - يغطي الملف الإعدادات أعلاه، ولا يغطي العملاء أو الخوادم أو الفواتير أو مصادر البنية التحتية (اتصالات CloudStack و Proxmox). قم بتوصيل تلك عبر [AI Chat](https://nexcmp.com/ar/docs/configure-with-ai/ai-chat-in-admin/) أو صفحات الإدارة. - يتم مطابقة المناطق والخطط بواسطة `slug`. لا تقم بإعادة تسمية اسم مختصر (slug) في الملف: سيتم إنشاؤه كعنصر جديد. - الخطة التي يستخدمها العملاء بالفعل لا يمكن تغيير حجمها؛ قم بإنشاء خطة جديدة بدلاً من ذلك. - احتفظ بالملفات المصدرة بشكل خاص حتى وإن كانت لا تحتوي على أسرار: فهي تسرد أسعارك وعناوينك وأسماء حساباتك. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | `missing version: 1` | الملف لا يبدأ بـ `version: 1` | أضفه. | | `unsupported version 2` | الملف يحتوي على رقم إصدار آخر | تقرأ هذه اللوحة الإصدار 1 فقط. | | `unknown section 'x' (known: ...)` | مفتاح رئيسي مكتوب بشكل خاطئ أو غير مدعوم | استخدم الأقسام أعلاه. | | `YAML error: ...` | ملف YAML غير صالح (المسافات البادئة، علامات الجدولة) | أصلح السطر الذي يذكره الرسالة. | | `config is larger than 1 MB` | الملف كبير جداً | قم بتقسيمه واستخدام `--section`. | | `no API key: set NEXCMP_KEY=ak_... or run as root on the server` | لم يجد الأمر أي مفتاح | قم بالتشغيل باستخدام `sudo`، أو قم بتصدير `NEXCMP_KEY` والاحتفاظ به عبر sudo. | | `panel not reachable` | خدمة اللوحة لا تعمل على المنفذ الافتراضي | تحقق من `sudo nexcmp status`. | | بنود الفوترة تحت `skipped` | أقسام الفوترة تحتاج إلى `--confirm-billing` | أضف العلامة وراجع بنود `$` أولاً. | | العناصر تحت `pending` | التغيير يحتاج إلى تأكيد | افتح **API & AI agents**، أو نتيجة الاستيراد/التصدير، واضغط على **Confirm** على البطاقة. | | لم يتم تحديث السر | لم يتم تعيين قيمة `NEXCMP_SECRET_`، لذا تم الاحتفاظ بالسر المحفوظ | قم بتصدير المتغير وقم بالتطبيق مرة أخرى. | | إخفاء تحت `errors` مع HTTP 403 `insufficient_scope` | يفتقر المفتاح إلى نطاق هذا القسم | استخدم مفتاحاً بالصلاحية، أو قم بالتنفيذ بصلاحيات الجذر (root). | | إخفاء تحت `errors` مع HTTP 403 `demo_read_only` | لوحة تجريبية | طبق على تثبيت حقيقي. | --- # أمثلة على التوجيهات {#example-prompts} > **الموقع في لوحة الإدارة:** AI Chat (`/agent`) أو زر **Ask AI** العائم في أي صفحة إدارة. تعمل المطالبات نفسها في أي عميل ذكاء اصطناعي متصل عبر [MCP](https://nexcmp.com/ar/docs/configure-with-ai/mcp-admin/). ## الوظيفة {#what-it-does} توضح هذه التوجيهات طريقة الاستعلام. يوضح كل منها ما يفعله المساعد خلف الكواليس، والنطاقات التي يحتاجها (لعميل خارجي أو مفتاح)، والأماكن التي يُطلب منك فيها الموافقة. استبدل قيم الأمثلة بقيمك الخاصة. ::: tip لا تقم أبداً كتابة سر في نص الدردشة بالنسبة لكلمات المرور ومفاتيح API والرموز، استخدم حقل **Secret** بجوار إدخال AI Chat ([التفاصيل](https://nexcmp.com/ar/docs/configure-with-ai/ai-chat-in-admin/#secrets)). لا يرى الذكاء الاصطناعي سوى عنصر نائب يمثل السر، وليس القيمة. مع عميل ذكاء اصطناعي خارجي يمر السر عبر ذلك العميل، لذا يُفضل إدخاله في لوحة الإدارة. ::: ## تحقق من موقعك الحالي {#check-where-you-are} ```text Check my setup progress and tell me the next three things to do, in order. ``` يستدعي المساعد `setup_checklist` و`system_health` (النطاق `admin:read`) ويجيب بناءً على الحالة الفعلية. انظر [Setup progress checklist](https://nexcmp.com/ar/docs/configure-with-ai/setup-checklist/). ## الإعداد الأول {#first-setup} ```text Help me finish the initial setup. Go through the checklist, explain each open step in one sentence, ask me for what you need, and show me every change before it is applied. ``` هذا يماثل مطالبة MCP `initial-setup`. يتطلب `admin:read` بالإضافة إلى نطاقات الخطوات التي تقبلها. توقع ظهور بطاقة تأكيد لكل تغيير في AI Chat. ## إضافة مجموعة Proxmox VE {#add-a-proxmox-ve-cluster} ```text I want to sell servers from my Proxmox VE cluster at https://pve.example.com:8006. Add it, test the connection, create a zone called "New York" in the US, attach the cluster to it, and then propose starter plans. ``` ماذا يحدث: 1. يطلب المساعد معرف رمز API (`user@realm!tokenid`) وسره. ضع السر في حقل **Secret**. أنشئ رمزاً محدوداً أولاً: [Proxmox VE](https://nexcmp.com/ar/docs/infrastructure/proxmox/). 2. يستدعي `proxmox_add` و`proxmox_test` و`zone_create` و`proxmox_attach_zone`. 3. يقترح خططاً مع `plans_from_offerings` وينتظر موافقتك (انظر المثال التالي). النطاقات: `infra:write`، `secrets:write`، `catalog:write`، `admin:read`. ## إنشاء جدول خطط بهامش ربح 40% {#create-a-plan-table-with-a-40-margin} ```text Suggest a starter plan table from my CloudStack offerings. My costs are $4 per vCPU per month, $2 per GB of RAM per month and $0.08 per GB of disk per month. Use a 40% margin, show me the table with cost, price per month and price per hour, and create the plans only after I approve. ``` يستدعي المساعد `plans_from_offerings` باستخدام `margin_pct` 40 وتكاليفك. الهامش هو نسبة سعر البيع التي تمثل ربحاً: عند نسبة 40%، الخطة التي تبتلعك $60 تباع بـ $100. الاستدعاء الأول يعيد معاينة فقط. عندما توافق، فإنه يستدعي الأداة مرة أخرى باستخدام `apply=true`، مما ينشئ الخطط في خطوة واحدة ويطلب تأكيداً واحداً لأن الأسعار متضمنة. بالنسبة لـ Proxmox، فإنه يستخدم `backend_id` وقائمة أحجام افتراضية (1، 2، 2 و 4 vCPU). النطاقات: `catalog:write`، `admin:read`. راجع [Plans](https://nexcmp.com/ar/docs/catalog/plans/). ![إجابة AI Chat تُظهر جدول معاينة للخطط مع التكلفة والسعر الشهري والسعر بالساعة](https://nexcmp.com/ar/docs/images/configure-with-ai/example-prompts-01-plan-preview.webp) ## تكوين البريد الإلكتروني وإرسال رسالة اختبار {#configure-email-and-send-a-test-message} ```text Configure outgoing email with smtp.example.com, port 587, STARTTLS, user "mailer@example.com", sender name "Example Cloud", sender address "no-reply@example.com". Use my Secret field for the password "smtp_password". Then send a test email to admin@example.com. ``` يستدعي المساعد `smtp_get` و `smtp_configure` و `smtp_test` ويخبرك ما إذا تم قبول الرسالة. النطاقات: `settings:write`، `secrets:write`. راجع [SMTP and e-mail templates](https://nexcmp.com/ar/docs/administration/smtp-and-emails/). ## إعداد Stripe {#set-up-stripe} ```text Set up Stripe in test mode. My publishable key is pk_test_XXXX. Use the secret key and the webhook secret from my Secret field (names stripe_secret_key and stripe_webhook_secret). Then test the credentials and tell me which webhook URL I must add in Stripe. ``` `payment_configure` هو دائماً إجراء من خطوتين: ترى معاينة مع إخفاء القيم السرية وتوافق عليها. ثم يتحقق `payment_test` من بيانات الاعتماد مع Stripe. النطاقات (Scopes): `billing:write`، `secrets:write`. انتقل إلى وضع التشغيل المباشر (live mode) فقط بعد إجراء دفعة اختبارية. راجع [Stripe](https://nexcmp.com/ar/docs/billing/stripe/). ## تفعيل تنبيهات تيليجرام {#turn-on-telegram-alerts} ```text Add my Telegram chat 123456789 for admin alerts. The bot token is in my Secret field as telegram_bot_token. Send a test message. ``` يستدعي المساعد `telegram_configure` و`telegram_test`. النطاقات (Scopes): `settings:write`، `secrets:write`. راجع [Telegram notifications](https://nexcmp.com/ar/docs/administration/telegram-notifications/). ## العثور على عميل وإضافة رصيد {#find-a-customer-and-add-credit} ```text Find the customer with e-mail customer@example.com, show me their balance and servers, and add $10.00 of credit because of the outage on Monday. ``` يستدعي المساعد `customers_search` و`customer_get` (للقراءة فقط)، ثم `customer_adjust_balance` مع `delta_cents` 1000 وسبب محدد. يتطلب هذا **دائماً** موافقتك: تقول بطاقة التأكيد "changes a customer balance" وتُظهر المبلغ والسبب الذي سيتم تسجيله في سجل التدقيق (audit log). النطاقات (Scopes): `admin:read`، `billing:write`. ## تصدير إعداداتي {#export-my-configuration} ```text Export my whole configuration as YAML. Do not include secrets. Then tell me which settings differ from a typical new installation. ``` يستدعي المساعد `config_export`. يتم استبدال الأسرار بمراجع `secret://`. احفظ النتيجة كـ `nexcmp.yaml` واحتفظ بها في نظام التحكم الإصداري. راجع [Configuration as code](https://nexcmp.com/ar/docs/configure-with-ai/config-as-code/). النطاق (Scope): `admin:read`. ## كتابة موجّهات (Prompts) جيدة {#write-good-prompts} - اعرض الهدف والوقائع: الأسماء، الأسعار، عناوين البريد الإلكتروني. لا تقم بلصق الأسرار. - اطلب معاينة أولاً لأي شيء يكلف مالاً أو يحذف بيانات. - اطلب من المساعد "قراءة القيمة الحالية قبل تغييرها". التعليمات المدمجة تفعل ذلك بالفعل. - إذا بدا رد ما خاطئاً، فاسأل "ما هي الأداة التي استدعيتها وبأي وسائط؟". تُظهر بطاقات الأدوات في AI Chat كليهما. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | يقول المساعد إنه لا يملك أداة لشيء ما | نطاق (Scope) هذه الأداة غير ممنوح، أو أن الإجراء مغلق أمام الذكاء الاصطناعي | تحقق من [Admin API keys](https://nexcmp.com/ar/docs/configure-with-ai/admin-api-keys/#what-a-key-can-never-do)، أو قم بذلك في لوحة المشرف. | | يطلب منك لصق كلمة مرور | تجاهل النموذج التعليمات | ارفض؛ استخدم حقل السر (Secret) أو أدخل القيمة في لوحة المشرف. | | لا شيء يتغير بعد "تنفيذ ذلك" (do it) | التغييرات في انتظار تأكيدك | قم بالتمرير إلى بطاقة التأكيد واضغط على **Confirm**. | | تم إنشاء الخطط بسعر لم تكن تتوقعه | كانت التكاليف أو الهامش في الموجه (prompt) خاطئة | قم بتعديل الخطط على صفحة الخطط أو اطلب من المساعد إعادة تسعيرها؛ تتطلب تغييرات الأسعار تأكيداً. | --- # قائمة التحقق من تقدم الإعداد {#setup-progress-checklist} > **Where in the admin:** Overview › Dashboard (`/`)، بطاقة **Setup progress** في الأعلى. تعرض القوائم الفارغة في Plans و Customers و Zones و Payments و Infrastructure نفس المساعدة. ## الوظيفة {#what-it-does} يحتاج التثبيت الجديد إلى عشرة أشياء قبل أن يتمكن العميل الأول من الطلب والدفع. تتحقق بطاقة **Setup progress** منها نيابة عنك من الإعدادات الفعلية، وتُظهر عدد المنجز منها، وتُسمي **الخطوة التالية** وتضع رابطاً للصفحة التي تقوم فيها بذلك. إذا كان لديك مصدر ذكاء اصطناعي متصل، فإن **Do it for me** يفتح [AI assistant](https://nexcmp.com/ar/docs/configure-with-ai/ai-chat-in-admin/) مع سؤال جاهز لتلك الخطوة. يمكن للمساعد (وأي عميل ذكاء اصطناعي عبر [MCP](https://nexcmp.com/ar/docs/configure-with-ai/mcp-admin/)) قراءة نفس القائمة باستخدام الأداة `setup_checklist`. ## الخطوات العشر {#the-ten-steps} | # | الخطوة | تُعد منجزة عندما | أين تقوم بذلك | |---|---|---|---| | 1 | الترخيص نشط | تم تفعيل الترخيص لنطاقك | System › Admin › License & updates (`/license`). انظر [License and purchase](https://nexcmp.com/ar/docs/getting-started/license-and-purchase/). | | 2 | اتصال بمصدر للبنية التحتية | CloudStack متصل، أو تم إضافة مجموعة Proxmox VE واحدة على الأقل | Infrastructure › Cloud provider › Providers (`/infra/providers`). راجع [CloudStack](https://nexcmp.com/ar/docs/infrastructure/cloudstack/) و[Proxmox VE](https://nexcmp.com/ar/docs/infrastructure/proxmox/). | | 3 | إنشاء منطقة | وجود منطقة واحدة على الأقل | Infrastructure › Datacenter › Zone (`/infra/zones`). راجع [Zones](https://nexcmp.com/ar/docs/infrastructure/zones/). | | 4 | قوالب نظام التشغيل | تم تفعيل قالب واحد على الأقل | Services › Virtual Machines › Plans & pricing، علامة التبويب Templates (`/vm/catalog?tab=templates`). راجع [OS templates](https://nexcmp.com/ar/docs/infrastructure/templates/). | | 5 | إنشاء الخطط | تم تفعيل خطة واحدة على الأقل | Services › Virtual Machines › Plans & pricing (`/vm/catalog`). راجع [Plans and pricing](https://nexcmp.com/ar/docs/catalog/plans/). | | 6 | إعداد المدفوعات | تم تكوين Stripe أو PayPal أو العملات المشفرة أو التحويل البنكي | Finance › Payment channels (`/payments`). راجع [Payment channels](https://nexcmp.com/ar/docs/billing/payment-channels/). | | 7 | البريد الإلكتروني (SMTP) | تم تكوين البريد الإلكتروني الصادر | System › Settings › Email (`/settings/email`). راجع [SMTP and e-mail templates](https://nexcmp.com/ar/docs/administration/smtp-and-emails/). | | 8 | Branding | تم تحميل شعار أو تغيير اسم العلامة التجارية عن الاسم الافتراضي | System › Settings › Brand (`/settings/branding`). راجع [Branding](https://nexcmp.com/ar/docs/customers/branding/). | | 9 | الشروط والخصوصية | تم ملء نص قانوني واحد على الأقل | System › Settings › Legal (`/settings/legal`). راجع [Legal pages](https://nexcmp.com/ar/docs/customers/legal/). | | 10 | إجراء طلب تجريبي | وجود طلب واحد على الأقل | قم بتقديم طلب بصفتك عميلاً في بوابة العملاء للتحقق من عمل كل شيء من البداية إلى النهاية؛ ترتبط البطاقة بصفحة الفوترة (`/billing`). | تُظهر البطاقة `done/total` (على سبيل المثال 6/10)، وشريط تقدم، والخطوة التالية مع زر **Open**، وعند توصيل مصدر ذكاء اصطناعي، يظهر زر **Do it for me**. انقر فوق أي خطوة للانتقال إلى صفحتها. وبجوار كل خطوة، يفتح رابط صغير صفحة التوثيق المطابقة؛ وتُظهر بعض الخطوات أيضاً تفاصيل مثل "2 zone(s)". ![بطاقة تقدم الإعداد في نظرة عامة مع إنجاز ثلاث خطوات من أصل عشرة وأزرار الفتح والتنفيذ نيابة عني](https://nexcmp.com/ar/docs/images/configure-with-ai/setup-checklist-01-card.webp) ## استخدامه {#use-it} 1. افتح صفحة النظرة العامة. توجد البطاقة في الأعلى. استخدم السهم لتصغيرها؛ حيث يتذكر اللوحة خيارك في متصفحك. 2. انقر فوق **Open** للانتقال إلى صفحة الخطوة التالية، أو انقر فوق **Do it for me**. 3. باستخدام **Do it for me**، يفتح المساعد بطلب مثل "اقترح جدول خطة مبتدئة من عروضي بهامش 40%، وعرض المعاينة قبل إنشائه." أجب عن أسئلته، ثم راجع و**Confirm** كل بطاقة. انظر [AI Chat in the admin](https://nexcmp.com/ar/docs/configure-with-ai/ai-chat-in-admin/). 4. عند إكمال الخطوات العشر جميعها، تختفي البطاقة. ### القوائم الفارغة {#empty-lists} عندما تكون صفحة Plans أو Customers أو Zones أو Payments أو Infrastructure فارغة، تعرض الصفحة كتلة **Next step** تتضمن توضيحاً، وزراً للإجراء، وزر **Do it for me**، ورابطاً للتوثيق، لكي لا تواجه أبداً جدولاً فارغاً. ![صفحة خطط فارغة مع توضيح للخطوة التالية وزر التنفيذ نيابة عني](https://nexcmp.com/ar/docs/images/configure-with-ai/setup-checklist-02-empty.webp) ## اطلب ذلك بكلماتك الخاصة {#ask-for-it-in-your-own-words} لا تحتاج إلى البطاقة. في AI Chat أو أي عميل ذكاء اصطناعي متصل، يمكنك أن تسأل: ```text Check my setup progress and take me through the open steps, one at a time. ``` هذا هو أيضاً موجه MCP `initial-setup`. يستدعي المساعد `setup_checklist`، ويوضح سبب أهمية كل خطوة مفتوحة، ويطلب المعلومات التي يحتاجها ويستخدم الأداة المطابقة. النطاقات المطلوبة: `admin:read` لقراءة القائمة، بالإضافة إلى نطاق الخطوة التي تريد إنجازها. راجع [Example prompts](https://nexcmp.com/ar/docs/configure-with-ai/example-prompts/). ## التحقق {#verify} 1. بعد الانتهاء من إتمام خطوة ما، يرتفع عداد البطاقة في المرة التالية التي يتم فيها تحميل صفحة النظرة العامة. 2. في المساعد، يعود `setup_checklist` بنفس الأرقام، مع وجود `done: true` على الخطوة المكتملة. ## الحدود والملاحظات {#limits-notes} - تتحقق عمليات الفحص مما يتم حفظه، وليس مما إذا كان يعمل. تُحتسب البوابة المُكوَّنة كمنجزة حتى لو فشل اختبارها. استخدم أزرار **Test** في كل صفحة، وأداة `system_health` للمشكلات. - هذه البطاقة مخصصة للمسؤولين فقط. - تحتاج ميزة **Do it for me** إلى مصدر AI مُمتد ضمن System ›Settings › AI accounts؛ وبدون ذلك، يتم عرض **Open** فقط. - الخطوات العشر هي نفسها لكل تثبيت؛ فالخطوة التي لا تنوين استخدامها (على سبيل المثال، المدفوعات على سحابة خاصة) تظل تُحتسب كمفتوحة. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | البطاقة مفقودة | تم إنجاز جميع الخطوات العشر، أو تعذر تحميل البطاقة | أعد تحميل نظرة عامة. اسأل `setup_checklist` في AI Chat لمعرفة الحالة. | | تظل الخطوة مفتوحة بعد إتمامها | لم يكتمل الحفظ، أو لم يتحقق الشرط بعد (على سبيل المثال، يوجد قالب ولكنه معطل) | افتح صفحة الخطوة وتحقق من الجدول أعلاه. | | تظل العلامة التجارية مفتوحة بعد تغيير الشعار | تُحتسب العلامة التجارية عند وجود شعار أو اختلاف اسم العلامة التجارية عن الافتراضي "NexCMP" | قم بتحميل شعار أو تعيين اسمك الخاص. | | لا تفعل ميزة **Do it for me** شيئاً | لا يوجد مصدر AI متصل، أو لوحة العرض التجريبي | قم بتوصيل مصدر في حسابات الـ AI. | --- # إعدادات SMTP وقوالب البريد الإلكتروني {#smtp-and-e-mail-templates} > **المكان في لوحة التحكم:** System › Settings › Email (`/settings/email`) — علامات التبويب **SMTP** و **Email templates**. سجل التسليم: Overview › Support › Sent emails (`/support/emails`). ## الوظيفة {#what-it-does} يرسل NexCMP رسائل بريد إلكتروني للتحقق من التسجيل، وإعادة تعيين كلمة المرور، و"VM ready" (مع كلمة المرور الأولية)، والفواتير، وانخفاض الرصيد، والتجديدات، وعمليات تعبئة الرصيد، وردود الدعم الفني والمزيد. تمر جميعها عبر **حساب SMTP واحد توفره أنت**. توجد الرسائل والقوالب بـ 16 لغة؛ ويتم استخدام لغة العميل. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | خادم SMTP | المضيف، والمنفذ (Port)، وبيانات الاعتماد لأي مزود (خادمك الخاص، Brevo، Amazon SES، Mailgun، Google Workspace …) | | الشبكة | حركة المرور الصادرة (Outbound TCP) من خادم NexCMP إلى مضيف ومنفذ SMTP (587 عبر STARTTLS، أو 465 عبر TLS، أو 25) | | نطاق المرسل | نطاق تتحكم فيه، مع نشر سجلي **SPF و DKIM** للمزود وسجل DMARC | | الإذن | يجب السماح لحساب SMTP بالإرسال عنوان **From** | ::: warning قابلية التسليم تحتوي رسائل البريد الإلكتروني مثل "VM ready" على كلمات مرور. إذا لم يتطابق سجل SPF/DKIM/DMARC لنطاق المرسل مع مزود SMTP، فستنتهي في مجلد البريد العشوائي (Spam). تذكرك الصفحة بذلك. ::: ## إعداد مزود البريد الإلكتروني {#prepare-the-e-mail-provider} 1. في لوحة تحكم المزود، أضف وحقق من نطاق الإرسال الخاص بك (على سبيل المثال `example.com`). 2. انشر سجلات DNS الخاصة بـ SPF و DKIM و DMARC التي يُظهرها المزود. 3. أنشئ مستخدم SMTP (أو مفتاح API-SMTP) وسجل المضيف، والمنفذ، واسم المستخدم، وكلمة المرور. ## الربط في NexCMP {#connect-in-nexcmp} 1. افتح مسار **System › Settings › Email**، ثم علامة التبويب **SMTP**. 2. املأ النموذج: | الحقل | مثال | ملاحظات | |---|---|---| | المضيف | `smtp.example.net` | خادم SMTP | | المنفذ | `587` | | | الأمان | STARTTLS (587) | اختر الوضع الذي يتطلبه مزود الخدمة الخاص بك | | اسم المستخدم | `smtp-user` | | | كلمة المرور | (مخفي) | للكتابة فقط: تعرض الصفحة ما إذا تم تعيينه أم لا | | البريد الإلكتروني للـ المرسل | `no-reply@example.com` | يجب أن يكون مخولاً لدى المزود | | اسم المرسل | `Example Cloud` | الافتراضي هو اسم علامتك التجارية | | الرد إلى (اختياري) | `support@example.com` | حيث تذهب ردود العملاء | ![علامة التبويب SMTP في الإعدادات، البريد الإلكتروني مع المضيف، المنفذ، الأمان، اسم المستخدم، حقول المرسل وزر إرسال اختبار](https://nexcmp.com/ar/docs/images/administration/smtp-and-emails-01-smtp.webp) 3. انقر على **Save**، ثم **Send test** وأدخل عنوانك الخاص. يتم تخزين الإعدادات في ملف تقييد الوصول (`smtp.json`، الوضع 0600) وفقط العامل في الخلفية `nexcmp-vmd` يقوم بإرسال البريد؛ بينما تقوم خدمة الويب بوضعه في قائمة الانتظار فقط. ## التحقق {#verify} - تصل رسالة الاختبار إلى صندوق الوارد (تحقق من البريد العشوائي أيضاً). في مصدر الرسالة، تأكد من `dkim=pass` و `spf=pass`. - افتح **Support › Sent emails**: لكل رسالة حالة (في الانتظار، مرسلة، فاشلة) ونتيجة التسليم. تتم إعادة محاولة الرسائل الفاشلة حتى 3 مرات. - قم بتسجيل عميل اختبار في البوابة وتأكد من وصول بريد التحقق الإلكتروني. ## تعديل قوالب البريد الإلكتروني {#edit-e-mail-templates} تعرض علامة التبويب **Email templates** كل قالب حسب المفتاح، مع اللغات التي يتوفر بها (على سبيل المثال `verify_email`، `reset_password`، `vm_ready`، `invoice_paid`، `low_balance`، `topup_received`، `ticket_reply`، `scale_up` ...). 1. انقر على قالب واختر لغة. 2. تعديل الموضوع والنص. يتم ملء العناصر النائبة عند وضع الرسالة في قائمة الانتظار. 3. حفظ. يسري التغيير **فوريًا** على الرسائل الموضوعة في قائمة الانتظار بعد ذلك. ![علامة تبويب قوالب البريد الإلكتروني التي تعرض مفاتيح القوالب ولغاتها](https://nexcmp.com/ar/docs/images/administration/smtp-and-emails-02-templates.webp) ## القيود والملاحظات {#limits-and-notes} - حساب SMTP واحد لكل تثبيت. يتلقى عملاء الموزعين البريد الإلكتروني عبر نفس الحساب ما لم يتم تكوين الموزع بشكل مختلف. - تطبق حدود الإرسال الخاصة بالمزود؛ لا يقوم NexCMP بتقييد السرعة بما يتجاوز إعادة المحاولة. - بدون SMTP تعمل اللوحة، ولكن لا يمكن للعملاء إكمال تحقق التسجيل وإعادة تعيين كلمة المرور. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | لا يصل البريد الإلكتروني التجريبي أبداً | بيانات اعتماد خاطئة، المنفذ محظور، المرسل غير مصرح له | تحقق من `journalctl -u nexcmp-vmd` لمعرفة خطأ SMTP؛ جرب المنفذ 587 مع STARTTLS؛ وتأكد من عنوان From لدى المزود. | | الرسائل تذهب إلى البريد العشوائي | سجلات SPF/DKIM/DMARC مفقودة أو غير متطابقة | انشر سجلات المزود وأرسل من هذا النطاق. | | "failed" في البريد الإلكتروني المرسل | رفض المزود الرسالة | افتح الصف لمعرفة رد المزود. | | حقل كلمة المرور يبدو فارغاً بعد الحفظ | حسب التصميم (للكتابة فقط) | تظهر التسمية "current: set" بمجرد تخزين كلمة المرور. | --- # تنبيهات تيليجرام والمسؤول {#telegram-and-admin-alerts} > **أين في الإدارة:** System › Settings › Admin alerts (`/settings/alerts`). اختصارات الدعم: Customers › Support › Tickets (`/support/tickets`)، علامة التبويب **Settings**. ## الوظيفة {#what-it-does} تعلمك NexCMP **أنت** — المشغل — عندما يحتاج أمر ما إلى الاهتمام، وعندما يسجل عميل جديد أو يتم إيداع رصيد. تُرسل التنبيهات إلى **قناة** واحدة أو أكثر: Telegram، أو webhook، أو البريد الإلكتروني. الحدث المُرسل إلى قنوات المسؤول يتضمن: فشل نشر، اختفاء جهاز افتراضي، تعطل الشبكة، انخفاض عناوين IP الحرة عن 30، عنصر منتهي الصلاحية (تحذير لمدة 1 ساعة)، نزاع في Stripe، عامل معطل، تجاوز ذاكرة العضو المؤقت للحد، تسجيل عميل جديد، وإيداعات معتمدة. أحداث العملاء توضع في طابور بشكل دائم وتُعاد محاولتها بتأخير متزايد (من 30 ثانية حتى 1 ساعة) حتى يقبلها Telegram. ## المتطلبات {#requirements} | العنصر | المتطلب | |---|---| | Telegram | روبوت تم إنشاؤه باستخدام **@BotFather** (رمز التوثيق) و**معرف الدردشة (chat ID)** للمجموعة أو المستخدم الذي يجب أن يتلقى الرسائل | | الشبكة | HTTPS الصادر إلى `api.telegram.org` | | Webhook (بديل) | نطة نهاية HTTPS تقبل حمولة التنبيه | ## إعداد Telegram {#prepare-telegram} 1. افتح **@BotFather** في Telegram، وأرسل `/newbot`، واختر اسماً؛ ثم انسخ **رمز الروبوت (bot token)** (`123456789:AA...`). 2. أنشئ مجموعة، وأضف الروبوت إليها، وأرسل أي رسالة. 3. اعثر على **معرف الدردشة (chat ID)**: افتح `https://api.telegram.org/bot/getUpdates` في متصفح واقرأ `chat.id` (تبدأ معرفات المجموعات بـ `-`). ## الربط في NexCMP {#connect-in-nexcmp} 1. افتح **System › Settings › Admin alerts**. 2. في **Add channel** اختر **Type: Telegram**، واضبط **Destination** على معرف الدردشة و**Secret (bot token)** على الرمز. انقر فوق **Add**. 3. تأكد من تفعيل مفتاح التبديل **Send admin Telegram (VM module)**؛ يُظهر السطر *VM module status (read-only)* القيمة "on". ![صفحة تنبيهات المشرف مع نموذج إضافة قناة المضبوط على Telegram](https://nexcmp.com/ar/docs/images/administration/telegram-notifications-01-channel.webp) ## التحقق {#verify} تظهر القناة ضمن **Configured channels**. قم بتشغيل حدث (على سبيل المثال، تسجِّل عميلاً اختبارياً) وستصل الرسالة إلى المجموعة. إذا لم تُكوَّن أي قناة، فتحذر الصفحة من أن "بدون قناة، ستمر الهجمات دون ملاحظة"، وفي السجل، يتم تسجيل أحداث Telegram محلياً فقط. ## اختصارات الدعم للعملاء {#support-shortcuts-for-customers} يمكن لعنصر واجهة دعم العملاء إظهار أزرار **Telegram** و**Zalo**. تظل مخفية حتى يتم تكوينها في إعدادات الدعم: أدخل رابط `https://t.me/...` لـ Telegram ورابط أو رمز الاستجابة السريعة (QR) لـ Zalo. يُقبل فقط روابط `https://`. يمكن لدردشة الدعم أيضاً إشعار مجموعة Telegram الخاصة بك بالسؤال ومسودة الإجابة — راجع [AI Chat](https://nexcmp.com/ar/docs/ai/ai-chat/). ## القيود والملاحظات {#limits-and-notes} - يتم تخزين رمز الروبوت مع القناة ولا يُعرض مرة أخرى. - تستخدم أحداث Telegram أول قناة Telegram مفعلة تحتوي على كل من وجهة ورمز. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | العَرَض | السبب | الحل | |---|---|---| | لا توجد رسالة تصل | معرف دردشة خاطئ، أو الروبوت ليس في المجموعة، أو لم تتم مراسلة الروبوت من قبل | أعد التحقق من المعرف باستخدام `getUpdates`؛ أرسل رسالة إلى الروبوت أو المجموعة أولاً. | | يعمل لفترة ثم يتوقف | تم إلغاء الرمز في BotFather | أنشئ رمزاً جديداً وقم بتحديث القناة. | | `Telegram: no channel` في السجلات | لا توجد قناة Telegram مفعلة | أضف واحدة كما هو موضح أعلاه. | --- # سجل التدقيق والنشاط {#audit-log-and-activity} > **أين في لوحة المشرف:** System › Logs › Activity (`/logs`)، Admin actions (`/logs/admin`)، Console (`/logs/console`)، Login (`/logs/logins`)، VM events (`/logs/vm-events`)؛ Overview › Support › Sent emails. تسجل NexCMP كل إجراء مهم. استخدم صفحة **Activity** كخط زمني واحد، وعلامات التبويب الأخرى لتضييق نطاق البحث. ## علامات التبويب {#tabs} | علامة التبويب | المحتوى | |---|---| | **Activity** | خط زمني موحد عبر جميع المصادر: إجراءات المسؤولين، أحداث الأجهزة الافتراضية، عمليات تسجيل الدخول، نظام الإحالة، وأخطاء النظام | | **Admin actions** | التغييرات التي أجراها المسؤولون (على سبيل المثال `customer.block`، `customer.delete`)، مع عنوان IP الخاص بالمشرف | | **Console** | تسجيلات الدخول إلى Admin console وطلبات النظام مثل طلب التحديث | | **Login** | عمليات تسجيل دخول العملاء وحالات الإخفاق | | **VM events** | خطوات النشر، الإنشاء، كلمة المرور، الحذف، وغيرها من أحداث دورة الحياة لكل جهاز افتراضي | ## قراءة صفحة {#reading-a-row} الأعمدة: **Time**، **Source**، **Level**، **Actor** (من قام بالإجراء)، **Target**، **Services**، **Action** (رمز الحدث مثل `customer.delete`)، و**Details**. انقر فوق **Open** للحصول على السجل الكامل. ![صفحة الأنشطة مع مرشحات المصدر والموقع والخدمة الموجودة أعلى الخط الزمني](https://nexcmp.com/ar/docs/images/administration/audit-log-01-activity.webp) ## التصفية والبحث {#filter-and-search} 1. اختر **source** و**site** و**service** من القوائم المنسدلة. 2. قم بتحديد نطاق زمني **From date** / **To date**. 3. اكتب رمز حدث (على سبيل المثال `customer.block` أو `destroy`) في مربع البحث — يتطابق بحث الأنشطة مع رمز الحدث. ## الاحتفاظ بالبيانات والتصدير {#retention-and-exports} تُحفظ السجلات في قواعد بيانات NexCMP في `/var/lib/nexcmp` وتُدرج ضمن [النسخ الاحتياطية](https://nexcmp.com/ar/docs/getting-started/backup-and-restore/). وتعتمد مدة الاحتفاظ على نوع السجل: حيث تُحذف محاولات تسجيل دخول العملاء الأقدم من 180 يوماً وسجلات طلبات مفاتيح API للعملاء الأقدم من 60 يوماً. ويحتفظ سجل تدقيق مفاتيح API للمسؤول بما يصل إلى نحو 200,000 سجل حديث. ولا تعني هذه الحدود تطبيق مدة الاحتفاظ نفسها على المخطط الزمني الموحد للنشاط. ## الاستخدامات الشائعة {#common-uses} | السؤال | أين تبحث | |---|---| | من قام بتعليق حساب هذا العميل؟ | إجراءات المسؤولين، ابحث عن `customer.block` | | لماذا اختفى جهاز افتراضي؟ | أحداث الأجهزة الافتراضية، قم بالتصفية حسب مُعرّف الجهاز الافتراضي؛ وكذلك النشاط | | هل استلم العميل البريد الإلكتروني؟ | Overview › Support › Sent emails | | متى تم طلب آخر تحديث؟ | علامة التبويب Console | --- # الأمان {#security} > **أين في لوحة الإدارة:** System › Admin › Console security (`/account`)، Admin users (`/users`)؛ System › Settings › Customer logins (`/settings/login`). ## لوحة تحكم المسؤول {#admin-console} ### المصادقة الثنائية (TOTP) {#two-factor-authentication-totp} وحدة التحكم متاحة عبر الإنترنت، لذا يرجى تفعيل المصادقة الثنائية (TOTP). 1. افتح **System › Admin › Console security**. 2. ضمن **Two-factor authentication (TOTP)** انقر فوق **Start setup**. 3. قم بسحّ رمز الاستجابة السريعة (QR code) باستخدام Google Authenticator أو Authy أو 1Password أو Bitwarden، ثم أدخل الرمز المكون من 6 أرقام. ### نطاقات IP المسموح بها لوحدة التحكم {#allowed-console-ip-ranges} تحت **Allowed console IP ranges** أدخل عنوان IP واحد أو نطاق CIDR (IPv4 أو IPv6) في كل سطر. **الحقل الفارغ يعني السماح من أي مكان.** خارج هذا النطاق، يتم حظر كل من تسجيل الدخول واجهة برمجة تطبيقات المسؤول API. ::: warning لا تحرم نفسك من الوصول تعرض الصفحة عنوان IP الحالي الخاص بك وتتطلب أن تتضمنه القائمة الجديدة. استخدم **+ Add my IP**. إذا تم حظرك على أي حال، فاستخدم [emergency access](https://nexcmp.com/ar/docs/getting-started/cli-reference/#emergency-access) من الخادم. ::: ### تغيير كلمة المرور {#change-password} املأ حقول **Current password** و**New password** و**Confirm new password**. استخدم كلمة مرور طويلة وفريدة (12 حرفاً أو أكثر؛ يفرض معالج الإعداد 12 حرفاً للمسؤول الأول). ### حسابات وأدوار المسؤولين {#administrator-accounts-and-roles} افتح **System › Admin › Admin users** واستخدم **+ Create account**. | الدور | الوصول | |---|---| | `admin` | وصول كامل إلى واجهة برمجة تطبيقات المشرف (admin API) | | `staff` | قراءة فقط عبر النظام بأكمله | | `user` | عرض للقراءة فقط لموارد عميل واحد | حساب الجذر (root) هو الحساب الذي تم إنشاؤه في [معالج الإعداد](https://nexcmp.com/ar/docs/getting-started/setup-wizard/). إجراءات الصف: **Edit**، **Reset PW**، **Key**، **Delete**. يتم تخزين كلمات المرور كقيم مُجزأة مملحة (salted hashes)؛ يؤدي تغيير الحساب أو قفله إلى إنهاء جلساته على الفور. ## تسجيل دخول العميل {#customer-sign-in} افتح **System › Settings › Customer logins**. | الإعداد | الوظيفة | |---|---| | **تسجيل الدخول باستخدام Google** | قم بالتفعيل، ثم أدخل معرف عميل OAuth والسر. انسخ **Callback URL** المعروض على الصفحة إلى *Google Cloud Console › APIs & Services › Credentials › OAuth client ID › Authorized redirect URIs*. استخدم **Test configuration**. | | **تسجيل الدخول باستخدام GitHub** | نفس الخطوات، مع *GitHub › Settings › Developer settings › OAuth Apps › Authorization callback URL* | | **مفتاح المرور (Passkey)** | تسجيل الدخول ببصمة الإصبع، رقم التعريف الشخصي، أو المفتاح الأجهزة؛ مُفعل افتراضيًا. ترتبط مفاتيح المرور بالنطاق؛ ويعمل نطاق كل موزع بشكل مستقل. أدخل نطاقًا قديمًا في *Legacy passkey Domain* بعد إعادة العلامة التجارية ليحصل العملاء على تلميح مفيد | | **إعادة المصادقة عند إضافة طرق تسجيل الدخول** | طلب كلمة المرور مرة أخرى قبل إضافة مفتاح مرور أو ربط حساب Google/GitHub (معطل افتراضياً) | | **تحقق الأمان (Captcha)** | Cloudflare Turnstile أو Google reCAPTCHA عند التسجيل: قم بالتفعيل، واختر المزود، وأدخل مفتاح الموقع ومفتاح السر | | **حظر نطاقات البريد الإلكتروني** | نطاق واحد في كل سطر (بحد أقصى 2000). يتم رفض العناوين المطابقة عند التسجيل باستخدام `email_domain_blocked` | ![صفحة تسجيل دخول العميل التي تعرض تسجيل الدخول عبر Google مع عنوان URL لإعادة الاتصال الخاص بها](https://nexcmp.com/ar/docs/images/administration/security-01-customer-logins.webp) ### السياسات المدمجة {#built-in-policies} | السياسة | القيمة | |---|---| | كلمة مرور العميل | 10 أحرف على الأقل، تتضمن حروفاً وأرقاماً | | جلسة العميل | 30 يوماً؛ جلسات "تسجيل الدخول كعميل" تستمر لمدة 1 ساعة | | التحقق من البريد الإلكتروني | مطلوب قبل إنشاء جهاز ظاهري (VM) عندما تكون ميزة *require e-mail verified* مفعلة في إعدادات المبيعات | | الحماية من سرقة البطاقات | الحسابات التي تقل أرصدتها عن الحد الأدنى للشحن يمكنها إنشاء عدد محدود فقط من الأجهزة الظاهرية (VMs) | ## تأمين الخادم {#server-hardening} - المنفذ 3000 مُغلق بعد الإعداد وتفعيل TLS؛ انظر [Installation](https://nexcmp.com/ar/docs/getting-started/installation/#the-panel-port-3000). - يعمل الخدمة كمستخدم غير مُصرح له `nexcmp` مع صندوق الحماية المقيد في systemd. - تُخزن مفاتيح واجهة برمجة التطبيقات (API keys)، وبيانات اعتماد الدفع، وكلمات مرور SMTP بشكل مشفر؛ المفتاح الرئيسي موجود في `/var/lib/nexcmp/secrets` — احمِ [backups](https://nexcmp.com/ar/docs/getting-started/backup-and-restore/). - يتم التحقق من الإصدارات باستخدام SHA-256 وتوقيع Ed25519 قبل التثبيت. --- # الإعدادات العامة {#general-settings} > **أين في لوحة المشرف:** System › Settings › General (`/settings`). تسرى التغييرات فوراً (ذاكرة تخزين مؤقت لمدة 30 ثانية). تحتوي الصفحة على ثلاثة أقسام. ## العلامة التجارية وعناوين URL {#branding-urls} | الحقل | الغرض | |---|---| | اسم العلامة التجارية (البريد الإلكتروني، الفواتير) | تُعرض في البريد الإلكتروني والفواتير. الشعار والألوان موجودة في [Branding](https://nexcmp.com/ar/docs/customers/branding/) | | اللغة الافتراضية | لغة الزوار الجدد | | رابط تطبيق العملاء | العنوان العام للبوّابة، على سبيل المثال `https://cloud.example.com` | | رابط وحدة التحكم | عنوان خدمة وحدة تحكم الأجهزة الافتراضية | | رابط المشرف | الرابط المستخدم عند "تسجيل الدخول بصفتك" عميل شريك موزع | | رابط وحدة تحكم الشركاء | يُستخدَم في روابط الدعوات، رسائل البريد الخاصة بالموزعين، وإعادة التوجيه بعد تعبئة الرصيد | يملأ معالج الإعداد هذه الحقول تلقائياً بناءً على نطاقك؛ لا تغيّرها إلا إذا قمت بنقل البوّابة. ## البائع والفوترة {#seller-invoicing} تتم طباعتها على كل فاتورة: | الحقل | مثال | |---|---| | اسم الكيان القانوني | Example Cloud Ltd | | الرقم الضريبي | `TAX-000000` | | العنوان | 1 Example Street, New York | | بريد الاتصال | `billing@example.com` | | بادئة رقم الفاتورة | `INV` (1–8 أحرف، A–Z و 0–9) | تحتفظ الفواتير الحالية بتفاصيل البائع ورقم الإصدار الذي صُدرت به؛ التغييرات تؤثر على الفواتير **الجديدة** فقط. ## الصيانة والمنطقة {#maintenance-region} قم بتفعيل **Customer app MAINTENANCE** لعرض شريط إعلاني و**حظر جميع إجراءات الكتابة الخاصة بالعملاء** بينما تستمر وحدة تحكم المشرف في العمل. أدخل **Maintenance message** التي سيراها العملاء. استخدم هذا أثناء ترقيات البنية التحتية الخاصة بك. ![صفحة الإعدادات العامة مع اسم العلامة التجارية، اللغة الافتراضية وحقول الروابط](https://nexcmp.com/ar/docs/images/administration/general-settings-01-general.webp) ## صفحات إعدادات أخرى {#other-settings-pages} | الصفحة | الدليل | |---|---| | Brand | [Branding](https://nexcmp.com/ar/docs/customers/branding/) | | Legal | [Legal](https://nexcmp.com/ar/docs/customers/legal/) | | Customer logins | [الأمان](https://nexcmp.com/ar/docs/administration/security/) | | Email | [إعدادات SMTP وقوالب البريد الإلكتروني](https://nexcmp.com/ar/docs/administration/smtp-and-emails/) | | Admin alerts | [تنبيهات Telegram والمسؤول](https://nexcmp.com/ar/docs/administration/telegram-notifications/) | | مزود الذكاء الاصطناعي | [مزودو AI](https://nexcmp.com/ar/docs/ai/ai-providers/) | --- # الإبلاغ عن خطأ {#report-a-bug} > **الموقع في لوحة الإدارة:** Top bar › **Report a bug** (بجوار Docs؛ يظهر للمسؤول الرئيسي فقط). هل عثرت على خلل في NexCMP؟ اضغط على **Report a bug** وصف المشكلة ثم أرسلها. يصل التقرير إلى فريق NexCMP كتذكرة عبر حساب ترخيصك في خطوة واحدة — دون الحاجة لتسجيل الدخول في أي مكان آخر أو نسخ ملفات السجل يدوياً. متاحة لجميع الخطط: تشمل NexCMP Free إصلاحات الأخطاء، وكذلك NexCMP Source. ::: info تقارير الأخطاء ليست طلبات دعم فني لا تتضمن NexCMP Free دعماً فنياً، لذا استخدم هذا النموذج للإبلاغ عن عيوب البرمجيات فقط. تتوفر المساعدة في الإعداد وعمليات الترحيل ضمن [NexCMP Source](https://nexcmp.com/pricing). ::: ## المتطلبات {#requirements} | العنصر | المتطلبات | |---|---| | الإصدار | NexCMP 1.5.2 أو أحدث | | من يمكنه الإرسال | حساب المسؤول الرئيسي. لا يمكن لحسابات الموظفين (للقراءة فقط) ولوحات الموزعين والعملاء والنسخة التجريبية المخصصة للقراءة فقط الإرسال | | الترخيص | ترخيص مفعل (Free أو Source) غير معلق | | الشبكة | يجب أن يتمكن الخادم من الوصول إلى `https://nexcmp.com` عبر HTTPS (العنوان نفسه المستخدم للتحقق من الترخيص والتحديثات) | ## إرسال تقرير {#send-a-report} 1. انقر على **Report a bug** في الشريط العلوي. على الهاتف، افتح القائمة واختر **Report a bug**. 2. أدخل **Subject** موجزاً. 3. تحت **What happened**، صف ما قمت به وما ظهر لك والنتيجة المتوقعة. 4. يمكنك اختيارياً سرد **خطوات إعادة إنتاج المشكلة**. 5. اختر **Impact**: **Blocking** (تعطل العمل تماماً)، أو **Major** (تعطل ميزة رئيسية)، أو **Minor** (مشكلة بسيطة أو شكلية). 6. اترك **Attach diagnostics** مفعلاً (موصى به) واطلع على مربع **What will be sent**. 7. انقر على **Send report**. في 1.6.1، يمكن تمرير محتوى النموذج مع بقاء أزرار الإجراءات مرئية، بما في ذلك على الهاتف. تُحجب قيم كلمات المرور التي تلي `password:` أو `password=` دون إزالة بقية التقرير. راجع نصك قبل الإرسال واستبعد بيانات العملاء وبيانات الاعتماد. ![مربع حوار Report a bug مع العنوان والوصف والتأثير وقائمة ما سيتم إرساله](https://nexcmp.com/ar/docs/images/administration/report-a-bug-01-dialog.webp) عند قبول التقرير، يعرض مربع الحوار رقم التذكرة ورابطاً لها. وتصل الردود، حال إرسالها من الفريق، إلى البريد الإلكتروني لحساب ترخيصك على nexcmp.com، كما تُدرج التذكرة تحت **Support** عند تسجيل دخولك هناك بصفتك مالك الترخيص. ## البيانات المرسلة {#what-is-sent} يعرض مربع **What will be sent** هذه التفاصيل بدقة قبل النقر على Send: | البيانات المرسلة | التفاصيل | |---|---| | النص الخاص بك | العنوان والوصف والخطوات ومستوى التأثير | | الإصدار والخطة والنطاق | إصدار NexCMP الخاص بك، وسواء كان Free أو Source، ونطاق التثبيت | | الصفحة الحالية | الصفحة التي تتواجد فيها داخل لوحة الإدارة، دون أي بيانات بعد `?` أو `#` | | المتصفح | نص user-agent لمتصفحك (الاسم والإصدار ونظام التشغيل)، مقتطعاً عند 200 حرف | | الأخطاء الأخيرة | حتى آخر 5 أخطاء في علامة تبويب المتصفح هذه. يقتصر خطأ البرنامج النصي على الرسالة فقط؛ وبالنسبة للطلبات الفاشلة، يتم إرسال الطريقة والمسار ورمز الحالة فقط | يمكنك إيقاف **Attach diagnostics**؛ وعندها لن يُرسل سوى النص الخاص بك والإصدار والخطة والنطاق فقط. ## ما لا يُرسل مطلقاً {#what-is-never-sent} - كلمات المرور والرموز التعريفية وملفات تعريف الارتباط ومفاتيح API. يتم حجب أي بيانات تشبهها في نصك أو في رسائل الخطأ (حيث تظهر كـ `***` أو `[redacted]`) على خادمك قبل إرسال أي شيء. - محتوى الطلبات والاستجابات — تُسجَّل الطلبات الفاشلة كطريقة ومسار وحالة فقط. - بيانات عملائك (الأسماء، والبريد الإلكتروني، والطلبات، والفواتير) وعناوين IP الخاصة بهم. - عنوان IP الخاص بمتصفحك وأي ملف من خادمك. وكما هو الحال مع كل عملية تحقق من الترخيص، يرى خادم الترخيص عنوان IP الذي يتصل منه خادمك. ترتبط التذكرة بنسخة التثبيت الخاصة بك من خلال رمز الترخيص المحفوظ في الخادم بالفعل، لذا تُحدَّد النسخة والنطاق والتثبيت بواسطة الخادم ولا يمكن تغييرها من المتصفح. ## الحدود {#limits} | الحد | القيمة | |---|---| | الموضوع | 150 حرفًا | | الوصف بالإضافة إلى الخطوات | 8 KB إجمالًا | | التقارير | 5 في الساعة و20 في اليوم للتثبيت بالكامل | إرسال التقرير نفسه مرتين (بعد حدوث خطأ في الشبكة على سبيل المثال) لا يُنشئ تذكرة ثانية. ## استكشاف الأخطاء وإصلاحها {#troubleshooting} | الرسالة | السبب | الحل | |---|---|---| | فعّل ترخيصك أولًا | لا يحتوي التثبيت على ترخيص مفعّل | افتح **License & updates** وقم بالتفعيل، ثم أرسل مجددًا | | تعذر الوصول إلى خادم الترخيص | لا يمكن للخادم الوصول إلى `nexcmp.com` | تحقق من اتصالات HTTPS الصادرة ونظام DNS من الخادم، ثم اضغط على **Send report** مجددًا — سيبقى النص كما هو | | عدد كبير جدًا من تقارير الأخطاء من هذا التثبيت | وصلت إلى الحد الأقصى البالغ 5 في الساعة أو 20 في اليوم | انتظر وحاول مرة أخرى؛ أو أضف الملاحظات الجديدة إلى التذكرة المفتوحة بدلًا من ذلك | | هذا الترخيص معلّق | الترخيص معلّق أو تم استرداد مبلغه | راجع [الترخيص والشراء](https://nexcmp.com/ar/docs/getting-started/license-and-purchase/) | | تم إلغاء هذا التثبيت | تم إلغاء التثبيت في بوابة التراخيص | فعّله مجددًا من **License & updates** | | تعذر تحديث رمز الترخيص | تعذر على الخادم تجديد رمز الترخيص الخاص به | افتح **License & updates**، واضغط على **Refresh**، ثم أرسل مجددًا | | زر Report a bug غير موجود | أنت مسجل الدخول بحساب موظف أو موزع أو عميل، أو على النسخة التجريبية للقراءة فقط | سجّل الدخول كمسؤول رئيسي | ::: tip بالنسبة للمساعد الذكي ومفاتيح API لا يمكن للمساعد في لوحة الإدارة أو مفاتيح API الخاصة بالمسؤول إرسال تقارير الأخطاء نيابة عنك: يتطلب الزر تسجيل دخول شخص كمسؤول رئيسي. ::: --- # أخطاء التثبيت {#installation-errors} يتوقف المثبت عند أول مشكلة حرجة ويطبع خطاً أحمر يبدأ بـ `✗`. قم بإصلاح السبب و**شغل نفس الأمر مرة أخرى** — من الآمن تكرار تشغيل المثبت. تبدأ الأسطر الإعلامية بـ `•`، والخطوات الناجحة بـ `✓`. ## فحوصات الجهاز {#machine-checks} | الرسالة | السبب | الحل | |---|---|---| | `must be run as root (sudo)` | لا يتم التشغيل بصلاحيات الجذر (root) | أضف `sudo` قبل الأمر، أو قم بتشغيله بصلاحيات الجذر (root). | | `only Ubuntu 22.04/24.04 is supported (this host: …)` | توزيعة أو إصدار آخر | استخدم خادم Ubuntu 22.04 أو 24.04. | | `only x86_64 is supported` | ARM أو وحدة معالجة مركزية أخرى | استخدم خادم x86_64. | | `requires ≥ 2 GB RAM (host has … MB)` | ذاكرة غيرเพียงية | أضف ذاكرة وصول عشوائي (RAM). | | `requires ≥ 8 GB free disk space on / (… GB available)` | نظام ملفات الجذر ممتلئ تقريباً | حرر مساحة أو قم بتوسيع `/`. | | `missing --license` / `missing --domain` | التثبيت الأول بدون تلك المعلمات | تمرير كلاهما — راجع [Installation](https://nexcmp.com/ar/docs/getting-started/installation/#parameters). | | `unknown argument: …` | خطأ مطبعي في المعلمة | تحقق من الإملاء؛ قم بالتنفيذ باستخدام `--help`. | | `apt-get failed (another apt/dpkg process, e.g. unattended-upgrades, may still be running)` | مدير الحزم مقفل | انتظر بضع دقائق (يقوم نظام Ubuntu الجديد بتشغيل التحديثات التلقائية بعد التمهيد) ثم أعد التشغيل. | | `… is a symlink — aborting` | `/opt/nexcmp` أو `/etc/nexcmp` عبارة عن رابط رمزي | استبدله بدليل حقيقي — يرفض المثبت الروابط الرمزية لأسباب تتعلق بالأمان. | ## تنشيط الترخيص {#license-activation} | الرسالة | السبب | الحل | |---|---|---| | `cannot connect to https://nexcmp.com` | لا توجد اتصالات HTTPS صادرة إلى خادم الترخيص | تحقق من نظام أسماء النطاقات (DNS) والجدار الناري والخادم الوكيل على الخادم: `curl -I https://nexcmp.com`. | | `license activation failed (HTTP …): ` | رفض خادم الترخيص المفتاح | اقرأ الرسالة: مفتاح خاطئ، نطاق غير مطابق للترخيص، ترخيص معلق أو ملغي. تحقق من صفحة الترخيص على [nexcmp.com/licenses](https://nexcmp.com/licenses). | | `no release available for this license yet` | الترخيص ليس له إصدار قابل للتنزيل | اتصل بالمبيعات؛ راجع [Support](https://nexcmp.com/ar/docs/troubleshooting/support/). | ## التنزيل والتحقق {#download-and-verification} | الرسالة | السبب | الحل | |---|---|---| | `failed to download release X` | مشكلة في الشبكة أثناء التنزيل | أعد التشغيل. | | `sha256 mismatch (… ≠ …)` | وصل الملف تالفاً أو تم تعديله | أعد التشغيل؛ إذا تكرر ذلك، فقد يقوم خادم وكيل بإعادة كتابة التنزيلات — جرب من شبكة أخرى. | | `release X is unsigned — refusing to install` | لم يقدم الخادم أي توقيع | لا تتخطي أبداً؛ اتصل بالدعم. | | `INVALID SIGNATURE for version X — aborting` | توقيع Ed25519 لا يتم التحقق منه | لا تقم بالتثبيت **أبداً**. اتصل بالدعم — هذا يعني أن الملف ليس إصداراً رسمياً. | | `openssl failed to read public key` | OpenSSL قديم جداً أو معطل | قم بتحديث حزمة `openssl`. | | `invalid version: …` | بيانات غير متوقعة من الخادم | أعد التشغيل؛ اتصل بالدعم إذا استمرت المشكلة. | ## بدء الخدمة {#service-start} | الرسالة | السبب | الحل | |---|---|---| | `service failed to start — check: journalctl -u nexcmp -n 50` | لم ترد اللوحة على `/healthz` خلال 3 دقائق | اقرأ السجل. الأسباب الشائعة: المنفذ (الافتراضي 3000) قيد الاستخدام بالفعل (`ss -ltnp | grep 3000`) — أعد التثبيت باستخدام `--port`؛ الملفات مملوكة لـ root في `/var/lib/nexcmp` — قم بتشغيل `sudo nexcmp fix-owner`. | ## nginx و TLS {#nginx-and-tls} | الرسالة | السبب | الحل | |---|---|---| | `DNS does not point to (nor to Cloudflare) — skipping nginx/TLS` | سجل A/AAAA مفقود أو خاطئ | راجع [DNS and Cloudflare](https://nexcmp.com/ar/docs/getting-started/dns-and-cloudflare/)، ثم أعد التشغيل. | | `certbot could not get a certificate yet — re-run the installer once DNS has settled` | فشل التحقق من Let's Encrypt (المنفذ 80 محظور، لم ينتشر نظام أسماء النطاقات، حد المعدل) | افتح المنفذ 80، وانتظر انتشار نظام أسماء النطاقات، وأعد التشغيل. تحقق من `/var/log/letsencrypt/letsencrypt.log`. | | `certbot could not renew now — keeping the existing certificate` | فشل التجديد المؤقت | غير ضار؛ أعد التشغيل لاحقاً. | | `nginx rejected the HTTPS configuration — kept the previous one (check: nginx -t)` | يتعارض موقع nginx آخر (نفس `server_name`، إعدادات مكررة) | قم بتشغيل `sudo nginx -t` وإصلاح التعارض، ثم أعد التشغيل. | | `apt-get could not install nginx` / `certbot`، أو `E: Failed to fetch … 404 Not Found` | مدير الحزم مقفل، أو أن فهرس حزم الخادم قديم (يحدث عادةً في صور القوالب التي لم يتم تحديثها منذ فترة) | قم بتشغيل `sudo apt-get update`، وانتظر حتى تنتهي أي عملية apt أخرى، ثم أعد تشغيل مثبت البرنامج. | | `openssl could not create the self-signed certificate` | مشكلة في OpenSSL | قم بتحديث `openssl`؛ ثم أعد التشغيل. | ## بعد التثبيت {#after-installation} | العَرَض | السبب | الحل | |---|---|---| | لا يمكن للمتصفح فتح `https://` | نظام الأسماء النطاقية (DNS) أو شهادة TLS غير جاهزة | `sudo nexcmp status`؛ استخدم [emergency access](https://nexcmp.com/ar/docs/getting-started/cli-reference/#emergency-access). | | `ERR_TOO_MANY_REDIRECTS` | وضع SSL في Cloudflare هو **Flexible** | قم بتعيين **Full (strict)** — [details](https://nexcmp.com/ar/docs/getting-started/dns-and-cloudflare/). | | يظهر المعالج رسالة تفيد بأن "setup code" غير صحيح | خطأ مطبعي أو استخدام رمز من عملية تثبيت سابقة | قم بتشغيل `sudo nexcmp status` وانسخ الرمز الحالي. | | تظهر الرخصة HTTP 421 | الملفات الموجودة في `/var/lib/nexcmp` مملوكة للمستخدم root | `sudo nexcmp fix-owner`، ثم `sudo systemctl restart nexcmp`. | --- # أخطاء التحديث {#update-errors} > **المسار في لوحة الإدارة:** System › Admin › License & updates (`/license`) تم وصف التحديثات في [Updating NexCMP](https://nexcmp.com/ar/docs/getting-started/updating/). عندما تبلغ بطاقة التحديث أو `sudo nexcmp update` عن خطأ: | الرسالة | السبب | الحل | |---|---|---| | `update plan expired — renew on the license page to receive this feature release` | تاريخ "updates until" الخاص بك يسبق تاريخ الإصدار. لا تزال إصلاحات الأمان متوفرة، بينما إصدارات الميزات غير متوفرة | قم بالتجديد على [nexcmp.com/licenses](https://nexcmp.com/licenses) (مقابل $99 سنوياً لـ NexCMP Free)، ثم تحقق مرة أخرى. يستمر البرنامج في العمل في هذه الأثناء. | | `sha256 mismatch (downloaded …, expected …)` | تنزيل تالف أو تم تعديله | أعد المحاولة. إذا تكرر الأمر، تحقق من الوكلاء (proxies) على المسار. | | `downgrade/same version rejected: X is not newer than Y` | الإصدار المحدد ليس أحدث من الإصدار قيد التشغيل | لا توجد إجراءات مطلوبة — أنت تستخدم أحدث إصدار. | | `extraction failed / main binary missing` | أرشيف تالف أو امتلاء القرص | تحقق من `df -h`؛ ثم أعد المحاولة. | | `systemctl restart failed` | تعذر إعادة تشغيل الخدمة بعد استبدال الملف الثنائي | `journalctl -u nexcmp -n 80`؛ يتم الاحتفاظ بالملف الثنائي السابق باسم `/opt/nexcmp/bin/nexcmp.bak` — راجع قسم التراجع (roll back) أدناه. | | خطأ في الخادم أثناء الاتصال بخادم التحديث | لا يوجد مسار للوصول إلى `nexcmp.com` أو انتهت صلاحية رمز الترخيص | تحقق من اتصال HTTPS الخارجي؛ وانقر على **Check now** في بطاقة الترخيص. | ## التراجع {#roll-back} إذا كان الإصدار الجديد يتصرف بشكل غير مألوف: ```bash sudo systemctl stop nexcmp-vmd nexcmp sudo cp /opt/nexcmp/bin/nexcmp.bak /opt/nexcmp/bin/nexcmp echo | sudo tee /opt/nexcmp/VERSION sudo systemctl start nexcmp nexcmp-vmd ``` إذا تم تشغيل ترحيل قاعدة البيانات بالفعل، قم استعادة [backup](https://nexcmp.com/ar/docs/getting-started/backup-and-restore/) الخاص بك الذي تم اخذه قبل التحديث أيضاً. ## `sudo nexcmp update` يقول إنه لا يمكنه العثور على المثبت {#sudo-nexcmp-update-says-it-cannot-find-the-installer} يقوم `nexcmp update` بتشغيل المثبت الموجود داخل الإصدار المثبت (`/opt/nexcmp/releases//share/install.sh`). إذا كان هذا الملف مفقوداً، قم بتشغيل أمر التثبيت من صفحة الترخيص الخاصة بك مرة أخرى. --- # الأسئلة الشائعة {#faq} ## الترخيص {#licensing} **ماذا يحدث إذا انتهت صلاحية رخصتي أو فقد الخادم الاتصال بالإنترنت؟** يظل الرمز صالحاً لمدة 14 يوماً ويتم تجديده يومياً. بعد ذلك، لا يمكن للعملاء إنشاء خدمات **جديدة**؛ بينما تظل الخدمات قيد التشغيل، والفوترة، وعمليات تسجيل الدخول تعمل بشكل طبيعي. راجع [License and purchase](https://nexcmp.com/ar/docs/getting-started/license-and-purchase/). **هل ما زلت أتحصل على إصلاحات الأمان بعد انتهاء فترة استحقاق التحديثات الخاصة بي؟** نعم — يتم توفير إصدارات الأمان دائماً؛ بينما تتطلب إصدارات الميزات استحقاقاً نشطاً. **Can I run NexCMP on a second server or domain?** قم بتفعيله باستخدام المفتاح والنطاق المسجل على الرخصة — راجع [License and purchase](https://nexcmp.com/ar/docs/getting-started/license-and-purchase/#moving-to-a-new-server-or-domain). ## التثبيت {#installation} **Does NexCMP need Docker, PostgreSQL or Redis?** لا. إنه برنامج واحد بقواعد بيانات SQLite، يتم تشغيله بواسطة systemd كمستخدم غير ممتاز. راجع [Requirements](https://nexcmp.com/ar/docs/getting-started/requirements/). **Can I install without a public domain?** نعم، استخدم `--no-nginx` ونفق SSH — راجع [Installation](https://nexcmp.com/ar/docs/getting-started/installation/#installing-without-a-public-domain-lab-or-test). **Why is port 3000 closed after setup?** لأسباب تتعلق بالأمان، تستمع اللوحة على `127.0.0.1` بمجرد انتهاء معالج الإعداد وتفعيل TLS. استخدم `sudo nexcmp open-port` للحالات الطارئة. ## البنية التحتية {#infrastructure} **Can I use CloudStack and Proxmox VE together?** نعم. يمكن أن تحتوي المنطقة على كليهما؛ وتختار كل خطة مصدرها. راجع [Proxmox VE](https://nexcmp.com/ar/docs/infrastructure/proxmox/) و [Zones](https://nexcmp.com/ar/docs/infrastructure/zones/). **Do I need the ROOT API key of CloudStack?** لا — ويجب ألا تستخدمه. أنشئ حساباً مخصصاً — [CloudStack](https://nexcmp.com/ar/docs/infrastructure/cloudstack/). **Why do some tabs or buttons not appear on a virtual machine?** تعرض الصفحات فقط ما يدعمه مصدر الجهاز الافتراضي (على سبيل المثال، لا يحتوي Proxmox VE على إعادة توجيه المنافذ). راجع جدول الإمكانيات في [Proxmox VE](https://nexcmp.com/ar/docs/infrastructure/proxmox/). ## العمليات {#operations} **How do I move NexCMP to another server?** قم بعمل نسخة احتياطية، وثبت نفس الإصدار على الخادم الجديد بنفس الرخصة، ثم استعن بالنسخة — راجع [Backup and restore](https://nexcmp.com/ar/docs/getting-started/backup-and-restore/). **Where are the logs?** `journalctl -u nexcmp -u nexcmp-vmd`، `/var/log/nexcmp`، ووحدة تحكم المسؤول ضمن System › Logs. راجع [Audit log](https://nexcmp.com/ar/docs/administration/audit-log/). **هل يمكنني الاطلاع على بوابة العملاء قبل التثبيت؟** نعم. تعرض صفحات الخدمات على [nexcmp.com](https://nexcmp.com/platform/) بوابة العملاء تبويباً تلو الآخر مع بيانات تجريبية؛ افتح *View demo* للعرض بملء الشاشة. لمشاهدة تثبيت فعلي، راسل المبيعات. --- # الدعم {#support} ## الاتصال {#contact} لا يوجد نموذج اتصال. أرسل بريداً إلكترونياً إلى **sales@nexcmp.com** — وهو يغطي الترخيص، والتجديدات، والنطاقات، والأسئلة التقنية. توفر صفحة ترخيصك على [nexcmp.com/licenses](https://nexcmp.com/licenses) رابطاً إلى نفس العنوان أيضاً. ## قبل أن تكتب {#before-you-write} 1. ابحث في هذه المستندات (اضغط على `/`) وتحقق من [Installation errors](https://nexcmp.com/ar/docs/troubleshooting/installation-errors/) و [Update errors](https://nexcmp.com/ar/docs/troubleshooting/update-errors/). 2. اجمع الحقائق أدناه — فهي تتيح للدعم الإجابة في رد واحد. ## ما يجب تضمينه {#what-to-include} | العنصر | كيفية الحصول عليه | |---|---| | إصدار NexCMP | `sudo nexcmp status` أو System › Admin › License & updates | | النطاق الرئيسي وآخر 4 أحرف من مفتاح الترخيص | License & updates (لا ترسل المفتاح الكامل أبداً) | | ما قمت به وما كنت تتوقعه | الخطوات الدقيقة | | نص الخطأ أو لقطة شاشة | أخفِ البيانات السرية قبل الإرسال | | حالة الخدمة | `sudo nexcmp status` | | أسطر السجل الأخيرة | `sudo journalctl -u nexcmp -u nexcmp-vmd -n 100 --no-pager` | | البنية التحتية | إصدار CloudStack أو Proxmox VE، منطقة واحدة أو عدة مناطق | ::: warning لا ترسل أي معلومات سرية أبداً لا ترسل مفاتيح الترخيص، أو مفاتيح API، أو كلمات المرور، أو رمز الإعداد، أو بيانات اعتماد الدفع، أو أرشيفات النسخ الاحتياطي. قم بإخفائها في السجلات ولقطات الشاشة. ::: ## تقارير الأمان {#security-reports} إذا كنت تعتقد أنك عثرت على ثغرة أمنية، فأرسل بريداً إلكترونياً إلى نفس العنوان مع كتابة "Security" في موضوع الرسالة وتجنب نشر التفاصيل علناً حتى يتم إصلاحها.