التكوين كشفرة برمجية

أين تجد ذلك في لوحة المشرف: System › Settings › Import/Export (/agent/config). على الخادم: الأمر nexcmp config export و plan و apply و nexcmp admin <tool>.

الوظيفة

يمكن حفظ تكوين لوحة التحكم الخاصة بك (العلامة التجارية، الإعدادات العامة، البريد الإلكتروني، تنبيهات تيليجرام، الوحدات، العملة، بوابات الدفع، الحدود، المناطق، الخطط، موزع الذكاء الاصطناعي والصفحات القانونية) كملف YAML واحد. يمكنك تحرير الملف بنفسك، أو طلب مساعد ذكاء اصطناعي لتعديله، أو الاحتفاظ به في نظام التحكم بالإصدار، وتطبيقه على نفس اللوحة أو لوحة أخرى. يمكنك دائماً رؤية قائمة التغييرات قبل حدوث أي شيء. ولا يتم كتابة الأسرار في الملف مطلقا.

استخدمه لاستنسخ إعدادات إلى تثبيت ثانٍ، أو لمراجعة التغييرات قبل طرحها مباشرة، أو لاستعادة الإعدادات بعد ارتكاب خطأ، أو للسماح للذكاء الاصطناعي باقتراح تكوين كامل تقرأه كمستند واحد.

المتطلبات

العنصر	المتطلب
NexCMP	1.4.0 أو أحدث.
سطر الأوامر	أنت `root` على خادم لوحة التحكم (استخدم `sudo`). يطلب الأمر من لوحة التحكم مفتاحاً مؤقتاً (15 دقيقة، لكافة النطاقات) من تلقاء نفسه. لاستخدام مفتاح أضيق نطاقاً بدلاً من ذلك، قم بتعيين `NEXCMP_KEY` إلى admin API key واحتفظ به عبر sudo، على سبيل المثال `sudo --preserve-env=NEXCMP_KEY nexcmp config plan -f nexcmp.yaml`.
صفحة المشرف	تم تسجيل الدخول بصفتك مشرفاً. هذه الصفحة للقراءة فقط على لوحة تجريبية.
Secrets	القيم المقدمة وقت التطبيق (انظر Secrets)؛ وليست موجودة داخل الملف أبداً.

تصدير، تعديل، معاينة، تطبيق

تصدير التكوين الحالي:
bash
```
sudo nexcmp config export -o nexcmp.yaml
```
بدون -o، تتم طباعة ملف YAML على الشاشة.
قم بتعديل nexcmp.yaml (راجع example أدناه). حافظ على version: 1 في الأعلى.
معاينة ما سيتم تغييره. لا يؤدي هذا إلى تغيير أي شيء:
bash
```
sudo nexcmp config plan -f nexcmp.yaml
```
يعرض كل سطر القسم والعنصر والحقل و old → new. تنتمي الأسطر التي تحمل العلامة $ إلى أقسام الفوترة (انظر Billing sections). إذا كانت لوحة التحكم تتطابق بالفعل مع الملف، سترى "No changes".
تطبيق. بدون --yes، يكون الأمر تشغيلاً تجريبياً (dry run) ويطبع القائمة نفسها فقط:
bash
```
sudo nexcmp config apply -f nexcmp.yaml --yes
```
قراءة النتيجة: applied، و pending (في انتظار تأكيدك)، و skipped، و errors.

الخيار	المعنى
`-f <file>`	ملف YAML (مطلوب لـ `plan` و `apply`).
`--yes`	التطبيق الفعلي. بدونه، يكون `apply` تشغيلاً تجريبياً.
`--confirm-billing`	تطبيق أقسام الفوترة أيضاً (`payments`، `currency`، `plans`). بدون ذلك يتم تخطيها.
`--section <name>`	تطبيق هذا القسم فقط. كرر الخيار لعدة أقسام.
`-o <file>`	مع `export`: كتابة ملف YAML في ملف.

رمز الخروج هو 0 عند تطبيق كل شيء أو عدم تغير شيء، و1 عند إرجاع خطأ، و2 في حالة وجود خطأ في الاستخدام أو المفتاح.

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`

ملف تجريبي

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، أو اختلاف رقم الإصدار، أو وجود قسم غير معروف قبل تشغيل أي شيء.

الأقسام

القسم	ما تتحكم فيه	ملاحظات
`branding`	اسم العلامة التجارية (حتى 60 حرفاً)، اللون الأساسي، عملة العرض (`usd` أو `vnd`)، اسم البائع.	الشعارات ليست جزءاً من الملف؛ استخدم صفحة العلامة التجارية.
`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 والبريد الإلكتروني. يتطلب تغيير المضيف أو المنفذ أو الأمان إعادة إدخال كلمة المرور.
`telegram`	قناة التنبيه مفعلة أو معطلة، معرف الدردشة، رميز البوت.	إشعارات تيليجرام.
`modules`	الوحدات الإضافية مفعلة أو معطلة (`key: true/false`).	فقط المفاتيح التي تتيح لك اللوحة تبديلها. راجع الوحدات.
`currency`	عملة العرض ومعدل يدوي من USD إلى VND (`0` تلقائي، وإلا من 15000 إلى 50000).	قسم الفوترة. راجع العملة ومسارات الصرف.
`payments`	بيانات اعتماد `stripe`، `paypal`، `crypto`، `bank` ومفاتيح `channels` (`pay_card_enabled`، `pay_wallets_enabled`، `pay_alipay_enabled`، `pay_paypal_enabled`، `pay_usdt_enabled`، `pay_sepay_enabled`).	قسم الفوترة. راجع قنوات الدفع.
`quotas`	حدود `quota_*`.	راجع الحصص.
`zones`	المناطق بواسطة `slug` (مطلوبة: `slug`، `name`، `country`؛ اختيارية `city`، `enabled`، `is_default`).	يتم إنشاء مناطق جديدة. المنطقة الموجودة مسبقاً لا تُعدل بواسطة الملف. راجع المناطق.
`plans`	الخطط بواسطة `slug` (مطلوبة: `slug`، `name`، `cpu`، `ram_mb`، `disk_gb`، `hourly_usd`؛ اختيارية `cs_offering_id`، `backend_id`، `zone_id`، `enabled`، `visible`، `sort`، `description`).	قسم الفوترة. يتم إنشاء خطط جديدة، وتحديث الخطط الحالية عبر الـ slug. الأسعار بالدولار الأمريكي لكل ساعة. راجع الخطط.
`ai_provider`	مزود الذكاء الاصطناعي في اللوحة المستخدم من قِبل AI Chat وAI Agent للعملاء.	AI provider.
`legal`	نصوص الشروط والخصوصية لكل لغة (`en`، `vi`).	الصفحات القانونية.

ترتيب التطبيق هو نفس الترتيب أعلاه: العناصر التي تشبه البنية التحتية قبل الخطط.

قواعد يجب تذكرها

متطابق وظيفياً (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 (قابل للقراءة العامة).

أقسام الفوترة

تؤدي payments، currency وplans إلى تغيير الأسعار أو مسارات الأموال. تتخلى nexcmp config apply --yes عنها ما لم تقم بإضافة --confirm-billing؛ يتم بعد ذلك إدراجها تحت skipped ("billing section - pass confirm_billing"). العلامة هي تأكيدك: معها، يتم تطبيق كل تغيير فوترة في الملف (وأي تغيير آخر يتطلب تأكيداً) دون مطالبة ثانية. قم بتشغيل plan أولاً واقرأ كل سطر محدد بـ $.

عند تطبيق نفس الملف بواسطة ذكاء اصطناعي (أداة config_apply في عميل MCP أو AI Chat)، يتم تجاهل العلامة، وبدلاً من ذلك تنتظر التغييرات المالية موافقتك.

استخدام صفحة الاستيراد/التصدير

افتح System › Settings › Import/Export.
ضمن Export انقر فوق Get current configuration، ثم Download .yaml للحفظ nexcmp.yaml. تظهر البيانات السرية كعناصر نائبة.
ضمن Import اختر ملفاً، أو اسحبه إلى داخل المربع، أو الصق ملف YAML.
اختياري: افتح Secrets that come with it (not in the file) وأضف اسمًا وقيمة لكل مرجع، على سبيل المثال smtp_password.
انقر فوق Preview changes. يعرض الجدول التغييرات مجمعة حسب القسم؛ وتحمل الأقسام المتعلقة بالمال علامة "Money-related". قم إلغاء تحديد الأقسام التي لا ترغب بها.
إذا كانت الأقسام المتعلقة بالمال مدرجة، فحدد Also apply money-related changes (prices, payment gateways, balances). بدون تحديد هذا الخيار، سيتم تخطيها.
انقر فوق Apply selected. توضح النتيجة ما تم تطبيقه أو تخطيه أو فشله. التغيير الذي يتم إرجاعه كمعلق في انتظار التأكيد يظهر بطاقة تأكيد؛ اضغط على Confirm عليها.

زر JSON Schema في الأعلى إلى اليمين يفتح مخطط البيانات.

تشغيل أي أداة من سطر الأوامر

nexcmp admin تشغيل نفس الأدوات الخاصة بمساعدي الذكاء الاصطناعي (قائمة الأدوات) وطباعة بتنسيق 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 تُطبق نطاقات المفتاح الخاصة به.

التحقق

sudo nexcmp config plan -f nexcmp.yaml مباشرة بعد apply --yes تطبع "No changes".
في لوحة الإدارة، تُظهر الصفحات التي قمت بتغييرها القيم الجديدة، وتقوم Logs › Admin actions بإدراج التغييرات.
تطبيق نفس الملف مرة أخرى لا يغير شيئاً.

الحدود والملاحظات

يغطي الملف الإعدادات أعلاه، ولا يغطي العملاء أو الخوادم أو الفواتير أو مصادر البنية التحتية (اتصالات CloudStack و Proxmox). قم بتوصيل تلك عبر AI Chat أو صفحات الإدارة.
يتم مطابقة المناطق والخطط بواسطة slug. لا تقم بإعادة تسمية اسم مختصر (slug) في الملف: سيتم إنشاؤه كعنصر جديد.
الخطة التي يستخدمها العملاء بالفعل لا يمكن تغيير حجمها؛ قم بإنشاء خطة جديدة بدلاً من ذلك.
احتفظ بالملفات المصدرة بشكل خاص حتى وإن كانت لا تحتوي على أسرار: فهي تسرد أسعارك وعناوينك وأسماء حساباتك.

استكشاف الأخطاء وإصلاحها

العَرَض	السبب	الحل
`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_<NAME>`، لذا تم الاحتفاظ بالسر المحفوظ	قم بتصدير المتغير وقم بالتطبيق مرة أخرى.
إخفاء تحت `errors` مع HTTP 403 `insufficient_scope`	يفتقر المفتاح إلى نطاق هذا القسم	استخدم مفتاحاً بالصلاحية، أو قم بالتنفيذ بصلاحيات الجذر (root).
إخفاء تحت `errors` مع HTTP 403 `demo_read_only`	لوحة تجريبية	طبق على تثبيت حقيقي.

التكوين كشفرة برمجية ​

الوظيفة ​

المتطلبات ​

تصدير، تعديل، معاينة، تطبيق ​

Secrets ​

ملف تجريبي ​

الأقسام ​

قواعد يجب تذكرها ​

أقسام الفوترة ​

استخدام صفحة الاستيراد/التصدير ​

تشغيل أي أداة من سطر الأوامر ​

التحقق ​

الحدود والملاحظات ​

استكشاف الأخطاء وإصلاحها ​