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 <tool>.

Description

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

É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 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) ; jamais à l'intérieur du fichier.

Exporter, modifier, prévisualiser, appliquer

1. Exporter la configuration actuelle :

   sudo nexcmp config export -o nexcmp.yaml

   Sans -o, le code YAML est affiché à l'écran.

2. Modifier nexcmp.yaml (voir l'exemple ci-dessous). Conserver version: 1 en haut.

3. Prévisualiser les modifications potentielles. Cela ne modifie rien :

   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). 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 :

   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 <file>	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 <name>	Appliquer uniquement cette section. Répéter l'option pour en appliquer plusieurs.
-o <file>	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

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 :

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

# 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

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.
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. 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.
modules	Modules optionnels activés ou désactivés (key: true/false).	Seules les clés que le panneau permet de basculer. Voir 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.
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.
quotas	Limites quota_*.	Voir 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.
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.
ai_provider	Le fournisseur d'IA du panneau utilisé pour l'AI Chat client et l'AI Agent.	AI provider.
legal	Texte des conditions et de la confidentialité par langue (en, vi).	Pages légales.

L'ordre d'application est l'ordre ci-dessus : les éléments liés à l'infrastructure avant les plans.

Règles à retenir

• 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

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

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.

Exécuter n'importe quel outil depuis la ligne de commande

nexcmp admin exécute les mêmes outils que les assistants IA (the tool list) et affiche du JSON :

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

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

• 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 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

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_<NAME> 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.