--- title: Configuration as code description: Exportez votre configuration en YAML, prévisualisez et appliquez avec nexcmp config ; les secrets sont exclus et validés par le schéma JSON. url: https://nexcmp.com/fr/docs/configure-with-ai/config-as-code/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # Configuration as code {#configuration-as-code} > **Où dans l'administration :** System › Settings › Import/Export (`/agent/config`). Sur le serveur : les commandes `nexcmp config export`, `plan` et `apply`, ainsi que `nexcmp admin `. ## Description {#what-it-does} La configuration de votre panel (image de marque, paramètres généraux, e-mails, alertes Telegram, modules, devise, passerelles de paiement, limites, zones, offres, fournisseur AI et pages légales) peut être sauvegardée sous forme de fichier YAML unique. Vous pouvez modifier ce fichier vous-même, demander à un assistant AI de le modifier, le conserver dans un système de contrôle de version et l'appliquer au même panel ou à un autre. Avant toute modification, une liste des différences s'affiche toujours. Les secrets ne sont jamais écrits dans le fichier. Utilisez-le pour cloner une configuration vers une seconde installation, examiner les modifications avant qu'elles ne soient effectives, restaurer des paramètres après une erreur ou laisser l'AI proposer une configuration complète que vous lisez comme un document unique. ## Prérequis {#requirements} | Élément | Prérequis | |---|---| | NexCMP | 1.4.0 ou supérieur. | | Ligne de commande | Vous êtes `root` sur le serveur du panel (utilisez `sudo`). La commande demande d'elle-même au panel une clé temporaire (15 minutes, toutes les portées). Pour utiliser à la place une clé plus restreinte, définissez `NEXCMP_KEY` sur une [admin API key](https://nexcmp.com/fr/docs/configure-with-ai/admin-api-keys/) et conservez-la via sudo, par exemple `sudo --preserve-env=NEXCMP_KEY nexcmp config plan -f nexcmp.yaml`. | | Page d'administration | Connecté en tant qu'administrateur. La page est en lecture seule sur un panel de démonstration. | | Secrets | Valeurs fournies au moment de l'application (voir [Secrets](#secrets)) ; jamais à l'intérieur du fichier. | ## Exporter, modifier, prévisualiser, appliquer {#export-edit-preview-apply} 1. Exporter la configuration actuelle : ```bash sudo nexcmp config export -o nexcmp.yaml ``` Sans `-o`, le code YAML est affiché à l'écran. 2. Modifier `nexcmp.yaml` (voir l'[exemple](#example-file) ci-dessous). Conserver `version: 1` en haut. 3. Prévisualiser les modifications potentielles. Cela ne modifie rien : ```bash sudo nexcmp config plan -f nexcmp.yaml ``` Chaque ligne indique la section, l'élément, le champ et `old → new`. Les lignes marquées `$` appartiennent aux sections de facturation (voir [Billing sections](#billing-sections)). Si le panel correspond déjà au fichier, vous voyez "No changes". 4. Appliquer. Sans `--yes`, la commande est une **simulation** (dry run) et affiche uniquement la même liste : ```bash sudo nexcmp config apply -f nexcmp.yaml --yes ``` 5. Lire le résultat : `applied`, `pending` (en attente de votre confirmation), `skipped` et `errors`. | Option | Description | |---|---| | `-f ` | Le fichier YAML (requis pour `plan` et `apply`). | | `--yes` | Appliquer réellement. Sans cette option, `apply` est une simulation. | | `--confirm-billing` | Appliquer également les sections de facturation (`payments`, `currency`, `plans`). Sans cette option, elles sont ignorées. | | `--section ` | Appliquer uniquement cette section. Répéter l'option pour en appliquer plusieurs. | | `-o ` | Avec `export` : écrire le YAML dans un fichier. | Le code de retour est 0 lorsque tout a été appliqué ou qu'aucun changement n'a eu lieu, 1 lorsqu'une erreur a été renvoyée, et 2 en cas d'erreur d'utilisation ou de clé. ### Secrets {#secrets} Le fichier contient des références au lieu de secrets, telles que `password: secret://smtp_password`. Lors de l'application, la valeur provient d'une variable d'environnement nommée `NEXCMP_SECRET_` suivie du nom de la référence en majuscules : ```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 ``` Si une référence n'a pas de valeur, le secret déjà enregistré dans le panel est **conservé**. Un secret qui n'a jamais été enregistré et n'est pas fourni reste vide. | Nom de la référence | Emplacement de destination | |---|---| | `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` | ## Exemple de fichier {#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). ``` Un fichier peut contenir un sous-ensemble quelconque de sections. Une section omise n'est pas modifiée. Un fichier supérieur à 1 Mo, un élément `version: 1` manquant, un numéro de version différent ou une section inconnue est rejeté avant toute exécution. ## Sections {#sections} | Section | Éléments contrôlés | Remarques | |---|---|---| | `branding` | Nom de la marque (jusqu'à 60 caractères), couleur principale, devise d'affichage (`usd` ou `vnd`), nom du vendeur. | Les logos ne font pas partie du fichier ; utilisez la [branding page](https://nexcmp.com/fr/docs/customers/branding/). | | `settings` | Une liste fixe de paramètres généraux : `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`. | Les autres clés sont ignorées. | | `email.smtp` | Hôte SMTP, port, sécurité (`starttls`, `tls`, `none`), utilisateur, mot de passe, nom et adresse de l'expéditeur, adresse de réponse. | [SMTP et e-mail templates](https://nexcmp.com/fr/docs/administration/smtp-and-emails/). La modification de l'hôte, du port ou de la sécurité nécessite de saisir à nouveau le mot de passe. | | `telegram` | Canal d'alerte activé ou désactivé, ID de chat, jeton du bot. | [Notifications Telegram](https://nexcmp.com/fr/docs/administration/telegram-notifications/). | | `modules` | Modules optionnels activés ou désactivés (`key: true/false`). | Seules les clés que le panneau permet de basculer. Voir [Modules](https://nexcmp.com/fr/docs/infrastructure/modules/). | | `currency` | Devise d'affichage et taux USD vers VND manuel (`0` automatique, sinon 15000 à 50000). | Section de facturation. Voir [Devise et taux de change](https://nexcmp.com/fr/docs/catalog/currency-and-exchange-rates/). | | `payments` | Identifiants `stripe`, `paypal`, `crypto`, `bank` et commutateurs `channels` (`pay_card_enabled`, `pay_wallets_enabled`, `pay_alipay_enabled`, `pay_paypal_enabled`, `pay_usdt_enabled`, `pay_sepay_enabled`). | Section de facturation. Voir [Canaux de paiement](https://nexcmp.com/fr/docs/billing/payment-channels/). | | `quotas` | Limites `quota_*`. | Voir [Quotas](https://nexcmp.com/fr/docs/billing/quotas/). | | `zones` | Zones par `slug` (requis : `slug`, `name`, `country` ; optionnel : `city`, `enabled`, `is_default`). | De nouvelles zones sont créées. Une zone existante n'est **pas modifiée** par le fichier. Voir [Zones](https://nexcmp.com/fr/docs/infrastructure/zones/). | | `plans` | Plans par `slug` (requis : `slug`, `name`, `cpu`, `ram_mb`, `disk_gb`, `hourly_usd` ; optionnel : `cs_offering_id`, `backend_id`, `zone_id`, `enabled`, `visible`, `sort`, `description`). | Section de facturation. De nouveaux plans sont créés, les existants sont mis à jour par leur slug. Les prix sont en USD par heure. Voir [Plans](https://nexcmp.com/fr/docs/catalog/plans/). | | `ai_provider` | Le fournisseur d'IA du panneau utilisé pour l'AI Chat client et l'AI Agent. | [AI provider](https://nexcmp.com/fr/docs/ai/ai-providers/). | | `legal` | Texte des conditions et de la confidentialité par langue (`en`, `vi`). | [Pages légales](https://nexcmp.com/fr/docs/customers/legal/). | L'ordre d'application est l'ordre ci-dessus : les éléments liés à l'infrastructure avant les plans. ## Règles à retenir {#rules-to-remember} - **Idempotent.** Appliquer le même fichier deux fois ne change rien la seconde fois. `plan` affiche "No changes". - **Aucune suppression.** Le fichier ne supprime jamais de zone, de plan ou de paramètre. Retirer une entrée du fichier laisse le panneau tel quel. - **Les règles de sécurité normales s'appliquent toujours.** En ligne de commande, chaque modification passe par les mêmes vérifications qu'un changement d'API : portées et règles IP. Une modification nécessitant une confirmation (un commutateur global, par exemple) est signalée sous `pending` avec un aperçu au lieu d'être appliquée, sauf si vous passez `--confirm-billing`, ce qui les confirme toutes. - **Les clients IA ne peuvent pas déverrouiller la facturation.** Lorsque `config_apply` est appelé par un client MCP, `confirm_billing` est ignoré ; les modifications financières attendent votre intervention. - **Vérifiez avant d'appliquer.** Le schéma JSON décrit chaque champ. Pointez votre éditeur dessus ou fournissez-le à une IA pour qu'elle écrive un YAML valide : `https://cloud.example.com/v1/admin/agent/config/schema.json` (accessible publiquement). ### Sections de facturation {#billing-sections} `payments`, `currency` et `plans` modifient les prix ou les flux financiers. `nexcmp config apply --yes` les **ignore** sauf si vous ajoutez `--confirm-billing` ; elles sont alors listées sous `skipped` ("billing section - pass confirm_billing"). L'indicateur sert de confirmation : avec lui, chaque modification de facturation dans le fichier (et tout autre changement nécessitant une confirmation) est appliquée sans second prompt. Exécutez d'abord `plan` et lisez chaque ligne marquée `$`. Lorsque le même fichier est appliqué par une IA (l'outil `config_apply` dans un client MCP ou AI Chat), l'indicateur est ignoré et les mouvements d'argent attendent plutôt votre approbation. ## Utiliser la page Import/Export {#use-the-import-export-page} 1. Ouvrez **System › Settings › Import/Export**. 2. Sous **Export**, cliquez sur **Get current configuration**, puis sur **Download .yaml** pour enregistrer `nexcmp.yaml`. Les secrets apparaissent sous forme de texte fictif. 3. Sous **Import**, choisissez un fichier, glissez-le dans la zone ou collez le YAML. 4. Facultatif : ouvrez **Secrets that come with it (not in the file)** et ajoutez un nom et une valeur pour chaque référence, par exemple `smtp_password`. 5. Cliquez sur **Preview changes**. Le tableau groupe les modifications par section ; les sections liées à l'argent comportent un tag "Money-related". Décochez les sections dont vous ne voulez pas. 6. Si des sections liées aux finances sont répertoriées, cochez **Also apply money-related changes (prices, payment gateways, balances)**. Sans cette coche, elles sont ignorées. 7. Cliquez sur **Apply selected**. Le résultat indique ce qui a été appliqué, ignoré ou a échoué. Une modification renvoyée comme étant en attente de confirmation apparaît sous forme de carte de confirmation ; cliquez sur **Confirm** sur celle-ci. Le bouton **JSON Schema** en haut à droite ouvre le schéma. ![Page d'importation/exportation avec la carte Export et la carte Import contenant le code YAML exporté](https://nexcmp.com/fr/docs/images/configure-with-ai/config-as-code-01-import-export.webp) ![Tableau d'aperçu des modifications regroupées par section avec un libellé de facturation et un bouton Apply selected](https://nexcmp.com/fr/docs/images/configure-with-ai/config-as-code-02-preview.webp) ## Exécuter n'importe quel outil depuis la ligne de commande {#run-any-tool-from-the-command-line} `nexcmp admin` exécute les mêmes outils que les assistants IA ([the tool list](https://nexcmp.com/fr/docs/configure-with-ai/mcp-admin/#tools)) et affiche du 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"}}' ``` Les arguments sont des paires `key=value` (les valeurs sont lues comme du JSON si elles s'analysent ainsi, sinon comme du texte) ou un unique objet `--json '{...}'`. Si l'action nécessite une confirmation, la commande affiche l'aperçu et s'arrête avec le code de sortie 3 et "Nothing changed". Lisez l'aperçu, puis réexécutez la même commande avec `--yes` pour l'appliquer. Exécutée en tant que root, la commande obtient une clé de 15 minutes avec toutes les permissions, l'étape de confirmation constitue donc votre garde-fou ; avec `NEXCMP_KEY`, les propres permissions de la clé s'appliquent. ## Vérification {#verify} 1. `sudo nexcmp config plan -f nexcmp.yaml` juste après un `apply --yes` affiche "No changes". 2. Dans l'administration, les pages que vous avez modifiées affichent les nouvelles valeurs, et **Logs › Admin actions** répertorie les modifications. 3. Appliquer à nouveau le même fichier ne change rien. ## Limites et notes {#limits-notes} - Le fichier couvre les paramètres ci-dessus, et non les clients, serveurs, factures ou sources d'infrastructure (connexions CloudStack et Proxmox). Connectez-les à l'aide de [AI Chat](https://nexcmp.com/fr/docs/configure-with-ai/ai-chat-in-admin/) ou des pages d'administration. - Les zones et les plans sont mis làmatch par `slug`. Ne renommez pas un slug dans le fichier : il serait créé comme un nouvel élément. - Un plan déjà utilisé par des clients ne peut pas modifier sa taille ; créez plutôt un nouveau plan. - Gardez les fichiers exportés confidentiels même s'ils ne contiennent aucun secret : ils répertorient vos prix, adresses et noms de compte. ## Dépannage {#troubleshooting} | Symptôme | Cause | Solution | |---|---|---| | `missing version: 1` | Le fichier ne commence pas par `version: 1` | Ajoutez-le. | | `unsupported version 2` | Le fichier a un autre numéro de version | Ce panneau lit uniquement la version 1. | | `unknown section 'x' (known: ...)` | Une clé de niveau supérieur mal orthographiée ou non prise en charge | Utilisez les sections ci-dessus. | | `YAML error: ...` | YAML invalide (indiçage, tabulations) | Corrigez la ligne mentionnée par le message. | | `config is larger than 1 MB` | Fichier trop volumineux | Divisez-le et utilisez `--section`. | | `no API key: set NEXCMP_KEY=ak_... or run as root on the server` | La commande n'a trouvé aucune clé | Exécutez avec `sudo`, ou exportez `NEXCMP_KEY` et conservez-le via sudo. | | `panel not reachable` | Le service du panneau ne s'exécute pas sur le port par défaut | Vérifiez `sudo nexcmp status`. | | Lignes de facturation sous `skipped` | Les sections de facturation nécessitent `--confirm-billing` | Ajoutez l'indicateur et examinez d'abord les lignes `$`. | | Éléments sous `pending` | La modification nécessite une confirmation | Ouvrez **API & AI agents**, ou le résultat de l'importation/exportation, et appuyez sur **Confirm** sur la carte. | | Un secret n'a pas été mis à jour | Aucune valeur `NEXCMP_SECRET_` n'a été définie, le secret enregistré a donc été conservé | Exportez la variable et appliquez-la à nouveau. | | Entrée sous `errors` avec HTTP 403 `insufficient_scope` | La clé n'a pas la permission pour cette section | Utilisez une clé disposant de la permission, ou exécutez en tant que root. | | Entrée sous `errors` avec HTTP 403 `demo_read_only` | Panneau de démo | Appliquer sur une vraie installation. |