Configurazione come codice

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

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

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 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); mai all'interno del file.

Esporta, modifica, anteprima, applica

1. Esporta la configurazione corrente:

   sudo nexcmp config export -o nexcmp.yaml

   Senza -o, il file YAML viene stampato a schermo.

2. Modifica nexcmp.yaml (vedi l'esempio sotto). Mantieni version: 1 in alto.

3. Visualizza l'anteprima delle modifiche. Questo non modifica nulla:

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

   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

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:

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

# 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

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.
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. La modifica di host, porta o sicurezza richiede nuovamente la password.
telegram	Canale di avviso attivo o disattivato, chat id, bot token.	Notifiche Telegram.
modules	Moduli opzionali attivi o disattivati (key: true/false).	Solo le chiavi che il pannello permette di attivare. Vedi Moduli.
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.
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.
quotas	Limiti quota_*.	Vedi Quote.
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.
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.
ai_provider	Il provider AI del pannello utilizzato da AI Chat e AI Agent per i clienti.	AI provider.
legal	Testo di termini e privacy per lingua (en, vi).	Pagine legali.

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

Regole da ricordare

• 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

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

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.

Esegui qualsiasi strumento dalla riga di comando

nexcmp admin esegue gli stessi strumenti degli assistenti AI (the tool list) e stampa 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"}}'

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

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

• Il file copre le impostazioni precedenti, non clienti, server, fatture o fonti infrastrutturali (connessioni CloudStack e Proxmox). Collega questi elementi tramite AI Chat 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

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.