--- title: التكوين كشفرة برمجية description: قم بتصدير تكوين لوحة التحكم إلى ملف YAML، واستعرض التغييرات وطبقها باستخدام أمر nexcmp config أو صفحة الاستيراد/التصدير؛ تبقى الأسرار خارج الملف ويتحقق منها مخطط JSON. url: https://nexcmp.com/ar/docs/configure-with-ai/config-as-code/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # التكوين كشفرة برمجية {#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` | لوحة تجريبية | طبق على تثبيت حقيقي. |