---
title: Configurazione come codice
description: Esporta la configurazione in YAML, vedi le modifiche e applicale con nexcmp config o Import/Export; i secret restano esclusi e JSON Schema la valida.
url: https://nexcmp.com/it/docs/configure-with-ai/config-as-code/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Configurazione come codice {#configuration-as-code}

> **Dove nel pannello di amministrazione:** System › Settings › Import/Export (`/agent/config`). Sul server: i comandi `nexcmp config export`, `plan` e `apply`, e `nexcmp admin <tool>`.

## Descrizione {#what-it-does}

La configurazione del tuo pannello (branding, impostazioni generali, email, avvisi Telegram, moduli, valuta, gateway di pagamento, limiti, zone, piani, il provider AI e le pagine legali) può essere salvata come un singolo file YAML. Puoi modificare il file in autonomia, chiedere a un assistente AI di modificarlo, conservarlo nel controllo versione e applicarlo allo stesso o a un altro pannello. Prima che qualsiasi cosa cambi, vedrai sempre un elenco delle differenze. I dati sensibili non vengono mai scritti nel file.

Usalo per clonare una configurazione su una seconda installazione, per verificare le modifiche prima che vadano online, per ripristinare le impostazioni dopo un errore o per fare in modo che un'intelligenza artificiale proponga un'intera configurazione che puoi leggere come un unico documento.

## Requisiti {#requirements}

| Elemento | Requisito |
|---|---|
| NexCMP | 1.4.0 o successivo. |
| Riga di comando | Ti trovi `root` sul server del pannello (usa `sudo`). Il comando richiede autonomamente al pannello una chiave temporanea (15 minuti, tutti gli ambiti). Per usare invece una chiave più ristretta, imposta `NEXCMP_KEY` su una [admin API key](https://nexcmp.com/it/docs/configure-with-ai/admin-api-keys/) e mantienila tramite sudo, ad esempio `sudo --preserve-env=NEXCMP_KEY nexcmp config plan -f nexcmp.yaml`. |
| Pagina di amministrazione | Accesso effettuato come amministratore. La pagina è di sola lettura su un pannello demo. |
| Segreti | Valori forniti al momento dell'applicazione (vedi [Secrets](#secrets)); mai all'interno del file. |

## Esporta, modifica, anteprima, applica {#export-edit-preview-apply}

1. Esporta la configurazione corrente:

   ```bash
   sudo nexcmp config export -o nexcmp.yaml
   ```

   Senza `-o`, il file YAML viene stampato a schermo.
2. Modifica `nexcmp.yaml` (vedi l'[esempio](#example-file) sotto). Mantieni `version: 1` in alto.
3. Visualizza l'anteprima delle modifiche. Questo non modifica nulla:

   ```bash
   sudo nexcmp config plan -f nexcmp.yaml
   ```

   Ogni riga mostra sezione, elemento, campo e `old → new`. Le righe contrassegnate da `$` appartengono alle sezioni di fatturazione (vedi [Billing sections](#billing-sections)). Se il pannello corrisponde già al file, vedrai "No changes".
4. Applica. Senza `--yes` il comando è una **simulazione** (dry run) e stampa solo lo stesso elenco:

   ```bash
   sudo nexcmp config apply -f nexcmp.yaml --yes
   ```

5. Leggi il risultato: `applied`, `pending` (in attesa della tua conferma), `skipped` e `errors`.

| Opzione | Significato |
|---|---|
| `-f <file>` | Il file YAML (obbligatorio per `plan` e `apply`). |
| `--yes` | Applica effettivamente. Senza questa opzione `apply` è una simulazione. |
| `--confirm-billing` | Applica anche le sezioni di fatturazione (`payments`, `currency`, `plans`). Senza questa opzione vengono saltate. |
| `--section <name>` | Applica solo questa sezione. Ripeti l'opzione per più sezioni. |
| `-o <file>` | Con `export`: scrive il file YAML in un file. |

Il codice di uscita è 0 quando tutto è stato applicato o non è cambiato nulla, 1 quando viene restituito un errore, 2 in caso di errore di utilizzo o di chiave.

### Segreti {#secrets}

Il file contiene riferimenti anziché dati sensibili, come `password: secret://smtp_password`. Al momento dell'applicazione, il valore proviene da una variabile d'ambiente denominata `NEXCMP_SECRET_` più il nome del riferimento in maiuscolo:

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

Se un riferimento non ha alcun valore, il dato sensibile già salvato nel pannello viene **mantenuto**. Un dato sensibile mai salvato e non fornito rimane vuoto.

| Nome del riferimento | Dove viene memorizzato |
|---|---|
| `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` |

## File di esempio {#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 file può contenere qualsiasi sottoinsieme delle sezioni. Una sezione omessa non viene modificata. Un file superiore a 1 MB, un `version: 1` mancante, un numero di versione differente o una sezione sconosciuta vengono rifiutati prima di qualsiasi esecuzione.

## Sezioni {#sections}

| Sezione | Cosa controlla | Note |
|---|---|---|
| `branding` | Nome del brand (fino a 60 caratteri), colore primario, valuta di visualizzazione (`usd` o `vnd`), nome del venditore. | I loghi non fanno parte del file; usa la [branding page](https://nexcmp.com/it/docs/customers/branding/). |
| `settings` | Un elenco fisso di impostazioni generali: `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`. | Le altre chiavi vengono ignorate. |
| `email.smtp` | Host SMTP, porta, sicurezza (`starttls`, `tls`, `none`), utente, password, nome e indirizzo del mittente, indirizzo di risposta (reply-to). | [SMTP and e-mail templates](https://nexcmp.com/it/docs/administration/smtp-and-emails/). La modifica di host, porta o sicurezza richiede nuovamente la password. |
| `telegram` | Canale di avviso attivo o disattivato, chat id, bot token. | [Notifiche Telegram](https://nexcmp.com/it/docs/administration/telegram-notifications/). |
| `modules` | Moduli opzionali attivi o disattivati (`key: true/false`). | Solo le chiavi che il pannello permette di attivare. Vedi [Moduli](https://nexcmp.com/it/docs/infrastructure/modules/). |
| `currency` | Valuta di visualizzazione e tasso manuale da USD a VND (`0` automatico, altrimenti da 15000 a 50000). | Sezione di fatturazione. Vedi [Valuta e tassi di cambio](https://nexcmp.com/it/docs/catalog/currency-and-exchange-rates/). |
| `payments` | Credenziali `stripe`, `paypal`, `crypto`, `bank` e interruttori `channels` (`pay_card_enabled`, `pay_wallets_enabled`, `pay_alipay_enabled`, `pay_paypal_enabled`, `pay_usdt_enabled`, `pay_sepay_enabled`). | Sezione di fatturazione. Vedi [Canali di pagamento](https://nexcmp.com/it/docs/billing/payment-channels/). |
| `quotas` | Limiti `quota_*`. | Vedi [Quote](https://nexcmp.com/it/docs/billing/quotas/). |
| `zones` | Zone per `slug` (obbligatori: `slug`, `name`, `country`; opzionali `city`, `enabled`, `is_default`). | Vengono create nuove zone. Una zona già esistente **non viene modificata** dal file. Vedi [Zone](https://nexcmp.com/it/docs/infrastructure/zones/). |
| `plans` | Piani per `slug` (obbligatori: `slug`, `name`, `cpu`, `ram_mb`, `disk_gb`, `hourly_usd`; opzionali `cs_offering_id`, `backend_id`, `zone_id`, `enabled`, `visible`, `sort`, `description`). | Sezione di fatturazione. I nuovi piani vengono creati, quelli esistenti vengono aggiornati tramite slug. I prezzi sono in USD all'ora. Vedi [Piani](https://nexcmp.com/it/docs/catalog/plans/). |
| `ai_provider` | Il provider AI del pannello utilizzato da AI Chat e AI Agent per i clienti. | [AI provider](https://nexcmp.com/it/docs/ai/ai-providers/). |
| `legal` | Testo di termini e privacy per lingua (`en`, `vi`). | [Pagine legali](https://nexcmp.com/it/docs/customers/legal/). |

L'ordine di applicazione è l'ordine precedente: gli elementi simili all'infrastruttura prima dei piani.

## Regole da ricordare {#rules-to-remember}

- **Idempotente.** L'applicazione dello stesso file due volte non cambia nulla la seconda volta. `plan` mostra "No changes".
- **Nessuna eliminazione.** Il file non rimuove mai una zona, un piano o un'impostazione. La rimozione di una voce dal file lascia il pannello così com'è.
- **Le normali regole di sicurezza continuano a valere.** Dalla riga di comando ogni modifica viene sottoposta agli stessi controlli di una modifica API: ambiti e regole IP. Una modifica che richiede conferma (un interruttore globale, ad esempio) viene segnalata in `pending` con un'anteprima invece di essere applicata, a meno che non si passi `--confirm-billing`, che le conferma tutte.
- **GliM client AI non possono sbloccare la fatturazione.** Quando `config_apply` viene chiamato da un client MCP, `confirm_billing` viene ignorato; le modifiche monetarie attendono l'utente.
- **Controlla prima di applicare.** Lo schema JSON descrive ogni campo. Puntaci il tuo editor o consegnalo a un'AI affinché scriva YAML valido: `https://cloud.example.com/v1/admin/agent/config/schema.json` (pubblicamente leggibile).

### Sezioni di fatturazione {#billing-sections}

`payments`, `currency` e `plans` modificano i prezzi o i percorsi del denaro. `nexcmp config apply --yes` **li salva** a meno che non si aggiunga `--confirm-billing`; vengono quindi elencati in `skipped` ("billing section - pass confirm_billing"). Il flag è la tua conferma: con esso, ogni modifica di fatturazione nel file (e qualsiasi altra modifica che richiederebbe una conferma) viene applicata senza un secondo prompt. Esegui prima `plan` e leggi ogni riga contrassegnata con `$`.

Quando lo stesso file viene applicato da un'AI (lo strumento `config_apply` in un client MCP o in AI Chat), il flag viene ignorato e le modifiche monetarie attendono invece la tua approvazione.

## Usa la pagina Importa/Esporta {#use-the-import-export-page}

1. Apri **System › Settings › Import/Export**.
2. Sotto **Export** fai clic su **Get current configuration**, quindi su **Download .yaml** per salvare `nexcmp.yaml`. I segreti appaiono come segnaposto.
3. Sotto **Import** scegli un file, trascinalo nella casella o incolla lo YAML.
4. Opzionale: apri **Secrets that come with it (not in the file)** e aggiungi un nome e un valore per ogni riferimento, ad esempio `smtp_password`.
5. Fai clic su **Preview changes**. La tabella raggruppa le modifiche per sezione; le sezioni relative al denaro recano il tag "Money-related". Deseleziona le sezioni che non desideri.
6. Se sono elencate sezioni relative ai costi, seleziona **Also apply money-related changes (prices, payment gateways, balances)**. Se non viene selezionata, verranno saltate.
7. Clicca **Apply selected**. Il risultato mostra ciò che è stato applicato, saltato o non riuscito. Una modifica restituita come in attesa di conferma appare come una scheda di conferma; premi **Confirm** su di essa.

Il pulsante **JSON Schema** in alto a destra apre lo schema.

![Pagina Import/Export con la scheda Export e la scheda Import contenenti il file YAML esportato](https://nexcmp.com/it/docs/images/configure-with-ai/config-as-code-01-import-export.webp)

![Tabella di anteprima delle modifiche raggruppate per sezione con un tag di fatturazione e un pulsante Apply selected](https://nexcmp.com/it/docs/images/configure-with-ai/config-as-code-02-preview.webp)

## Esegui qualsiasi strumento dalla riga di comando {#run-any-tool-from-the-command-line}

`nexcmp admin` esegue gli stessi strumenti degli assistenti AI ([the tool list](https://nexcmp.com/it/docs/configure-with-ai/mcp-admin/#tools)) e stampa 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"}}'
```

Gli argomenti sono coppie `key=value` (i valori vengono letti come JSON se analizzabili, altrimenti come testo) o un oggetto `--json '{...}'`. Se l'azione richiede conferma, il comando stampa l'anteprima e si ferma con codice di uscita 3 e "Nothing changed". Leggi l'anteprima, quindi esegui nuovamente lo stesso comando con `--yes` per applicarla. Se eseguito come root, il comando ottiene una chiave di 15 minuti con tutti gli ambiti, quindi il passaggio di conferma rappresenta la tua misura di sicurezza; con `NEXCMP_KEY` si applicano gli ambiti propri della chiave.

## Verifica {#verify}

1. `sudo nexcmp config plan -f nexcmp.yaml` subito dopo un `apply --yes` stampa "No changes".
2. Nell'amministrazione, le pagine modificate mostrano i nuovi valori e **Logs › Admin actions** elenca le modifiche.
3. Applicare nuovamente lo stesso file non apporta alcuna modifica.

## Limiti e note {#limits-notes}

- Il file copre le impostazioni precedenti, non clienti, server, fatture o fonti infrastrutturali (connessioni CloudStack e Proxmox). Collega questi elementi tramite [AI Chat](https://nexcmp.com/it/docs/configure-with-ai/ai-chat-in-admin/) o le pagine di amministrazione.
- Zone e piani vengono abbinati tramite `slug`. Non rinominare uno slug nel file: verrebbe creato come un nuovo elemento.
- Un piano già utilizzato dai clienti non può modificarne le dimensioni; crea invece un nuovo piano.
- Mantieni privati i file esportati anche se non contengono dati riservati: elencano prezzi, indirizzi e nomi di account.

## Troubleshooting {#troubleshooting}

| Sintomo | Causa | Soluzione |
|---|---|---|
| `missing version: 1` | Il file non inizia con `version: 1` | Aggiungilo. |
| `unsupported version 2` | Il file ha un numero di versione diverso | Questo pannello legge solo la versione 1. |
| `unknown section 'x' (known: ...)` | Una chiave di primo livello errata o non supportata | Usa le sezioni precedenti. |
| `YAML error: ...` | YAML non valido (indentazione, tabulazioni) | Correggi la riga indicata dal messaggio. |
| `config is larger than 1 MB` | File troppo grande | Suddividilo e usa `--section`. |
| `no API key: set NEXCMP_KEY=ak_... or run as root on the server` | Il comando non ha trovato alcuna chiave | Esegui con `sudo` oppure esporta `NEXCMP_KEY` e mantienilo tramite sudo. |
| `panel not reachable` | Il servizio del pannello non è in esecuzione sulla porta predefinita | Verifica `sudo nexcmp status`. |
| Righe di fatturazione sotto `skipped` | Le sezioni di fatturazione richiedono `--confirm-billing` | Aggiungi il flag ed esamina prima le righe `$`. |
| Elementi sotto `pending` | La modifica richiede conferma | Apri **API & AI agents**, oppure il risultato di Import/Export, e premi **Confirm** sulla scheda. |
| Un segreto non è stato aggiornato | Non è stato impostato alcun valore `NEXCMP_SECRET_<NAME>`, quindi è stato mantenuto il segreto salvato | Esporta la variabile e applica di nuovo. |
| Voce sotto `errors` con HTTP 403 `insufficient_scope` | La chiave non dispone dell'ambito per quella sezione | Usa una chiave con l'ambito oppure esegui come root. |
| Voce sotto `errors` con HTTP 403 `demo_read_only` | Pannello demo | Applica su un'installazione reale. |