# NexCMP 1.6.1 — full documentation > Complete NexCMP documentation in one file. Source: https://nexcmp.com/it/docs/ · generated 2026-11-02. --- # Cos'è NexCMP {#what-is-nexcmp} NexCMP è un software che installi sul **tuo server** per trasformare l'infrastruttura cloud in un prodotto vendibile. Ti offre: - un **portale clienti** in cui gli utenti possono registrasi, aggiungere credito, ordinare macchine virtuali e altri servizi, aprire una console, scattare snapshot e contattare il supporto; - una **console di amministrazione** (`/admin`) per gestire clienti, piani, prezzi, pagamenti, infrastruttura e impostazioni; - **fatturazione**: un portafoglio per cliente, addebiti orari o mensili, fatture, promozioni e quote di risorse; - **rivenditori white-label**: altri brand che vendono la tua capacità sotto il loro dominio; - un'**API**, uno strumento da riga di comando (`cmp`) e un server MCP per l'automazione; - **AI Chat** (assistente di supporto) e **AI Agent** (gestione di una VM in linguaggio naturale) opzionali. ## A cosa si connette {#what-it-connects-to} NexCMP non ospita direttamente le macchine virtuali, ma gestisce la piattaforma che lo fa. Una *source* (chiamata anche provider) è una delle seguenti: | Source | Uso tipico | Guida | |---|---|---| | Apache CloudStack | Cloud privato o pubblico con zone, reti, router virtuali e IP pubblici | [CloudStack](https://nexcmp.com/it/docs/infrastructure/cloudstack/) | | Proxmox VE | Server singoli o cluster già in esecuzione | [Proxmox VE](https://nexcmp.com/it/docs/infrastructure/proxmox/) | Altri moduli richiedono una propria infrastruttura: [server bare-metal](https://nexcmp.com/it/docs/infrastructure/dedicated/), [nodi VPN e proxy](https://nexcmp.com/it/docs/infrastructure/vpn-proxy-nodes/), [storage a oggetti S3](https://nexcmp.com/it/docs/infrastructure/s3/), [Kubernetes e Cloud privato](https://nexcmp.com/it/docs/infrastructure/kubernetes-and-private-cloud/). Vedi [Infrastructure requirements](https://nexcmp.com/it/docs/infrastructure/requirements/) per una tabella che li riassume tutti. ## Come è strutturato {#how-it-is-built} NexCMP è un programma singolo con due servizi systemd su un singolo server Ubuntu: - `nexcmp` — il server web: portale clienti, console di amministrazione, API, procedura guidata di configurazione; - `nexcmp-vmd` — il worker in background: processi di provisioning, sincronizzazione con CloudStack o Proxmox, cicli di fatturazione. I dati risiedono in `/var/lib/nexcmp` (database SQLite e file), la configurazione in `/etc/nexcmp`, il programma in `/opt/nexcmp`. Vedi [Architecture](https://nexcmp.com/it/docs/infrastructure/architecture/) per una panoramica completa. ## Prossimi passi {#where-to-go-next} 1. Verifica i [requirements](https://nexcmp.com/it/docs/getting-started/requirements/). 2. Ottieni una licenza — [License and purchase](https://nexcmp.com/it/docs/getting-started/license-and-purchase/). 3. [Install](https://nexcmp.com/it/docs/getting-started/installation/), quindi esegui la [setup wizard](https://nexcmp.com/it/docs/getting-started/setup-wizard/). 4. Collega la tua piattaforma: [CloudStack](https://nexcmp.com/it/docs/infrastructure/cloudstack/) o [Proxmox VE](https://nexcmp.com/it/docs/infrastructure/proxmox/). --- # Requisiti per il server NexCMP {#requirements-for-the-nexcmp-server} Questa pagina descrive il server che esegue NexCMP. I requisiti per CloudStack, Proxmox VE o altra infrastruttura sono in [Infrastructure requirements](https://nexcmp.com/it/docs/infrastructure/requirements/). ## Server {#server} | Elemento | Requisito | Verificato dal programma di installazione | |---|---|---| | Sistema operativo | Ubuntu **22.04** o **24.04** | Sì — si interrompe con un errore in caso di altre versioni | | Architettura CPU | x86_64 | Sì | | Memoria | 2 GB minimi (il programma di installazione rifiuta meno di circa 1.8 GB) | Sì | | Spazio disco libero | 8 GB liberi su `/` minimo | Sì | | Privilegi | root (`sudo`) | Sì | | Pacchetti | `curl`, `ca-certificates`, `zstd`, `tar`, `openssl`, `python3`, `openssh-client` — installati automaticamente | Installati se mancanti | | Con HTTPS | `nginx` e `certbot` — installati automaticamente a meno che non si passi `--no-nginx` | Installati se mancanti | ::: tip Dimensionamento Una piccola installazione (qualche centinaio di clienti) funziona agevolmente con 2 vCPU / 4 GB di RAM. L'utilizzo del disco è dominato dai database SQLite e dalle copie opzionali di aggiornamento e backup — pianifica 20 GB o più per la produzione. ::: ## Rete {#network} | Direzione | Porta | Scopo | |---|---|---| | In entrata | 80/tcp | Validazione Let's Encrypt e reindirizzamento a HTTPS | | In entrata | 443/tcp | Portale clienti, console di amministrazione, API | | In entrata | 3000/tcp | Procedura guidata di installazione alla prima configurazione e accesso di emergenza — vedi [Installation](https://nexcmp.com/it/docs/getting-started/installation/#the-panel-port-3000) | | In uscita | 443/tcp verso `nexcmp.com` | Attivazione della licenza, controllo giornaliero della licenza, aggiornamenti | | In uscita | verso le API CloudStack / API Proxmox | Provisioning e sincronizzazione | | In uscita | 443/tcp verso i provider di pagamenti, e-mail e AI abilitati | Stripe, PayPal, SMTP, provider AI e così via | Il server necessita di un **indirizzo IPv4 pubblico** se desideri che Let's Encrypt emetta un certificato direttamente. Se il dominio è gestito tramite proxy Cloudflare, vedi [DNS and Cloudflare](https://nexcmp.com/it/docs/getting-started/dns-and-cloudflare/). ## DNS - Un **dominio principale** (ad esempio `cloud.example.com`) — il portale è `https://cloud.example.com/` e la console di amministrazione è `https://cloud.example.com/admin`. - Opzionale: `admin.` e `partner.`. Se tali nomi risolvono sul server (o su Cloudflare), il programma di installazione li aggiunge al certificato. - Il dominio deve corrispondere a quello registrato sulla tua licenza. ## Non richiesto su questo server {#not-required-on-this-server} NexCMP viene eseguito come un normale utente di servizio senza privilegi (`nexcmp`). **Non** richiede privilegi di root in fase di esecuzione, Docker, un server di database separato, Redis o alcun software di hypervisor. --- # Licenza e acquisto {#license-and-purchase} > **Dove nel pannello di amministrazione:** System › Admin › License & updates (`/license`) NexCMP si attiva tramite una **chiave di licenza** che gestisci nel tuo [account NexCMP](https://nexcmp.com/licenses). Edizioni e prezzi correnti sono indicati su [nexcmp.com/pricing](https://nexcmp.com/pricing); questa pagina spiega il comportamento della licenza una volta ottenuta. ## Ottieni una licenza {#get-a-license} 1. Crea un account su [nexcmp.com](https://nexcmp.com/register) e verifica la tua e-mail. 2. Scegli un'edizione: - **NexCMP Free** — per operatori di rete con ASN proprio e una sottorete registrata a proprio nome. Invia una richiesta su [nexcmp.com/deploy](https://nexcmp.com/deploy) (azienda, ASN, sottorete, dominio del pannello). L'e-mail del tuo account deve appartenere al dominio aziendale indicato dal registro pubblico (WHOIS) per l'ASN o la sottorete. Ciascuna richiesta viene esaminata; riceverai un'esito via e-mail e la chiave di licenza comparirà solo dopo l'approvazione. - **NexCMP Source** — un aggiornamento una tantum, nessun ASN richiesto. Visita [nexcmp.com/pricing](https://nexcmp.com/pricing). 3. Apri la pagina della tua licenza. Mostra la **chiave di licenza** (formato `NXC-XXXXX-XXXXX-XXXXX-XXXXX`), il **dominio principale** e un comando di installazione pronto all'uso. ::: warning Conserva la chiave in privato La chiave di licenza attiva un'installazione. Trattala come una password: non incollarLa in ticket, chat o screenshot. ::: ## Cosa contiene una licenza {#what-a-license-contains} | Campo | Significato | |---|---| | Dominio principale | L'hostname su cui è in esecuzione il tuo portale. La chiave vi viene associata al momento dell'attivazione. | | Domini rivenditore | Hostname aggiuntivi gestiti come portali white-label — vedi [Resellers](https://nexcmp.com/it/docs/customers/resellers/). | | Aggiornamenti fino a | Data fino alla quale ricevi **aggiornamenti e correzioni di bug**. Una licenza Free inizia con **1 anno** dal giorno dell'approvazione; rinnovala per $99 all'anno nella pagina della tua licenza. Le correzioni di sicurezza vengono sempre rilasciate, anche dopo tale data. | | Stato | `active`, oppure sospesa / scaduta / revocata. | ## Alla scadenza dell'anno gratuito {#when-the-free-year-ends} Il software **continua a funzionare** al superamento della data "Updates until": clienti, servizi e fatturazione non subiscono interruzioni. Smetti di ricevere rilasci di nuove funzionalità e aggiornamenti di bug fix (le correzioni di sicurezza continuano ad arrivare). Rinnova per $99 all'anno nella pagina della tua licenza su [nexcmp.com/licenses](https://nexcmp.com/licenses) per continuare; il rinnovo aggiunge 12 mesi alla data di scadenza corrente. NexCMP Free include solo bug fix, nessun supporto tecnico e nessuna app. ## Cosa aggiunge NexCMP Source {#what-nexcmp-source-adds} Una licenza Source è un upgrade una tantum di $1,999 della tua licenza: il codice sorgente completo, tutte le app NexCMP (Android, iOS, Windows, macOS, Linux, Chrome / Edge / Brave e Firefox) compilate e brandizzate per te, e 30 giorni lavorativi con un ingegnere esperto — migrazione gratuita da VMware, WHMCS o un altro pannello, oppure una configurazione completa da A a Z. I nuovi rilasci del codice sorgente sono inclusi per 12 mesi; il successivo rinnovo ($99 all'anno) è facoltativo e il codice sorgente scaricato rimane tuo per sempre. Consulta i [Source license terms](https://nexcmp.com/legal/source-license/). ## Come l'installazione verifica la licenza {#how-the-installation-checks-its-license} - Durante l'installazione, il server attiva la chiave per il tuo dominio e riceve un **token firmato**. - Il token viene rinnovato automaticamente ogni **24 ore**. Rimane valido per **14 giorni**, pertanto una breve interruzione di Internet non crea problemi. - Tutti i rilasci e i token sono verificati tramite una firma Ed25519 integrata nel programma; un download manomesso viene rifiutato. Verifica lo stato in qualsiasi momento nella console di amministrazione o con `sudo nexcmp status`. ## Se la licenza non è valida {#if-the-license-is-not-valid} Quando il token scade, la licenza viene sospesa o il dominio non corrisponde più: - i clienti **non possono creare nuovi servizi** e la console di amministrazione mostra un banner; - i servizi già in esecuzione, **la fatturazione e i clienti esistenti non subiscono alcuna modifica**; - risolvi la causa (ricollega il server a Internet, rinnova su [nexcmp.com/licenses](https://nexcmp.com/licenses)) e fai clic su **Check now** in License & updates. ## Spostamento su un nuovo server o dominio {#moving-to-a-new-server-or-domain} Attiva sul nuovo server con la stessa chiave e il dominio registrato (vedi [Installation](https://nexcmp.com/it/docs/getting-started/installation/)). Per modificare il dominio registrato, fallo prima nella tua pagina di licenza su [nexcmp.com/licenses](https://nexcmp.com/licenses), quindi esegui nuovamente il programma di installazione con il nuovo `--domain`. --- # Installa NexCMP {#install-nexcmp} Il programma di installazione è uno script singolo fornito dal server di licenza. Verifica la macchina, attiva la tua licenza, scarica e verifica il programma, installa i servizi e (facoltativamente) configura nginx con un certificato Let's Encrypt. ## Prima di iniziare {#before-you-start} - Un server che soddisfi i [requirements](https://nexcmp.com/it/docs/getting-started/requirements/) e accesso root. - La tua **chiave di licenza** e il **dominio principale** dalla tua [license page](https://nexcmp.com/licenses) — vedi [License and purchase](https://nexcmp.com/it/docs/getting-started/license-and-purchase/). - Un record DNS per il dominio — vedi [DNS and Cloudflare](https://nexcmp.com/it/docs/getting-started/dns-and-cloudflare/). Puoi anche installare prima e correggere il DNS in un secondo momento; il programma di installazione indica cosa manca e può essere semplicemente eseguito di nuovo. ## Installa {#install} 1. Accedi al server e diventa root (o anteponi `sudo`). 2. Esegui il comando dalla tua pagina di licenza. Si presenta così: ```bash curl -fsSL https://nexcmp.com/install.sh | sudo bash -s -- \ --license NXC-XXXXX-XXXXX-XXXXX-XXXXX \ --domain cloud.example.com \ --email admin@example.com ``` 3. Attendi i segni di spunta. Un'installazione pulita richiede pochi minuti; il primo avvio crea lo schema del database e può impiegare fino a un minuto su dischi lenti. 4. Leggi il riepilogo alla fine. Stampa gli URL del portale e dell'amministrazione, il **codice di configurazione** e il passaggio successivo. ![Il programma di installazione al termine con l'URL del portale, l'URL di amministrazione e il codice di configurazione monouso](https://nexcmp.com/it/docs/images/getting-started/installation-01-finish.webp) ## Parametri {#parameters} | Parametro | Predefinito | Significato | |---|---|---| | `--license KEY` | obbligatorio alla prima installazione | La chiave di licenza. | | `--domain NAME` | obbligatorio alla prima installazione | Dominio principale. Deve corrispondere alla licenza. `https://` e i percorsi finali vengono rimossi. | | `--email ADDRESS` | nessuno | E-mail di contatto per gli avvisi di scadenza di Let's Encrypt. Senza di essa il certificato viene registrato senza e-mail. | | `--port N` | `3000` | Porta locale del pannello (1–65535). | | `--no-nginx` | disattivo | Non installare o configurare nginx / TLS. Da usare quando gestisci il tuo proxy inverso o vuoi prima dare un'occhiata a NexCMP. | | `--behind-cloudflare` | rilevato automaticamente | Forza la modalità "il dominio è protetto da Cloudflare". Normalmente rilevata dal DNS. | | `--channel NAME` | `stable` | Canale di rilascio. | Eseguire nuovamente il programma di installazione **senza parametri** riutilizza quelli salvati (`/etc/nexcmp/install.conf`) ed effettua l'aggiornamento in sicurezza, mantenendo dati, configurazione e account. È esattamente ciò che fa `sudo nexcmp update`. ## Cosa fa il programma di installazione {#what-the-installer-does} 1. **Verifica la macchina** — Ubuntu 22.04/24.04, x86_64, almeno 2 GB di RAM, 8 GB di disco libero. 2. **Installa i pacchetti** necessari (`curl`, `zstd`, `openssl`, `python3`, `openssh-client`...). 3. **Crea l'utente di servizio** `nexcmp` e le directory: `/opt/nexcmp` (programma, di proprietà di root, di sola lettura per il servizio), `/etc/nexcmp` (configurazione), `/var/lib/nexcmp` (dati), `/var/log/nexcmp`. 4. **Attiva la licenza** per il dominio e memorizza un ID istanza fisso per questa macchina. 5. **Scarica l'ultima versione disponibile** a cui hai diritto, quindi ne verifica lo SHA-256 e la firma Ed25519. Una release priva di firma valida viene rifiutata. Non effettua mai il downgrade di una versione più recente in esecuzione. 6. **Scrive la configurazione e le unità systemd** (`nexcmp`, `nexcmp-vmd`, `nexcmp-update`) e avvia i servizi; attende la risposta di `/healthz`. 7. **Configura nginx e TLS** (tranne se `--no-nginx`): ottiene un certificato Let's Encrypt con certbot (sfida webroot) per il dominio e per `admin.` / `partner.` quando anche questi nomi si risolvono. Se il DNS non punta ancora a questo server (o a Cloudflare), salta questo passaggio e lo segnala. 8. **Stampa un riepilogo** con gli URL e, se non esiste ancora alcun amministratore, il **codice di configurazione**. ## La porta del pannello (3000) {#the-panel-port-3000} - Durante la prima installazione il pannello rimane in ascolto su `0.0.0.0:3000` per consentirti di aprire la procedura guidata di configurazione su `http://:3000/setup`. - Una volta completata la procedura guidata **e** attivato il TLS, il pannello rimane in ascolto solo su `127.0.0.1`; nginx vi esegue il proxy di `https://`. - Per le emergenze (nginx non funzionante, DNS errato) puoi aprire la porta per un periodo limitato: `sudo nexcmp open-port 30` (30 minuti, dopodiché si chiude automaticamente) — oppure utilizzare un tunnel SSH: `ssh -L 3000:127.0.0.1:3000 ` e navigare su `http://127.0.0.1:3000/`. ::: warning HTTP non crittografato La porta 3000 utilizza HTTP in chiaro. Usala solo per la procedura guidata di configurazione su una rete attendibile o tramite un tunnel SSH. Non lasciarla aperta. ::: ## Installazione senza un dominio pubblico (laboratorio o test) {#installing-without-a-public-domain-lab-or-test} Puoi eseguire l'installazione su una macchina che non dispone ancora di un DNS: ```bash curl -fsSL https://nexcmp.com/install.sh | sudo bash -s -- \ --license NXC-XXXXX-XXXXX-XXXXX-XXXXX --domain lab.example.com --no-nginx ``` Quindi apri la procedura guidata tramite un tunnel SSH (`ssh -L 3000:127.0.0.1:3000 `, naviga su `http://127.0.0.1:3000/setup`). Esegui nuovamente l'installer senza `--no-nginx` non appena il DNS sarà configurato. ## Docker e Kubernetes {#docker-and-kubernetes} Non esiste un'immagine container pubblicata. L'installer (un'installazione nativa con systemd) è il metodo di installazione supportato. ## Verifica {#verify} ```bash sudo nexcmp status ``` Dovresti visualizzare la versione, `nexcmp: active`, `nexcmp-vmd: active`, `healthz: ok` e — fino al completamento della procedura guidata — il codice di configurazione. Prosegui con la [setup wizard](https://nexcmp.com/it/docs/getting-started/setup-wizard/). Se qualcosa non va, consulta [Installation errors](https://nexcmp.com/it/docs/troubleshooting/installation-errors/). --- # DNS e Cloudflare {#dns-and-cloudflare} NexCMP richiede un nome DNS — il suo **dominio principale** — e funziona in due modalità. ## Modalità A: il DNS punta direttamente al server {#mode-a-dns-points-straight-at-the-server} 1. Crea un record **A** `cloud.example.com → ` (e un record **AAAA** se il server dispone di IPv6). 2. Facoltativo, se utilizzati: `admin.cloud.example.com` e `partner.cloud.example.com` che puntano allo stesso IP. 3. Esegui (o riesegui) l'[installer](https://nexcmp.com/it/docs/getting-started/installation/). Rileva che il nome si risolve nell'IP pubblico del server e ottiene un certificato Let's Encrypt tramite la sfida HTTP-01 sulla porta 80. ## Modalità B: il dominio è protetto da proxy Cloudflare {#mode-b-the-domain-is-proxied-by-cloudflare} Crea gli stessi record con la nuvola arancione (**Proxied**). L'installer rileva che il nome si risolve esclusivamente verso gli indirizzi di Cloudflare e passa alla modalità Cloudflare: - nginx rimane in ascolto sulle porte 80/443 del tuo server; - il vero IP del visitatore viene letto dall'intestazione `CF-Connecting-IP` — **solo** per le connessioni provenienti dagli intervalli pubblicati di Cloudflare, in modo che non possa essere falsificato da nessun altro; - il certificato viene ottenuto tramite Let's Encrypt (Cloudflare inoltra la richiesta di verifica all'origine); se ciò non è ancora possibile, viene creato un **certificato di origine autofirmato** per consentire il funzionamento della modalità "Full", mentre una successiva esecuzione del programma di installazione effettuerà l'aggiornamento a Let's Encrypt. Puoi forzare questa modalità con `--behind-cloudflare`. ::: important Imposta la modalità SSL/TLS in Cloudflare In Cloudflare vai su **SSL/TLS › Overview** e seleziona **Full (strict)** una volta che il programma di installazione segnala un certificato Let's Encrypt. Con un certificato di origine autofirmato usa **Full**. **Flexible** causerà cicli di reindirizzamento. ::: ::: tip Se "Always Use HTTPS" è attivo, Cloudflare invia la richiesta di validazione alla porta 443 della tua origine. Il programma di installazione gestisce la situazione creando prima il certificato autofirmato temporaneo, per poi riprovare con Let's Encrypt. ::: ## Verifica {#check-it} ```bash dig +short cloud.example.com # A record (a Cloudflare address in mode B) curl -I https://cloud.example.com/healthz sudo certbot certificates # certificate name, domains and expiry ``` I certificati si rinnovano automaticamente tramite il timer di certbot. Il rinnovo utilizza la webroot `/var/www/nexcmp-acme`, quindi la porta 80 deve rimanere raggiungibile (direttamente o tramite Cloudflare). ## Problemi comuni {#common-problems} | Sintomo | Causa | Soluzione | |---|---|---| | Il programma di installazione indica "DNS … does not point to … (nor to Cloudflare) — skipping nginx/TLS" | Record DNS mancante, errato o non propagato | Correggi il record, attendi la propagazione ed esegui nuovamente il programma di installazione. | | Il browser mostra `ERR_TOO_MANY_REDIRECTS` dietro Cloudflare | La modalità SSL è **Flexible** | Imposta **Full (strict)** (o **Full**). | | Errore Cloudflare 525/526 | Certificato di origine rifiutato | Usa **Full** con un certificato di origine autofirmato o **Full (strict)** con Let's Encrypt. | | I log mostrano solo gli IP di Cloudflare per tutti i visitatori | Non sei in modalità Cloudflare | Esegui nuovamente il programma di installazione con `--behind-cloudflare`. | Maggiori informazioni in [Installation errors](https://nexcmp.com/it/docs/troubleshooting/installation-errors/). --- # Procedura di configurazione {#setup-wizard} > **Dove si trova nell'amministrazione:** la procedura guidata è una pagina indipendente su `/setup` mostrata solo finché non esiste il primo amministratore. In seguito, gli stessi controlli si trovano in System › Admin › Start (`/setup`). La procedura guidata trasforma una nuova installazione in un pannello operativo in quattro brevi passaggi. Viene eseguita sulla porta 3000 (`http://:3000/setup`) o, quando il TLS è già attivo, su `https:///setup`. ::: warning La procedura guidata scompare dopo il passaggio 3 Una volta creato l'amministratore, la procedura guidata viene chiusa e il codice di configurazione viene eliminato. Per accedere al pannello in seguito, utilizza la console di amministrazione. ::: ## Passaggio 0 — Codice di configurazione {#step-0-—-setup-code} Il programma di installazione stampa un **codice di configurazione monouso** alla fine. Puoi leggerlo nuovamente con: ```bash sudo nexcmp status ``` Incollalo in **Setup code** e fai clic su **Continue**. Il codice protegge la procedura guidata: nessuno che trovi la porta aperta può creare l'amministratore senza di esso. ![Passaggio 0 della procedura di configurazione che richiede il codice di configurazione monouso](https://nexcmp.com/it/docs/images/getting-started/setup-wizard-00-code.webp) ## Passaggio 1 — Licenza {#step-1-—-license} | Campo | Valore | |---|---| | Chiave di licenza | `NXC-XXXXX-XXXXX-XXXXX-XXXXX` — preattivata dal programma di installazione, quindi questo passaggio mostra normalmente "Activated for cloud.example.com" | | Dominio principale | Il dominio registrato sulla licenza | Se il programma di installazione ha già attivato la licenza, la procedura guidata la riconosce e prosegue. In caso contrario, inserisci la chiave e il dominio e fai clic su **Activate**. Gli errori vengono mostrati in rosso — vedi [Installation errors](https://nexcmp.com/it/docs/troubleshooting/installation-errors/). ![Fase 1 della procedura guidata di installazione che mostra la licenza già attivata per il dominio principale](https://nexcmp.com/it/docs/images/getting-started/setup-wizard-01-license.webp) ## Passaggio 2 — CloudStack (o Connetti in seguito) {#step-2-—-cloudstack-or-connect-later} Hai due possibilità: - **Connetti ora.** Inserisci l'**API URL** (`https://cloudstack.example.com/client/api`), la **API key** e la **Secret key** di CloudStack, fai clic su **Test connection**, quindi seleziona la **Zone**, la **Guest network for customer VMs**, un **Zone display name** e il **Country** a due lettere. Fai clic su **Save CloudStack**. - **Connetti in seguito.** Fai clic su **Connect later**. Tutto il resto funziona; potrai connettere CloudStack o Proxmox VE in un secondo momento nella sezione Infrastruttura. Fino ad allora, il pannello dello stato di salute ricorderà che non è connesso alcun sistema. ![Fase 2 della procedura guidata con i campi dell'API URL, della chiave API e della chiave segreta di CloudStack compilati con valori di esempio](https://nexcmp.com/it/docs/images/getting-started/setup-wizard-02-cloudstack-form.webp) ::: important Usa un account CloudStack dedicato Non utilizzare la chiave amministratore ROOT. Crea un dominio e un account dedicati per NexCMP e utilizza la relativa chiave API — vedi [CloudStack](https://nexcmp.com/it/docs/infrastructure/cloudstack/#create-a-dedicated-account-and-api-key). La procedura guidata verifica che la rete scelta appartenga alla zona e all'account associati a quella chiave. ::: ![Dopo Test connection: elenchi della zona e della rete guest, nome visualizzato della zona e campi del paese](https://nexcmp.com/it/docs/images/getting-started/setup-wizard-02b-cloudstack-picked.webp) Se prevedi di utilizzare solo **Proxmox VE**, scegli **Connect later** e segui [Proxmox VE](https://nexcmp.com/it/docs/infrastructure/proxmox/). ## Passaggio 3 — Amministratore e brand {#step-3-—-administrator-and-brand} | Campo | Regole | |---|---| | E-mail admin (accesso) | Indirizzo e-mail valido. Questo è il tuo nome utente amministratore. | | Password | Almeno 12 caratteri, con lettere e cifre. | | Nome del brand | Mostrato ai clienti (predefinito "Cloud"). Fino a 60 caratteri. | | E-mail di supporto | Predefinito sull'e-mail dell'amministratore. | ![Fase 3 della procedura guidata con e-mail amministratore, password, nome del brand ed e-mail di supporto](https://nexcmp.com/it/docs/images/getting-started/setup-wizard-03-admin.webp) Fai clic su **Finish setup**. Il pannello si riavvia (circa 1–2 secondi) e la pagina reindirizza al login amministrativo all'indirizzo `https:///admin/`. Se tale indirizzo non risponde ancora (DNS o TLS in corso), reindirizza invece a `/` sull'indirizzo corrente. ![La procedura guidata al completamento con il messaggio che indica il riavvio del pannello](https://nexcmp.com/it/docs/images/getting-started/setup-wizard-03-done.webp) ## Cosa configura la procedura guidata per te {#what-the-wizard-sets-up-for-you} - Nome del brand, URL del sito (`https://`), URL dell'amministratore (`https:///admin`), URL della console (`https:///console`), e-mail di supporto e nome del mittente. - Impostazioni predefinite per i moduli inclusi in NexCMP: DDoS & BGP, IA e SSH web sono **disattivati**; la misurazione della larghezza di banda è **attivata**. Vedi [Modules](https://nexcmp.com/it/docs/infrastructure/modules/). - Se hai connesso CloudStack: il provider #1, la sua prima zona, la rete guest e una coppia di chiavi di gestione associata alle VM dei clienti per consentirti di fornire assistenza. Avanti: [First login](https://nexcmp.com/it/docs/getting-started/first-login/). --- # Primo accesso e passaggi successivi {#first-login-and-next-steps} > **Dove nel pannello di amministrazione:** la pagina di login è `/admin`; dopo l'accesso la pagina di arrivo è Overview › Dashboard. ## Indirizzi {#addresses} | Cosa | URL | |---|---| | Portale clienti | `https:///` | | Console di amministrazione | `https:///admin` | | Configurazione / emergenza per IP | `http://:3000/` (vedi [la porta del pannello](https://nexcmp.com/it/docs/getting-started/installation/#the-panel-port-3000)) | | Controllo dello stato | `https:///healthz` | ## Accedi {#sign-in} 1. Apri `https:///admin`. 2. Inserisci l'e-mail e la password dell'amministratore create durante la procedura guidata. 3. Atterri sulla **Dashboard**. In alto compare un banner se la licenza non è valida o se non è connessa alcuna sorgente. ![La pagina di login dell'amministratore](https://nexcmp.com/it/docs/images/getting-started/first-login-01-login.webp) ## Checklist consigliata {#recommended-checklist} Segui questi punti in ordine: ognuno rimanda alla sua pagina. | # | Attività | Pagina | |---|---|---| | 1 | Attiva l'autenticazione a due fattori per il tuo account | [Security](https://nexcmp.com/it/docs/administration/security/) | | 2 | Collega una sorgente di infrastruttura (se hai scelto "Connect later") | [CloudStack](https://nexcmp.com/it/docs/infrastructure/cloudstack/) o [Proxmox VE](https://nexcmp.com/it/docs/infrastructure/proxmox/) | | 3 | Verifica le zone e i template delle macchine / l'elenco dei sistemi operativi | [Zones](https://nexcmp.com/it/docs/infrastructure/zones/), [Templates](https://nexcmp.com/it/docs/infrastructure/templates/) | | 4 | Rivedi piani e prezzi | [Plans](https://nexcmp.com/it/docs/catalog/plans/) | | 5 | Imposta logo, colori e pagine legali | [Branding](https://nexcmp.com/it/docs/customers/branding/), [Legal](https://nexcmp.com/it/docs/customers/legal/) | | 6 | Configura l'e-mail in uscita e invia un test | [SMTP and emails](https://nexcmp.com/it/docs/administration/smtp-and-emails/) | | 7 | Abilita almeno un canale di pagamento e prova una ricarica | [Payment channels](https://nexcmp.com/it/docs/billing/payment-channels/) | | 8 | Decidi quali moduli vendere | [Modules](https://nexcmp.com/it/docs/infrastructure/modules/) | | 9 | Effettua un ordine di prova come cliente ed eliminalo | [Ordering](https://nexcmp.com/it/docs/portal/ordering/) | | 10 | Esegui un primo backup | [Backup and restore](https://nexcmp.com/it/docs/getting-started/backup-and-restore/) | ## Crea il tuo primo ordine (smoke test) {#create-your-first-order-smoke-test} 1. Apri il portale clienti in una finestra in incognito e registra un account di prova. 2. Aggiungi credito (un voucher o un pagamento di prova). 3. Ordina il piano più piccolo nella tua zona. 4. Osserva la sua comparsa nel pannello di amministrazione in Services › Virtual Machines, apri la sua console e infine eliminalo. Se la VM non raggiunge lo stato *running*, apri **Infrastructure › Cloud provider › Sync & errors** e leggi l'errore. --- # Aggiornamento di NexCMP {#updating-nexcmp} > **Dove nel pannello di amministrazione:** System › Admin › License & updates (`/license`) → scheda *Update*. ## Cosa ricevi {#what-you-receive} | Tipo di rilascio | Consegnato quando | |---|---| | Correzoine di sicurezza | **Sempre**, anche dopo la data di "aggiornamenti fino al" | | Rilascio di funzionalità | Solo se pubblicato **entro o alla** data di "aggiornamenti fino al" | Puoi visualizzare entrambe le date in **License & updates**. Rinnova i diritti su [nexcmp.com/licenses](https://nexcmp.com/licenses). ## Aggiorna dalla console di amministrazione {#update-from-the-admin-console} 1. Apri **System › Admin › License & updates**. 2. Nella scheda **Update** fai clic su **Check for update**. La scheda mostra la versione corrente, la versione più recente che puoi installare, un tag *security* se pertinente e il changelog. 3. Fai clic su **Update to X.Y.Z** e conferma. Il programma scarica la versione, ne verifica la **firma SHA-256 e Ed25519**, sostituisce il binario in modo atomico (mantenendo una copia `.bak`) e si riavvia. Previsto circa **10 secondi** di downtime. 4. Ricarica la pagina e controlla la versione in alto a destra di License & updates. ![La scheda Update con la versione in esecuzione e il pulsante Check for new version](https://nexcmp.com/it/docs/images/getting-started/updating-01-card.webp) ## Aggiorna dalla riga di comando {#update-from-the-command-line} ```bash sudo nexcmp update ``` Questo esegue il programma di installazione integrato *all'interno della versione attualmente installata* (non uno script scaricato in quel momento) con i parametri salvati da `/etc/nexcmp/install.conf`. Aggiorna il binario, le unità systemd, i template nginx e l'agente del nodo, mantenendo dati, configurazione e account. ::: tip Nessun downgrade Se il server offre una versione precedente a quella in esecuzione, il programma di installazione mantiene la versione in esecuzione. ::: ## Prima di aggiornare {#before-you-update} 1. Crea un backup: `sudo nexcmp backup` — vedi [Backup and restore](https://nexcmp.com/it/docs/getting-started/backup-and-restore/). 2. Leggi il changelog nella scheda Update. Per le modifiche introdotte dalla 1.3, consulta [Note di rilascio fino alla 1.6.1](https://nexcmp.com/it/docs/getting-started/release-notes/), inclusi l'aggiornamento dell'agent VPN e le regole dei prezzi Bare Metal. 3. Aggiorna durante un periodo di quiete; le macchine virtuali in esecuzione non vengono toccate, ma i clienti non possono utilizzare il portale per alcuni secondi. ## Dopo l'aggiornamento {#after-you-update} - Esegui `sudo nexcmp status` e conferma che entrambi i servizi siano attivi. - Apri la Dashboard di amministrazione e la pagina **Needs attention**. - Le migrazioni del database vengono eseguite automaticamente al primo avvio della nuova versione. - Se utilizzi nodi VPN, aggiorna il relativo agent separatamente e controlla le letture dei consumi. L'aggiornamento del pannello rende disponibile il nuovo agent, ma non garantisce che ogni nodo remoto lo stia già eseguendo. Consulta [Quota dati dei nodi VPN](https://nexcmp.com/it/docs/infrastructure/vpn-proxy-nodes/#data-allowance-on-a-vpn-node). Se un aggiornamento fallisce, vedi [Update errors](https://nexcmp.com/it/docs/troubleshooting/update-errors/). --- # Note di rilascio {#release-notes} > **Dove nell'admin:** System › Admin › License & updates (`/license`), scheda **Update**. Queste note descrivono le modifiche successive alla 1.3 fino a **NexCMP 1.6.1**. Esegui un backup prima di aggiornare e usa la release proposta nella scheda **Update** della tua installazione. Consulta [Aggiornamento di NexCMP](https://nexcmp.com/it/docs/getting-started/updating/) per i comandi e la verifica delle firme. ## 1.6.1 - **Metriche Bare Metal:** la scheda **Overview** del cliente mostra riquadri per CPU, RAM, attività del disco e rete con lo storico recente. Le misurazioni mancanti mostrano un trattino e una motivazione. Le letture di rete richiedono un contatore di traffico; non vengono dedotte dall'inventario hardware di iDRAC. - **Piani di esempio Bare Metal:** i nomi di esempio utilizzano `BM-40C-`. I piani di esempio predefiniti che non hai modificato ricevono nomi neutri. I piani modificati vengono preservati e un piano a cui si fa riferimento mantiene il proprio codice. Verifica l'hardware effettivo del server prima di rendere vendibile un piano. - **Cambi di piano:** l'elenco delle richieste nell'admin si ordina lato server e mantiene le azioni visibili durante lo scorrimento orizzontale. - **Report a bug:** il modulo scorre mantenendo visibili i pulsanti. Il mascheramento delle password preserva il testo diagnostico circostante. - **Caricamento:** le risorse della pagina e i dati dell'admin utilizzati più spesso vengono caricati in anticipo per ridurre i tempi di attesa nella navigazione. Consulta [Configurazione, prezzi e controlli cliente per Bare Metal](https://nexcmp.com/it/docs/infrastructure/dedicated/) e [Report a bug](https://nexcmp.com/it/docs/administration/report-a-bug/). ## 1.6.0 - **Configurazione Bare Metal:** inserisci le reti iDRAC, l'indirizzo del server ISO e l'indirizzo di callback del pannello in **Safety › Management network connection**. I valori di esempio bloccano le operazioni in produzione finché non vengono configurati. - **Hosting ISO:** `sudo nexcmp dedicated-setup-iso` configura il server web ISO della rete di gestione. L'installer può installare la console e gli strumenti ISO con `--baremetal` o tramite le opzioni ISO. L'assenza di tali strumenti blocca le operazioni in produzione con `tools_missing`. - **Prezzi Bare Metal:** una nuova installazione o un'installazione non utilizzata inizia con prezzi in USD. Un'installazione che contiene già dati di prezzo in VND mantiene i VND e richiede comunque un tasso USD/VND. L'aggiornamento non reinterpreta i prezzi esistenti come dollari. - **Pagina server del cliente:** rinnova in anticipo, programma una modifica del ciclo di fatturazione, richiedi un cambio di piano, visualizza le fatture e consulta le credenziali di accesso al SO dopo l'installazione. Un nuovo proprietario non può vedere la password di quello precedente. - **Profili cliente:** otto schede raggruppano overview, services, billing, quota, security, support, affiliate e log. I servizi condividono un'unica tabella ricercabile e ordinabile. - **Azioni sui servizi:** il blocco, lo sblocco, l'annullamento senza rimborso o con rimborso utilizzano una finestra di dialogo comune. I rimborsi tornano al wallet originale o all'allocazione del credito; i gateway di pagamento non vengono rimborsati automaticamente. Vedi [Server dedicati](https://nexcmp.com/it/docs/infrastructure/dedicated/) e [Gestione dei clienti](https://nexcmp.com/it/docs/customers/managing-customers/). Il BYOIP e il collegamento di una subnet cliente a un server Bare Metal rimangono non disponibili in NexCMP. ## 1.5.2 L'amministratore principale può aprire **Report a bug** accanto a **Docs** e inviare un ticket all'account della licenza senza effettuare un accesso separato. La diagnostica è facoltativa. Lo staff, i clienti e gli assistenti IA non possono inviare segnalazioni tramite questa azione. Vedi [Segnala un bug](https://nexcmp.com/it/docs/administration/report-a-bug/). ## 1.5.1 - **Utilizzo VPN:** i nodi agent segnalano il traffico al pannello. Una sottoscrizione che esaurisce la soglia di GB viene sospesa; torna disponibile dopo un upgrade della larghezza di banda o all'inizio di un nuovo periodo. I nodi senza report sull'utilizzo mostrano **Not measured** e non vengono sospesi in base ai GB. - **Agent VPN:** la versione 1.5.1 ritenta l'invio dei dati di utilizzo non confermati, invia il traffico finale all'arresto e chiude le connessioni aperte quando un endpoint viene arrestato. Aggiorna sia gli agent remoti che il pannello. - **Add-on VPN ritirati:** High IP Reputation, High Concurrency e High Priority Network non sono più in vendita. Le relative tariffe vengono rimosse dagli importi dei rinnovi futuri delle sottoscrizioni esistenti; i periodi passati non vengono rimborsati. Se un add-on è stato eliminato dal catalogo, controlla l'importo del rinnovo manualmente. - **Etichette di protocollo:** il proxy HTTP IPv4 è in plain HTTP. Gli indirizzi IPv4 non ruotano. La porta 443 del proxy IPv6 gestisce SOCKS5; non è un endpoint proxy HTTPS. - **Nuova installazione:** l'inizializzazione del database ritenta i conflitti di migrazione temporanei tra pannello e worker, evitando che il salvataggio del primo provider richieda un riavvio. Vedi [Nodi VPN e proxy IPv6](https://nexcmp.com/it/docs/infrastructure/vpn-proxy-nodes/). ## 1.5.0 **AI Models** è un modulo opzionale di gateway e fatturazione, disattivato per impostazione predefinita. Aggiungi le sorgenti dei modelli che gestisci o che sei autorizzato a rivendere, sincronizza i modelli, imposta prezzi e instradamenti, abilita i modelli e apri le vendite. Non include account provider, modelli o prezzi predefiniti. È separato dal modulo AI Chat e AI Agent. Vedi [AI Models](https://nexcmp.com/it/docs/infrastructure/ai-models/). ## 1.4.2 L'installazione del nodo proxy IPv6 utilizza il demone e lo script di rete inclusi nel pacchetto di rilascio. Il pannello richiede `sshpass` per l'installazione SSH basata su password. Il pannello esegue le pianificazioni di rotazione e la configurazione del nodo esclude l'indirizzo del gateway dalle allocazioni. La personalizzazione del brand consente di impostare un nome visualizzato personalizzato per il servizio VPN. Vedi [Nodi VPN e proxy IPv6](https://nexcmp.com/it/docs/infrastructure/vpn-proxy-nodes/). ## 1.4.0–1.4.1 - **Amministrazione dell'IA:** sono disponibili l'AI Chat di amministrazione, gli account IA personali, le chiavi API di amministrazione, il server MCP di amministrazione, i connettori OAuth, l'importazione/esportazione della configurazione e la checklist di configurazione. Vedi [Configurazione con l'IA](https://nexcmp.com/it/docs/configure-with-ai/overview/). - **Licenze:** i flussi di lavoro Free e Source includono build ufficiali e build personalizzate da sorgente. L'account, le licenze, i download e la documentazione utilizzano `nexcmp.com`. Vedi [Licenza e acquisto](https://nexcmp.com/it/docs/getting-started/license-and-purchase/). - **Link alla documentazione:** **Docs** nell'area di amministrazione apre la guida relativa alla pagina corrente. - **Valute:** per impostazione predefinita, una nuova installazione segue la lingua del cliente. USD/VND proviene da una tabella pubblica dei tassi di cambio o dal tuo tasso fisso. Vedi [Valute e tassi di cambio](https://nexcmp.com/it/docs/catalog/currency-and-exchange-rates/). - **Zone a sorgente mista:** i prezzi pubblici dei Cloud Server funzionano quando CloudStack e Proxmox VE condividono una zona. I piani utilizzano la propria sorgente di infrastruttura. - **Prezzi derivati dalle offerte:** la percentuale è un margine sul prezzo di vendita. Un margine del 40% su un costo di $60 genera $100, prima di qualsiasi arrotondamento. ## Checklist di aggiornamento {#upgrade-checklist} 1. Esegui un backup, leggi la scheda **Update**, aggiorna ed esegui `sudo nexcmp status`. 2. Aggiorna gli agent VPN e verifica che i nodi segnalino il traffico misurato prima di fare affidamento sull'interruzione basata sui GB. 3. Se utilizzi Bare Metal, controlla i campi della rete di gestione, gli strumenti richiesti, l'unità di prezzo, i template e i piani di esempio prima di aprire le vendite o avviare le operazioni in produzione. 4. Apri un profilo cliente e verifica il relativo elenco dei servizi. Controlla l'importo e l'allocazione del pagamento originale prima di confermare un annullamento con rimborso. 5. Mantieni disattivati i moduli opzionali finché la relativa infrastruttura non è pronta. Per AI Models, verifica un provider, un modello con prezzo e una richiesta cliente completata con successo prima di aprire le vendite. --- # Backup and restore {#backup-and-restore} > **Dove si trova nell'amministrazione:** System › Admin › Backup (`/backup`) appare solo quando il modulo DDoS & BGP è abilitato; per un'installazione standard utilizza la riga di comando sottostante. ## Cosa viene incluso nel backup {#what-is-backed-up} `sudo nexcmp backup` crea un archivio compresso contenente: | Parte | Contenuto | |---|---| | `data/**/*.db` | Ogni database SQLite in `/var/lib/nexcmp`, copiato con l'API di backup online di SQLite — coerente anche mentre il pannello è in esecuzione | | `files.tar` | Tutti gli altri file in `/var/lib/nexcmp` (file di impostazioni, caricamenti di personalizzazione, `secrets/`), ad eccezione dei database e della cartella `updates/` | | `etc/` | Una copia di `/etc/nexcmp` (impostazioni del programma di installazione, ID istanza, porta e binding) | ::: warning L'archivio contiene le tue chiavi master `secrets/` contiene la chiave che cifra le API key, le credenziali di pagamento e le password SMTP salvate nel database. L'archivio viene creato con permessi `0600`. Conservalo cifrato e fuori dal server. Senza queste chiavi, un database ripristinato non potrà decifrare i propri segreti. ::: ## Esegui un backup {#take-a-backup} ```bash sudo nexcmp backup # writes to /var/backups/nexcmp sudo nexcmp backup /mnt/nas/nexcmp # or to another directory ``` Il comando mostra il percorso dell'archivio, ad esempio `/var/backups/nexcmp/nexcmp-backup-20261030-120000.tar.zst`. ### Pianificalo {#schedule-it} ```bash echo '17 3 * * * root /usr/local/bin/nexcmp backup /var/backups/nexcmp && find /var/backups/nexcmp -name "nexcmp-backup-*" -mtime +14 -delete' | sudo tee /etc/cron.d/nexcmp-backup ``` Copia la cartella fuori dalla macchina (Object Storage, NAS, un altro server). ## Ripristino {#restore} Esegui il ripristino su un server in cui è installata la **stessa versione (o più recente)** di NexCMP. 1. Installa NexCMP con l'[installer](https://nexcmp.com/it/docs/getting-started/installation/) utilizzando gli stessi dominio e licenza, ma **non** avviare il setup wizard. 2. Arresta i servizi: ```bash sudo systemctl stop nexcmp-vmd nexcmp ``` 3. Estrai l'archivio in una directory temporanea: ```bash sudo mkdir /root/restore && sudo tar --zstd -xf nexcmp-backup-20261030-120000.tar.zst -C /root/restore ``` 4. Ripristina i file: ```bash sudo tar -xf /root/restore/files.tar -C /var/lib/nexcmp sudo cp -a /root/restore/data/. /var/lib/nexcmp/ sudo cp -a /root/restore/etc/. /etc/nexcmp/ sudo chown -R nexcmp:nexcmp /var/lib/nexcmp ``` 5. Avvia i servizi e verifica: ```bash sudo systemctl start nexcmp nexcmp-vmd sudo nexcmp status ``` 6. Accedi a `https:///admin` con l'amministratore del sistema *di cui hai eseguito il backup*. ::: tip Fai una prova Esegui i passaggi da 1 a 6 su un server di prova almeno una volta, prima che sia necessario. Un backup mai ripristinato è solo una speranza. ::: ## Non incluso {#not-included} - Configurazione e certificati nginx (rigenerati dall'installer; i certificati Let's Encrypt vengono riemessi). - I tuoi server CloudStack / Proxmox VE e le macchine virtuali su di essi — fanne il backup con i rispettivi strumenti. --- # Disinstallazione di NexCMP {#uninstall-nexcmp} ::: warning I clienti perdono l'accesso La disinstallazione arresta il portale e il billing. Le macchine virtuali su CloudStack o Proxmox VE continuano a funzionare, ma non verranno più gestite né fatturate. Esegui prima un [backup](https://nexcmp.com/it/docs/getting-started/backup-and-restore/). ::: ## Rimuovi il programma, mantieni i dati {#remove-the-program-keep-the-data} ```bash sudo nexcmp uninstall ``` Questo disabilita e rimuove i servizi `nexcmp` e `nexcmp-vmd`, il sito e lo snippet nginx, `/opt/nexcmp` e il comando `nexcmp`. **I dati rimangono** in `/var/lib/nexcmp` e `/etc/nexcmp`, così un'eventuale installazione successiva sullo stesso server ripartirà da dove eri rimasto. ## Rimuovi tutto {#remove-everything} ```bash sudo nexcmp uninstall --purge ``` Elimina inoltre `/var/lib/nexcmp`, `/etc/nexcmp`, `/var/log/nexcmp` e l'utente di sistema `nexcmp`. Questa operazione non può essere annullata. ## Dopo la disinstallazione {#after-uninstalling} - I certificati Let's Encrypt e i pacchetti `nginx` / `certbot` non vengono rimossi. Se vuoi, puoi rimuovere il certificato con `sudo certbot delete --cert-name `. - Rilascia il dominio nella pagina delle tue licenze su [nexcmp.com/licenses](https://nexcmp.com/licenses) se intendi attivarlo altrove. - Elimina l'account CloudStack dedicato o il token API di Proxmox creati per NexCMP se non ti servono più. --- # Riferimento comandi `nexcmp` {#nexcmp-command-reference} L'installer posiziona un helper in `/usr/local/bin/nexcmp`. Eseguilo sul server NexCMP. I comandi che modificano il sistema richiedono `sudo`. (Lo strumento lato cliente per le API è un programma differente, vedi [cmp CLI](https://nexcmp.com/it/docs/developers/cmp-cli/).) | Comando | Richiede root | Descrizione | |---|---|---| | `nexcmp status` | No (maggiori dettagli con `sudo`) | Versione, stato dei servizi (`nexcmp`, `nexcmp-vmd`), `/healthz`, riepilogo licenza, stato porte pubbliche, codice di configurazione se la procedura guidata non è terminata | | `nexcmp update` | Sì | Esegue l'installer incluso nella release installata con i parametri salvati — vedi [Aggiornamento](https://nexcmp.com/it/docs/getting-started/updating/) | | `nexcmp backup [dir]` | Sì | Backup su `/var/backups/nexcmp` (o `dir`) — vedi [Backup and restore](https://nexcmp.com/it/docs/getting-started/backup-and-restore/) | | `nexcmp uninstall [--purge]` | Sì | Rimuove servizi e programma; `--purge` rimuove anche i dati — vedi [Uninstall](https://nexcmp.com/it/docs/getting-started/uninstall/) | | `nexcmp open-port [minutes]` | Sì | **Emergency**: resta in ascolto sulla porta del pannello (predefinita 3000) su tutte le interfacce per 1–1440 minuti (predefinito 30), quindi si chiude automaticamente | | `nexcmp close-port` | Sì | Chiudi subito la finestra di emergenza | | `nexcmp fix-owner` | Sì | Ripristina la proprietà dei file in `/var/lib/nexcmp` appartenenti a root assegnandoli all'utente `nexcmp` | ## `nexcmp status` ```text Version : 1.6.1 nexcmp : active nexcmp-vmd : active healthz : ok License : active · domain cloud.example.com · token valid until 2026-11-12 · updates until 2027-10-30 Public port: 127.0.0.1 only (nginx proxy; emergency: sudo nexcmp open-port) ``` Se i file nella directory dei dati appartengono a root (ad esempio perché creati eseguendo un altro comando `nexcmp` con `sudo` come root), `status` stampa un avviso poiché l'utente del servizio non può leggerli; un sintomo tipico è la licenza che restituisce HTTP 421. Risolvi con `sudo nexcmp fix-owner`. La stessa correzione viene eseguita automaticamente a ogni avvio del servizio. ## Accesso di emergenza {#emergency-access} Quando il dominio, nginx o TLS non funzionano, puoi comunque raggiungere il pannello: ```bash sudo nexcmp open-port 30 # http://:3000/ for 30 minutes sudo nexcmp close-port # close it earlier ``` Più sicuro, senza aprire nulla: `ssh -L 3000:127.0.0.1:3000 user@server` e visita `http://127.0.0.1:3000/`. ## Ambiente {#environment} | Variabile | Utilizzato per | |---|---| | `NEXCMP_BASE` | Sovrascrive l'URL di base del server delle licenze (predefinito `https://nexcmp.com`); solo per test | File e directory: programma `/opt/nexcmp`, configurazione `/etc/nexcmp`, dati `/var/lib/nexcmp`, log `/var/log/nexcmp` e `journalctl -u nexcmp -u nexcmp-vmd`. --- # Requisiti infrastrutturali {#infrastructure-requirements} > **Dove si trova nell'admin:** Infrastructure (la sezione nel menu a sinistra) e System › Admin › License & updates (`/license`) per l'attivazione dei moduli. Questa pagina elenca ciò di cui ogni modulo ha bisogno **all'esterno** del server NexCMP. Per il server stesso (Ubuntu, memoria, disco, porte) vedi [Requirements for the NexCMP server](https://nexcmp.com/it/docs/getting-started/requirements/). Per attivare i moduli, vedi [Modules](https://nexcmp.com/it/docs/infrastructure/modules/). ## Modulo per modulo {#module-by-module} | Modulo | Infrastruttura minima | Dettagli | |---|---|---| | **Virtual Machines on CloudStack** | Apache CloudStack 4.23 (testato), KVM, una zona avanzata con una rete guest e un intervallo di IP pubblici; un dominio dedicato e un account con una chiave API (mai ROOT); almeno un template pronto e un'offerta di servizio | [CloudStack](https://nexcmp.com/it/docs/infrastructure/cloudstack/) | | **Virtual Machines on Proxmox VE** | Proxmox VE 9.x (verificato sulla 9.2); un token API con un ruolo personalizzato; uno storage che supporta i cloni; un bridge; un blocco IPv4 con un gateway; un template cloud-init per sistema operativo e per nodo | [Proxmox VE](https://nexcmp.com/it/docs/infrastructure/proxmox/) | | **OS templates** | CloudStack: una macchina di compilazione Linux con libguestfs e un web server per l'immagine. Proxmox VE: template di immagini cloud con il guest agent | [OS templates](https://nexcmp.com/it/docs/infrastructure/templates/) | | **Bare metal / Dedicated Server** | Server Dell con iDRAC 9 raggiungibili via HTTPS (Redfish) dal pannello su una rete di gestione; un server HTTP su tale rete che distribuisce i file ISO; cartelle ISO scrivibili per il servizio NexCMP | [Dedicated servers](https://nexcmp.com/it/docs/infrastructure/dedicated/) | | **AI Models** | Una o più sorgenti di modelli autorizzate alla rivendita, con API compatibile con OpenAI o Anthropic e chiave propria; HTTPS in uscita (porta 443, dominio pubblico) dal pannello a ogni sorgente, oppure un gateway interno elencato in Allowed internal hosts; nessuna GPU o hardware dedicato richiesto | [AI Models](https://nexcmp.com/it/docs/infrastructure/ai-models/) | | **VPN** | Uno o più host Linux (x86_64, systemd, root) con indirizzi IPv4 pubblici sull'interfaccia o instradati verso di essa, HTTPS in uscita verso il tuo pannello | [Nodi VPN e proxy](https://nexcmp.com/it/docs/infrastructure/vpn-proxy-nodes/) | | **IPv6 Proxy** | Host Linux (x86_64, systemd, `nft`, `ip`, `ss`, `sysctl`) con un IPv4 pubblico, porte 80, 443 e 60001-65535 libere e un prefisso IPv6 da /32 a /64 funzionante per il traffico in uscita; accesso SSH con password per l'installazione una tantum | [Nodi VPN e proxy](https://nexcmp.com/it/docs/infrastructure/vpn-proxy-nodes/) | | **Object Storage (S3)** | Un cluster Ceph con RADOS Gateway (RGW), un utente Admin Ops e un endpoint HTTPS pubblico sulla porta 443 | [S3](https://nexcmp.com/it/docs/infrastructure/s3/) | | **Kubernetes** | CloudStack con il Kubernetes Service (CKS) abilitato, almeno una ISO di versione Kubernetes e un'offerta di servizio di control plane gratuita di esattamente 2 vCPU e 2048 MB | [Kubernetes e Private Cloud](https://nexcmp.com/it/docs/infrastructure/kubernetes-and-private-cloud/) | | **Private Cloud** | CloudStack con un'offerta VPC e un'offerta di rete per piano di banda (più un'offerta bloccata a 1 Mbps) | [Kubernetes e Private Cloud](https://nexcmp.com/it/docs/infrastructure/kubernetes-and-private-cloud/) | | **OS & ISO Images** | CloudStack la cui VM di storage secondario può raggiungere Internet per scaricare le immagini dei clienti (link diretti, senza reindirizzamenti); l'account CloudStack può registrare template e ISO | [Modules](https://nexcmp.com/it/docs/infrastructure/modules/) | | **Bandwidth** | Nessun elemento extra con la sorgente predefinita: l'utilizzo viene letto dalle statistiche delle VM di CloudStack. Le VM su Proxmox VE non vengono misurate | [Bandwidth](https://nexcmp.com/it/docs/catalog/bandwidth/) | | **AI Chat and AI Agent** | Un'API compatibile con OpenAI (URL di base, modello e chiave) che il server del pannello può raggiungere. Nessun software aggiuntivo sui tuoi server | [AI providers](https://nexcmp.com/it/docs/ai/ai-providers/) | | **DDoS & BGP** | Un pacchetto add-on che richiede un host router di confine con daemon eseguiti come root (BGP, filtraggio, statistiche di flusso). Non fa parte dell'installazione standard | [Modules](https://nexcmp.com/it/docs/infrastructure/modules/) | | **DDoS Shield** | L'add-on DDoS & BGP | [Modules](https://nexcmp.com/it/docs/infrastructure/modules/) | | **Web SSH terminal** | Un servizio proxy SSH separato e una rotta dedicata. Non fa parte dell'installazione standard; l'AI Agent non ne ha bisogno | [Modules](https://nexcmp.com/it/docs/infrastructure/modules/) | ## Panoramica dei percorsi di rete {#network-paths-at-a-glance} | Da | A | Porta | Scopo | |---|---|---|---| | Server del pannello | Server di gestione CloudStack | 443 o 8080 (in base a come lo pubblichi) | API | | Server del pannello | Nodo Proxmox VE | 8006/tcp | API e console | | Server del pannello | Dell iDRAC | 443/tcp (e la porta VNC, predefinita 5901) | Redfish e console | | iDRAC | Server web ISO | la porta HTTP scelta (ad esempio 8080) | Media virtuali | | Server del pannello | Ceph RGW | 443/tcp | Admin Ops | | Server del pannello | Nodo proxy IPv6 | Porta SSH inserita | Installazione una tantum | | Nodi VPN e proxy | Pannello (tramite nginx) | 443/tcp | Registrazione, heartbeat, configurazione | | Clienti | Nodi VPN e proxy | porte per IP 65001-65535 (VPN); 80, 443, 60001-65535 (proxy IPv6) | Il servizio stesso | ::: tip Mantieni private le reti di gestione Gli indirizzi di gestione di iDRAC e dell'hypervisor devono trovarsi su una rete non raggiungibile dai clienti. NexCMP rifiuta gli indirizzi iDRAC al di fuori degli intervalli privati consentiti. ::: ## Lista di controllo prima della vendita {#checklist-before-you-sell} 1. L'infrastruttura del primo servizio è connessa e **Test connection** è verde. 2. Una zona è pronta per la vendita (vedi [Zones](https://nexcmp.com/it/docs/infrastructure/zones/)): un backend attivo, un piano e un template pronto. 3. È configurato un canale di pagamento (vedi [Payment channels](https://nexcmp.com/it/docs/billing/payment-channels/)). 4. L'e-mail funziona (vedi [SMTP and e-mails](https://nexcmp.com/it/docs/administration/smtp-and-emails/)). 5. Hai effettuato un ordine di test e hai eliminato la VM. --- # Architettura {#architecture} > **Dove nel pannello di amministrazione:** questa è una pagina di riferimento. I servizi descritti qui sono visibili con `sudo nexcmp status`; le connessioni sono configurate in Infrastructure e System › Settings. ## Lo schema {#the-picture} ![Architettura di NexCMP: i clienti raggiungono nginx tramite DNS e opzionalmente Cloudflare, nginx fa da proxy verso il pannello sulla porta 3000, il pannello e il worker si collegano a CloudStack, Proxmox VE, iDRAC, Ceph, ai gateway di pagamento, SMTP e a un provider di intelligenza artificiale, mentre i nodi VPN e proxy IPv6 comunicano a loro volta con il pannello](https://nexcmp.com/it/docs/images/infrastructure/architecture.svg) ### Lo stesso diagramma a parole {#the-same-diagram-in-words} 1. Un cliente o amministratore apre `https://cloud.example.com` (il portale), `https://cloud.example.com/admin` (la console di amministrazione) o chiama la REST API. Il DNS punta il nome sul tuo server o su Cloudflare, che fa da proxy. 2. **nginx** sul server del pannello è in ascolto sulle porte 80 (reindirizzamento e rinnovo del certificato) e 443 (TLS) e inoltra ogni richiesta al **panel** su `127.0.0.1:3000`. Dopo la procedura guidata di configurazione, il pannello rimane in ascolto solo sull'interfaccia di loopback. 3. Il **panel** (`nexcmp.service`) gestisce il portale clienti, la console di amministrazione, la REST API, la procedura guidata di configurazione e i download necessari ai nodi (il binario dell'agent, lo script di installazione, lo strumento da riga di comando `cmp`). Controlla inoltre la tua licenza una volta al giorno. 4. Il **worker** (`nexcmp-vmd.service`) è in ascolto su `127.0.0.1:8112`, accessibile solo localmente. Esegue qualsiasi operazione che richieda tempo o debba avvenire secondo pianificazione: processi di provisioning, sincronizzazione con CloudStack e Proxmox VE, cicli di fatturazione, raccolta del traffico di banda e connessioni alla console del browser. 5. Da questi due processi NexCMP effettua chiamate verso l'esterno: **CloudStack** (API di gestione), **Proxmox VE** (API sulla porta 8006, certificato associato), **Dell iDRAC** (Redfish su HTTPS nella rete di gestione), **Ceph RGW** (S3 e Admin Ops su HTTPS), **gateway di pagamento** (provider Stripe, PayPal, USDT e bonifico bancario, che a loro volta richiamano i tuoi URL webhook), **il tuo server SMTP**, un **provider di IA** con un'API compatibile con OpenAI e opzionalmente **Telegram**. 6. **I nodi VPN** eseguono `cmp-agent`. Ciascun nodo si registra una volta tramite un token monouso, quindi invia un heartbeat ogni 5 secondi tramite HTTPS al pannello e ne riceve la configurazione nella risposta. **I nodi proxy IPv6** vengono installati una volta dal pannello tramite SSH e successivamente prelevano la propria configurazione dal pannello. 7. Lo stato è memorizzato in database SQLite e in alcuni file in `/var/lib/nexcmp`. Le credenziali per CloudStack, Proxmox, S3, iDRAC e il provider di IA vengono salvate in forma crittografata (AES-256-GCM) utilizzando file di chiave principale nella stessa area. ## Servizi e processi {#services-and-processes} | Processo | Eseguito come | In ascolto su | Funzione | |---|---|---|---| | `nginx` | root (worker `www-data`) | 80, 443 | TLS, reindirizzamento, proxy verso il pannello | | `nexcmp` | `nexcmp` | 3000 (tutte le interfacce durante la prima installazione, poi `127.0.0.1`) | Portale, console di amministrazione, API, procedura guidata, download | | `nexcmp-vmd` | `nexcmp` | `127.0.0.1:8112` | Job, sincronizzazione, fatturazione, banda, console | | `nexcmp-update` | root | nessuno | Applica gli aggiornamenti richiesti dalla console di amministrazione (un'unità path attende la richiesta) | | `cmp-agent` (sui nodi VPN) | root | le porte in ascolto della VPN | Invia i report al pannello, esegue listener proxy su IPv4 pubblici | Il pannello e il worker vengono eseguiti come utente ordinario senza alcuna capability Linux, con un file system di sola lettura tranne `/var/lib/nexcmp` e `/var/log/nexcmp`. Non richiedono root, Docker, database separati o Redis. ## File e loro posizioni {#files-and-where-they-are} | Percorso | Contenuto | |---|---| | `/opt/nexcmp` | Il programma: release, `bin/`, file condivisi come il generatore di template. Di proprietà di root, di sola lettura per il servizio. | | `/etc/nexcmp` | Impostazioni del programma di installazione (`install.conf`), porta e bind (`nexcmp.env`). | | `/var/lib/nexcmp` | Database SQLite, branding caricato, cartella di download dell'agente, stato della licenza, file della chiave master. Esegui il backup di questi elementi. | | `/var/log/nexcmp` | Log. | Vedi [Backup and restore](https://nexcmp.com/it/docs/getting-started/backup-and-restore/). I file della chiave master devono essere salvati insieme ai database, altrimenti un database ripristinato non potrà decrittografare le credenziali memorizzate. ## Chi si connette a chi {#who-connects-to-whom} | Direzione | Percorso | Porta | Note | |---|---|---|---| | Da cliente a pannello | Internet, DNS, Cloudflare opzionale, nginx | 443 | Vedi [DNS and Cloudflare](https://nexcmp.com/it/docs/getting-started/dns-and-cloudflare/). | | Da pannello a server delle licenze | `nexcmp.com` | 443 | Attivazione, controllo giornaliero e aggiornamenti. | | Da pannello a Apache CloudStack | API | 443 o 8080 | La console della VM, la banda e le funzionalità Kubernetes utilizzano lo stesso endpoint. | | Da pannello a Proxmox VE | API e console WebSocket | 8006 | Certificato bloccato tramite SHA-256. | | Da pannello a iDRAC | Redfish | 443, VNC 5901 | Solo rete di gestione. | | Da iDRAC a server ISO | HTTP | la tua porta | L'iDRAC effettua il pull dell'ISO. | | Da pannello a Ceph RGW | Admin Ops | 443 | | | Da pannello a SMTP | SMTP | 587 o 465 | | | Da pannello a provider AI | HTTPS | 443 | Solo quando il modulo AI è attivo. | | Da gateway di pagamento a pannello | Webhook | 443 | Chiamate di ritorno da Stripe e PayPal. | | Da nodo a pannello | `cmp-agent` | 443 | Registrazione, heartbeat, aggiornamento. | | Da pannello a nodo proxy IPv6 | SSH | la porta inserita | Solo per la prima installazione. | ## Perché è importante {#why-it-matters} - **Un pannello raggiungibile è un pannello attaccabile.** Mantieni la porta 3000 chiusa una volta completata la procedura guidata di configurazione. L'installatore lo fa già quando il TLS è attivo. - **Il worker deve essere in esecuzione** per consentire qualsiasi creazione o fatturazione. `sudo nexcmp status` mostra sia i servizi sia il controllo dello stato di salute. - **Pianifica i firewall in uscita.** Se il traffico in uscita del server del pannello è filtrato, autorizza le destinazioni nella tabella sopra. - **Il traffico di gestione rimane fuori dal percorso pubblico.** Le connessioni a CloudStack, Proxmox VE, iDRAC e Ceph vanno direttamente dal server del pannello a tali sistemi, mai tramite nginx o Cloudflare. --- # Moduli {#modules} > **Dove nel pannello di amministrazione:** System › Admin › License & updates (`/license`), la scheda **Module**. ## Descrizione {#what-it-does} Un modulo è un servizio o una funzionalità che puoi attivare o disattivare interamente. Un modulo **spento** è nascosto dal menu di amministrazione e i clienti non possono acquistarlo; le sue rotte API restituiscono `404 module_disabled` dove il modulo è un componente aggiuntivo. L'attivazione di un modulo espone solo la funzionalità: l'infrastruttura sottostante deve comunque essere collegata (vedi l'ultima colonna). ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Account | Un amministratore con accesso in scrittura. Il personale di sola visualizzazione può vedere gli interruttori ma non modificarli. | | Infrastruttura | Vedi la tabella: ogni modulo elenca ciò di cui ha bisogno. | | Dipende da | Alcuni moduli ne richiedono altri (DDoS Shield richiede DDoS & BGP). | ## Prepara l'infrastruttura {#prepare-the-infrastructure} Non richiesto per l'interruttore in sé. Collega l'infrastruttura di ciascun modulo come descritto nella pagina collegata nella tabella. ## Collega in NexCMP {#connect-in-nexcmp} 1. Apri **System › Admin › License & updates** e scorri fino alla scheda **Module**. Viene indicato che i moduli disabilitati sono nascosti dal menu di amministrazione e non possono essere acquistati dai clienti. 2. Usa l'interruttore di un modulo. La pagina conferma **Saved: reloading menu** e si ricarica, così il menu cambia immediatamente. ![La scheda Module in License & updates con un interruttore per ciascun modulo](https://nexcmp.com/it/docs/images/infrastructure/modules-01-license-modules.webp) ### I moduli {#the-modules} | Modulo (come mostrato) | Predefinito | Cosa aggiunge | Necessità | Pagina | |---|---|---|---|---| | **Virtual Machines** | sempre attivo | Catalogo VM, ordini, console, snapshot | CloudStack o Proxmox VE | [CloudStack](https://nexcmp.com/it/docs/infrastructure/cloudstack/), [Proxmox VE](https://nexcmp.com/it/docs/infrastructure/proxmox/) | | **Bandwidth** | **on** | Quote, componenti aggiuntivi, avvisi e azioni di superamento soglia per VM, Kubernetes e S3 | Nulla di extra (statistiche VM CloudStack) | [Bandwidth](https://nexcmp.com/it/docs/catalog/bandwidth/) | | **OS & ISO Images** | disattivo | I clienti registrano le proprie immagini OS e ISO, fatturate al GB | CloudStack; accesso a Internet per la relativa VM di storage secondario | [Requirements](https://nexcmp.com/it/docs/infrastructure/requirements/) | | **Kubernetes** | disattivo | Cluster Kubernetes (CKS) | CloudStack con CKS abilitato | [Kubernetes e Private Cloud](https://nexcmp.com/it/docs/infrastructure/kubernetes-and-private-cloud/) | | **Private Cloud** | disattivo | VPC con piani a banda dedicata | CloudStack VPC e offerte di rete | [Kubernetes e Private Cloud](https://nexcmp.com/it/docs/infrastructure/kubernetes-and-private-cloud/) | | **Object Storage** | disattivo | Account S3 su Ceph RGW, con tariffazione a consumo | Ceph RGW e una zona con servizio S3 | [S3](https://nexcmp.com/it/docs/infrastructure/s3/) | | **VPN** | disattivo | VPN sui tuoi nodi | Nodi con `cmp-agent` in esecuzione | [Nodi VPN e proxy](https://nexcmp.com/it/docs/infrastructure/vpn-proxy-nodes/) | | **IPv6 Proxy** | disattivo | Proxy IPv6 sui tuoi nodi | Nodi proxy con un prefisso IPv6 | [Nodi VPN e proxy](https://nexcmp.com/it/docs/infrastructure/vpn-proxy-nodes/) | | **Bare Metal** | disattivo | Server Dell tramite iDRAC: ordini, installazione OS, console, alimentazione | iDRAC 9 su rete di gestione | [Dedicated servers](https://nexcmp.com/it/docs/infrastructure/dedicated/) | | **AI Models** | disattivo | Un gateway per vendere l'accesso ai modelli IA: un'unica chiave per più modelli, prezzi per modello, limiti di consumo, log e fatturazione su wallet | Sorgenti di modelli fornite da te: API compatibile con OpenAI o Anthropic con chiave propria | [AI Models](https://nexcmp.com/it/docs/infrastructure/ai-models/) | | **AI** | disattivo | AI Chat (supporto automatizzato) e AI Agent (gestione VM in linguaggio naturale) | Un provider compatibile con OpenAI | [AI providers](https://nexcmp.com/it/docs/ai/ai-providers/) | | **DDoS Shield** | disattivo | Protezione IP per i clienti; richiede DDoS & BGP, quindi l'opzione resta disabilitata senza di essa | L'add-on DDoS & BGP | sotto | | **DDoS & BGP** | off, **add-on** | Console router edge: BGP, RTBH, XDP, sessioni e traffico edge | Un host edge con demoni root | sotto | ### Funzione dei singoli interruttori {#which-switch-does-what} - **Bare Metal** prevede due livelli. L'interruttore del modulo mostra il menu admin e le API. La vendita ai clienti è un interruttore separato con conferma digitata in **Services › Dedicated Server**, e qualsiasi operazione di scrittura su un iDRAC resta bloccata finché non attivi **live ops** in **Infrastructure › Bare Metal › Safety**. Vedi [Dedicated servers](https://nexcmp.com/it/docs/infrastructure/dedicated/). - Per **Kubernetes**, **Private Cloud**, **VPN**, **IPv6 Proxy** e **Images**, l'interruttore del modulo e quello di vendita nella pagina del servizio controllano la medesima impostazione. - Anche **AI** richiede un provider configurato in **System › Settings › AI provider**. - **AI Models** prevede due livelli. L'interruttore del modulo mostra il menu admin e le API. La vendita ai clienti è un interruttore separato nella parte superiore delle pagine AI Models, disattivato per impostazione predefinita. Vedi [AI Models](https://nexcmp.com/it/docs/infrastructure/ai-models/). ### Moduli caricati all'avvio {#modules-read-at-start-up} Tre funzionalità non corrispondono a normali interruttori. Vengono lette **una sola volta all'avvio dei servizi** e richiedono un'infrastruttura non inclusa nell'installazione standard. | Funzionalità | Impostazione | Stato | Requisiti | |---|---|---|---| | DDoS & BGP | `module_ddos` | Mostrato come **Add-on package** quando disattivato, **Installed** quando attivato. Non è presente alcun interruttore nella console. | Demoni per edge router (BGP, RTBH, XDP, statistiche di flusso) eseguiti come root. Il pannello viene eseguito come utente non privilegiato e non può eseguirli. | | IA | `module_ai` | Un normale interruttore. Le route si aggiornano immediatamente; i job in background di AI Chat (analisi dei ticket, risposte pianificate) si avviano al riavvio successivo dei servizi. La console indica che è consigliato un riavvio. | Il provider AI. | | Terminale Web SSH | `feature_ssh_web` | Disattivato per impostazione predefinita, nessun interruttore nella console | Un servizio proxy SSH separato e la relativa route. Senza di esso, la scheda Console del portale mostra solo VNC. L'**AI Agent non ne ha bisogno**: esegue i comandi tramite una connessione SSH stabilita direttamente dal pannello. | Dopo aver modificato un'impostazione di avvio, riavvia i servizi: `sudo systemctl restart nexcmp nexcmp-vmd`. ## Verifica {#verify} 1. La voce di menu del modulo compare (o scompare) dopo il ricaricamento. 2. Per un modulo rivolto ai clienti, il portale mostra la nuova voce di menu per gli utenti autenticati. Un modulo disattivato non mostra nulla oppure "coming soon". ## Limiti e note {#limits-and-notes} - Disattivare un modulo non elimina nulla. Le macchine virtuali, i cluster, gli account S3 e gli abbonamenti in esecuzione continuano a funzionare e a essere fatturati; i clienti non possono semplicemente crearne di nuovi. - Le pagine delle quote elencano solo i servizi i cui moduli sono attivi. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | La voce di menu non è comparsa | La pagina non è stata ricaricata | Ricarica la console di amministrazione. | | L'interruttore DDoS Shield è disattivato | DDoS & BGP non è installato | DDoS Shield richiede il componente aggiuntivo DDoS & BGP. | | "This module is an add-on package and cannot be switched here" (HTTP 409 o 422) | Tu (o uno script) hai tentato di attivare DDoS & BGP | Si tratta di un pacchetto aggiuntivo; non è presente alcun interruttore. | | "DDoS Shield richiede il componente aggiuntivo DDoS & BGP" | Lo stesso, per DDoS Shield | Installa prima il componente aggiuntivo. | | Una rotta di modulo restituisce 404 `module_disabled` | Il modulo è disattivato | Attiva il modulo. | | AI Chat risponde ma l'indagine sul ticket non si avvia mai | Il modulo AI è stato attivato senza un riavvio | `sudo systemctl restart nexcmp nexcmp-vmd`. | | Il personale di sola lettura non può salvare | Il loro ruolo è di sola lettura | Usa un account amministratore. | --- # Zone {#zones} > **Dove trovarlo nell'amministrazione:** Infrastructure › Datacenter › Zone (`/infra/zones`). La pagina dei dettagli di una zona è `/infra/zones/`. ## Descrizione {#what-it-does} Una **zona** è la posizione scelta da un cliente durante l'ordine: un paese e una città con una bandiera, oltre ai servizi venduti in quel luogo. È un concetto di vendita, distinto dalle zone, dai cluster e dai nodi delle piattaforme sottostanti. Dietro a una zona si collega l'**infrastruttura**: una zona CloudStack, un cluster Proxmox VE, nodi VPN con intervalli IP, un backend S3. La Zona 1 viene creata dalla [procedura guidata di installazione](https://nexcmp.com/it/docs/getting-started/setup-wizard/), con il nome visualizzato e il paese inseriti. Aggiungi altre zone quando disponi di infrastrutture in più luoghi o per assegnare posizioni dedicate a VPN e S3. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Permessi | Un account amministratore. Un ruolo del personale di sola lettura può visualizzare ma non modificare. | | Infrastruttura | Una zona non vende nulla finché non le viene associato qualcosa (vedi "Quale servizio vende dove" sotto). | | Dipende da | [CloudStack](https://nexcmp.com/it/docs/infrastructure/cloudstack/) o [Proxmox VE](https://nexcmp.com/it/docs/infrastructure/proxmox/) per le VM, [nodi VPN e proxy](https://nexcmp.com/it/docs/infrastructure/vpn-proxy-nodes/) per la VPN, [S3](https://nexcmp.com/it/docs/infrastructure/s3/) per l'object storage. | ## Prepara l'infrastruttura {#prepare-the-infrastructure} Non richiesto. Una zona è un record all'interno di NexCMP. ## Collega in NexCMP {#connect-in-nexcmp} ### Crea una zona {#create-a-zone} 1. Apri **Infrastructure › Datacenter › Zone** e clicca su **Add zone**. 2. Compila il modulo: | Campo | Valore di esempio | Note | |---|---|---| | Paese | `United States` | Seleziona la bandiera. | | Città | `New York` | Facoltativo. | | Nome (vietnamita), Nome (inglese) | `New York` | Il nome visualizzato dai clienti in ciascuna lingua. | | Slug | `us-new-york` | a-z, 0-9, trattino, 2-32 caratteri. Compilato automaticamente in base a paese e città finché non ne digiti uno personalizzato. | | Visibilità | Pubblico | **Public** sono visibili a tutti i clienti; **Hidden** vengono assegnate solo da un amministratore. | | Order | `0` | I numeri più bassi compaiono per primi negli elenchi. | | Servizi venduti in questa zona | Virtual Machines (VM), VPN, Object Storage (S3) | Selezionarne almeno uno. | | Active | On | **Off** nasconde la zona ai clienti. | | Predefinito | disattivo | La zona preselezionata per i clienti che non ne hanno scelta una. Esattamente una zona è quella predefinita. | ![Finestra di aggiunta zona con paese, città, slug e servizi spuntati](https://nexcmp.com/it/docs/images/infrastructure/zones-01-add-zone.webp) 3. Fai clic su **Create zone**. L'elenco mostra la zona con la sua bandiera, il proprietario, i servizi, lo stato e il conteggio di VM, piani e infrastruttura collegata. ![Elenco zone con la zona predefinita e una seconda zona](https://nexcmp.com/it/docs/images/infrastructure/zones-02-list.webp) ### Verifica gli elementi collegati {#look-at-what-is-attached} Fai clic su una riga per aprire la zona. La scheda **Provider infrastructure** elenca ciascun backend collegato con il rispettivo provider, tipo (CloudStack o Proxmox VE), area geografica, stato e priorità. La scheda **VPN infrastructure** elenca gli intervalli VPN e i nodi della zona e rimanda al pool VPN. ![Dettaglio zona con la scheda Provider infrastructure](https://nexcmp.com/it/docs/images/infrastructure/zones-03-detail.webp) ### Dove viene venduto ciascun servizio {#which-service-sells-where} | Service | Come viene integrato in una zona | |---|---| | Virtual Machines su CloudStack | La procedura guidata (o **Infrastructure › Cloud provider › CloudStack**) collega CloudStack alla zona 1. | | Virtual Machines su Proxmox VE | Nella scheda **Clusters** del cluster, seleziona **Attach cluster to zone**. Il cluster si unisce a una zona **esistente**, solitamente quella che vende tramite CloudStack. | | VPN | Un nodo VPN che segnala i propri intervalli di IP pubblici crea (o si unisce a) una zona per il proprio paese e inserisce gli intervalli nel pool VPN. Puoi anche assegnare la zona e il nodo di un intervallo in **VPN IP pools**. | | IPv6 Proxy | Un nuovo nodo proxy IPv6 crea la propria zona nello stato **off**. Attiva la zona qui affinché i clienti possano sceglierla. | | Object Storage (S3) | Spunta il servizio S3 nella zona, quindi collega il backend in **Ceph S3 (RGW)**. | ### Quando una zona può vendere macchine virtuali? {#when-can-a-zone-sell-virtual-machines} Una zona mostra il tag **not ready to sell VMs** finché non dispone di almeno un backend attivo e vendibile, **e** di almeno un piano visibile, **e** di almeno un template pronto su quel backend. Il modulo d'ordine per i clienti elenca solo le zone pronte. ## Verifica {#verify} 1. La zona appare nell'elenco come **On**, con la bandiera corretta. 2. La sua pagina di dettaglio mostra il backend o gli intervalli VPN previsti. 3. Per le VM: il tag **not ready to sell VMs** scompare. Nel portale clienti, avvia un ordine e verifica che la zona venga proposta. ## Limiti e note {#limits-and-notes} - In questa versione di NexCMP i clienti ordinano le macchine virtuali nella **default zone** (zona 1). Le altre zone vengono utilizzate per VPN, IPv6 Proxy e Object Storage, oppure per preparare una località prima che disponga di infrastruttura; la nota sotto l'elenco delle zone indica la stessa cosa. - Una zona può essere eliminata solo quando non vi è nulla di collegato: nessun backend, VM, piano o intervallo VPN. La zona predefinita non può essere eliminata; imposta prima un'altra zona come predefinita. - Le zone di proprietà di un rivenditore possono essere solo attivate o disattivate e nascoste o mostrate da te; gli altri campi sono bloccati. - Lo slug fa parte dei riferimenti interni. Sceglilo una sola volta. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | "Nome della zona obbligatorio" / "Seleziona il paese" / "Seleziona almeno 1 servizio" | Un campo obbligatorio è vuoto | Inserisci il nome, seleziona il paese e spunta un servizio. | | "Slug non valido (a-z 0-9 -, 2-32 caratteri)" | Lo slug contiene altri caratteri o ha una lunghezza errata | Usa solo lettere minuscole, cifre e trattini. | | Tag "non pronto per vendere VM" | Nessun backend di vendita attivo, nessun piano o nessun template pronto in quella zona | Collega l'infrastruttura, quindi aggiungi un piano e un template. Vedi [Plans](https://nexcmp.com/it/docs/catalog/plans/) e [Templates](https://nexcmp.com/it/docs/infrastructure/templates/). | | Delete è disabilitato con "still attached" | La zona ha backend, VM, piani o intervalli VPN | Rimuovili o spostali prima. | | Delete è disabilitato con "Default zone" | La zona è quella predefinita | Imposta un'altra zona come predefinita. | | I clienti non vedono la zona | È nascosta, inattiva o non ha alcun servizio spuntato | Imposta Visibility su Public, Active su On e spunta il servizio. | | Manca una zona S3 dal modulo del backend | Il servizio S3 non è spuntato sulla zona | Modifica la zona e spunta **Object Storage (S3)**. | --- # CloudStack > **Dove nell'amministrazione:** Infrastructure › Cloud provider › CloudStack › API connection (`/infra/cloudstack?tab=connect`). La prima connessione può essere effettuata anche nella [setup wizard](https://nexcmp.com/it/docs/getting-started/setup-wizard/), passaggio 2. ## Descrizione {#what-it-does} NexCMP vende macchine virtuali eseguite sul tuo cloud Apache CloudStack. Distribuisce, avvia, arresta, ridimensiona, acquisisce snapshot ed elimina le VM tramite l'API di CloudStack, assegna indirizzi IP pubblici dalla zona, legge l'utilizzo per la fatturazione e la larghezza di banda, e mostra la capacità e lo stato nella console di amministrazione. CloudStack rimane la fonte di verità per gli hypervisor; NexCMP è la vetrina, la fatturazione e il portale sovrastanti. Usa questa pagina quando CloudStack è (o sarà) la tua fonte principale di VM. Per una seconda fonte affiancata, vedi [Proxmox VE](https://nexcmp.com/it/docs/infrastructure/proxmox/). ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Versione di CloudStack | 4.23 è la release testata. La console delle VM richiede la versione 4.18 o successiva e il ridimensionamento live di CPU/RAM di una VM in esecuzione richiede la 4.23 con KVM. | | Tipo di zona | Una zona con almeno una rete guest per le VM dei clienti e un intervallo di IP pubblici con indirizzi liberi. | | Hypervisor | KVM è l'hypervisor testato. | | Account | Un **dominio e un account dedicati** creati per NexCMP. Non usare mai la chiave dell'amministratore ROOT. | | Raggiungibilità API | Il server del pannello deve raggiungere l'URL API del server di gestione (`https://cloudstack.example.com/client/api`) tramite HTTP(S). La console delle VM, la larghezza di banda e le funzionalità di Kubernetes usano lo stesso endpoint. | | Chiave di sola lettura facoltativa | Una seconda chiave di sola lettura consente alla console di amministrazione di mostrare host, storage, VM di sistema e intervalli di IP pubblici. Non necessaria per vendere VM. | | IP pubblico | Indirizzi IPv4 pubblici liberi nella zona. Il prefisso che NexCMP può vendere viene configurato in Sales IP pools. | | Template | Almeno un template pronto e abilitato all'uso con password e un'offerta di servizi visibile al tuo account. Vedi [Templates](https://nexcmp.com/it/docs/infrastructure/templates/). | | Storage | Storage primario per i volumi dell'account e, se vendi snapshot o immagini, storage secondario. | | Dipende da | Nessuno. Kubernetes, Private Cloud, Images e Bandwidth dipendono da questa pagina. | ::: warning Non usare la chiave amministratore ROOT Crea un dominio e un account dedicati per NexCMP. In questo modo la chiave raggiungerà solo quel dominio e una chiave compromessa non potrà intaccare il resto del tuo cloud. La procedura guidata di configurazione verifica inoltre che la rete scelta appartenga alla zona **e** all'account proprietario della chiave. ::: ## Prepara l'infrastruttura {#prepare-the-infrastructure} I comandi utilizzano [CloudMonkey](https://cloudstack.apache.org/) (`cmk`) autenticato come amministratore di CloudStack. Sostituisci i nomi di esempio e i segnaposto tra parentesi angolari. ### Crea un account dedicato e una chiave API {#create-a-dedicated-account-and-api-key} 1. Crea il dominio che conterrà tutto ciò che appartiene a NexCMP. ```bash cmk create domain name=nexcmp ``` Prendi nota di `id` nell'output; viene utilizzato come `` in seguito. 2. Trova il ruolo che desideri assegnare all'account. ```bash cmk list roles type=DomainAdmin filter=id,name ``` | Ruolo | Quando sceglierlo | |---|---| | **Domain Admin** (consigliato) | Set di funzioni completo: VM, reti, progetti per Kubernetes, VPC, immagini. La sua portata si ferma al dominio `nexcmp`. | | User | Solo ciclo di vita delle VM. Un utente semplice non può eliminare definitivamente le VM a meno che l'impostazione globale `allow.user.expunge.recover.vm` non sia true; in tal caso NexCMP arresta la VM e CloudStack la elimina definitivamente dopo `expunge.delay`. | 3. Crea l'account e il suo primo utente. Usa una password casuale lunga; non verrà mai più inserita. ```bash cmk create account name=nexcmp-api username=nexcmp-api \ password='CHANGE-ME-LONG-RANDOM' email=ops@example.com \ firstname=NexCMP lastname=API roleid= domainid= ``` 4. Genera la coppia di chiavi API per il nuovo utente. ```bash cmk list users domainid= username=nexcmp-api filter=id,username cmk generate userkeys id= ``` Copia `apikey` e `secretkey`. Sono la **API key** e la **Secret key** da inserire in NexCMP. NexCMP le memorizza crittografate e in seguito mostra solo gli ultimi quattro caratteri. 5. Assicurati che il dominio non abbia limiti di risorse restrittivi (istanze, volumi, IP pubblici, reti, snapshot, template, progetti). ```bash cmk list resourcelimits domainid= ``` ### Crea la rete guest per le VM dei clienti {#create-the-guest-network-for-customer-vms} Le VM dei clienti vengono distribuite in una rete guest che appartiene al nuovo account. Una rete isolata con un router virtuale (VR) e i servizi Static NAT, Firewall e Port Forwarding funziona bene, poiché NexCMP associa un IP pubblico a ciascuna VM con il NAT statico. ```bash cmk list networkofferings state=Enabled guestiptype=Isolated filter=id,name cmk create network name=customers displaytext=customers zoneid= \ networkofferingid= account=nexcmp-api domainid= ``` Controlla i criteri di egress predefiniti dell'offerta: se sono impostati su "deny", le VM dei clienti non avranno accesso in uscita finché non verranno aggiunte le regole di firewall egress. ### Rendi visibili offerte e template {#make-offerings-and-templates-visible} - **Service offerings** e **network offerings** devono essere pubbliche o assegnate al dominio `nexcmp`, altrimenti l'account non potrà elencarli o utilizzarli. - Registra o condividi almeno un template (vedi [Templates](https://nexcmp.com/it/docs/infrastructure/templates/)). NexCMP elenca i template pronti e in evidenza. ### Facoltativo: chiave di sola lettura per le pagine dell'infrastruttura {#optional-read-only-key-for-infrastructure-pages} Le schede **Capacity**, **Host**, **Storage** e **System VM** e l'elenco degli intervalli di IP pubblici utilizzano una seconda chiave che necessita solo dell'accesso in lettura a sei comandi. Crea un ruolo limitato anziché riutilizzare una chiave amministratore completa: ```bash cmk create role name=nexcmp-readonly type=Admin # is the id printed above for api in listHosts listCapacity listSystemVms listVlanIpRanges listClusters listStoragePools; do cmk create rolepermission roleid= rule=$api permission=allow done cmk create rolepermission roleid= rule='*' permission=deny ``` Quindi crea un account con quel ruolo (nel dominio ROOT, poiché legge i dati a livello di zona), genera le relative chiavi come al passaggio 4 e inseriscile come **RO API key** nella sezione successiva. ### Verifica il percorso di rete {#check-the-network-path} Dal server del pannello: ```bash curl -fsS -o /dev/null -w '%{http_code}\n' https://cloudstack.example.com/client/api ``` Qualsiasi risposta HTTP (anche 4xx) dimostra che la porta è raggiungibile. Un timeout indica un problema di firewall o DNS dalla tua parte. ## Collega in NexCMP {#connect-in-nexcmp} ### Nella procedura guidata di configurazione {#in-the-setup-wizard} Il passaggio 2 della [setup wizard](https://nexcmp.com/it/docs/getting-started/setup-wizard/) richiede gli stessi valori. **Test connection** elenca le zone e le reti visibili alla chiave; scegli la zona e la rete guest, un nome visualizzato per la zona e il paese, quindi fai clic su **Save CloudStack**. La procedura guidata rifiuta una rete che non si trova in quella zona o non è visibile alla chiave. ![Passaggio 2 della procedura guidata con l'URL dell'API di CloudStack e le chiavi inserite, oltre alla zona e alla rete scelte dopo Test connection](https://nexcmp.com/it/docs/images/infrastructure/cloudstack-01-wizard-step.webp) ### Successivamente, nella console di amministrazione {#later-in-the-admin-console} 1. Apri **Infrastructure › Cloud provider › CloudStack** e seleziona la scheda **API connection**. 2. Compila la scheda **Connection**: | Campo | Valore di esempio | |---|---| | Endpoint API | `https://cloudstack.example.com/client/api` | | Chiave API (accesso in scrittura) | `XXXX` (lascia vuoto per mantenere la chiave salvata) | | Chiave segreta | `XXXX` | | Chiave API RO / Chiave segreta RO | opzionale, dall'account di solo lettura | | ID zona | l'UUID della tua zona | ![La scheda di connessione API con un endpoint di esempio e chiavi mascherate](https://nexcmp.com/it/docs/images/infrastructure/cloudstack-02-connect-form.webp) 3. Fai clic su **Test connection** prima di salvare. Testa le chiavi inserite senza salvarle: la chiave di scrittura con `listZones` e `listCapabilities`, e la chiave di sola lettura con `listSystemVms`. 4. Fai clic su **Save connection**. Mantieni attivo **Enable CloudStack connection**; disattivandolo, il worker interromperà tutti i processi di CloudStack senza perdita di dati. 5. Apri **Services › Virtual Machines › Policy › Provisioning** per impostare la rete guest predefinita, le offerte personalizzate e la coppia di chiavi predefinita per le nuove VM. ![Criteri VM, scheda Provisioning, con l'ID di rete predefinito](https://nexcmp.com/it/docs/images/infrastructure/cloudstack-04-provisioning.webp) 6. Apri **Infrastructure › Cloud provider › Sales IP pools** e, in **Configure sales ranges**, imposta **Sellable IP range prefixes** (ad esempio `203.0.113.`) e **Prefixi IP esclusi** se alcuni indirizzi nella zona non devono mai essere venduti. Lascia il prefisso vuoto per consentire qualsiasi indirizzo libero. ![Pool di IP di vendita con il prefisso vendibile 203.0.113. impostato](https://nexcmp.com/it/docs/images/infrastructure/cloudstack-05-sales-ip-pool.webp) ### Cosa legge e scrive NexCMP {#what-nexcmp-reads-and-writes} | Area | Letture | Modifiche | |---|---|---| | VMs | elenco, stati, cronologia di utilizzo, endpoint della console | distribuzione, avvio, arresto, riavvio, reinstallazione, eliminazione, ridimensionamento, reimpostazione della password e della chiave SSH | | Dischi e snapshot | volumi, snapshot di VM, backup | creazione, collegamento, scollegamento, ridimensionamento, eliminazione, snapshot, ripristino | | Networking | reti, router, IP pubblici, firewall, port forwarding, regole di bilanciamento del carico | associazione e rilascio di IP pubblici, NAT statico, firewall, port forwarding, regole di egress, reti e ACL per Private Cloud | | Catalogo | offerte di servizi, dischi e reti, template, ISO, tipi di sistemi operativi | registrazione ed eliminazione di template e ISO (Immagini), offerte di servizi durante la creazione di piani personalizzati | | Kubernetes | versioni supportate, cluster, configurazione | progetti, limiti di risorse, reti, cluster (modulo Kubernetes) | | Chiave di sola lettura | host, cluster, pool di storage, VM di sistema, capacità, intervalli IP VLAN | nessuna | ### CPU e RAM in tempo reale e larghezza di banda {#live-cpu-and-ram-and-bandwidth} - **Hot-plug.** Una VM in esecuzione può essere ridimensionata senza riavvio solo se il template lo consente (scalabile dinamicamente) e il guest attiva nuove CPU e RAM online. NexCMP attiva Auto Scaling per i template il cui nome termina in `vN` con N pari o superiore a 6, o quando viene impostato manualmente nel campo **vCPU/RAM hot-plug** del template. Vedi [Templates](https://nexcmp.com/it/docs/infrastructure/templates/). - **Origine larghezza di banda.** Con le impostazioni predefinite, NexCMP misura il traffico dalle statistiche delle VM CloudStack (`listVirtualMachinesUsageHistory`, rilevate ogni 5 minuti e sommate per interfaccia di rete della VM). I dati includono il traffico tra le VM, quindi possono risultare leggermente superiori rispetto a quanto conterebbe un router di margine. Mantieni abilitata la raccolta delle statistiche delle VM CloudStack; gli intervalli più lunghi della conservazione delle statistiche vengono ignorati. Vedi [Bandwidth](https://nexcmp.com/it/docs/catalog/bandwidth/). ## Verifica {#verify} 1. **Test connection** restituisce "Write key: OK" con la tua zona e la versione di CloudStack. 2. **Infrastructure › Cloud provider › Providers** mostra il provider come attivo con un orario di test recente. Il pannello dello stato della dashboard non mostra più "CloudStack: not connected". 3. **Sales IP pools** elenca gli indirizzi liberi (si aggiorna circa una volta al minuto). 4. Ordina una piccola VM dal portale clienti o dalla console di amministrazione e verifica che raggiunga lo stato Running, disponga di un IP pubblico e che tu possa aprire la console. ## Limiti e note {#limits-and-notes} - In questa versione di NexCMP è possibile connettere un solo cluster CloudStack. La finestra di dialogo **Add cloud provider** può testare le chiavi di un secondo cluster ma non può salvarle. - Una zona CloudStack è associata alla zona predefinita di NexCMP; un CloudStack con più zone è limitato alla zona inserita, quindi le VM, gli IP e le reti delle altre zone vengono ignorati. - L'eliminazione della rete guest in CloudStack causa il fallimento di ogni nuovo deployment. La console di amministrazione mostra un avviso rosso quando la rete scompare. - Le credenziali non lasciano mai il server. L'API restituisce solo gli ultimi quattro caratteri. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | `listCapabilities: cloudstack 401: unable to verify user credentials and/or request signature` | Chiave API o segreto errati, chiave di un altro utente o problema di clock sul server del pannello | Rigenera le chiavi con `cmk generate userkeys` e incollale entrambe. Controlla l'ora del server del pannello. | | Test: `listZones: …` o timeout | Il server del pannello non riesce a raggiungere l'URL dell'API | Controlla DNS, firewall e il percorso `/client/api` esatto. | | Procedura guidata: "network not found in that zone for this API key" | La rete scelta appartiene a un altro account o a un'altra zona | Crea la rete nell'account dedicato (vedi sopra) e riesegui **Test connection**. | | Procedura guidata: "pick a zone and a network" | Test non eseguito oppure nessuna zona o rete selezionata | Fai clic su **Test connection** e seleziona entrambi gli elenchi. | | Banner "Chiave CloudStack non configurata" | Nessuna chiave ancora salvata ("Connect later") | Compila la scheda Connection, **Save connection**, quindi **Test connection**. | | Banner "CloudStack connection is OFF" | L'interruttore **Enable CloudStack connection** è disattivato | Attivalo e salva. | | Chiave di sola lettura: "unusable …" nel test | Autorizzazione del ruolo mancante o account errato | Verifica i sei comandi consentiti e che l'account si trovi nel dominio ROOT. | | "Zone public IP ranges not measured yet" o "no public IP ranges declared" | Nessuna chiave di sola lettura, oppure la zona non ha effettivamente alcun intervallo pubblico | Aggiungi la chiave di sola lettura o un intervallo di IP pubblici in CloudStack. | | "Pool vuoto — attendi 60 s per la sincronizzazione vmd" | L'elenco degli IP viene aggiornato dal worker una volta al minuto | Attendi un minuto e ricarica. | | "IP liberi esauriti nell'intervallo 203.0.113." | Tutti gli indirizzi nel prefisso vendibile sono occupati | Aggiungi indirizzi alla zona, amplia il prefisso o rilascia gli IP non utilizzati. | | "Impossibile recuperare i dati di rete (CloudStack non risponde o la chiave non ha i permessi)" | La chiave ha perso l'accesso oppure CloudStack è disattivato | Esegui **Test connection**; verifica che l'account sia abilitato. | | "La rete guest NON esiste" | La rete è stata eliminata in CloudStack | Crea nuovamente la rete e impostala come predefinita in Provisioning. | --- # Proxmox VE > **Dove nel pannello di amministrazione:** Infrastructure › Cloud provider › Providers (`/infra/providers`), quindi la pagina del provider (`/infra/providers/`) con le schede Overview, Clusters, VMs, Servers e Credentials. I piani si impostano in Services › Virtual Machines › Plans & pricing (`/vm/catalog`). ## Descrizione {#what-it-does} NexCMP può vendere macchine virtuali eseguite su uno o più cluster Proxmox VE, in affiancamento o in sostituzione di CloudStack. Una VM viene creata clonando un template OS con clone completo, quindi configurata tramite cloud-init: dimensioni, indirizzo IP da un pool definito dall'utente, password di root e chiave SSH. I clienti ottengono il controllo dell'alimentazione, la console, gli snapshot, la reinstallazione, il reset della password e le metriche nel portale. Non vedono mai il cluster, il nodo o il nome dell'origine. Usalo quando utilizzi già Proxmox VE o per offrire un secondo pool di VM con prezzi differenti. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Proxmox VE | PVE 9.x. L'integrazione è stata verificata sulla 9.2. Richiede il contenuto storage `import` e l'opzione disco `import-from` (PVE 8.2 o versioni successive). | | Rete dal pannello | HTTPS verso l'API del cluster, `https://:8006`. Nessun percorso, nome utente o query. Sia il pannello che il worker si connettono; la console del browser viene inoltrata tramite proxy attraverso il pannello. | | Account | Un utente PVE dedicato con un **API token** e un ruolo personalizzato con i privilegi elencati di seguito. Non usare mai `root@pam`. | | Storage | Uno storage per i dischi delle VM che supporta i clone (ad esempio `local-lvm`). Per il generatore di template integrato, lo storage denominato `local` con i tipi di contenuto `import` e `snippets`. | | Rete | Un bridge Linux (ad esempio `vmbr0`) che raggiunge la rete in cui risiedono gli IP dei clienti. Usa un bridge compatibile con le VLAN se inserisci un tag VLAN. | | IP | Un blocco IPv4 (da /16 a /30) instradato verso quel bridge, con un gateway. NexCMP assegna gli indirizzi in autonomia; Proxmox non dispone di una gestione degli IP. | | Template | Una VM template cloud-init per ciascun OS, su ogni nodo su cui effettui il deployment, con il guest agent QEMU. | | Zona | Una zona esistente a cui collegare il cluster. Vedi [Zones](https://nexcmp.com/it/docs/infrastructure/zones/). | | Dipende da | Nessuno. | ## Prepara l'infrastruttura {#prepare-the-infrastructure} Esegui i comandi come root su qualsiasi nodo del cluster. ### 1. Crea un ruolo, un utente e un API token con privilegi minimi {#_1-create-a-least-privilege-role-user-and-api-token} 1. Crea il ruolo. L'elenco dei privilegi corrisponde esattamente a ciò che utilizza NexCMP; non contiene nulla che modifichi utenti, definizioni di storage o il datacenter. ```bash pveum role add NexCMP -privs "VM.Allocate VM.Clone VM.Config.CDROM VM.Config.CPU VM.Config.Cloudinit VM.Config.Disk VM.Config.HWType VM.Config.Memory VM.Config.Network VM.Config.Options VM.PowerMgmt VM.Audit VM.Console VM.Snapshot VM.Snapshot.Rollback VM.Backup VM.GuestAgent.Audit VM.GuestAgent.Unrestricted Datastore.Audit Datastore.AllocateSpace Datastore.AllocateTemplate Sys.Audit Sys.AccessNetwork SDN.Use SDN.Audit Pool.Audit Mapping.Audit Mapping.Use" ``` `Sys.AccessNetwork` è richiesto per il download dell'immagine cloud. PVE 9 non dispone del privilegio `VM.Monitor`; non aggiungerlo. 2. Crea l'utente e un token. `--privsep 1` significa che i diritti del token corrispondono all'**intersezione** tra i permessi dell'utente e quelli propri del token. ```bash pveum user add nexcmp@pve --comment "NexCMP" pveum user token add nexcmp@pve api --privsep 1 ``` Il comando stampa il token **secret una sola volta** (un UUID). Copialo adesso. L'ID del token è `nexcmp@pve!api`. 3. Assegna il ruolo **sia** all'utente che al token. Questo è il passaggio che spesso si dimentica: con la separazione dei privilegi, solo il token riceve errori 403 come `Datastore.Audit` se l'utente non ha i permessi. ```bash pveum acl modify / --roles NexCMP --users nexcmp@pve pveum acl modify / --roles NexCMP --tokens 'nexcmp@pve!api' ``` 4. Verificalo dal server del pannello: ```bash curl -sk -H 'Authorization: PVEAPIToken=nexcmp@pve!api=' https://192.0.2.10:8006/api2/json/version ``` Un documento JSON con un `version` indica che il token funziona. (`-k` serve solo per questa verifica rapida; NexCMP memorizza il certificato autonomamente, vedi sotto.) ### 2. Controlla il bridge e lo storage {#_2-check-the-bridge-and-the-storage} ```bash pvesm status # storages, type, content and free space ip -br link show type bridge ``` - Le VM dei clienti ricevono `virtio` interfacce di rete sul bridge inserito in NexCMP. Se configuri una VLAN, il bridge deve supportare le VLAN. - Posiziona le VM dei clienti su un bridge o una VLAN **separati dall'indirizzo di gestione del nodo**. Se condividono una rete, il set di IP di gestione automatico del firewall di Proxmox apre le porte 22, 8006, 3128, 5900-5999 e 60000-60050 del nodo a ogni VM in quella rete. Se non puoi separarli, aggiungi una regola DROP esplicita per la subnet delle VM verso tali porte prima della regola ACCEPT di gestione. ### 3. Note sullo storage (LVM-thin) {#_3-storage-notes-lvm-thin} - Lascia il **zeroing del thin-pool sui valori predefiniti**. Disattivarlo (`lvchange -Zn`) può lasciare vecchi dati nei blocchi appena allocati e corrompere le tabelle delle partizioni o i file system delle VM clonate. - I dischi che segnalano "write cache: disabled" possono clonare a pochi MB/s. Controlla con `hdparm -W /dev/sdX` e abilita la cache di scrittura se il disco dispone di protezione contro la perdita di alimentazione. ### 4. Abilita il contenuto `import` (solo per il generatore di template integrato) {#_4-enable-the-import-content-only-for-the-built-in-template-builder} Il generatore integrato scarica l'immagine cloud nello storage denominato `local` e crea il template da essa. Aggiungi `import` (e `snippets`) all'elenco dei contenuti di quello storage. Mantieni i tipi che usi già; `--content` sostituisce l'intero elenco: ```bash pvesm status --storage local # note the current content pvesm set local --content iso,vztmpl,backup,import,snippets ``` ### 5. Crea un template OS da un'immagine cloud {#_5-build-an-os-template-from-a-cloud-image} Un template è una VM cloud-init clonata da NexCMP. Ciascuno è registrato sotto una breve **OS key** come `ubuntu-24.04` con il relativo ID della VM. Crea un template per OS **su ogni nodo che riceverà le VM**, poiché il clone viene eseguito sul nodo scelto. **Opzione A, consigliata: crealo tu stesso.** Le immagini cloud standard di Ubuntu e Debian non contengono il guest agent e non consentono il login come root, mentre NexCMP imposta la password di root tramite cloud-init. Prepara prima l'immagine: ```bash apt install -y libguestfs-tools wget -O noble.qcow2 https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img virt-customize -a noble.qcow2 --install qemu-guest-agent \ --write /etc/cloud/cloud.cfg.d/99-nexcmp.cfg:$'ssh_pwauth: true\ndisable_root: false\n' \ --write /etc/ssh/sshd_config.d/00-nexcmp.conf:$'PermitRootLogin yes\nPasswordAuthentication yes\n' ``` Quindi crea la VM del template (l'ID 9000 è un esempio; mantieni gli ID dei template sotto il valore `vmid from`, predefinito 1000): ```bash qm create 9000 --name tpl-ubuntu-24-04 --memory 2048 --cores 2 --cpu host --ostype l26 \ --scsihw virtio-scsi-single --net0 virtio,bridge=vmbr0 --agent 1 --serial0 socket --vga serial0 qm set 9000 --scsi0 local-lvm:0,import-from=$PWD/noble.qcow2,discard=on,iothread=1 qm set 9000 --ide2 local-lvm:cloudinit --boot order=scsi0 qm template 9000 ``` **Opzione B: il generatore integrato.** La scheda **Create OS template from cloud image** nella scheda Clusters (vedi sotto) scarica un'immagine qcow2, crea il template e lo registra. Crea la VM con cloud-init e il flag del guest agent, ma non modifica il contenuto dell'immagine. Usala solo con un'immagine che consente già il login come root e avvia il guest agent, oppure quando fornisci anche uno snippet vendor-data di cloud-init. Il guest agent è necessario per **Reset password** e per mostrare l'indirizzo IP della VM. ### 6. Conosci l'impronta digitale del certificato (facoltativo) {#_6-know-the-certificate-fingerprint-optional} NexCMP considera affidabile il cluster memorizzando l'impronta digitale SHA-256 del suo certificato TLS, quindi un certificato autofirmato va benissimo. Per visualizzare il valore che NexCMP memorizzerà: ```bash openssl x509 -in /etc/pve/local/pve-ssl.pem -noout -fingerprint -sha256 ``` ## Collega in NexCMP {#connect-in-nexcmp} 1. Apri **Infrastructure › Cloud provider › Providers** e fai clic su **Add cloud provider**. Scegli **Proxmox VE** e compila i campi: | Campo | Valore di esempio | |---|---| | Name | `Proxmox cluster 1` | | Endpoint | `https://192.0.2.10:8006` | | Token id | `nexcmp@pve!api` | | Token secret | `XXXX` (l'UUID stampato al passaggio 1) | | Slug | `pve-1` (a-z, 0-9, trattino, 2-32 caratteri) | | Default node | `pve1` (vuoto: il nodo online con più RAM libera) | | Storage | `local-lvm` | | Bridge | `vmbr0` | ![Finestra di dialogo Aggiungi provider cloud con Proxmox VE selezionato ed esempi di endpoint, token e valori di storage](https://nexcmp.com/it/docs/images/infrastructure/proxmox-01-add-provider.webp) 2. Fai clic su **Save & open provider** e inserisci un motivo quando richiesto. Il token viene crittografato prima di essere memorizzato. 3. Nella scheda **Overview** fai clic su **Test connection**. Il primo test riuscito **memorizza l'impronta digitale TLS del cluster**; da quel momento in poi verrà rifiutato qualsiasi certificato differente. 4. Apri la scheda **Clusters**. La scheda **Node · storage · bridge** elenca ciò che l'API rileva; la scheda **Cluster configuration** contiene le impostazioni: | Campo | Significato | |---|---| | Default node | Nodo utilizzato per le nuove VM. Se vuoto, indica il nodo online con più RAM libera. | | Storage, Bridge, VLAN | Storage del disco, bridge NIC e tag VLAN facoltativo (0 indica nessun tag). | | CPU type | `host` per impostazione predefinita. Utilizza `x86-64-v2-AES` quando i nodi dispongono di generazioni di CPU differenti. | | vmid from | Primo ID di VM assegnato alle VM dei clienti (predefinito 1000). | | Storage ISO, Storage backup | Lascia vuoto a meno che tu non li utilizzi; se vuoto, le funzioni ISO e di backup non vengono offerte. | | Template OS | Uno per riga, `os-key=vmid`, ad esempio `ubuntu-24.04=9000`. | | Pinned TLS fingerprint (SHA-256) | Compilato dal primo test. Cancellalo ed esegui nuovamente il test dopo aver sostituito il certificato del cluster. | ![Scheda Clusters, scheda Cluster configuration con esempio di nodo, storage, bridge ed elenco di template OS](https://nexcmp.com/it/docs/images/infrastructure/proxmox-03-cluster-config.webp) 5. Facoltativo: se hai utilizzato l'Opzione B precedente, compila **Create OS template from cloud image** (chiave OS `ubuntu-24.04`, vmid `9000`, nodo `pve1`, URL dell'immagine qcow2) e fai clic su **Create template**. L'operazione viene eseguita in background per alcuni minuti; il risultato si trova nel registro di audit. ![Scheda Create OS template from cloud image con un esempio di URL di immagine Ubuntu](https://nexcmp.com/it/docs/images/infrastructure/proxmox-04-template-from-image.webp) 6. Fai clic su **Add pool** in **Cluster IP pool** e crea il pool da cui le VM attingono gli indirizzi: | Campo | Valore di esempio | |---|---| | Name | `customers-1` | | CIDR | `198.51.100.0/24` | | Gateway | `198.51.100.1` (mai assegnato a una VM) | | DNS | `1.1.1.1,8.8.8.8` (da 1 a 4 indirizzi IPv4) | | Bridge, VLAN | `vmbr0`, `0` | | Already used IPs | uno per riga, `ip note`, ad esempio `198.51.100.10 monitoring` | NexCMP non assegna mai l'indirizzo di rete, l'indirizzo di broadcast, il gateway o un indirizzo riservato. I pool dello stesso cluster non possono sovrapporsi. Un pool può essere eliminato solo quando nessuno dei suoi indirizzi è in uso. ![Finestra di dialogo Aggiungi pool IP con un esempio di /24 e gateway](https://nexcmp.com/it/docs/images/infrastructure/proxmox-05-ip-pool.webp) 7. In **Attach cluster to zone**, scegli la zona e, facoltativamente, il nome di un nodo, quindi fai clic su **Attach to zone**. Il cluster si unisce alla zona che già vende VM, consentendo a una zona di includere contemporaneamente CloudStack e Proxmox. La nuova risorsa **non viene venduta per impostazione predefinita** e non modifica il comportamento dei piani esistenti. ![Scheda Attach cluster to zone con una zona esistente selezionata](https://nexcmp.com/it/docs/images/infrastructure/proxmox-06-attach-zone.webp) 8. Apri **Services › Virtual Machines › Plans & pricing** e fai clic su **Add plan**. In **Infrastructure source** scegli il cluster Proxmox, quindi imposta CPU, RAM, disco e prezzo. Un piano Proxmox non richiede alcuna offerta CloudStack. Per vendere la stessa configurazione da entrambe le fonti, utilizza **Clone** su un piano e seleziona l'altra fonte. Il disco del piano deve essere almeno grande quanto il disco del template; Proxmox non è in grado di ridurre le dimensioni di un disco. ### Importa una VM già esistente {#import-a-vm-that-already-exists} Apri la scheda **Servers** per elencare le macchine virtuali sul cluster. **Import** assegna una VM esistente a un account cliente senza alcun costo: non viene fatturato nulla per ore, tempo di spegnimento o traffico. Il cliente può avviare, arrestare, riavviare e aprire la console ma non può eliminarla; solo un amministratore può farlo. Durante l'importazione NexCMP legge solamente dal cluster. - Il cluster deve essere associato a una zona **con il nome del nodo** di quella VM (lascia vuoto il nodo e le importazioni segnalano che la regione non è configurata). - Per rendere una VM **protetta** (arresto, riavvio, reinstallazione, ripristino di snapshot, eliminazione e cambio piano vengono rifiutati), importala dalla riga di comando con `--protect`: ```bash sudo -u nexcmp /opt/nexcmp/bin/nexcmp px-import --provider pve-1 --server-ref pve1/101 --account-id 12 --hostname web-1 --protect ``` ### Cosa è supportato e cosa non lo è su Proxmox {#what-is-and-is-not-supported-on-proxmox} | Funzionalità | Proxmox VE | |---|---| | Crea, accendi/spegni/riavvia, elimina | Sì | | Ridimensiona CPU e RAM, ingrandisci il disco | Sì, ma la VM viene arrestata, modificata e riavviata (nessun ridimensionamento a caldo) | | Snapshots | Sì, fino a 5 per VM: crea, elenca, ripristina, elimina | | Reinstallazione | Sì: la VM viene ricostruita dal template e mantiene il suo ID, IP e impostazioni, con una nuova password | | Reimposta password | Sì, tramite il guest agent | | Console | Sì, una console via browser inoltrata dal pannello | | Metriche | Sì: CPU, memoria, rete e disco | | Montaggio ISO, backup, firewall, IPv6, port forwarding, cambio IP, volumi extra, Auto Scaling, DDoS Shield, VPC, misurazione della banda | Non disponibile. La pagina della VM del cliente nasconde ciò che un source non può fare. | ## Verifica {#verify} 1. **Test connection** mostra OK e lo stato del provider è attivo. 2. **Clusters** elenca i tuoi nodi come online, con lo storage e il bridge. 3. **Cluster IP pool** mostra i conteggi degli indirizzi liberi, usati e trattenuti. 4. La chiave del sistema operativo compare tra i template della zona in **Services › Virtual Machines › Template** dopo che il cluster è stato collegato. 5. Ordina una VM di test da un piano che utilizza il cluster. Dovrebbe ottenere un indirizzo dal pool, una password di root e una console funzionante; il pool mostra un indirizzo utilizzato. ## Limiti e note {#limits-and-notes} ::: tip Zone a sorgente mista A partire da NexCMP 1.4.0, il listino prezzi pubblico di Cloud Server funziona anche quando CloudStack e Proxmox VE condividono una zona. Ciascun piano utilizza la propria **Infrastructure source**. Dopo aver collegato un cluster, controlla il listino prezzi pubblico ed effettua un ordine di prova per ciascuna sorgente. ::: - È possibile aggiungere più cluster Proxmox. Ciascuno corrisponde a un provider. - Una zona offre un source predefinito; un piano con il proprio **Infrastructure source** viene distribuito esattamente su quel cluster, a condizione che il cluster sia attivo e si trovi nella zona del piano. - Un cluster dietro la stessa zona di CloudStack mantiene i suoi piani legacy su CloudStack. Esegui un test d'ordine completo prima del lancio. - Il token API può essere solo sostituito, mai visualizzato. Sostituiscilo nella scheda **Credentials**: crea prima il nuovo token in Proxmox, inseriscilo, esegui **Test connection**, quindi revoca il vecchio token. - Le azioni Test, Sync e cluster-info sono limitate a sei chiamate al minuto per amministratore. - NexCMP fattura ai tuoi clienti; i costi dell'hardware e delle licenze del cluster sono a tuo carico. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | Test: "Key rejected (wrong access key / secret, or revoked)" o HTTP 401/403 | ID token o secret errati, oppure l'ACL è stata assegnata solo al token | Esegui nuovamente i due comandi `pveum acl modify` (utente **e** token) e verifica che l'ID del token sia `user@realm!tokenid`. | | Test: "Could not connect to the provider" o "Timed out" | Firewall, host o porta errati | Controlla `https://host:8006` dal server del pannello. | | Test: "Endpoint non valido o non presente nella allowlist" | L'endpoint contiene un percorso, un utente, una query oppure non è HTTPS | Usa esattamente `https://host:8006`. | | "il certificato TLS del cluster NON corrisponde al fingerprint associato" | Il certificato del cluster è stato sostituito | Cancella **Pinned TLS fingerprint** nella scheda Clusters, salva e riesegui **Test connection**. | | Slug rifiutato | Non rispetta a-z, 0-9, trattino o non ha una lunghezza di 2-32 caratteri | Usa qualcosa di simile a `pve-1`. | | "Formato ID token: user@realm!tokenid e secret obbligatorio" | ID token o segreto mancante | Inseriscili entrambi; il segreto è l'UUID stampato al momento della creazione del token. | | "Riga del template non valida: …" | Una riga in **Template OS** non è `key=vmid` | Usa lettere, cifre, `.`, `_`, `-` nella chiave e un vmid di almeno 100. | | "Chiave OS: a-z 0-9 . _ - e vmid ≥ 100" | Chiave o ID non validi in **Create template** | Correggi la chiave del sistema operativo e usa un vmid disponibile. | | "vmid … already exists" durante la creazione di un template | Il vmid è già in uso | Scegli un altro ID. | | "l'URL punta a un indirizzo interno" | L'URL dell'immagine è un IP interno | Usa un URL pubblico; i nomi vengono risolti da Proxmox. | | L'attività del template fallisce durante il download | Lo storage `local` non dispone del contenuto `import` | `pvesm set local --content …,import,snippets`, quindi riprova. Un nome file deve terminare con `.qcow2`, `.raw`, `.vmdk`, `.ova` o `.ovf`. | | "cluster has no online nodes" o "node … is not online" | Il nodo predefinito è spento o scritto in modo errato | Correggi **Default node** o lascialo vuoto. | | "l'immagine non appartiene al cluster" | Il sistema operativo del piano non è presente in **Template OS** | Aggiungi la chiave all'elenco e salva. | | La distribuzione rimane in attesa e poi fallisce durante la clonazione | La VM del template non si trova sul nodo scelto | Crea il template su quel nodo oppure imposta **Default node** sul nodo che lo contiene. | | Il cliente non riesce ad accedere come root | L'immagine blocca il login come root | Ricrea il template come descritto nell'Opzione A. | | Il ripristino della password non ha alcun effetto | Agent guest non installato nel guest | Installa e abilita `qemu-guest-agent` nel template. | | "Nome, CIDR e gateway sono obbligatori" | Campo del pool mancante | Compilali tutti e tre. | | Pool create: "overlaps with pool …", "gateway must be within range (not network/broadcast address)" oppure "cidr: network address must be …" | Pool sovrapposto, gateway errato o CIDR non su un confine di rete | Usa un intervallo libero, un gateway al suo interno e un CIDR scritto come indirizzo di rete (ad esempio `198.51.100.0/24`). | | Import: "la region non è impostata" | Il cluster è collegato senza il nome del nodo della VM | Collega il cluster alla zona specificando il nome del nodo. | --- # Template di OS e ISO {#os-templates-and-isos} > **Dove nell'admin:** Services › Virtual Machines › Template (`/vm/templates`). I template Proxmox sono elencati per cluster in Infrastructure › Cloud provider › Providers › (cluster) › Clusters. ## Descrizione {#what-it-does} Un template è l'immagine del sistema operativo da cui si avvia una nuova VM. NexCMP non memorizza direttamente le immagini: legge quelle segnalate da CloudStack (pronte, in evidenza) o quelle elencate per un cluster Proxmox, permettendoti di scegliere quali vendere assegnando un nome orientato al cliente, un’icona e un utente di accesso. Questa pagina mostra come preparare immagini perfettamente compatibili con NexCMP: accesso tramite password, ridimensionamento live di CPU e RAM, file di swap e disco di root che si espande fino alle dimensioni del piano. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Generatore di template CloudStack | Una macchina Linux con `libguestfs-tools` (`virt-customize`, `virt-sparsify`, `guestfish`), `qemu-utils`, `curl` e circa 5 GB di spazio libero su disco. Non sono richiesti KVM né i permessi di root. Accesso a Internet per l'installazione dei pacchetti (o compilazione con `--offline`). | | Dove si trova il generatore | È incluso in ogni release in `/opt/nexcmp/releases//share/templates/` sul server del pannello. Non è necessario eseguirlo lì: basta copiare la cartella su qualsiasi macchina Linux. | | Server Web | Qualsiasi server HTTP(S) raggiungibile dalla VM di storage secondario di CloudStack per pubblicare il file `.qcow2` completato. Non deve necessariamente essere raggiungibile da Internet. | | CloudStack | Un account autorizzato a registrare i template, l'ID della zona e di un tipo di OS corrispondente. Vedi [CloudStack](https://nexcmp.com/it/docs/infrastructure/cloudstack/). | | Proxmox VE | VM template Cloud-init con QEMU guest agent, una per OS e per nodo. Vedi [Proxmox VE](https://nexcmp.com/it/docs/infrastructure/proxmox/). | | Dipende da | [CloudStack](https://nexcmp.com/it/docs/infrastructure/cloudstack/) o [Proxmox VE](https://nexcmp.com/it/docs/infrastructure/proxmox/) collegati preventivamente. | ## Prepara l'infrastruttura {#prepare-the-infrastructure} ### CloudStack: compila un template {#cloudstack-build-a-template} Immagini di base supportate (l'immagine del produttore viene scaricata e il relativo checksum verificato prima di qualsiasi modifica): | Immagine | `--distro` | Utente di accesso | |---|---|---| | Ubuntu 22.04 | `ubuntu-22.04` | `ubuntu` | | Ubuntu 24.04 | `ubuntu-24.04` | `ubuntu` | | Debian 12 | `debian-12` | `debian` | | Rocky Linux 9 | `rocky-9` | `rocky` | Altre distribuzioni: aggiungi una riga a `distros.conf` (URL dell'immagine, file di checksum, famiglia `deb` o `rpm`). 1. Copia il generatore su una macchina di compilazione ed eseguilo: ```bash cp -r /opt/nexcmp/releases//share/templates ~/templates && cd ~/templates ./build-template.sh --distro ubuntu-24.04 --version v7 --work ./out ``` Aggiungi `--panel-url https://cloud.example.com` per integrare un agente di monitoraggio opzionale al primo avvio che si registra con il tuo pannello (solo HTTPS). Senza di esso, non viene aggiunto alcun agente. Altre opzioni: `--base ` per usare un'immagine scaricata, `--offline` per saltare l'installazione dei pacchetti. 2. Il risultato è `out/ubuntu-24.04-v7.qcow2` e il suo `.sha256`. La compilazione termina eseguendo `verify-image.sh`, che ispeziona l'immagine completata in sola lettura rifiutandone una difettosa (viene mantenuta come `.unverified`). Puoi rieseguirlo in qualsiasi momento: `./verify-image.sh out/ubuntu-24.04-v7.qcow2 --no-agent`. Cosa inserisce il generatore nell'immagine: | Elemento | Motivo | |---|---| | `qemu-guest-agent` | CloudStack può interrogare la VM su CPU e IP e metterla in pausa per gli snapshot. | | cloud-init con l'origine dati CloudStack, `set_passwords` a ogni avvio, login SSH con password | La password generata viene recuperata dal router virtuale e **Reset password** funziona. | | Una regola udev per CPU e RAM aggiunte a caldo | I vCPU e la RAM aggiunti a caldo si attivano autonomamente, quindi il ridimensionamento live e l'Auto Scaling funzionano. | | Un servizio di file di swap | Crea `/swapfile` del minore tra il 50% della RAM e 4 GiB dopo che il disco è cresciuto. `touch /etc/cmp-swap.disabled` lo disattiva. | | cloud-init `growpart` e `resizefs` | Il piccolo disco di root si estende alla dimensione del disco del piano al primo avvio. | | machine-id vuoto, nessuna chiave host SSH | Ogni VM ottiene la propria identità. | ::: warning Nomina il template ` ` NexCMP attiva **Auto Scaling** per i template il cui nome termina in `vN` o `vN.M` con **N di 6 o superiore** (`Ubuntu 24.04 v7`, `Rocky Linux 9 v7.1`). Il builder applica questo per `--version`. Registra il template con il nome esatto stampato. ::: 3. Pubblica il file e registralo in CloudStack. Usa lo SHA-256 stampato dalla compilazione e registralo solo dopo che il file è stato scritto completamente: ```bash cmk list ostypes keyword="Ubuntu 24.04" filter=id,description cmk register template name="Ubuntu 24.04 v7" displaytext="Ubuntu 24.04 v7" \ url=https://files.example.com/ubuntu-24.04-v7.qcow2 zoneid= format=QCOW2 hypervisor=KVM \ ostypeid= passwordenabled=true sshkeyenabled=true isdynamicallyscalable=true \ requireshvm=true isextractable=false ispublic=true isfeatured=true \ checksum="{SHA-256}" \ details[0].guest.cpu.mode=host-passthrough details[0].rootDiskController=osdefault ``` - `passwordenabled=true` consente a CloudStack di generare la password della VM. - `isdynamicallyscalable=true` consente il ridimensionamento live. - `host-passthrough` è necessario per l'avvio delle immagini correnti di Rocky e Alma; `osdefault` mantiene portabile il controller del disco. 4. Attendi che il template raggiunga **Download Complete / Ready**. L'immagine del vendor mantiene la sua piccola dimensione virtuale (circa 3.5 GiB per Ubuntu e Debian, 10 GiB per Rocky). Ricorda che il disco di un piano non può essere più piccolo del disco del template. ### Proxmox VE: crea un template {#proxmox-ve-make-a-template} Crea un template VM cloud-init per OS su ogni nodo su cui effettui il deployment, con il guest agent installato e il login root abilitato, quindi registralo come `os-key=vmid`. I comandi completi si trovano in [Proxmox VE](https://nexcmp.com/it/docs/infrastructure/proxmox/). Il builder CloudStack sopra **non** è per Proxmox: configura cloud-init per l'origine dati CloudStack. ### ISO {#isos} I clienti montano le proprie ISO tramite il modulo **Images** (CloudStack) o il modulo Server Dedicati. Questi sono separati dai template OS di questa pagina. Vedi [Modules](https://nexcmp.com/it/docs/infrastructure/modules/) e [Dedicated servers](https://nexcmp.com/it/docs/infrastructure/dedicated/). ## Collega in NexCMP {#connect-in-nexcmp} 1. Apri **Services › Virtual Machines › Template**. Fai clic su **Sync now** o attendi fino a 15 minuti. La sincronizzazione aggiunge i template pronti e in evidenza in CloudStack. ![La pagina dei template che elenca i template sincronizzati con il loro stato di pronto e la colonna di hot-plug della CPU](https://nexcmp.com/it/docs/images/infrastructure/templates-01-list.webp) 2. Fai clic su **Edit** su un nuovo template e imposta ciò che vedono i clienti: | Campo | Valore di esempio | |---|---| | Nome visualizzato per i clienti | `Ubuntu 24.04 LTS` | | Famiglia OS | `ubuntu` (icona e utente predefinito) | | Versione | `24.04` | | Nome utente di login | `ubuntu` (Windows: `Administrator`; altro: `root`) | | Icona | URL dell'immagine, un percorso o un nome | | Order | `10` | | Active | On | | Hot-plug vCPU/RAM (scale live) | **Auto by name (v6 or later)**, **Yes** o **No (needs a restart)** | ![Finestra di modifica del template con nome visibile al cliente, famiglia OS, utente di login e opzione di hot-plug](https://nexcmp.com/it/docs/images/infrastructure/templates-02-edit.webp) 3. Attiva il template. Un template che CloudStack non elenca più viene nascosto automaticamente (e ricevi un avviso su Telegram se configurato); non viene mai eliminato da NexCMP. ### Sostituisci un template con una build più recente {#replace-a-template-with-a-newer-build} Usa **More › Replace with new version** sul template venduto. Scegli il nuovo template pronto e attualmente disabilitato. La voce venduta punterà quindi alla nuova build mantenendo nome, ordine e icona; quella vecchia viene disabilitata come via di ritorno (per tornare indietro, usa **Replace** sulla nuova voce). Le macchine virtuali in esecuzione non vengono toccate. Se la nuova build appartiene a un'altra famiglia di OS, spunta prima la conferma. ## Verifica {#verify} 1. La riga mostra **ready** e, per le build denominate `vN` con N pari o superiore a 6, **CPU hot-plug: supported**. 2. Distribuisci una VM di test dal template e controlla all'interno della VM: - puoi effettuare l'accesso con la password mostrata nel portale; - `df -h /` mostra la dimensione del disco del piano; - dopo un ridimensionamento a caldo (**Change plan** senza riavvio), `nproc` e `free -m` aumentano; - `swapon --show` elenca `/swapfile` (i dischi con spazio libero inferiore alla swap più 2 GiB vengono saltati); - `systemctl is-active qemu-guest-agent` stampa `active`. 3. Se hai integrato l'agent, la VM appare tra gli host monitorati del pannello un minuto dopo il primo avvio. La VM necessita di un IP pubblico proprio: il pannello la riconosce tramite il suo IP sorgente pubblico. ## Limiti e note {#limits-and-notes} - Il builder è solo per Linux e compila immagini Linux. Altre immagini (ad esempio Windows) possono essere registrate in CloudStack con altri mezzi; NexCMP elenca ciò che CloudStack segnala. - Viene fornito solo l'agent amd64; le altre architetture saltano l'installazione dell'agent. - L'immagine viene controllata con `guestfish` ma non viene mai avviata dal builder. Distribuisci sempre una VM di test prima di vendere una nuova immagine. - Salta l'agent su una VM con `touch /etc/cmp-agent.disabled` prima del primo avvio. Rimuovilo in seguito con `systemctl disable --now cmp-agent cmp-agent-install; rm -rf /etc/cmp-agent /usr/local/bin/cmp-agent`, quindi elimina l'agent nella console di amministrazione. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | `virt-customize` non riesce a scaricare i pacchetti | La macchina di build non ha connettività di rete in uscita | Correggi il DNS o il proxy su quella macchina, oppure compila con `--offline` su un'immagine di base che possiede già i pacchetti. | | `libguestfs: error: /usr/bin/supermin exited with error status 1` | Il kernel dell'host non è leggibile dall'utente corrente (Ubuntu) | `sudo chmod +r /boot/vmlinuz*`, oppure esegui la build come root. | | Il checksum differisce o l'immagine del vendor non esiste più | I vendor spostano i loro file "latest" | Scarica tu stesso l'immagine, controllala rispetto al file di checksum del vendor e passala con `--base`. | | Rocky: un XFS più recente non può essere montato | Il kernel dell'host è troppo vecchio | Compila su una macchina con un kernel recente. | | `--version must be v6 or higher` | Il nome deve essere `vN` con N pari o superiore a 6 | Usa `--version v7`. | | `--panel-url must be a plain https:// URL` | L'agent viene scaricato ed eseguito come root, quindi l'HTTP in chiaro viene rifiutato | Usa un URL `https://` senza spazi, virgolette o stringa di query. | | Il template rimane **not ready** | CloudStack non ha completato il download | Attendi **Download Complete**, verifica che la VM di storage secondario possa raggiungere l'URL. | | La riga mostra **no-pass** | Il template è stato registrato senza `passwordenabled=true` | Registralo di nuovo con quel flag. | | L'hot-plug della CPU mostra **unsupported** | Il nome non termina con `vN` (N pari o superiore a 6) | Rinomina il template o imposta **vCPU/RAM hot-plug** su **Yes** in Edit se l'immagine dispone della regola udev. | | "Empty template list" dopo la prima connessione | La sincronizzazione non è stata eseguita | Fai clic su **Sync now** (richiede il worker in esecuzione) o attendi il ciclo di 15 minuti. | --- # Server dedicati (bare metal) {#dedicated-servers-bare-metal} > **Dove nel pannello di amministrazione:** Infrastructure › Bare Metal (Servers `/infra/baremetal`, IP Pools, Stock / iDRAC import, Operations, Templates, Customer ISOs, Safety). Piani e abbonamenti: Services › Dedicated Server (`/dedicated`). Attiva il modulo in System › Admin › License & updates (`/license`). ## Descrizione {#what-it-does} NexCMP gestisce i server fisici **direttamente tramite il loro iDRAC**, tramite le API Redfish. I clienti noleggiano un intero server: possono accenderlo e spegnerlo, aprire una console nel browser, montare una ISO o installare un sistema operativo da un template, oltre a visualizzare hardware e metriche. Non vedono mai l'indirizzo, il nome utente o la password dell'iDRAC. Usalo per rivendere server dedicati dai tuoi rack. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Hardware | Server Dell con **iDRAC 9** e API Redfish. | | Rete di gestione | **A tuo carico.** Il server del pannello deve raggiungere ogni iDRAC su **HTTPS 443** (e la porta VNC di iDRAC, predefinita **5901**, per la console), e ogni iDRAC deve raggiungere il server web ISO descritto di seguito. L'indirizzo iDRAC deve essere un **indirizzo IPv4 in un intervallo privato** (RFC 1918, un prefisso /16 o inferiore) indicato nell'impostazione `dedicated_bmc_cidrs`. I nomi DNS e IPv6 vengono rifiutati. NexCMP non crea questa rete e non può testarla al posto tuo. | | Account iDRAC | Un account con privilegi di **Administrator** su ciascun iDRAC. NexCMP lo utilizza per leggere il server e per inviare i pochi comandi consentiti (alimentazione, virtual media, one-time boot, console). Non crea mai account iDRAC per i tuoi clienti. | | Strumenti sul server del pannello | `xorriso` e `genisoimage` (generano la ISO di installazione di ciascun server) e `novnc` (la pagina della console nel browser). Installali con `sudo apt-get install -y xorriso genisoimage novnc` oppure lascia che lo faccia il programma di installazione: eseguilo con `--baremetal` o forniscigli le opzioni del server ISO; anche un aggiornamento li installa se il modulo Bare Metal è già attivo. Se uno di essi manca, **Safety** lo segnala con un avviso rosso, **live ops** rifiuta di attivarsi (errore `tools_missing`) e la console e l'installazione del sistema operativo segnalano l'assenza di uno strumento anziché fallire successivamente. | | Server web ISO | Un semplice server **HTTP** sulla rete di gestione che distribuisce la cartella ISO di NexCMP agli iDRAC. Il suo indirizzo è un indirizzo IPv4 privato con porta facoltativa, ad esempio `http://10.20.0.2:8080`, **senza alcun path**, memorizzato in `dedicated_iso_base_url`. Deve supportare i byte range. La cartella viene scritta dal worker del pannello, quindi il server web viene solitamente eseguito sul **server del pannello stesso**, in ascolto su un indirizzo assegnato a quel server sulla rete di gestione. NexCMP include un sito nginx pronto all'uso e un comando in un singolo passaggio (vedi sotto). | | Cartelle ISO | Una cartella per i file ISO e, al suo interno, `pub` (ciò che leggono gli iDRAC) e `server` (le ISO dei clienti). Il comando in un singolo passaggio utilizza `/srv/nexcmp-iso`; in sua assenza vengono usati i valori predefiniti dell'installazione (impostazioni `dedicated_iso_lib_dir`, `dedicated_iso_pub_dir`, `dedicated_iso_server_dir`). Il worker di NexCMP deve poter **scrivere** in queste cartelle. Viene eseguito con un file system di sola lettura ad eccezione di `/var/lib/nexcmp`, pertanto una cartella posizionata altrove richiede un drop-in di systemd (installato automaticamente dal comando in un singolo passaggio). | | Indirizzo di callback | `dedicated_callback_base`, un `https://` che il server in fase di installazione può raggiungere e che punta al tuo pannello. | | Storage | Spazio disco libero per la libreria ISO e per le ISO fornite dai clienti. | | Dipende da | Il modulo **Bare Metal**, una zona e i pool di IP dei server. | ::: warning I valori di esempio non costituiscono una configurazione Una nuova installazione include valori di esempio in `dedicated_bmc_cidrs`, `dedicated_iso_base_url` e `dedicated_callback_base` (una rete privata di esempio e `https://example.com`). Non corrispondono alla tua rete. Finché uno di essi rimane un valore di esempio, le pagine Bare Metal mostrano un avviso rosso **Management network not configured**, l'importazione di un iDRAC non supera il controllo della allow-list e lo switch **live ops** rifiuta di attivarsi (errore `config_placeholder`). Configura i tre valori in **Infrastructure › Bare Metal › Safety › Management network connection** (vedi sotto). ::: ## Prepara l'infrastruttura {#prepare-the-infrastructure} 1. **Metti ogni iDRAC su una rete di gestione** non raggiungibile dai clienti e assegna a ciascuno un indirizzo IPv4 privato fisso. Verifica le API Redfish dal server del pannello: ```bash curl -sk -u 'nexcmp-admin:XXXX' https://10.20.0.11/redfish/v1/Systems | head ``` 2. **Crea un account amministratore sull'iDRAC** per NexCMP (tramite l'interfaccia web di iDRAC o `racadm`). Usa una password complessa e univoca. Non riutilizzare mai l'account integrato dell'iDRAC. 3. **Pubblicare la cartella ISO per gli iDRAC con un solo comando.** Sul server del pannello, come root, specificando l'indirizzo assegnato al server sulla rete di gestione e la rete degli iDRAC: ```bash sudo nexcmp dedicated-setup-iso --listen 10.20.0.2:8080 --allow 10.20.0.0/24 ``` `--listen` deve essere un indirizzo di questo server (IPv4 privato, porta 8080 se omessa). `--allow` elenca le reti iDRAC (CIDR privati, /16 o inferiori, fino a 8, separati da virgole); solo esse possono effettuare il download, e il comando le usa anche come `dedicated_bmc_cidrs` quando l'impostazione contiene ancora il valore di esempio. `--dir /path` sceglie un'altra cartella ISO (predefinita `/srv/nexcmp-iso`). Il comando: - crea la cartella contenente `pub` e `server`, assegnandone la proprietà all'utente del servizio NexCMP; - crea il gruppo `nexcmp-iso` e vi aggiunge l'utente nginx, consentendo a nginx di leggere una ISO mentre un iDRAC la tiene montata, escludendo chiunque altro; - installa il sito nginx `nexcmp-iso` (mantenuto solo se `nginx -t` lo accetta; nginx viene installato se mancante) e un drop-in di systemd `nexcmp-vmd.service.d/iso.conf` (`ReadWritePaths` per la cartella, `SupplementaryGroups=nexcmp-iso`); - scrive le impostazioni ISO (`dedicated_iso_base_url`, le tre cartelle, il gruppo) e riavvia il worker di NexCMP. Può essere eseguito nuovamente con altri valori, e `sudo nexcmp dedicated-setup-iso --remove` rimuove il sito nginx e il drop-in (i file ISO vengono mantenuti). Può anche essere eseguito durante l'installazione: aggiungi `--iso-listen`, `--iso-allow` (e `--iso-dir`) al comando di installazione. Il comando **non** crea la rete di gestione e non contatta alcun iDRAC; se i valori sono errati, l'indirizzo non è presente su questo server o la porta è occupata, si interrompe con un messaggio prima di modificare qualsiasi cosa, e una configurazione di sito nginx rifiutata da `nginx -t` non viene mantenuta. 4. **Cosa distribuisce il server web ISO.** Il sito nginx risponde a `GET` (e `HEAD`, con intervalli di byte) per `/pub/.iso` e nient'altro: nessun elenco di directory, nessun altro percorso nella cartella (la libreria e `server/` non sono raggiungibili), nessun altro metodo e solo dalle reti `--allow` (chiunque altro riceve 403). NexCMP espone ogni ISO che un iDRAC deve leggere come file o collegamento temporaneo in `pub`; nginx segue un collegamento solo quando il collegamento e la sua destinazione hanno lo stesso proprietario (l'utente del servizio), quindi un collegamento a un file di sistema viene rifiutato. Verificalo da un altro host sulla rete di gestione: ```bash curl -I http://10.20.0.2:8080/ # 403 or 404, never a listing curl -I http://10.20.0.2:8080/pub/ # 403 or 404 ``` Un file di test in `pub` dovrebbe rispondere a una richiesta `Range` con 206. *Configurazione manuale alternativa:* il sito nginx e il drop-in sono inclusi come template nel pacchetto di rilascio (`share/dedicated/nginx-iso.conf` e `share/dedicated/vmd-iso.conf` in `/opt/nexcmp/releases//`). Copiali, sostituisci i segnaposto `__...__` (indirizzo di ascolto, cartella, righe allow, gruppo) e mantieni le regole sopra indicate. 5. **Tieni pronte le immagini OS.** Posiziona le ISO auto-installanti nella cartella della libreria (vedi **Templates** sotto). I clienti possono anche aggiungere ISO da un link; queste vengono scaricate sul server e non passate mai all'iDRAC come URL. ## Collega in NexCMP {#connect-in-nexcmp} ### 1. Attiva il modulo {#_1-turn-the-module-on} In **System › Admin › License & updates**, attiva **Bare Metal**. La categoria **Bare Metal** appare sotto Infrastructure. Vedi [Modules](https://nexcmp.com/it/docs/infrastructure/modules/). ### 2. Imposta la connessione di rete di gestione {#_2-set-the-management-network-connection} Apri **Infrastructure › Bare Metal › Safety**. La scheda **Management network connection** contiene i tre valori che determinano se il sistema può funzionare: | Campo | Impostazione | Cosa inserire | |---|---|---| | Rete iDRAC (CIDR) | `dedicated_bmc_cidrs` | Le reti private dei tuoi iDRAC, ad esempio `10.20.0.0/24`. Solo CIDR privati, /16 o inferiori, fino a 8, separati da virgola. È possibile importare solo gli iDRAC inclusi in questi intervalli. | | Server ISO per gli iDRAC | `dedicated_iso_base_url` | `http://[:port]`, nessun percorso: l'indirizzo del server web ISO della sezione precedente, ad esempio `http://10.20.0.2:8080`. Il comando one-step lo compila automaticamente. | | Indirizzo di callback del pannello | `dedicated_callback_base` | `https://`, nessun percorso: l'indirizzo chiamato dal server in fase di installazione per segnalare il completamento. Deve essere raggiungibile dalla rete di tale server. `example.com`, `localhost` e simili vengono rifiutati. | Il modulo verifica il formato durante la digitazione e il server lo controlla nuovamente al salvataggio; un valore errato viene rifiutato con la relativa motivazione e il valore memorizzato rimane invariato. Un campo che contiene ancora il valore di esempio predefinito presenta l'etichetta rossa **Not configured** e ogni pagina Bare Metal mostra l'avviso rosso **Management network not configured** finché tutti e tre i valori non sono effettivi. Le modifiche vengono registrate nell'audit log con il tuo motivo. Salvare nuovamente il valore di esempio non è considerato una configurazione, a meno che tu non lo abbia digitato manualmente. ### 3. Controlla il safety gate (per ora lascialo chiuso) {#_3-check-the-safety-gate-leave-it-closed-for-now} Apri **Infrastructure › Bare Metal › Safety**. **Live ops** è l'interruttore globale per ogni comando di scrittura verso un iDRAC (alimentazione, supporti virtuali, console e installazione del sistema operativo). È inizialmente **off** e non può essere attivato finché la connessione di rete di gestione sopra indicata contiene ancora valori di esempio (l'interruttore risponde con `config_placeholder` indicando i campi). Le scritture vengono rifiutate a livello di API e nuovamente all'interno del worker, mentre la lettura dello stato continua a funzionare. Un secondo blocco, **ops_locked**, protegge ogni server: i server appena importati sono sempre bloccati, anche quando live ops è attivo. ![La pagina Safety con Live ops disattivato e l'elenco delle azioni bloccate](https://nexcmp.com/it/docs/images/infrastructure/dedicated-01-safety.webp) ### 4. Importa i server {#_4-import-servers} 1. Apri **Infrastructure › Bare Metal › Stock / iDRAC import**. 2. In **Add one server** inserisci l'indirizzo iDRAC, l'account e la password, quindi clicca **Test connection**. Il test invia solo comandi di lettura e non salva nulla. | Campo | Valore di esempio | |---|---| | Indirizzo iDRAC (URL o host) | `10.20.0.11` | | Account | `nexcmp-admin` | | Password | `XXXX` | | Etichetta | `rack1-01` (empty: generated) | | Assegna un IP da un pool | opzionale; scegli il pool di IP di servizio del server | | Includi nell'elenco di vendita | disattivato finché non sei pronto | ![Stock e importazione iDRAC con un indirizzo di esempio e un test in sola lettura riuscito](https://nexcmp.com/it/docs/images/infrastructure/dedicated-02-import-server.webp) 3. Clicca **Save to stock**. NexCMP legge il modello, la CPU, la RAM, i dischi, le schede di rete e il codice di servizio dall'iDRAC. Il server entra in stock **bloccato**. 4. Per molti server usa **Bulk import**: un server per riga, campi separati da virgola, punto e virgola o Tab. **Preview** controlla la whitelist, i duplicati dell'indirizzo iDRAC o del codice di servizio e legge l'hardware (fino a quattro server alla volta). ### 5. ISO dei clienti e indirizzo web ISO {#_5-customer-isos-and-the-iso-web-address} Apri **Infrastructure › Bare Metal › Customer ISOs**. - **HTTP address serving ISOs to iDRAC** è `dedicated_iso_base_url`, lo stesso valore presente nella scheda Safety (modificabile in entrambe le posizioni). Inserisci l'indirizzo sulla rete di gestione del tuo server web ISO. - **Customer ISO limits** imposta la dimensione di una singola ISO, lo spazio di archiviazione ISO totale, lo spazio libero minimo, il tempo di conservazione delle ISO (in ore), il tempo massimo di download e il numero di download simultanei. ![ISO dei clienti con l'indirizzo HTTP per gli iDRAC e i limiti delle ISO](https://nexcmp.com/it/docs/images/infrastructure/dedicated-03-iso-settings.webp) ### 6. Template del sistema operativo {#_6-os-templates} Apri **Infrastructure › Bare Metal › Templates**. Elenca le ISO auto-installanti trovate nella cartella della libreria. Clicca **Register** su un file per inserire la famiglia OS, la versione e l'account (precompilati dal nome del file), quindi attiva il template con **Enable**. L'abilitazione di un template non avvia nulla: ogni installazione passa comunque attraverso il cancello di sicurezza. **Unregister** rimuove solo la riga del template, mai il file. ![Template Bare Metal con una ISO registrata e una non registrata](https://nexcmp.com/it/docs/images/infrastructure/dedicated-04-os-templates.webp) ### 7. Pool IP {#_7-ip-pools} Apri **Infrastructure › Bare Metal › IP Pools** e aggiungi gli intervalli IPv4 che i server ricevono come indirizzi di servizio. Ogni server riceve un indirizzo; l'opzione **Assign an IP from a pool** durante l'importazione prende il successivo disponibile. Gli indirizzi liberi vengono conteggiati per pool. ![Pool di IP Bare Metal con intervalli di esempio e conteggi dei liberi](https://nexcmp.com/it/docs/images/infrastructure/dedicated-05-ip-pools.webp) ### 8. Piani e vendita {#_8-plans-and-sale} 1. Apri **Services › Dedicated Server › Plans & pricing**. Modifica i quattro piani di esempio (denominati `BM-40C-` nella 1.6.1) o crea i tuoi: prezzo, cicli e costo di attivazione. **In una nuova installazione i prezzi vengono inseriti in dollari statunitensi, al centesimo, e il wallet viene addebitato esattamente per tale importo: non è necessario alcun tasso di cambio.** Un'installazione che aveva già piani con prezzi in dong vietnamiti mantiene i dong e necessita comunque di un tasso di cambio nelle relative impostazioni (senza di esso, gli ordini vengono rifiutati con `dedicated_fx_unavailable`). I piani di esempio partono con un prezzo pari a 0 e **disattivati**: un piano in vendita richiede un prezzo superiore a 0. Verifica ciascun piano rispetto all'hardware effettivamente importato; il nome di un piano di esempio non rileva né modifica l'hardware di un server. 2. Apri il server (Infrastructure › Bare Metal › the server › **Sales**), **associa il piano** e attiva **Sellable**. 3. Attiva le **live ops** (pagina Safety, con la conferma digitata) e sblocca i server che vuoi gestire (scheda **Lock** del server, inserendo una motivazione che verrà registrata nel log di audit). 4. In **Services › Dedicated Server**, attiva le vendite. Questa operazione richiede due passaggi: leggi le conseguenze, quindi digita `ENABLE SALES`. Fino ad allora i clienti non vedranno alcuna pagina d'ordine e non gli verrà addebitato nulla. ![Piani Dedicated Server con l'interruttore delle vendite disattivato](https://nexcmp.com/it/docs/images/infrastructure/dedicated-06-plans.webp) ### Cosa possono fare i clienti nella pagina del proprio server {#what-customers-can-do-on-their-server-page} La pagina del server di un cliente include sedici schede suddivise in sette gruppi (Overview, Control, Network, Hardware, Billing, Activity, Settings). Il gruppo **Billing** contiene: - **Piano e rinnovo**: paga da 1 a 24 mesi in anticipo in un solo passaggio; la nuova data viene calcolata a partire dalla data di rinnovo attuale e il wallet viene addebitato una sola volta. Il rinnovo automatico può essere attivato o disattivato. - **Billing cycle**: scegli un altro ciclo (ad esempio trimestrale); viene applicato a partire dal **prossimo** rinnovo e al momento non viene addebitato né rimborsato nulla. - **Change plan**: il cliente può **richiedere** un altro piano. La richiesta non comporta alcun addebito. Puoi approvarla o rifiutarla in **Services › Dedicated Server › Plan changes**, dopo aver aggiornato l'hardware o trasferito il server. Un upgrade approvato addebita la differenza per il resto del periodo già pagato dal cliente; un downgrade non rimborsa nulla e si applica a partire dal periodo successivo. - **Invoices**: tutte le fatture relative a quel server (ordine, rinnovi, upgrade). In **Plan changes**, ordina le richieste per ID, data, stato, piani o server; l'ordinamento riguarda l'intero risultato sul server. La colonna delle azioni rimane visibile quando scorri orizzontalmente su uno schermo stretto. Nella parte superiore di **Overview** quattro riquadri dinamici mostrano **CPU**, **RAM**, **Disk** e **Network**, con un piccolo grafico relativo alle ultime 24 ore. CPU, RAM e Disk indicano le percentuali di utilizzo rilevate dall'ultimo polling iDRAC (Disk rappresenta l'attività di I/O, non lo spazio libero); Network indica la velocità corrente in entrata e in uscita oltre al totale mensile, ricavati dal contatore del traffico. Un riquadro mostra **—** e una breve motivazione quando il server è spento, l'iDRAC non è raggiungibile o la macchina non segnala tale valore; non mostra mai uno 0 fittizio. Queste letture provengono da Dell iDRAC e, in assenza di un contatore del traffico, il riquadro Network rimane su **—**. I riquadri si aggiornano ogni minuto a pagina aperta, e un clic apre la scheda **Hardware** o **Bandwidth**. In **Overview** la scheda **Access** mostra il nome utente e la password del sistema operativo installato, nascosta per impostazione predefinita con i pulsanti **Show** e **Copy**. È disponibile dopo ogni installazione, non solo una volta, e un nuovo proprietario del server non vede mai la password del proprietario precedente. Se la password del sistema operativo viene modificata all'interno del server, la scheda continua a mostrare quella impostata al momento dell'installazione. La scheda **Bandwidth** appare solo se alimentata da un contatore del traffico (vedi Limiti). Non è presente alcuna scheda **Subnet**: portare il proprio prefisso IP su un server noleggiato non fa parte di NexCMP. ### Cosa possono e non possono fare i clienti {#what-customers-can-and-cannot-do} | I clienti possono | Mai possibile | |---|---| | Visualizzare inventario, stato di salute, stato di alimentazione e metriche | Visualizzare l'indirizzo iDRAC, il nome utente o la password | | Accensione, spegnimento pulito, riavvio, spegnimento forzato, reset | Modificare gli account iDRAC o le impostazioni di rete iDRAC | | Aprire una console del browser (una sessione alla volta) | Modificare BIOS o RAID, cancellare i log, aggiornare il firmware, reimpostare l'iDRAC | | Montare una ISO o un proprio link ISO, impostare il boot una sola volta, reinstallare il sistema operativo da un template abilitato | Eseguire chiamate Redfish grezze (le funzioni non esistono in NexCMP) | NexCMP non crea account iDRAC per i clienti: utilizzano esclusivamente i controlli del portale, e l'indirizzo e il login di iDRAC non vengono mai mostrati loro. ## Verifica {#verify} 0. In **Safety**, la scheda **Management network connection** non mostra alcuna etichetta rossa e le pagine Bare Metal non mostrano alcun avviso rosso. Da un host sulla rete di gestione, `curl -I http:///` non elenca i file. 1. **Test connection** sul modulo di importazione restituisce modello, CPU, RAM e service tag. 2. Il server compare in **Servers** con il rispettivo hardware. Con le **live ops disattivate**, qualsiasi azione di alimentazione viene rifiutata con il messaggio "Server control is temporarily disabled system-wide". 3. Dopo aver attivato le live ops e sbloccato un server di test, spegni e riaccendi il server da **Operations** o dalla pagina del server, quindi apri la console. 4. Effettua un ordine di test con un piano di prova: il server viene assegnato, il sistema operativo viene installato e l'installazione termina quando il server risponde al pannello. ## Limiti e note {#limits-and-notes} - Ogni server fisico ha al massimo un abbonamento attivo. - Un comando di scrittura viene inviato solo quando **sia** le live ops sono attive **che** il blocco del server è aperto. Il controllo viene ripetuto all'interno del worker immediatamente prima di ciascun comando. - Lo stato **Installing** attende che il nuovo sistema operativo risponda sulla sua porta (SSH 22, Windows 3389, Proxmox 8006) prima che l'ordine venga completato; l'installazione ha un limite di tempo (`dedicated_install_timeout_min`, predefinito 150 minuti). - La larghezza di banda per i server dedicati viene conteggiata tramite un agente di rilevamento del traffico non compreso nell'installazione standard. Senza di esso non viene registrato nulla, il portale nasconde la scheda Bandwidth e l'API riporta `capabilities.bandwidth` come `false`. - Le azioni di amministrazione su un noleggio (blocco, sblocco, cancellazione con o senza rimborso) sono le stesse azioni unificate previste per qualsiasi altro servizio, con i rimborsi accreditati sul saldo da cui sono stati pagati. - I server non vengono rivenduti tramite i rivenditori: Dedicated viene venduto esclusivamente dal sito principale. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | Il test fallisce con un errore di indirizzo | L'indirizzo non è un valore letterale IPv4 in `dedicated_bmc_cidrs` (privato, /16 o inferiore) oppure la porta non è consentita | Usa l'indirizzo IPv4 di iDRAC e aggiungi la relativa rete in Safety › Management network connection (`dedicated_bmc_cidrs`). I nomi DNS e IPv6 vengono rifiutati. | | Avviso rosso "Management network not configured" o lo switch live ops risponde `config_placeholder` | Uno tra `dedicated_bmc_cidrs`, `dedicated_iso_base_url` e `dedicated_callback_base` contiene ancora il valore di esempio predefinito | Inserisci i valori reali in Safety › Management network connection. | | Un campo viene rifiutato durante il salvataggio | Formato errato (CIDR non privato o più ampio di /16, indirizzo ISO diverso da `http://[:port]`, callback diverso da `https://`) oppure un indirizzo di esempio come `example.com` | Leggi il messaggio sotto il campo; il valore memorizzato resta invariato. | | `nexcmp dedicated-setup-iso` si interrompe prima di modificare qualsiasi cosa | `--listen` non è un indirizzo di questo server, la porta è già in uso oppure un valore non è valido | Usa l'indirizzo assegnato a questo server sulla rete di gestione, un'altra porta o correggi il valore indicato nel messaggio. | | "Il certificato TLS dell'iDRAC differisce da quello memorizzato - il polling e le azioni di scrittura sono stati interrotti" | Il certificato iDRAC è stato sostituito (nuovo certificato, iDRAC sostituito) | Apri il server, scheda **Access**, confronta le due impronte digitali e, se la modifica è voluta, fai clic su **Repin certificate**. | | "Il controllo dei server è temporaneamente disabilitato a livello di sistema" | Le operazioni in tempo reale sono disattivate | Attivalo in **Safety**. | | "Questo server è bloccato per le operazioni" | Il blocco per singolo server è chiuso | Apri il blocco nella scheda **Lock** del server specificando un motivo. | | "È già in corso un'altra operazione su questo server" | Un'operazione precedente non è terminata | Attendi; controlla **Operations**. | | "Un'altra sessione di console è già aperta su questo server" | Una sola console alla volta | Chiudi l'altra sessione. | | "Il controller del server è temporaneamente non disponibile" | L'iDRAC non risponde | Controlla la rete di gestione e l'iDRAC. | | Il montaggio di un ISO fallisce con un errore 403 o 404 dall'iDRAC | Il server web non riesce a leggere il file o l'indirizzo di base non è corretto | Controlla i permessi del server web ISO e l'indirizzo **HTTP address serving ISOs to iDRAC**. | | "Questo piano è esaurito nella località selezionata" | Nessun server vendibile con quel piano nella zona | Associa il piano a un server e attiva **Sellable**. | | "Nessun indirizzo IPv4 disponibile da assegnare al momento" | Il pool di IP è vuoto | Aggiungi indirizzi al pool. | | "L'installazione automatica del sistema operativo non è disponibile al momento" | Mancano i prerequisiti di installazione | Verifica che un template sia abilitato e che le cartelle ISO siano scrivibili; i clienti possono comunque installare tramite ISO e console. | | L'installazione si blocca | Il server in fase di installazione non riesce a raggiungere l'indirizzo di callback | Controlla `dedicated_callback_base` e verifica che la rete del server possa raggiungere il tuo pannello tramite HTTPS. | --- # Nodi VPN e proxy IPv6 {#vpn-and-ipv6-proxy-nodes} > **Dove nell'admin:** Infrastructure › VPN & Proxy nodes › Agents & external nodes (`/agents`), VPN IP pools (`/vpn/pool`), IPv6 Proxy nodes (`/vpn/proxy6/nodes`). I servizi veri e propri si trovano in Services › VPN e Services › IPv6 Proxy. Entrambi i moduli si attivano in System › Admin › License & updates. ## Descrizione {#what-it-does} NexCMP vende accesso VPN e proxy in uscita da **indirizzi IP di tua proprietà**, su server gestiti da te. Esistono due tipi di nodi: - **Nodo VPN.** Un piccolo programma in Go, `cmp-agent`, viene eseguito sul tuo host Linux. Rileva gli indirizzi IPv4 pubblici sull'host, apre un listener SOCKS5, HTTP e UDP su ogni indirizzo venduto e invia il traffico dallo **stesso IP** a cui si è connesso il cliente (stesso IP in uscita). Invia lo stato al pannello ogni pochi secondi. - **Nodo proxy IPv6.** Un servizio proxy che fornisce ai clienti indirizzi da un prefisso IPv6 instradato verso l'host. Il pannello lo installa per te tramite SSH. Usali per rivendere indirizzi IP puliti nei paesi in cui disponi di server. ## Requisiti {#requirements} ### Nodo VPN {#vpn-node} | Elemento | Requisito | |---|---| | Sistema operativo | Una distribuzione Linux con systemd e un kernel 4.15 o successivo (supporto free-bind IPv6). Il binario dell'agente fornito è solo **x86_64** (amd64). | | Privilegi | root, per l'installazione. Il servizio mantiene solo `CAP_NET_ADMIN`, `CAP_NET_RAW` e `CAP_DAC_READ_SEARCH`. | | Strumenti | `curl` o `wget` e `sha256sum` (l'installer si rifiuta di continuare senza aver controllato il file). | | Indirizzi pubblici | Indirizzi IPv4 pubblici assegnati su un'interfaccia dell'host (uno per `/32`), **oppure** un prefisso instradato verso l'host che aggiungi come subnet aggiuntiva (IPv4 da /16 a /32, IPv6 da /48 a /128). Gli intervalli privati, CGNAT e di documentazione vengono ignorati. | | Rete, in ingresso | I clienti si connettono a ciascun IP pubblico venduto sulle **porte 65001-65535** (TCP per SOCKS5 e HTTP, UDP per l'associazione UDP). Ogni endpoint utilizza un set di tre porte consecutive. | | Rete, in uscita | HTTPS (443) verso il dominio del tuo pannello. L'agent rileva inoltre il proprio paese su `ip-api.com` (HTTP) e `ipinfo.io` (HTTPS), con un limite di 3.5 secondi. | | Posta elettronica | Le connessioni in uscita verso la porta 25 sono sempre bloccate; non esiste alcuna impostazione per aprirla. | | Docker, VPN e interfacce virtuali | Le interfacce denominate `docker*`, `veth*`, `br-*`, `cni*`, `flannel*`, `virbr*`, `cali*`, `tun*`, `tap*`, `wg*` e `tailscale*` non contribuiscono con indirizzi. | | Dipende da | Il modulo **VPN**, una zona (creata automaticamente dal paese dell'host) e il pannello NexCMP raggiungibile via HTTPS. | ### Nodo proxy IPv6 {#ipv6-proxy-node} | Elemento | Requisito | |---|---| | Sistema operativo | Linux con systemd su **x86_64**. I comandi `systemctl`, `nft`, `ip`, `ss`, `sysctl` e `useradd` devono esistere; in caso contrario l'installazione si interrompe indicando il comando mancante. | | Accesso per l'installazione | Un indirizzo IPv4 pubblico (gli indirizzi privati, di loopback e CGNAT vengono rifiutati), la porta SSH, un account con diritti di root o `sudo` e la relativa **password**. La password viene utilizzata solo per l'installazione e non viene memorizzata. | | Porte libere | **80, 443 e qualsiasi porta superiore a 60000** devono essere libere. L'installer non arresta né modifica mai i servizi già in esecuzione; segnala le porte occupate e si ferma. | | IPv6 | Un prefisso pubblico compreso tra **/32 e /64** all'interno di `2000::/3` che l'host può utilizzare come sorgente per il traffico in uscita, recapitato tramite **instradamento** (routed) verso l'host oppure **on-link** con proxy NDP (vedi sotto). | | Rete | I clienti si collegano all'IPv4 del nodo sulla porta 80 (proxy HTTP), sulla porta 443 (SOCKS5) e sulle porte 60001-65535 (una porta per IP statico). Il nodo non ha certificati, quindi non è presente alcun proxy HTTPS. Il traffico esce solo via IPv6 e soltanto verso destinazioni con un indirizzo IPv6. Il nodo recupera la propria configurazione dal pannello tramite HTTPS. | | Software del nodo sul server del pannello | Il demone del nodo e il relativo script di rete sono inclusi nel pacchetto di rilascio di NexCMP. Il pannello li copia dalla propria cartella di installazione (`/opt/nexcmp/releases//bin`, o `/opt/nexcmp/bin` su una build personalizzata) su ciascun nodo durante l'installazione. Il server del pannello richiede inoltre `sshpass` e un client SSH; il programma di installazione aggiunge `sshpass`, mentre su un server installato prima della versione 1.4.2 lo si aggiunge con `sudo apt-get install -y sshpass`. | | Dipende da | Il modulo **IPv6 Proxy** e l'URL del pannello a cui i nodi rispondono (**IPv6 Proxy › Settings › Panel URL for nodes**, predefinito `https://`). | ## Prepara l'infrastruttura {#prepare-the-infrastructure} ### Nodo VPN {#vpn-node-1} 1. **Provisioning dell'host** con una distribuzione Linux supportata e gli indirizzi IPv4 pubblici che desideri vendere, configurati sull'interfaccia di rete o instradati verso l'host. 2. **Se vendi un blocco instradato**, prevedi di inserirlo come **Extra subnet** quando aggiungi il nodo. L'agent installa una route `local dev lo` in modo che l'host accetti il traffico per ciascun indirizzo del blocco, segnalando poi gli indirizzi rilevati. L'agent legge inoltre la tabella di routing reale dell'host e non vende né cattura mai un indirizzo di **gateway**: se il blocco contiene il next-hop di una delle route dell'host (ad esempio l'indirizzo del router di un blocco on-link), l'agent installa le route `local` solo per le parti del blocco circostanti, segnala il gateway al pannello e quest'ultimo esclude quell'indirizzo dal pool e da qualsiasi allocazione. Rimuove le route installate quando la subnet supplementare cambia o l'agent si arresta. 3. **Apri il firewall.** Consenti traffico TCP e UDP in ingresso **65001-65535** sugli indirizzi pubblici e HTTPS in uscita verso il pannello. 4. **Facoltativo: contatori di byte per IP.** La contabilità conntrack (`net.netfilter.nf_conntrack_acct = 1`) consente al ruolo di monitoraggio di contare i byte per IP. Il pannello può attivarla inviando all'agent un comando `acct`, che scrive anche `/etc/sysctl.d/99-cmp-agent.conf`. Il ruolo VPN in sé non ne ha bisogno. 5. **Verifica il pannello dal nodo:** ```bash curl -fsS -o /dev/null -w '%{http_code}\n' https://cloud.example.com/install.sh ``` ### Nodo proxy IPv6 {#ipv6-proxy-node-1} Un prefisso IPv6 raggiunge il nodo in uno di questi due modi. L'installer li testa entrambi con connessioni in uscita reali e mantiene ciò che funziona. | Tipo | Significato | Configurazione | |---|---|---| | **Instradato** | Il tuo upstream instrada un prefisso (ad esempio un /48 o un /56) **verso l'indirizzo del nodo stesso**. I pacchetti in uscita possono utilizzare qualsiasi indirizzo nel prefisso come mittente e le risposte tornano al nodo. | Richiedi al tuo provider un prefisso instradato il cui next hop sia il nodo. Nient'altro sul nodo: il servizio proxy usa socket trasparenti, una tabella di policy routing fissa e `nft`. | | **On-link** | Il /64 si trova sulla stessa LAN del nodo. Le risposte funzionano solo se il nodo risponde alla discovery dei vicini per ciascun indirizzo in uso (**NDP proxy**). | Il servizio imposta, solo su quell'interfaccia, `net.ipv6.conf..accept_ra=2`, `forwarding=1` e `proxy_ndp=1`, memorizza i valori precedenti, li ripristina all'arresto e blocca l'inoltro degli indirizzi del pool in modo che il nodo non diventi un router per il pool. | Come funziona la verifica: il nodo tenta una connessione TCP verso un indirizzo IPv6 pubblico (porta 443) da un indirizzo casuale del prefisso candidato, entro 6 secondi. I candidati sono indirizzi globali sulle interfacce con un prefisso pari o inferiore a /64, oltre a route di tipo `local`, `unreachable` o `blackhole` comprese tra /16 e /64. Un prefisso più breve di /64 viene accettato come **routed** se un /64 casuale al suo interno funziona. ::: warning Non utilizzare lo stesso prefisso due volte Un prefisso non può sovrapporsi a quello di un altro nodo e non può essere più ampio di un prefisso già appartenente al pool IPv6 del pannello. Un /64 **all'interno** del pool del pannello è consentito. Le sovrapposizioni vengono segnalate come "assign range … (node …)" nell'esito dell'installazione e il prefisso viene ignorato. ::: Limitazioni applicate autonomamente dal nodo: i clienti non possono inviare posta (porte 25, 465, 587, 2525) dagli indirizzi del pool e il traffico IPv4 del demone è limitato alle risposte, al pannello e al DNS. ## Collega in NexCMP {#connect-in-nexcmp} ### Nodo VPN {#vpn-node-2} 1. Su **System › Admin › License & updates**, attiva l'interruttore **VPN**. Vedi [Modules](https://nexcmp.com/it/docs/infrastructure/modules/). ![La scheda Modulo con gli interruttori VPN e IPv6 Proxy](https://nexcmp.com/it/docs/images/infrastructure/vpn-proxy-nodes-01-modules.webp) 2. Apri **Infrastructure › VPN & Proxy nodes › Agents & external nodes**. Hai due modi per aggiungere un nodo. **a. Installa tramite SSH.** Clicca su **+ Add server (SSH)** e compila: | Campo | Valore di esempio | |---|---| | Indirizzo IPv4 del server | `192.0.2.50` | | Porta SSH | `22` | | Utente SSH | `root` | | Password SSH | `XXXX` | | Nome visualizzato | `node-ny-1` (vuoto: prende il nome dall'IP) | | Ruolo del server | Nodo VPN / Proxy esterno | | Assegnazione della zona | Auto tramite GeoIP (crea / assegna zona) o una zona esistente | | Sottorete extra (opzionale) | vuoto per la scansione automatica delle interfacce, o un blocco instradato come `203.0.113.0/24` | | Abilita alla vendita dopo l'installazione | attivo per contrassegnare come vendibile ogni indirizzo rilevato | Clicca su **Connect & install**. Il pannello si connette via SSH, esegue l'installatore a riga singola sul nodo con un ticket monouso e mostra il nome del nodo, la posizione GeoIP e gli intervalli rilevati. ![Finestra di dialogo Aggiungi nodo via SSH con un esempio di indirizzo e ruolo del server](https://nexcmp.com/it/docs/images/infrastructure/vpn-proxy-nodes-02-add-server-ssh.webp) **b. Installazione manuale.** Fai clic su **Generate manual install token**. Il comando viene mostrato **una sola volta**; copialo ed eseguilo sul nodo: ```bash curl -fsSL https://cloud.example.com/install.sh | sudo sh -s -- --token XXXX --name node-ny-1 ``` L'installazione tramite token registra la macchina solo per il monitoraggio: per sicurezza, il pannello non consente a una macchina dotata del token condiviso di assegnarsi il ruolo VPN (l'aggiunta di `--roles vpn` al comando non ha effetto). Dopo che la macchina compare nell'elenco, aprila e assegna manualmente il ruolo **VPN**. L'installazione tramite SSH (opzione a) assegna al nodo il ruolo VPN fin dall'inizio. Un nuovo token revoca quello precedente; gli host già registrati continuano a funzionare perché utilizzano una propria chiave. ![Finestra del comando di installazione che mostra il comando con token monouso](https://nexcmp.com/it/docs/images/infrastructure/vpn-proxy-nodes-03-install-command.webp) Cosa fa l'installatore: scarica `cmp-agent-linux-amd64` dal pannello, ne **verifica l'SHA-256**, lo installa in `/usr/local/bin/cmp-agent`, si registra con il token, scrive `/etc/cmp-agent/agent.json` e avvia il servizio systemd `cmp-agent`. Per rimuoverlo: `curl -fsSL https://cloud.example.com/install.sh | sudo sh -s -- --uninstall`. 3. Dopo il primo heartbeat, il nodo compare nell'elenco. Il suo paese viene rilevato tramite GeoIP (prima la ricerca del nodo stesso, poi il database del pannello); se non ne esiste già una, viene creata e resa pubblica una **zona** per quel paese, e gli indirizzi trovati sull'host diventano intervalli del pool. 4. Apri **Infrastructure › VPN & Proxy nodes › VPN IP pools** per visualizzare gli intervalli, la rispettiva zona e il nodo, e per modificare la zona, il nodo o l'interruttore **Sellable** di ciascun intervallo. **Enable range** consente ai nuovi ordini di usare i suoi IP liberi; **Disable range** interrompe solo le nuove allocazioni, mentre gli IP già assegnati continuano a funzionare. ![Pool di IP VPN con intervalli segnalati da un nodo](https://nexcmp.com/it/docs/images/infrastructure/vpn-proxy-nodes-04-vpn-pool.webp) 5. Apri **Services › VPN**, imposta il listino prezzi e attiva le vendite. Lo switch **Sell VPN** in **Subscriptions** corrisponde allo stesso switch del modulo VPN in License & updates. 6. **Facoltativo: rinomina il servizio.** In **Settings › Branding**, **VPN service display name** modifica il nome visualizzato del servizio VPN nel menu clienti, nella pagina d'ordine, nella pagina di dettaglio e nell'elenco di deploy (ad esempio `IPv4 Proxy`, `Datacenter Proxy` o `Static Residential Proxy`; fino a 40 caratteri, lasciando vuoto si mantiene `VPN`). Modifica solo le etichette: route, dati e API restano invariati. ### Nodo proxy IPv6 {#ipv6-proxy-node-2} 1. Su **System › Admin › License & updates**, attiva l'interruttore **IPv6 Proxy**. 2. Apri **Infrastructure › VPN & Proxy nodes › IPv6 Proxy nodes** e clicca su **Add node (SSH)**. Inserisci l'indirizzo IPv4 del nodo, la porta SSH, l'utente, la password, un nome opzionale e un **Reason** (verrà registrato nel registro di audit), quindi clicca su **Install**. ![Finestra di dialogo Aggiungi nodo IPv6 con un indirizzo di esempio e un motivo](https://nexcmp.com/it/docs/images/infrastructure/vpn-proxy-nodes-05-proxy6-add-node.webp) 3. Dopodiché il pannello esegue in sequenza: verifica la macchina e le porte, copia il demone, lo script di rete, l'unità di servizio e un file di ambiente specifico per il nodo (un token del nodo e una chiave di firma della password), esegue la **probe** per trovare i prefissi utilizzabili, registra i prefissi nel pool, avvia il servizio e attende fino a 90 secondi per il primo report. **Install log** mostra ogni passaggio. 4. Un nuovo nodo crea la propria zona nello stato **off** (in base al GeoIP dell'IPv4 del nodo). Attiva la zona in **Infrastructure › Datacenter › Zone** affinché i clienti possano sceglierla. 5. Imposta un limite di **Mbps cap** totale per nodo (da 10 a 100000 per direzione). Sotto **Services › IPv6 Proxy** imposta il listino prezzi e attiva le vendite. 6. Verifica **IPv6 Proxy › Settings › Panel URL for nodes**. I nodi chiamano questo indirizzo (`https://host`, senza percorso) per recuperare la configurazione e inviare report. Lasciare vuoto equivale a `https://`. Deve trattarsi di un host il cui indirizzo punta direttamente al pannello, così che l'IPv4 del nodo lo raggiunga senza modifiche. ::: tip Pianificazione della rotazione I clienti possono impostare un intervallo di rotazione automatica da 30 a 600 secondi. In NexCMP il pannello gestisce tale pianificazione (e la pulizia oraria dei log di connessione); i nodi acquisiscono un nuovo indirizzo entro circa 5 secondi. ::: ### Come comunica un nodo {#how-a-node-reports} | | Nodo VPN (`cmp-agent`) | Nodo proxy IPv6 | |---|---|---| | Registrazione | Ticket o token una tantum via HTTPS, poi la propria chiave | Installazione SSH una tantum, poi un token del nodo | | Heartbeat | Ogni **5 secondi** (10 s per un agente di solo monitoraggio); il pannello può impostare da 3 a 300 s. Dopo un errore, effettua un backoff con incrementi di 5 s fino a 60 s | Il nodo invia un report circa ogni 60 secondi e recupera la configurazione | | Mostrato come online | Un heartbeat negli ultimi **60 secondi** | **attivo** negli ultimi **120 secondi**, altrimenti **heartbeat mancato** | | Modifica della configurazione | Applicata al successivo heartbeat | Applicata entro circa 5 secondi | | Aggiornamenti | Il pannello può inviare un comando `upgrade` con la nuova versione, l'URL e l'hash SHA-256 | Reinstallazione dalla riga del nodo | ### Soglia dati su un nodo VPN {#data-allowance-on-a-vpn-node} A partire da NexCMP **1.5.1**, l'agent del nodo VPN trasmette il traffico gestito a ogni heartbeat e il pannello lo somma al consumo del piano per il periodo corrente. Lo stesso valore viene mostrato al cliente (schede Overview e Bandwidth) e a te (VPN › Subscriptions, colonna Used e riga del nodo). - **Interruzione.** Quando un piano ha esaurito i propri GB per il periodo, il pannello smette di inviare gli endpoint di quel piano all'agent, per cui le nuove connessioni vengono rifiutate e quelle attive vengono chiuse. L'interruzione si verifica entro un heartbeat, pertanto un piano può superare di poco il limite. I piani con livello Unlimited non vengono mai interrotti. - **Riattivazione.** Il servizio del piano viene ripristinato entro un heartbeat dopo che il cliente ha acquistato ulteriore larghezza di banda o all'avvio del periodo successivo. - **Non misurato.** Un nodo il cui agent non ha inviato i dati di utilizzo (ad esempio un agent meno recente) viene mostrato come **Not measured** e i relativi piani non vengono mai interrotti a causa dei GB. - **Aggiorna l'agent.** Usa l'agent **1.5.1** sui nodi. Gli agent precedenti vengono comunque conteggiati, ma possono perdere i byte di un heartbeat non riuscito, di un endpoint arrestato o di un riavvio, e non chiudono le connessioni aperte quando un piano viene interrotto. Aggiorna dalla riga del nodo (Reinstall) o con il comando `upgrade`. - Il conteggio riguarda il payload che transita attraverso il proxy, pertanto è leggermente inferiore (circa 1 %) rispetto ai byte trasmessi sulla rete. ### Add-on VPN ritirati {#retired-vpn-add-ons} High IP Reputation, High Concurrency e High Priority Network non sono più disponibili per i nuovi ordini. Gli abbonamenti esistenti mantengono le selezioni degli add-on, ma dai relativi importi di rinnovo vengono rimosse le tariffe ritirate. Non è previsto alcun rimborso per i periodi già pagati. L'adeguamento applica il prezzo di catalogo corrente dell'add-on; se tale prezzo è stato modificato o l'add-on è stato eliminato, verifica l'importo di rinnovo dell'abbonamento prima del rinnovo successivo. ## Verifica {#verify} 1. La riga del nodo è online. Per un nodo VPN, **Agents & external nodes** mostra zona, paese, ruolo e intervalli rilevati. 2. **VPN IP pools** elenca gli intervalli con IP liberi; la pagina di dettaglio della zona mostra l'infrastruttura VPN. 3. Ordina un piano VPN o proxy di test. Il cliente riceve un endpoint `ip:port`, un nome utente e una password; connettiti tramite essi e verifica che l'IP pubblico visibile sia quello del nodo (ad esempio `curl --proxy socks5h://USER:XXXX@IP:PORT https://ifconfig.me`). 4. Su un nodo IPv6, esegui sull'host: ```bash systemctl is-active nft list tables | grep proxy6 ss -ltn | grep -E ':(80|443|6[0-9]{4})\b' ``` ## Limiti e note {#limits-and-notes} - Gli host Windows possono eseguire l'agente di monitoraggio ma non il ruolo VPN. - Traffico incluso (GB per periodo) di un piano VPN: a partire da NexCMP 1.5.1 il pannello somma il traffico segnalato dall'agent del nodo VPN e disattiva i proxy del piano quando i GB del periodo sono esauriti (vedi "Data allowance on a VPN node" più sotto). I piani IPv6 Proxy non hanno una soglia di GB; limitano la velocità in Mbps per piano. - Gli indirizzi IPv4 di un piano VPN non ruotano. Un cliente segnala un IP in blacklist; tu o il rivenditore approvate una sostituzione dalla stessa zona. Solo IPv6 Proxy effettua la rotazione. - Vengono segnalati al massimo 64 intervalli per heartbeat. - Un set di endpoint VPN utilizza tre porte per ogni IP venduto. Con le porte 65001-65535 ciascun IP serve un numero limitato di endpoint (178 set di porte); il pannello salta i set già utilizzati in precedenza. - L'eliminazione di un nodo proxy IPv6 è consentita solo quando nessun piano detiene un IP su di esso. Rimuove gli intervalli e il token del nodo; il software sull'host non viene disinstallato. - È possibile rivendere un intervallo che ospita anche le tue VM: la VPN utilizza solo le porte 65001-65535, condividendo quindi l'IP con altri servizi. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | "registrazione non riuscita (token non valido o server irraggiungibile)" | Token errato o già utilizzato, oppure il pannello non è raggiungibile | Genera un nuovo token o riprova l'installazione SSH. | | "firma del file non corrispondente - STOP" | L'agente scaricato differisce dall'hash SHA-256 pubblicato | Verifica la cartella `/dl/` del pannello e che nulla modifichi il download durante il transito. | | "questo installer è solo per Linux" / "l'architettura … non è ancora supportata" | Windows o un'architettura diversa da x86_64 (la release include l'agent solo per x86_64) | Utilizza un host Linux x86_64. | | Il nodo non compare | Il nodo non riesce a raggiungere il pannello tramite HTTPS | Testa `curl https:///install.sh` dal nodo; controlla il DNS e il firewall. | | Il nodo compare con il paese errato | La ricerca del paese non è riuscita, quindi è stato utilizzato il database degli indirizzi del pannello | Consenti l'accesso in uscita a `ip-api.com` e `ipinfo.io` o seleziona esplicitamente la zona nel modulo SSH. | | Nessun intervallo rilevato | Nessun IPv4 pubblico su un'interfaccia non virtuale | Aggiungi un indirizzo pubblico o inserisci il blocco instradato come **Extra subnet**. | | La VPN funziona, il traffico esce da un altro IP | L'IP venduto non è assegnato o instradato verso l'host | Assicurati che l'IP si trovi su un'interfaccia o sia coperto da `local … dev lo`. | | "il server del pannello non dispone di sshpass" | L'host del pannello non riesce ad accedere ai nodi con password | Esegui `sudo apt-get install -y sshpass openssh-client` sul server del pannello, quindi installa nuovamente il nodo. | | "not found in the installed package" durante l'installazione di un nodo IPv6 | Il pannello è precedente alla versione 1.4.2 oppure è una build personalizzata senza i file del nodo | Aggiorna NexCMP alla versione 1.4.2 o successiva; per una build personalizzata usa `build.sh`, che ora include `brandy-proxy6d` e `brandy-proxy6-net`. | | "SSH: …" all'inizio di un'installazione IPv6 oppure "SSH to internal/loopback addresses is not allowed" | Porta, utente o password errati, SSH bloccato o indirizzo privato | Utilizza l'IPv4 pubblico del nodo e verifica l'accesso manualmente con `ssh -p PORT USER@IP`. | | "architettura … non supportata (solo x86_64)" | Il nodo non è x86_64 | Utilizza un host x86_64. | | "comando mancante sul nodo: …" | `nft`, `ip`, `ss`, `sysctl`, `systemctl` o `useradd` non installati | Installa i pacchetti, quindi esegui nuovamente l'installazione. | | "porte in uso da un altro servizio sul nodo: … — 80, 443, 60001-65535 devono essere libere" | Le porte 80, 443 o una porta superiore a 60000 sono occupate | Sposta l'altro servizio; l'installatore non lo arresta. | | "nessun prefisso IPv6 con accesso a Internet trovato dal nodo (probe di egress reale non riuscito)" | Nessun prefisso instradato, proxy NDP non possibile o nessun IPv6 in uscita | Verifica che il prefisso sia instradato al nodo, che l'interfaccia abbia connettività IPv6 e che nulla filtri il traffico in uscita. | | "tutti gli intervalli rilevati appartengono già a un altro nodo" | Il prefisso è già utilizzato da un altro nodo | Rimuovilo dall'altro nodo o scegli un altro prefisso. | | L'installazione termina con "no initial report received from node" | Il servizio è stato avviato ma non ha raggiunto il pannello entro 90 secondi | Controlla l'URL del pannello fornito ai nodi e il percorso HTTPS del nodo verso di esso; vedi il **Install log**. | | La riga del nodo mostra **missed heartbeat** | Nessun report per 120 secondi | Controlla il servizio sul nodo, il suo orologio e il percorso verso il pannello. | | I clienti non visualizzano alcuna posizione IPv6 | La zona è disattivata | Abilita la zona in **Zone**. | --- # AI Models {#ai-models} > **Nel pannello admin:** System › Admin › License & updates (`/license`) per attivare il modulo. Quindi Services › AI Models: Providers (`/ai/providers`), Models (`/ai/models`), Profit (`/ai/profit`) e Audit (`/ai/audit`). I clienti utilizzano AI › API nel portale clienti. ## Descrizione {#what-it-does} AI Models è un gateway e un livello di fatturazione sul tuo pannello. I tuoi clienti ottengono chiavi API e chiamano **un unico endpoint sul tuo dominio**, nel formato compatibile con OpenAI o Anthropic. Scegli quali modelli offrire e il costo di ciascuno per 1 milione di token. NexCMP verifica la chiave, i limiti e il wallet, invia la richiesta al provider che hai aggiunto, conteggia i token e addebita l'importo sul wallet prepagato del cliente. **Le sorgenti dei modelli sono a tuo carico.** NexCMP viene fornito senza provider, modelli, indirizzi predefiniti o prezzi. Non fornisce modelli, chiavi API, token o account provider. ::: warning Verifica prima i termini delle tue sorgenti Molte sorgenti di modelli limitano la rivendita o la cessione dell'accesso a terzi. Utilizza solo sorgenti che sei autorizzato a usare e rivendere, e rispetta i loro termini e le normative applicabili. Questa pagina non costituisce una consulenza legale. ::: AI Models è un prodotto distinto da **AI Chat and AI Agent** (modulo **AI**, vedi [provider AI](https://nexcmp.com/it/docs/ai/ai-providers/)). I due moduli non dipendono l'uno dall'altro. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Modulo | **AI Models** attivato in License & updates, Modules. È disattivato per impostazione predefinita. | | Provider | Una o più sorgenti di modelli che sei autorizzato a rivendere, ciascuna con una API compatibile con OpenAI (`/chat/completions`), una API compatibile con Anthropic (`/messages`) o entrambe. Ciascuna richiede un URL di base e una chiave API. | | Rete | Il pannello deve raggiungere ciascun provider tramite **HTTPS sulla porta 443** a un nome di dominio pubblico. Un provider su un host interno, un'altra porta o in semplice HTTP deve essere elencato in **Allowed internal hosts** (impostazione `ai_endpoint_allow`). | | Clienti | Un account cliente con un indirizzo email verificato e un saldo nel wallet. | | Hardware | Nessuno. NexCMP si limita a inoltrare le richieste: nessuna GPU e nessun file di modello. | ## Prepara l'infrastruttura {#prepare-the-infrastructure} 1. Ottieni una chiave API da ciascuna sorgente di modelli che intendi utilizzare e annota il relativo URL di base (ad esempio `https://api.example.com/v1`). 2. Verifica i termini della sorgente relativi alla rivendita. 3. Se una sorgente è in esecuzione all'interno della tua rete, stabilisci il suo indirizzo, ad esempio `http://10.0.0.5:8000/v1`. Inserirai `10.0.0.5:8000` in **Allowed internal hosts**. ## Collega in NexCMP {#connect-in-nexcmp} ### 1. Attiva il modulo {#_1-turn-the-module-on} Apri **System › Admin › License & updates**, individua la scheda **Module** e attiva **AI Models**. Il menu si ricarica e appare **Services › AI Models**. Finché il modulo è disattivato, le pagine del cliente, quelle di amministrazione e il gateway rispondono tutte con `404 module_disabled` e nessun provider viene contattato. ![La scheda Module con lo switch AI Models attivato](https://nexcmp.com/it/docs/images/infrastructure/ai-models-01-modules.webp) ### 2. Aggiungi un provider {#_2-add-a-provider} 1. Apri **AI Models › Providers** e seleziona **Add provider**. 2. Inserisci uno **slug** breve, un **name** (visibile solo a te), il **type** (OpenAI-compatible, Anthropic-compatible o Both), il **base URL**, la **API key** e una **priority** (un numero più basso viene tentato per primo). 3. Salva. La chiave viene memorizzata in modo cifrato e in seguito ne vengono mostrati solo gli ultimi quattro caratteri. È possibile inserire una chiave solo da una sessione amministratore autenticata. Usa **Both** solo per un gateway che gestisce realmente entrambi i formati. NexCMP **non** converte tra i due formati: un modello fornito da un provider compatibile con OpenAI viene raggiunto su `/ai/v1/chat/completions`, mentre uno fornito da un provider compatibile con Anthropic su `/ai/v1/messages`. ![La pagina Providers che elenca tre provider di esempio con tipo, priorità e stato](https://nexcmp.com/it/docs/images/infrastructure/ai-models-02-providers.webp) ### 3. Testa la connessione {#_3-test-the-connection} Scegli **Test connection** sul provider. NexCMP legge `GET /models` con la chiave e restituisce **ok**, oppure il motivo dell'errore: **auth** (chiave errata), **blocked**, **billing** o **unreachable**. I test sono limitati a 6 al minuto. ### 4. Sincronizza i modelli {#_4-sync-the-models} Scegli **Sync models**. NexCMP legge l'elenco dei modelli del provider e aggiunge ciascun nuovo modello **disattivato e senza prezzo**. Un modello non più presente nell'elenco del provider viene contrassegnato. Finché il modulo è attivo, l'elenco viene sincronizzato automaticamente anche ogni 6 ore (impostazione `ai_models_sync_hours`). ### 5. Imposta i prezzi e attiva i modelli {#_5-set-prices-and-switch-models-on} 1. Apri **AI Models › Models**. 2. Per ogni modello che desideri vendere, imposta il **prezzo di vendita** in dollari USA per 1 milione di token: **input**, **cached input** e **output**. 3. Facoltativamente, inserisci il tuo **costo** per il modello. In questo modo **Profit** mostrerà le entrate a fronte dei costi per giorno e per modello, e un prezzo di vendita inferiore al costo più il margine minimo (impostazione `ai_min_margin_pct`, 10 per impostazione predefinita) verrà rifiutato a meno che tu non confermi una perdita intenzionale. **Set price from cost** utilizza un ricarico a tua scelta; non è previsto alcun ricarico predefinito. 4. Attiva il modello. Un modello senza prezzo di vendita non può essere attivato. Un prezzo di cached input lasciato a zero viene fatturato al prezzo di input. ![La pagina Models con i prezzi di vendita di input, cached input e output e gli interruttori di attivazione](https://nexcmp.com/it/docs/images/infrastructure/ai-models-03-models.webp) ### 6. Routes e failover {#_6-routes-and-failover} Su un modello, **Routes** elenca i provider che lo gestiscono, in ordine. Aggiungi un secondo provider come fallback, definisci l'ordine e, facoltativamente, assegna un nome di modello diverso per ciascun provider (il nome inviato al provider può differire da quello pubblicato). Quando un provider restituisce un errore del server, un errore di autorizzazione o fatturazione, un modello mancante o un limite di frequenza, NexCMP prova la route successiva. Se una lettura va in timeout dopo l'invio della richiesta, **non** viene inviata a un altro provider, evitando doppi addebiti. Ogni provider è regolato a `ai_provider_rpm` richieste al minuto (50 per impostazione predefinita). Se un provider continua a restituire errori di autorizzazione o fatturazione, NexCMP avvisa l'amministratore su Telegram, se configurato. ### 7. Attiva l'interruttore di vendita {#_7-open-the-sale-switch} Nella parte superiore delle pagine AI Models, l'**interruttore di vendita** (impostazione `feature_ai_models`) è disattivato per impostazione predefinita. Finché rimane disattivato, i clienti vedono che il servizio non è ancora aperto e il listino prezzi pubblico lo segnala come non disponibile. Verifica che almeno un modello sia attivo, abbia un prezzo di vendita e una route con una chiave, quindi attivalo. ### Cosa possono fare i clienti {#what-customers-can-do} Nel portale clienti, **AI › API**: - **Models** mostra i tuoi modelli e i relativi prezzi, l'URL di base e comandi di esempio già pronti. - **API Keys**: crea, rinomina, ruota, disabilita ed elimina chiavi. Il segreto viene mostrato una sola volta; viene memorizzato solo un hash. Per ciascuna chiave: modelli consentiti, scadenza, un soft budget (invia un avviso) e un hard budget (blocca con `402`), richieste al minuto e token al minuto. - **Usage** per modello, chiave e giorno, con esportazione. - **Logs**: registrazioni delle richieste filtrabili (orario, chiave, modello, token, costo, stato, latenza). **Prompt e risposte non vengono registrati.** I log vengono conservati per 90 giorni per impostazione predefinita (`ai_log_retention_days`). - **Settings**: un budget dell'account e l'indirizzo email per gli avvisi di budget. - **Playground**: chatta con un modello, confronta i modelli affiancati e copia il codice corrispondente. ![La pagina API Keys del cliente con gli URL di base per entrambi i formati API](https://nexcmp.com/it/docs/images/infrastructure/ai-models-04-keys.webp) Gli endpoint del gateway, sul tuo dominio: ```text POST /ai/v1/chat/completions OpenAI-compatible POST /ai/v1/messages Anthropic-compatible (also /ai/v1/messages/count_tokens) GET /ai/v1/models model list GET /ai/v1/models/pricing public price list, no key needed ``` ### Wallet e fatturazione {#wallet-and-billing} L'utilizzo dell'AI viene addebitato sullo stesso wallet prepagato di qualsiasi altro servizio. Prima che una richiesta venga inviata a un provider, NexCMP riserva l'importo massimo stimato per il costo della richiesta; se il saldo è inferiore al minimo (`ai_min_balance_cents`, 20 centesimi per impostazione predefinita) o insufficiente, la richiesta viene rifiutata con `402 insufficient_balance` e **nessun provider viene contattato**. L'utilizzo viene aggregato per account e registrato nelle voci mastro del wallet ogni ora, con una scansione ogni 5 minuti; l'utilizzo non ancora contabilizzato viene già sottratto dal saldo visibile al gateway. I rivenditori possono vendere AI Models sul proprio dominio: il loro ricarico o sconto si applica al tuo prezzo di vendita e al loro wholesale wallet viene addebitato il prezzo all'ingrosso. Un interruttore AI dedicato per rivenditore, attivo per impostazione predefinita, controlla chi può venderlo. ## Verifica {#verify} 1. Dopo il passaggio 3, **Test connection** mostra **ok** e il conteggio dei modelli. 2. Dopo il passaggio 4 i nuovi modelli compaiono nell'elenco, disattivati e senza prezzo. 3. Come cliente con un wallet ricaricato, crea una chiave ed effettua una chiamata al gateway: ```bash curl https://your-domain/ai/v1/chat/completions \ -H "Authorization: Bearer sk-ai-…" -H "Content-Type: application/json" \ -d '{"model":"model-one","messages":[{"role":"user","content":"hello"}]}' ``` Una risposta `200` restituisce la risposta del modello. **Usage** mostra la richiesta, e **Profit** la mostra se hai inserito un costo. 4. Con il wallet a zero, la stessa chiamata restituisce `402 insufficient_balance`. ## Limiti e note {#limits-and-notes} - Il modulo non include provider, modelli o prezzi predefiniti e non acquisisce mai listini prezzi da un provider. - I tool eseguiti sul lato provider con addebito per chiamata, come la ricerca web, vengono rifiutati poiché non possono essere misurati. Viene inoltrato solo un set ristretto di parametri di richiesta. - Il consumo di token viene ricavato dalla risposta del provider; se la risposta non ne contiene, NexCMP lo stima e contrassegna la registrazione come stimata. - Gli errori restituiti da un provider vengono ripuliti prima di raggiungere il cliente (nomi, host, indirizzi e il nome del modello del provider vengono rimossi). I clienti non vedono mai quale provider ha gestito la richiesta. - I clienti raggiungono il gateway tramite il dominio del tuo pannello, pertanto il protocollo TLS di tale dominio deve essere operativo. - NexCMP non fornisce accordi sul livello di servizio (SLA), fine-tuning o hosting GPU per questo modulo. ## Troubleshooting {#troubleshooting} | Sintomo | Causa e soluzione | |---|---| | Tutte le pagine di AI Models e il gateway rispondono con `404 module_disabled` | Il modulo è disattivato. Attiva **AI Models** in License & updates, Modules. | | L'aggiunta di un provider fallisce con `endpoint_host_not_allowed`, `endpoint_must_be_https` o `invalid_endpoint_port` | L'URL di base deve utilizzare HTTPS sulla porta 443 con un nome di dominio pubblico. Per un host interno, un'altra porta o HTTP standard, inserisci `host:port` in **Allowed internal hosts**. | | `blocked_endpoint` | L'indirizzo è un IP o il nome si risolve in un indirizzo privato. Inseriscilo in **Allowed internal hosts** se questa è la configurazione desiderata. | | **Test connection** restituisce `auth` | La chiave è errata o non dispone dei permessi necessari. Inserisci nuovamente la chiave. | | Impossibile attivare un modello (`no_price`) | Imposta prima un prezzo di vendita. | | I clienti ricevono `503 ai_unavailable` | L'opzione di vendita è disattivata, oppure l'interruttore AI del rivenditore è disattivato. | | I clienti ricevono `503 upstream_unavailable` | Nessun instradamento attivo provvisto di chiave serve questo modello nel formato richiesto. Verifica i route del modello e la tipologia di provider. | | I clienti ricevono `402 insufficient_balance` | Il saldo del wallet è inferiore al minimo o insufficiente per la richiesta. Invita il cliente a effettuare una ricarica. | --- # Object Storage (S3, Ceph RGW) {#object-storage-s3-ceph-rgw} > **Dove trovarlo nel pannello:** Infrastructure › Cloud provider › Ceph S3 (RGW) (`/infra/s3`). Account: Services › Object Storage › S3 accounts (`/s3`). Prezzi: Services › Object Storage › PAYG pricing (`/s3/policy`). Attiva il modulo in System › Admin › License & updates. ## Descrizione {#what-it-does} I clienti creano account S3 dal portale e ottengono le chiavi di accesso. NexCMP crea ed elimina gli utenti corrispondenti sul tuo **Ceph RADOS Gateway (RGW)** tramite la RGW Admin Ops API, legge l'utilizzo per la fatturazione e addebita il pay-as-you-go: storage oltre una soglia gratuita per GB al mese (fatturato a ore) e traffico di download per GB. I caricamenti sono gratuiti. Usalo quando gestisci un cluster Ceph con RGW e desideri rivendere object storage. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Ceph | Un cluster con almeno un demone RGW, con la **Admin Ops API** abilitata (l'impostazione predefinita `rgw_enable_apis` include `admin`). | | Utente admin | Un utente RGW per NexCMP con le funzionalità elencate di seguito. Non utilizzare un utente che possiede i dati dei clienti. | | Endpoint | L'endpoint S3 utilizzato dai clienti e l'endpoint Admin Ops. Entrambi sono scritti come `https://host` **senza percorso, solo porta 443**, e devono risolversi in un indirizzo **pubblico**: gli indirizzi loopback, link-local, multicast, privati e unique-local vengono rifiutati. | | Certificato | Un certificato valido per l'host dell'endpoint. | | Log di utilizzo | Logging dell'utilizzo RGW attivo (`rgw_enable_usage_log = true`), in modo che l'API di utilizzo possa segnalare il traffico. | | Zona | Una zona master con il servizio **Object Storage (S3)** spuntato. Vedi [Zones](https://nexcmp.com/it/docs/infrastructure/zones/). | | Storage | Capacità in Ceph per le quote che vendi. | | Dipende da | Il modulo **Object Storage**. Il traffico di download concorre inoltre al conteggio di [Bandwidth](https://nexcmp.com/it/docs/catalog/bandwidth/). | ## Prepara l'infrastruttura {#prepare-the-infrastructure} Su un nodo admin Ceph: 1. Crea l'utente admin e assegnagli le funzionalità Admin Ops necessarie: ```bash radosgw-admin user create --uid=nexcmp-admin --display-name="NexCMP admin" radosgw-admin caps add --uid=nexcmp-admin --caps="users=*;buckets=*;usage=read;metadata=read" radosgw-admin user info --uid=nexcmp-admin ``` Copia `access_key` e `secret_key` dall'output. Sono la **Admin access key** e la **Admin secret key** in NexCMP. 2. Attiva il log di utilizzo e riavvia i gateway: ```bash ceph config set client.rgw rgw_enable_usage_log true ``` 3. Posiziona i gateway dietro HTTPS sulla porta 443 (un reverse proxy o il TLS nativo di RGW), pubblica il nome DNS ed esegui il test dal server del pannello: ```bash curl -fsS -o /dev/null -w '%{http_code}\n' https://s3.example.com/ ``` Dovresti ricevere una risposta XML S3 (HTTP 200 o 403), non un timeout. ## Collega in NexCMP {#connect-in-nexcmp} 1. **Assegna il servizio S3 a una zona.** Apri **Infrastructure › Datacenter › Zone**, modifica la zona e spunta **Object Storage (S3)**. Solo le zone master con il servizio S3 compaiono nel modulo di backend. 2. Apri **Infrastructure › Cloud provider › Ceph S3 (RGW)** e clicca **Add backend**: | Campo | Valore di esempio | |---|---| | Backend name | `Ceph RGW 1` | | Zona | la zona del passaggio 1 | | RGW Admin Ops endpoint | `https://s3.example.com` | | Endpoint S3 cliente | `https://s3.example.com` | | Regione di firma S3 | `default` | | Chiave di accesso amministrativa | `XXXX` | | Chiave segreta amministrativa | `XXXX` | | Active | on | | Abilita vendite (richiede prima il test di connessione) | **off** per ora | | Motivo della modifica | `initial setup` | ![Finestra di dialogo S3 del backend con endpoint di esempio, regione e chiavi mascherate](https://nexcmp.com/it/docs/images/infrastructure/s3-02-backend-dialog.webp) 3. Fai clic su **OK** (salva), quindi su **Check** nella riga. NexCMP chiama l'API Admin Ops con la chiave admin. **Ceph connection successful** e il tag **Verified** indicano che funziona. 4. Fai clic su **Edit**, attiva l'opzione **Enable sales** e salva. NexCMP si rifiuta di aprire le vendite finché un controllo non va a buon fine. 5. Apri **Services › Object Storage › PAYG pricing** e imposta i prezzi: | Campo | Significato | |---|---| | Spazio oltre il piano gratuito (VND/GB/mese) | Prezzo dello spazio; fatturato a ore come prezzo mensile diviso per 730. | | Download (VND/GB) | Prezzo per il traffico in uscita. | | Upload (VND/GB) | Sempre 0. | | Livello gratuito con VM in esecuzione (GB) | Fissato a 100 GB per account finché il cliente ha almeno una VM in esecuzione, condiviso tra i relativi account S3 in base alle dimensioni. | | Limite di debito (VND) | L'ammontare di utilizzo non pagato consentito. | | Soglia di fatturazione (VND) | L'utilizzo viene aggregato in un'unica fattura una volta superato questo importo. | | Saldo minimo per creare S3 (VND) | Saldo del portafoglio necessario per creare un account. | | Max account S3 per cliente, Quota tecnica predefinita (GB) | Limiti per i nuovi account. | ![Modulo di prezzo S3 PAYG](https://nexcmp.com/it/docs/images/infrastructure/s3-04-pricing.webp) I prezzi S3 sono inseriti in VND. Vengono convertiti per la visualizzazione e gli addebiti sul portafoglio al tasso di cambio in vigore; vedi [Currency and exchange rates](https://nexcmp.com/it/docs/catalog/currency-and-exchange-rates/). ## Verifica {#verify} 1. **Check** restituisce "Ceph connection successful". 2. Come cliente (o con un account di test), crea un account S3. Su Ceph, `radosgw-admin user list` mostra un nuovo utente e **S3 accounts** lo elenca. 3. Crea un bucket con qualsiasi client S3 utilizzando le chiavi del cliente rispetto all'endpoint del cliente. Carica un file. 4. Dopo il ciclo di fatturazione dell'ora successiva, **S3 accounts** mostra l'utilizzo. ## Limiti e note {#limits-and-notes} - Un backend che ha già account associati mantiene la propria **zona, endpoint e regione**; per modificarli, crea un nuovo backend. - Una zona può avere il proprio backend; account e backend sono associati definitivamente a una zona. - Il livello gratuito e "gli upload sono gratuiti" sono regole fisse, non opzioni. - Le chiavi vengono memorizzate crittografate; la console mostra solo un campo "lascia vuoto per mantenere la chiave corrente". Una coppia di chiavi viene sempre inserita insieme. - Le chiavi segrete dei clienti vengono mostrate una volta sola alla creazione, mai più. Una chiave smarrita viene sostituita rigenerandola. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | "Endpoint requires HTTPS" | L'endpoint utilizza HTTP in chiaro | Pubblica HTTPS sulla porta 443. | | "Porta dell'endpoint non consentita" | Una porta diversa dalla 443 | Usa la porta HTTPS standard. | | "Indirizzo dell'endpoint non consentito" | Il nome viene risolto in un indirizzo privato, di loopback, link-local o unique-local | Usa un indirizzo pubblico. | | "L'endpoint deve contenere solo protocollo e host" | L'URL contiene un percorso, una query o informazioni utente | Usa solo `https://host`. | | "Impossibile risolvere l'endpoint" | Il DNS non viene risolto dal server del pannello | Correggi il DNS. | | "Failed to connect to Ceph" | Errore di firewall o TLS | Esegui il test con `curl` dal server del pannello. | | "Ceph returned HTTP 403 AccessDenied" | Chiavi errate o funzionalità mancanti | Verifica le chiavi ed esegui nuovamente `radosgw-admin caps add`. | | "Invalid Ceph response" | L'endpoint non è un'API RGW Admin Ops | Puntalo verso RGW, non verso una pagina web. | | "Il test di connessione deve riuscire prima di abilitare le vendite" | Hai attivato le vendite prima di un **Check** riuscito | Esegui **Check**, quindi abilita le vendite. | | "Tutte le nuove chiavi per l'endpoint sono obbligatorie" | L'endpoint è stato modificato senza entrambe le chiavi | Inserisci la chiave di accesso e la chiave segreta insieme. | | "Il backend ha già risorse collegate; crea un nuovo backend per cambiare zona o endpoint" | Esistono account su questo backend | Crea un nuovo backend. | | "Seleziona la master zone con il servizio S3" | La zona non è una zona master o non dispone del servizio S3 | Seleziona **Object Storage (S3)** sulla zona. | | "Invalid region" | La regione contiene caratteri diversi da lettere, cifre, `-` e `_` | Usa `default` o il nome del tuo RGW zonegroup. | | "Riepilogo dell'utilizzo di Ceph mancante; non fatturato" | Log di utilizzo disabilitato | Abilita `rgw_enable_usage_log`. | --- # Kubernetes e Private Cloud {#kubernetes-and-private-cloud} > **Dove nel pannello di amministrazione:** Kubernetes: Infrastructure › Cloud provider › CloudStack › Kubernetes (CKS) (`/infra/cloudstack?tab=k8s`), quindi Services › Kubernetes (Overview, Clusters, Versions, Policy). Private Cloud: Services › Private Cloud (Overview `/vpc`, VPC `/vpc/list`, Plans & pricing `/vpc/plans`). Attiva entrambi i moduli in System › Admin › License & updates. ## Descrizione {#what-it-does} - **Kubernetes.** I clienti creano cluster Kubernetes gestiti sul tuo CloudStack tramite CloudStack Kubernetes Service (CKS). Il control plane è gratuito; i clienti pagano per i nodi **worker**. NexCMP crea una rete separata e un IP pubblico per ciascun cluster, mantenendo isolati i cluster dei diversi clienti. - **Private Cloud.** I clienti ottengono una rete privata (un VPC di CloudStack) con router, subnet (tier), regole firewall (network ACL) e macchine virtuali all'interno. Viene venduto tramite **piano di banda** con velocità dedicata e illimitata (ad esempio 50, 100, 500 Mbps, 1 e 3 Gbps). Ciascun cliente può avere un VPC per impostazione predefinita. Entrambi sono basati su [CloudStack](https://nexcmp.com/it/docs/infrastructure/cloudstack/) e utilizzano la sua API tramite la stessa connessione. ## Requisiti {#requirements} ### Kubernetes {#kubernetes} | Elemento | Requisito | |---|---| | CloudStack | 4.23 (testato). CKS deve essere **abilitato** (`cloud.kubernetes.service.enabled = true`). | | Account | Un account **Domain Admin** nel dominio dedicato, in modo che NexCMP possa creare un progetto CloudStack per ciascun cliente e i relativi limiti di risorsa. Vedi [CloudStack](https://nexcmp.com/it/docs/infrastructure/cloudstack/#create-a-dedicated-account-and-api-key). | | `endpoint.url` | L'impostazione globale di CloudStack deve puntare alla tua API di gestione, raggiungibile dalle VM del cluster. NexCMP mostra il valore e l'esito di un controllo dell'endpoint. | | Versioni | Almeno una voce di versione supportata per Kubernetes con la relativa ISO dei binari, in stato **Enabled**. Le versioni giunte a fine vita non possono essere messe in vendita. | | Offerta del piano di controllo | Un'offerta di servizio gratuita con **esattamente 2 vCPU, 2048 MB RAM e un limite CPU** (`limitcpuuse = true`), visibile all'account. Il server rifiuta qualsiasi altra configurazione con `cp_offering_invalid`. | | Rete | Un'offerta di rete isolata compatibile con CKS che sia abilitata. | | IP | Indirizzi IPv4 pubblici gratuiti nell'intervallo vendibile; ogni cluster ne utilizza uno. | | Capacità | Ciascun cluster richiede da 2 a 4 GB di RAM per il piano di controllo e una piccola VM router. Monitora le schede della capacità. | ### Private Cloud {#private-cloud} | Elemento | Requisito | |---|---| | CloudStack | 4.23 (testata) con VPC abilitato. | | Offerta VPC | Un'offerta VPC. Un'offerta dual-stack assegna a ogni livello anche un IPv6 /64. | | Offerte di rete per i livelli | **Un'offerta di rete per ogni piano di banda**, creata per VPC, con la **velocità di rete** (Mbps) pari a quella del piano, più un'offerta **bloccata** di **1 Mbps** applicata quando un VPC viene bloccato per mancato pagamento. | | Account | L'account dedicato (consigliato Domain Admin). Le reti VPC rimangono nell'account, non nei progetti. | | IP | Indirizzi IPv4 pubblici gratuiti (ciascun VPC ne usa uno per il NAT di origine). | | Spazio di indirizzamento | Ciascun VPC riceve un /16 da `10.128.0.0/9`. Mantieni tale intervallo inutilizzato sulle tue reti. | | Dipende da | CloudStack connesso; il modulo **Private Cloud**. | ## Prepara l'infrastruttura {#prepare-the-infrastructure} ### Kubernetes: abilita CKS e aggiungi le versioni {#kubernetes-enable-cks-and-add-versions} 1. Abilita il servizio e imposta l'endpoint, quindi riavvia il server di gestione: ```bash cmk update configuration name=cloud.kubernetes.service.enabled value=true cmk update configuration name=endpoint.url value=https://cloudstack.example.com/client/api sudo systemctl restart cloudstack-management ``` `endpoint.url` viene richiamato dal controller del cluster, quindi deve essere un indirizzo raggiungibile dalle VM del cluster. 2. Crea un'ISO dei binari Kubernetes per la versione che desideri vendere, utilizzando lo script `create-kubernetes-binaries-iso.sh` dell'albero sorgente di CloudStack, ospitala su un server web e registrala: ```bash cmk add kubernetessupportedversion name="Kubernetes 1.35.0" semanticversion=1.35.0 \ url=https://files.example.com/setup-v1.35.0-calico-amd64.iso zoneid= \ mincpunumber=2 minmemory=2048 cmk list kubernetessupportedversions filter=name,semanticversion,state,isostate ``` Attendi che lo stato dell'ISO diventi **Ready** e la versione sia **Enabled**. 3. Crea l'offerta del piano di controllo, limitata al dominio NexCMP: ```bash cmk create serviceoffering name=K8S-CP-2-2 displaytext="Kubernetes control plane" \ cpunumber=2 cpuspeed=1000 memory=2048 limitcpuuse=true offerha=false domainid= ``` 4. Verifica che un'offerta di rete CKS sia abilitata: ```bash cmk list networkofferings state=Enabled forvpc=false filter=id,name ``` ### Private Cloud: crea le offerte {#private-cloud-create-the-offerings} Nell'interfaccia utente di CloudStack (**Service Offerings › Network Offerings › Add network offering**) o tramite `cmk`: 1. Elenca quelle esistenti: ```bash cmk list vpcofferings filter=id,name,state cmk list networkofferings forvpc=true filter=id,name,networkrate,state ``` 2. Usa un'offerta VPC abilitata (dual-stack se desideri IPv6). Se te ne serve una nuova, clona l'offerta VPC predefinita di CloudStack e abilitala. 3. Per **ciascun** piano di banda che vendi, crea un'offerta di rete **per VPC** (clona l'offerta predefinita "isolated network offering for VPC networks") e imposta **Network rate (Mb/s)** sulla velocità del piano: `50`, `100`, `500`, `1000`, `3000`. Abilita ciascuna offerta. 4. Crea un'ulteriore offerta con **network rate 1** (`VPC-LOCKED-1M`) per i VPC bloccati: i clienti potranno comunque raggiungere i propri server via SSH, ma la velocità sarà limitata. 5. Prendi nota dell'UUID di ogni offerta. NexCMP ne ha bisogno nella sezione successiva. ::: warning Gli ID delle offerte fornite non esistono nel tuo cloud Il modulo Private Cloud è precompilato con gli UUID di offerta appartenenti a un'altra installazione CloudStack. Sostituisci **ciascuno** di essi con il tuo, altrimenti il primo ordine di VPC non andrà a buon fine. ::: ## Collega in NexCMP {#connect-in-nexcmp} ### Kubernetes {#kubernetes-1} 1. Apri **Infrastructure › Cloud provider › CloudStack** e scegli la scheda **Kubernetes (CKS)**. La scheda a destra **CKS status on CloudStack (read-only)** mostra `kubernetesserviceenabled`, `endpoint.url` con **Endpoint check**, l'offerta di rete CKS, le impostazioni `cloud.kubernetes.*` e l'elenco di ISO e versioni. Fai clic su **Recheck** dopo aver risolto un problema. 2. In **Sales config**, scegli **Control plane Offering** (viene visualizzato un avviso se non è esattamente 2 vCPU / 2048 MB / limite CPU), imposta **Max workers per cluster** (da 1 a 9: CKS consente 10 nodi incluso il nodo di controllo), attiva l'interruttore **Enable CKS for this backend** e fai clic su **Save**. L'interruttore rimane disabilitato finché non viene scelta un'offerta. ![La scheda Kubernetes (CKS) con l'offerta del piano di controllo scelta e la scheda dello stato CKS](https://nexcmp.com/it/docs/images/infrastructure/kubernetes-and-private-cloud-01-cks.webp) 3. Apri **Services › Kubernetes › Versions** e fai clic su **Sync from CloudStack**. Attiva l'interruttore **Available for new clusters** per le versioni che vendi, imposta la versione predefinita e, facoltativamente, una data di **End of life (EOL)**. 4. Apri **Services › Kubernetes › Policy**. In **Worker plans** aggiungi piani con un **Plan code** (da A a Z, da 0 a 9, trattino, fino a 16 caratteri). Imposta **NVMe per worker (GB)**, **Min and max workers** e i limiti del cluster (cluster attivi per account, creazioni ogni 24 ore, limite globale, operazioni CKS simultanee). Quindi attiva **Sell Kubernetes (CKS)**. Almeno un piano deve rimanere in vendita. ![Criteri Kubernetes con i piani worker e l'interruttore di vendita](https://nexcmp.com/it/docs/images/infrastructure/kubernetes-and-private-cloud-03-policy.webp) ### Private Cloud {#private-cloud-1} 1. Apri **Services › Private Cloud** (Panoramica). Nella scheda dei criteri, sostituisci **VPC offering** e **Locked offering tier** con i tuoi UUID. Verifica i limiti (VPC per account, tier, VM e regole ACL per VPC, saldo in ore di canone del piano necessario per la creazione, modifiche del piano ogni 24 ore, operazioni simultanee in cui 0 è un arresto di emergenza) e i server DNS. Fai clic su **Save** (viene richiesto un motivo). ![Panoramica di Private Cloud con i campi dell'offerta VPC e dell'offerta bloccata](https://nexcmp.com/it/docs/images/infrastructure/kubernetes-and-private-cloud-04-vpc-policy.webp) 2. Apri **Services › Private Cloud › Plans & pricing**. Per ogni piano fai clic su **Edit** e imposta **VND price per month**, **On sale** e l'UUID del **CloudStack tier offering** la cui velocità di rete corrisponde ai Mbps del piano. La riga mostra costi e profitti a pieno utilizzo, così puoi vedere quali piani sono al di sotto dei tuoi costi. ![Finestra di dialogo di modifica del piano per un piano di banda Private Cloud](https://nexcmp.com/it/docs/images/infrastructure/kubernetes-and-private-cloud-05-vpc-plan.webp) 3. Attiva l'interruttore **Sell Private Cloud**. Per provarlo prima, aggiungi ID di account di test a **Beta accounts**: tali account possono utilizzare il servizio mentre l'interruttore di vendita è disattivato. ## Verifica {#verify} 1. Kubernetes: la scheda dello stato mostra `kubernetesserviceenabled: true`, un controllo dell'endpoint riuscito e una versione abilitata. Crea un cluster di test con un singolo worker come cliente; dovrebbe raggiungere lo stato di esecuzione e `kubectl get nodes` dovrebbe mostrarlo come pronto. Eliminalo in seguito: la rete e l'IP tornano nel pool. 2. Private Cloud: crea un VPC con il piano più piccolo come cliente di test. Il VPC risulta attivo, un tier ottiene la sua subnet, una VM nel tier raggiunge Internet tramite il router VPC e **Change plan** verso un piano più grande diventa effettivo in circa 20 secondi senza interrompere le connessioni. ## Limiti e note {#limits-and-notes} - Kubernetes: i worker vengono fatturati come le VM ai prezzi del piano e contano come VM nei limiti delle VM. Un cluster può avere al massimo 9 worker a causa del limite CKS di 10 nodi. - Kubernetes: il piano di controllo, il router e l'IP pubblico di un cluster sono gratuiti per il cliente; i relativi costi sono a tuo carico. - Private Cloud: tutti i piani sono **unmetered**. I prezzi nel modulo sono in dong vietnamiti al mese; la colonna dei costi utilizza un prezzo di riferimento che non è il tuo, quindi usa i tuoi numeri. - Un VPC bloccato è limitato a 1 Mbps, non viene fatturato e non viene eliminato automaticamente. - Private Cloud utilizza un router per VPC, non una coppia ridondante. Se il suo host si guasta, CloudStack lo ricostruisce in pochi minuti. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | `cp_offering_invalid` / "Questa offering non è 2 vCPU / 2048 MB / limitcpuuse" | L'offencing del control-plane ha dimensioni diverse o nessun limite CPU | Crea l'offencing come al passaggio 3 e selezionalo di nuovo. | | L'interruttore **Enable CKS** è disattivato | Nessun offencing del control-plane selezionato | Selezione prima uno. | | `kubernetesserviceenabled: false` | CKS è disattivato in CloudStack | Abilitalo e riavvia il server di gestione. | | Il controllo dell'endpoint non è riuscito | `endpoint.url` non è raggiungibile dalle VM del cluster | Imposta un URL raggiungibile, riavvia il server di gestione e fai clic su **Recheck**. | | "EOL: impossibile abilitare per la vendita" | La data di fine vita della versione è trascorsa | Registra una versione più recente. | | "Nessuna versione: fai clic su Sync from CloudStack" | Nessuna versione Kubernetes registrata | Registra una versione ed esegui la sincronizzazione. | | "Il backend CKS è OFF: i clienti non possono creare cluster anche se il flag di vendita è abilitato" | Il flag di vendita è attivo ma il backend CKS è disattivato | Abilita CKS nella scheda CloudStack. | | "Almeno 1 piano deve essere in vendita" | Ultimo piano worker rimosso | Mantieni almeno un piano o disattiva la vendita di Kubernetes. | | Cluster bloccato durante la creazione | Capacità insufficiente o ISO mancante | Controlla le schede di capacità e lo stato ISO della versione. | | Un nuovo VPC non riesce nel primo passaggio | L'offencing VPC o l'ID dell'offencing tier non è valido | Sostituisci ogni UUID di offencing con uno del tuo CloudStack. | | "cs_offering_id deve essere un UUID" | Un ID di offencing non è un UUID | Incolla l'id da `cmk list networkofferings`. | | La modifica del piano non è riuscita | Il nuovo offencing tier non esiste o la velocità di rete non è corretta | Controlla l'UUID dell'offencing e la sua velocità di rete. | --- # Piani e prezzi {#plans-and-pricing} > **Dove nell'admin:** Services › Virtual Machines › Plans & pricing (`/vm/catalog`), con le schede Plan, Custom plan, Cycle e Offering CloudStack. I template si trovano nella pagina separata Services › Virtual Machines › Template (`/vm/templates`). ## Descrizione {#what-it-does} Un **piano** è una dimensione che i clienti possono acquistare: vCPU, RAM, disco di root e un prezzo, in una zona, da una sorgente (CloudStack o un cluster Proxmox VE). Il cliente sceglie un piano, un sistema operativo e un **ciclo di fatturazione** (orario, mensile o un termine prepagato più lungo). I piani sono venduti nel portale clienti, tramite l'API e nei siti dei rivenditori. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Source | CloudStack connesso (un piano punta a un service offering di CloudStack) o un cluster Proxmox VE associato alla zona. Vedi [CloudStack](https://nexcmp.com/it/docs/infrastructure/cloudstack/) e [Proxmox VE](https://nexcmp.com/it/docs/infrastructure/proxmox/). | | Zona | Una zona che vende macchine virtuali. Vedi [Zones](https://nexcmp.com/it/docs/infrastructure/zones/). | | Template | Almeno un template abilitato e pronto. Vedi [OS templates](https://nexcmp.com/it/docs/infrastructure/templates/). | | Tasso di cambio | Solo se inserisci i prezzi in VND. Vedi [Currency and exchange rates](https://nexcmp.com/it/docs/catalog/currency-and-exchange-rates/). | | Permessi | Un amministratore; ogni modifica di prezzo richiede un motivo. | ## Prepara l'infrastruttura {#prepare-the-infrastructure} - **CloudStack:** crea i service offering che desideri vendere (pubblici o condivisi con il dominio NexCMP). Un piano punta a un offering. La scheda **Offering CloudStack** elenca gli offering e i disk offering in tempo reale da CloudStack (memorizzati in cache per 60 secondi). Quando la tabella dei piani è vuota, il worker crea automaticamente sei piani dai tuoi offering reali. - **Proxmox VE:** nulla in Proxmox; un piano include CPU, RAM e disco propri. Il disco non deve essere più piccolo del disco del template. ## Collega in NexCMP {#connect-in-nexcmp} ### Come vengono memorizzati i prezzi {#how-prices-are-stored} NexCMP memorizza ogni prezzo in **micro-dollari all'ora** (µ$/ora; 1 µ$ equivale a 1/1,000,000 USD). Puoi digitare il prezzo nell'unità che preferisci e il modulo lo convertirà: | Unità | Note | |---|---| | USD / ora (6 decimali) | Memorizzato così com'è. | | USD / mese | Diviso per l'impostazione delle ore al mese (730). | | VND / mese | Convertito una sola volta al tasso di cambio corrente, quindi memorizzato in µ$/ora. Viene visualizzato solo quando esiste un tasso. | Il modulo mostra il risultato: µ$/ora, USD/ora, il prezzo mensile e ogni ciclo di fatturazione. **Prezzo mensile = prezzo orario × 730**; un ciclo più lungo è **prezzo mensile × mesi × (1 − sconto)**. ### Aggiungi un piano {#add-a-plan} 1. Apri **Services › Virtual Machines › Plans & pricing** e fai clic su **Add plan**. 2. Compila il modulo: | Campo | Valore di esempio | |---|---| | Nome del piano | `VM-2-4` | | Slug | vuoto: generato dal nome | | Zona | la tua zona predefinita | | Origine dell'infrastruttura | vuoto per CloudStack o un cluster Proxmox | | Offerta di servizi CloudStack (attivo) | scegline uno (visibile solo per CloudStack) | | CPU (core), RAM (MB), Disco principale (GB) | `2`, `4096`, `40` | | Disk offering | facoltativo, per una dimensione principale personalizzata | | Inserisci prezzo per / Prezzo | `USD / month`, `12` | | Descrizione breve | `2 vCPU, 4 GB RAM, 40 GB NVMe` | | Order | `10` | | Active | Attivo: i clienti possono acquistare | | Visibilità | Visibile nel catalogo | | Motivo della modifica del prezzo | `initial price` | 3. Fai clic su **OK**. Il piano viene visualizzato nella tabella con il relativo prezzo orario e mensile e una cella per ogni ciclo abilitato. ![Tabella dei piani con prezzi orari, mensili e per ciclo](https://nexcmp.com/it/docs/images/catalog/plans-02-list.webp) ### Cicli di fatturazione {#billing-cycles} Apri la scheda **Cycle** per impostare quali cicli i clienti possono scegliere e i relativi sconti. | Ciclo | Predefinito | Note | |---|---|---| | Orario | sempre attivo | Addebitato ora per ora. | | Mensile | attivo, 0% | | | 1 anno | attivo, 10% | | | 2 anni | attivo, 15% | | | 3 anni | attivo, 20% | | Puoi rinominare un ciclo, modificarne lo sconto (da 0 a 90%) e attivarne o disattivarne lo stato. Le modifiche si applicano alle macchine virtuali acquistate o rinnovate **dopo** il salvataggio; quelle in esecuzione mantengono il prezzo bloccato. ![Scheda Ciclo con sconti per ciclo di fatturazione](https://nexcmp.com/it/docs/images/catalog/plans-03-cycles.webp) ### Imposta un piano base e deriva gli altri {#set-a-base-plan-and-derive-the-others} **Imposta piano base + deriva altri piani** ricalcola l'intera tabella a partire da un unico prezzo. Scegli il piano base e il rispettivo prezzo, quindi mantieni i **rapporti di prezzo attuali** tra i piani oppure calcola in base ai **prezzi dei componenti** (µ$/ora per vCPU, per GB di RAM e per GB di NVMe, con uno sconto bundle opzionale da 0 a 50%). Una tabella di anteprima mostra i prezzi vecchi e nuovi prima di registrare qualsiasi modifica. Clicca su **Apply** e inserisci una motivazione. Quando applichi i nuovi prezzi: le macchine virtuali **orarie** in esecuzione ottengono un prezzo **inferiore** a partire dall'ora di fatturazione successiva, mentre quelle prepagate lo ricevono al rinnovo. Se un prezzo **aumenta**, le macchine virtuali in esecuzione mantengono il prezzo precedente. ### Piani personalizzati {#custom-plans} La scheda **Custom plan** permette ai clienti di scegliere dimensioni personalizzate di vCPU, RAM e NVMe. Imposta il prezzo unitario orario per una vCPU, un GB di RAM e un GB di NVMe (lascia vuoto per derivarlo da uno sconto percentuale), i valori minimi, massimi e di incremento per ciascuno, e i cicli di fatturazione applicabili. Un piano **personalizzato** dovrebbe costare più di un piano fisso delle stesse dimensioni, altrimenti i clienti salterebbero il piano fisso; la pagina segnala le righe in cui il piano personalizzato risulta più economico. Attiva **Enable custom plans for customers** per metterli in vendita; se disattivata, nel portale verrà mostrato "Coming soon". Ciascuna VM personalizzata ottiene una riga di piano nascosta dedicata; tali righe non possono essere modificate o eliminate finché la VM esiste. ### Modifica, nascondi, clona, elimina {#change-hide-clone-delete} | Action | Descrizione | |---|---| | **Edit** | Modifica nome, descrizione, ordine, prezzo, stato attivo e visibilità. | | **On/Off** | **Off**: i clienti non possono effettuare acquisti; le macchine virtuali in esecuzione non subiscono variazioni. | | **Hide / Show** | Un piano nascosto non compare nel catalogo, ma le VM esistenti continuano a utilizzarlo e gli amministratori possono assegnarlo. | | **Clone** | Crea un nuovo piano nella stessa zona con una nuova origine, dimensione o prezzo, nascondendo opzionalmente quello vecchio. Per vendere la stessa configurazione tramite CloudStack e Proxmox, clonala e seleziona l'altra origine. | | **Sposta su/giù** | Modifica l'ordine. | | **Delete** | Rimuove il piano dalla vendita e dalla tabella. Le VM che lo utilizzano già lo mantengono. | ::: warning I piani in uso sono bloccati Una volta che un piano dispone di VM, la sua **zona, offerta, CPU, RAM, disco e origine** vengono bloccati per evitare modifiche silenziose alle macchine in esecuzione. Usa **Clone** per creare la nuova configurazione; il vecchio piano manterrà le proprie VM. ::: ## Verifica {#verify} 1. Il piano compare nella tabella con il prezzo orario e mensile previsto. 2. Nel portale clienti, avvia un ordine: la zona offre il piano e i prezzi dei cicli corrispondono alla scheda **Cycle**. 3. Effettua un ordine di test, verifica l'addebito sul credito rispetto al prezzo mostrato ed elimina la VM. ## Limiti e note {#limits-and-notes} - Un piano appartiene a **una sola** zona e a **una sola** origine. - I prezzi sono memorizzati in µ$/ora; il prezzo in VND mostrato viene calcolato e arrotondato in base al **passo di arrotondamento VND** (vedi la pagina delle valute). Il credito è sempre in USD. - I rivenditori ottengono un prezzo all'ingrosso e al dettaglio derivato dal prezzo di listino; la modifica del prezzo di un piano esistente non copia i prezzi personalizzati del rivenditore su un clone di cui è stata modificata la configurazione. - I limiti di minimo, massimo e incremento dei piani personalizzati vengono verificati rispetto ai limiti nativi di CloudStack; un disco massimo superiore al limite `storage.max.volume.size` di CloudStack causerà il fallimento e il rimborso dei deployment. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | "Plan name obbligatorio" / "Service offering obbligatorio" | Campo mancante | Inserisci il nome; per CloudStack seleziona un'offerta. | | "CPU/RAM/disco devono essere > 0" | Una dimensione è vuota o pari a zero | Inseriscile tutte e tre. | | "Prezzo non valido (µ$/hr deve essere da 1 a 100,000,000)" | Il prezzo è fuori intervallo | Controlla l'unità e l'importo. | | "La modifica del prezzo richiede un motivo" | Motivo vuoto durante la modifica | Digita un motivo (almeno 3 caratteri). | | "L'offerta "X" è 4c/8192 ma il piano specifica 2c/4096 - CloudStack eseguirà il provisioning in base all'offerta. Vuoi salvare?" | I valori del piano differiscono da quelli dell'offerta | Rendili coincidenti o conferma per mantenere la dimensione di CloudStack. | | "Impossibile recuperare le offerte da CloudStack" | La connessione non è attiva o la chiave non dispone dei permessi necessari | Vedi [CloudStack](https://nexcmp.com/it/docs/infrastructure/cloudstack/). | | "Il template non è pronto su CloudStack - il deployment fallirà. Vuoi abilitarlo comunque?" | Hai abilitato un template non ancora pronto | Attendi che il template sia pronto. | | Il piano non può essere modificato ("contiene VM - bloccato") | Le VM utilizzano il piano | Clonalo. | | Il piano non viene mostrato ai clienti | Disattivato, nascosto o la zona non è pronta | Controlla **Active**, **Visibility** e il tag della zona. Vedi [Zones](https://nexcmp.com/it/docs/infrastructure/zones/). | | "Seleziona almeno 1 ciclo di fatturazione" | Nessun ciclo spuntato per i piani personalizzati | Selezionarne almeno uno. | | "Lo sconto bundle deve essere compreso tra 0 e 50%" | Fuori intervallo | Usa un valore da 0 a 50. | | Opzione di prezzo in VND mancante | Nessun tasso di cambio disponibile | Aggiorna prima il tasso. | --- # Quote di banda e add-on {#bandwidth-quotas-and-add-ons} > **Dove trovarlo nell'amministrazione:** Services › Bandwidth: Summary (`/bandwidth`), Add-on (`/bandwidth/addons`) e Quotas, pricing & policy (`/bandwidth/policy`). L'interruttore del modulo si trova in System › Admin › License & updates. ## Descrizione {#what-it-does} La banda assegna a ogni servizio misurato una **quota** di traffico mensile. NexCMP misura l'utilizzo, avvisa il cliente all'80% e al 100% e, in caso di superamento della quota, agisce secondo la tua **policy di superamento**. I clienti possono acquistare **add-on** con terabyte extra dal proprio credito; puoi anche assegnare add-on gratuitamente. | Service | Quota | |---|---| | Virtual Machines | Per VM al mese (predefinito 2048 GB, ovvero 2 TB) | | Kubernetes | La quota della VM moltiplicata per il numero di worker | | Object Storage | Traffico di download per cliente al mese (predefinito 100 GB); oltre tale soglia si applica il normale prezzo a consumo | | VPN | Mantiene la quota del proprio piano; aggiorna la banda nella pagina VPN | | Private Cloud | **Illimitata** | ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Modulo | **Bandwidth** è attivo per impostazione predefinita. Disattivalo in License & updates per nasconderlo. | | Fonte di misurazione | Con la sorgente predefinita, **CloudStack VM statistics**. Mantieni abilitata la raccolta delle statistiche delle VM in CloudStack; la conservazione predefinita di 720 minuti è sufficiente. | | Proxmox VE | Le VM su Proxmox VE **non vengono misurate**. | | Tasso di cambio | Il prezzo del componente aggiuntivo viene inserito in VND. Vedi [Currency and exchange rates](https://nexcmp.com/it/docs/catalog/currency-and-exchange-rates/). | | Dipende da | [CloudStack](https://nexcmp.com/it/docs/infrastructure/cloudstack/) per il traffico di VM e Kubernetes, [S3](https://nexcmp.com/it/docs/infrastructure/s3/) per i download di storage. | ## Prepara l'infrastruttura {#prepare-the-infrastructure} Non richiesto oltre alla connessione di CloudStack. NexCMP legge `listVirtualMachinesUsageHistory` per tutte le VM dell'account in un'unica chiamata, ogni 5 minuti, in finestre di al massimo due ore. Ogni campione copre un minuto e viene **sommato**. I campioni vengono presi tre minuti nel passato per dare loro il tempo di arrivare. Un intervallo più lungo della conservazione di CloudStack (circa 12 ore) viene saltato e registrato. ::: info Cosa significano i numeri L'utilizzo viene conteggiato sull'interfaccia di rete di ciascuna VM, quindi include il traffico tra le VM, non solo il traffico verso Internet. Può essere leggermente superiore a quanto conteggiato da un router di bordo. ::: ## Collega in NexCMP {#connect-in-nexcmp} 1. Apri **Services › Bandwidth › Quotas, pricing & policy**. 2. Imposta i valori e fai clic su **Save**; viene richiesto e registrato un motivo. Il worker applica la modifica entro circa 30 secondi. | Campo | Predefinito | Significato | |---|---|---| | Abilita banda (menu cliente e acquisto componenti aggiuntivi) | on | L'interruttore per la parte di vendita del modulo. | | VM, GB/mese (Kubernetes = questo valore × worker) | 2048 | Quota per VM per periodo. | | S3, GB download/mese per cliente | 100 | Oltre tale limite si applica la normale tariffa a consumo S3. | | Direzione della quota (VM, Kubernetes) | In + out | O **Outbound only**. | | +1 TB price (VND) | 100,000 | Convertito in centesimi al tasso di cambio. | | Massimo per acquisto (TB) | 50 | | | Overage policy | suspend | **notify**, **throttle** o **suspend** (sotto). | | Imponi sospensione effettiva da | data di migrazione + 24 ore | Prima di questa data nulla viene sospeso; i clienti vengono solo avvisati. | | Limite di velocità della limitazione (Mbps) | | Utilizzato solo da throttle. | ![Criterio di banda: quote predefinite, prezzo componente aggiuntivo e criterio per superamento soglia](https://nexcmp.com/it/docs/images/catalog/bandwidth-01-policy.webp) ### Criteri di superamento {#overage-policies} | Policy | Cosa succede quando un servizio supera il 100% | |---|---| | **notify** | Il cliente viene avvisato. Nient'altro. | | **throttle** | Come notify per ora: il limitatore di velocità non è collegato in questa versione. | | **suspend** (predefinito) | La VM, il cluster o l'account S3 viene sospeso finché il cliente non acquista un componente aggiuntivo o inizia il periodo successivo. Efficace solo a partire dalla data **suspend-from**. | Gli avvisi all'80% e al 100% (campanella ed e-mail) vengono eseguiti sempre, una volta per soglia, periodo e servizio. Se sblocchi un servizio sospeso per banda mentre è ancora oltre la quota, il controllo successivo (entro 5 minuti) lo sospenderà nuovamente. Per farlo continuare a funzionare, **concedi un componente aggiuntivo**. ### Monitorizza l'utilizzo e assegna componenti aggiuntivi {#watch-usage-and-grant-add-ons} Apri **Services › Bandwidth › Summary**. Vengono elencati tutti i servizi con il relativo utilizzo nel periodo corrente, la quota inclusa di componenti aggiuntivi, la quota rimanente e le soglie dell'80% e del 100%. I riquadri KPI mostrano il numero di servizi, i componenti aggiuntivi venduti negli ultimi 30 giorni e lo stato del collector (in esecuzione, cursore). La tabella **Daily** mostra il periodo corrente giorno per giorno. ![Riepilogo della banda con lo stato del collector e l'utilizzo per servizio](https://nexcmp.com/it/docs/images/catalog/bandwidth-02-summary.webp) Per concedere maggiore margine a un cliente, usa **Grant** su un servizio (un componente aggiuntivo di interi terabyte a costo zero). Apri **Add-on** per visualizzare la cronologia degli acquisti e delle assegnazioni, dalla più recente, con un filtro per tipo. ![Cronologia dei componenti aggiuntivi con acquisti e assegnazioni gratuite](https://nexcmp.com/it/docs/images/catalog/bandwidth-03-addons.webp) ### Cosa vedono i clienti {#what-customers-see} Il portale clienti riceve un menu **Bandwidth** con l'utilizzo, la quota rimanente e un'azione **buy +1 TB** pagata dal credito (fino al tuo massimo per acquisto). I componenti aggiuntivi sono validi per il periodo corrente. ## Verifica {#verify} 1. Il collector in **Summary** è in esecuzione e il suo cursore avanza ogni pochi minuti. 2. Una VM con traffico mostra l'utilizzo dopo circa 10-15 minuti. 3. Per visualizzare gli avvisi, riduci la quota della VM a pochi GB su un'installazione di **test** e genera un po' di traffico. Non farlo in produzione: la quota si applica a ogni VM. ## Limiti e note {#limits-and-notes} - L'utilizzo viene conteggiato per periodo (un mese). Componenti aggiuntivi e quote si applicano al periodo corrente. - "Enforce actual suspend from" ti protegge dal sospendere i clienti nel momento in cui il modulo viene abilitato per la prima volta. - In questa versione, la policy di limitazione invia solo notifiche. - La modifica della quota si applica a ogni sito, inclusi i siti dei rivenditori. I prezzi retail e wholesale dei componenti aggiuntivi dei rivenditori seguono il loro sconto o ricarico. - La banda per i **Dedicated servers** è un argomento separato; vedi [Dedicated servers](https://nexcmp.com/it/docs/infrastructure/dedicated/). ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | L'utilizzo rimane a zero per una VM in esecuzione | Il worker è fermo, CloudStack è disconnesso o le statistiche delle VM sono disabilitate | Controlla `sudo nexcmp status` e **Test connection** in [CloudStack](https://nexcmp.com/it/docs/infrastructure/cloudstack/); abilita le statistiche delle VM in CloudStack. | | L'utilizzo presenta dei vuoti | La conservazione dei dati di CloudStack è stata superata o il worker è rimasto inattivo per più di circa 12 ore | Non recuperabile; il divario viene registrato. | | L'utilizzo è leggermente superiore al previsto | È incluso il traffico tra le VM e altro traffico di interfaccia | Previsto; spiegalo ai clienti. | | Un servizio sospeso torna a essere sospeso dopo lo sblocco | Risulta ancora oltre la quota | Assegna un componente aggiuntivo o aumenta la quota. | | Nessun elemento viene sospeso nonostante la policy sia impostata su **suspend** | La data di inizio sospensione è nel futuro | Impostala su adesso (la pagina mostra "ACTIVE" quando è attiva). | | "bw_over_policy deve essere notify, throttle o suspend" | Policy non valida inviata tramite le API | Usa uno dei tre valori. | | Le VM di Proxmox non mostrano alcun utilizzo | Non sono monitorate | Previsto. | | I clienti non possono acquistare componenti aggiuntivi | La banda è disattivata o il portafoglio è vuoto | Controlla l'interruttore e il portafoglio. | --- # Valute e tassi di cambio {#currency-and-exchange-rates} > **Dove nel pannello di amministrazione:** Finance › Payment channels › Exchange rates (`/payments/fx`) per i tassi. System › Settings › Brand (`/settings/branding`) per il selettore **Site currency**. ## Descrizione {#what-it-does} NexCMP gestisce wallet e fatture in USD. I prezzi dei piani VM sono memorizzati in microdollari all'ora. Le valute di visualizzazione consentono ai clienti di consultare gli importi in USD nella propria valuta a un tasso pubblicato; non modificano il saldo del wallet. Alcuni servizi accettano prezzi inseriti in VND, inclusi gli add-on di larghezza di banda, S3, Private Cloud e i piani Bare Metal esistenti che mantengono i prezzi in VND. I bonifici bancari tramite Sepay vengono pagati in VND. I tassi sono **pubblicati da un amministratore**. Nulla si aggiorna automaticamente, quindi i tassi salvati rimangono esattamente quelli attuali finché non premi il pulsante di aggiornamento. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Accesso a Internet | Il server del pannello deve raggiungere `open.er-api.com` (per USD/VND) e `api.frankfurter.dev` (per le altre valute) quando premi **Update exchange rates**. | | Permessi | Richiesto un amministratore per le modifiche; ogni modifica richiede l'inserimento di un motivo. | | Dipende da | Nessuno. [Plans](https://nexcmp.com/it/docs/catalog/plans/), [Bandwidth](https://nexcmp.com/it/docs/catalog/bandwidth/), [S3](https://nexcmp.com/it/docs/infrastructure/s3/) e i bonifici bancari in VND utilizzano il tasso. | ## Prepara l'infrastruttura {#prepare-the-infrastructure} Non richiesto. Se il tuo server filtra il traffico in uscita, consenti HTTPS verso i due servizi indicati sopra. ## Collega in NexCMP {#connect-in-nexcmp} ### 1. Scegli la valuta del sito {#_1-choose-the-site-currency} Apri **System › Settings › Brand** e imposta **Site currency**: | Scelta | Cosa vedono i clienti | |---|---| | **Language-based (auto)** (l'impostazione predefinita in una nuova installazione) | Il portale seleziona una valuta di visualizzazione in base alla lingua (tabella seguente). Il cliente può comunque scegliere USD. | | **USD** | Prezzi e saldi esclusivamente in USD. Nessun selettore di valuta e nessun importo convertito. | | **VND** | Impostazione legacy; segue le stesse regole di visualizzazione basate sulla lingua di Auto. | Salva. Le pagine dei clienti si aggiornano entro circa un minuto. Quando il sito segue la lingua del cliente: | Lingua | Valuta di visualizzazione | |---|---| | Inglese | USD | | Vietnamita | VND | | Cinese (semplificato / tradizionale) | CNY / TWD | | Giapponese, coreano | JPY, KRW | | Francese, tedesco, spagnolo, italiano | EUR | | Portoghese, russo | BRL, RUB | | Arabo, hindi | SAR, INR | | Indonesiano, tailandese | IDR, THB | Una valuta il cui tasso non è stato pubblicato non viene proposta: il portale ripiega su USD. ### 2. Pubblica i tassi {#_2-publish-the-rates} 1. Apri **Finance › Payment channels › Exchange rates**. 2. La scheda **Currency by language** elenca le 11 valute di visualizzazione con il rispettivo tasso per USD, la fonte (Frankfurter) e l'ora dell'ultimo aggiornamento. Fai clic su **Update exchange rates**. Il pulsante esegue due operazioni in un solo passaggio: legge la tabella del mercato pubblico per **USD/VND** e legge gli altri 11 tassi. Entrambi vengono verificati prima che uno dei due venga salvato. Se uno dei due fallisce, non viene modificato nulla e rimangono i tassi precedenti. 3. La scheda **Active exchange rate** mostra il tasso USD/VND in vigore, la relativa etichetta di origine (mercato pubblico o fisso), il margine e i valori di riferimento del mercato con i relativi timestamp. 4. La scheda **Config** (salva con una motivazione): | Campo | Significato | Intervallo | |---|---|---| | Margine (pb, 100 = 1 %) | Aggiunto al tasso di riferimento di mercato. Il tasso effettivo è pari al tasso di riferimento più il margine, arrotondato per eccesso. | Da 0 a 1000 | | Tasso fisso (VND per USD, 0 = segue il mercato) | Un tasso impostato manualmente. Sostituisce il dato di mercato. | 0 o 15,000 a 50,000 | | Soglia di salto (pb) | Un nuovo tasso di mercato che differisce da quello attuale per un valore superiore a questo viene **sospeso** finché non lo confermi. | Da 50 a 2000 (predefinito 500) | | Intervallo di arrotondamento VND | Arrotonda i prezzi in VND e gli importi dei bonifici bancari. | 1, 100, 1,000 (default) o 10,000 | 5. Se un nuovo tasso di mercato varia oltre la soglia, compare la scheda **Pending exchange rate** e il tasso **non viene applicato**. Verificalo rispetto al riferimento scelto e fai clic su **Apply this rate**. Un tasso di mercato al di fuori dell'intervallo tra 15,000 e 50,000 VND per USD viene rifiutato perché non ragionevole. Gli aggiornamenti manuali sono limitati a una richiesta ogni cinque minuti, quindi il pulsante può chiederti di attendere. 6. La tabella **Exchange rate history** elenca ogni tasso recuperato o confermato con data e ora, tasso effettivo, riferimento di mercato, fonte, stato di applicazione, autore della modifica e una nota (le variazioni bloccate sono contrassegnate come **held**). ## Modalità di utilizzo di un tasso {#how-a-rate-is-used} | Contesto | Regola | |---|---| | Portafoglio e fatture | Centesimi di USD. Il tasso non modifica mai un saldo. | | Piani VM inseriti in VND | Convertiti **una sola volta** al tasso in vigore al momento del salvataggio, quindi memorizzati in USD. Le successive variazioni del tasso non ricalcolano il prezzo di questi piani VM. | | Bonifico bancario tramite SePay | Il cliente paga `ceil(USD × rate)`, arrotondato per eccesso all'intervallo di arrotondamento. SePay è **bloccato** finché non esiste un tasso USD/VND. | | Piani Bare Metal | Le nuove installazioni utilizzano direttamente USD. I piani VND esistenti mantengono la propria unità di prezzo e richiedono un tasso al momento dell'addebito; vedi [Server dedicati](https://nexcmp.com/it/docs/infrastructure/dedicated/). | | Altri pagamenti internazionali inseriti in VND | Arrotondato al centesimo più vicino. | | Visualizzazione nel portale | USD moltiplicati per il tasso pubblicato della valuta di visualizzazione, formattati per la lingua. | ## Verifica {#verify} 1. **Active exchange rate** mostra un valore USD/VND con un orario di "recupero" recente. 2. La griglia **Currency by language** mostra i tassi non vuoti. 3. Nel portale clienti, passa alla lingua vietnamita (valuta del sito su Auto): i prezzi vengono mostrati in dong; passa al giapponese: yen. Con la valuta del sito su USD, vengono mostrati solo i dollari. 4. In un modulo di piano (Plans & pricing) l'elenco **Enter price by** offre **VND / month**. ## Limiti e note {#limits-and-notes} - Nessun aggiornamento automatico. Premi **Update exchange rates** quando desideri nuovi tassi e imposta un promemoria se i tassi sono importanti per la tua attività. - Per USD/VND viene utilizzato il tasso di mercato pubblico; si tratta di un tasso di riferimento piuttosto che di una quotazione bancaria di acquisto o vendita. Le altre valute di visualizzazione provengono da Frankfurter; una data antecedente a 14 giorni o una tabella incompleta viene rifiutata. - Il margine e il tasso fisso riguardano solo USD/VND. Le 11 valute di visualizzazione non prevedono alcun margine. - Ciascuna lingua del cliente ha una valuta. Il cambio di lingua ripristina la valuta associata a tale lingua, a meno che il cliente non abbia scelto USD per la stessa lingua. - I siti dei rivenditori seguono gli stessi tassi. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | "Nuovo tasso di cambio discosta oltre la soglia - IN SOSPESO, richiede conferma manuale" | Il salto è superiore alla soglia | Verifica e fai clic su **Apply this rate**, oppure modifica la soglia. | | "Il server ha rifiutato il nuovo tasso di cambio" | Il valore di mercato non è compreso tra 15,000 e 50,000 o non è valido | Attendi e riprova, oppure imposta un tasso fisso. | | L'aggiornamento richiede di attendere prima di riprovare | Aggiornamenti troppo frequenti | Attendi e riprova. | | "impossibile recuperare il tasso: …" | Il server del pannello non riesce a raggiungere i servizi di tassi | Consenti il traffico HTTPS in uscita e riprova. | | Tag **Sepay blocked** | Nessun tasso USD/VND è stato ancora pubblicato | Premi **Update exchange rates** o imposta un tasso fisso. | | Manca una valuta nel portale | Il relativo tasso è mancante | Premi **Update exchange rates**. | | I clienti visualizzano i prezzi solo in USD | La valuta del sito è USD o il tasso è mancante | Imposta **Site currency** su Auto e pubblica i tassi. | | "Tabella dei tassi di cambio incompleta; tassi precedenti mantenuti" | Frankfurter ha restituito meno di 11 valute | Riprova più tardi; non è stato modificato nulla. | | L'opzione VND manca nel modulo del piano | Nessun tasso USD/VND | Pubblica prima un tasso. | --- # Canali di pagamento {#payment-channels} > **Dove si trova nell'amministrazione:** Finance › Payment channels (`/payments`). Interruttori e commissioni: Finance › Payment channels › Fees & limits (`/payments/fees`). NexCMP utilizza un **portafoglio USD prepagato**. I clienti aggiungono fondi al portafoglio tramite un canale di pagamento; ogni servizio viene quindi pagato dal portafoglio. Un canale viene mostrato ai clienti solo quando è sia **abilitato** che **configurato**. ## Descrizione {#what-it-does} I canali di pagamento collegano i tuoi conti di pagamento (Stripe, PayPal, Binance, una banca vietnamita) al portafoglio del cliente. Un pagamento confermato diventa esattamente un accredito sul portafoglio — ogni accredito è identificato dall'ID di pagamento del gateway, in modo che un webhook duplicato non possa mai aggiungere fondi due volte. Usa questa pagina per verificare quali canali sono pronti, le loro prestazioni negli ultimi 30 giorni e quali richiedono attenzione. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Indirizzo HTTPS pubblico | I gateway inviano i webhook a `https:///v1/billing/...`, quindi il tuo pannello deve essere raggiungibile da Internet tramite TLS valido (vedi [DNS and Cloudflare](https://nexcmp.com/it/docs/getting-started/dns-and-cloudflare/)). | | Account | Il tuo account personale presso ciascun provider che desideri utilizzare. Le credenziali vengono inserite nell'amministrazione e non vengono mai più mostrate (solo gli ultimi 4 caratteri). | | Ruolo amministratore | Un account amministratore. | | Dipendenze | Nessuno. Il canale bancario VN richiede inoltre un [tasso di cambio](https://nexcmp.com/it/docs/catalog/currency-and-exchange-rates/). | ## I canali {#the-channels} | Canale | Cosa vede il cliente | Configurato in | Articolo | |---|---|---|---| | Carta (Stripe) | Modulo carta, carta salvata | Payment channels › Stripe | [Stripe](https://nexcmp.com/it/docs/billing/stripe/) | | Apple Pay, Google Pay, Link | Pulsanti digitali (Stripe Express Checkout) | Stripe, più registrazione del dominio | [Stripe](https://nexcmp.com/it/docs/billing/stripe/#apple-pay-google-pay-and-link) | | Alipay | Reindirizzamento ad Alipay (addebitato in JPY da Stripe) | Stripe, più Fees & limits | [Stripe](https://nexcmp.com/it/docs/billing/stripe/#alipay) | | PayPal | Pulsanti PayPal, account PayPal salvato | Payment channels › PayPal | [PayPal](https://nexcmp.com/it/docs/billing/paypal/) | | USDT | Indirizzo di deposito e importo esatto | Payment channels › USDT | [USDT](https://nexcmp.com/it/docs/billing/usdt/) | | Bonifico bancario VN | Codice QR e dettagli di bonifico (solo interfaccia in vietnamita) | Payment channels › VN bank transfer | [Bonifico bancario (Vietnam)](https://nexcmp.com/it/docs/billing/bank-transfer-vn/) | ## Prepara l'infrastruttura {#prepare-the-infrastructure} Non richiesto. Tutto è configurato nell'amministrazione; non c'è nulla da installare sul server. ## Collega in NexCMP {#connect-in-nexcmp} 1. Apri **Finance › Payment channels** (`/payments`). La tabella di panoramica elenca ogni canale con il suo stato. 2. Apri la scheda specifica del canale (**Stripe**, **PayPal**, **USDT**, **VN bank transfer**) e segui il relativo articolo. Ogni scheda termina con un pulsante **Save** e, dove disponibile, un pulsante **Test**. 3. Apri **Fees & limits** (`/payments/fees`), individua la voce **Payment gateways & fees (wallet top-up)** delle carte, attiva il canale con il relativo interruttore e fai clic su **Save channels & fees**. ![Panoramica dei canali di pagamento che elenca i gateway con il loro stato di attivazione, configurazione e le statistiche a 30 giorni](https://nexcmp.com/it/docs/images/billing/payment-channels-01-overview.webp) ![Pagina Commissioni e limiti con gli interruttori dei canali e i campi delle commissioni](https://nexcmp.com/it/docs/images/billing/payment-channels-02-fees.webp) ### Interruttori e commissioni (Fees & limits) {#switches-and-fees-fees-limits} | Impostazione | Predefinito | Significato | |---|---|---| | Carta (Stripe) | On | Modulo carta nella schermata di deposito. Nascondono finché Stripe non dispone di una chiave segreta. | | Apple Pay, Google Pay, Link | On | Pulsanti di portafoglio. Vengono visualizzati solo quando il dominio è verificato su Stripe. | | Alipay | Disattivato | Richiede Alipay attivato nella Dashboard di Stripe. | | PayPal | Disattivato | Mostrato solo quando PayPal è configurato. | | USDT (Binance) | Disattivato | L'interruttore è bloccato finché l'indirizzo di deposito non viene verificato con Binance. | | Commissione Stripe % / fissa (centesimi) | 3.6 % e 0 | Utilizzato per mostrare al cliente la commissione e calcolare l'importo accreditato. Impostalo sulla tua tariffa Stripe effettiva. | | Commissione PayPal % / fissa | 4.4 % e 30 cents | Lo stesso, per PayPal. | | Commissione USDT % | 1 % | Lo stesso, per USDT. | | Il cliente paga la commissione di ricarica | Disattivato | **On**: il cliente paga l'importo + la commissione e il portafoglio riceve l'importo completo. **Off**: la commissione viene detratta e il portafoglio riceve l'importo meno la commissione. | Il cliente vede sempre la commissione e il credito finale del portafoglio prima di pagare. Disattivando un canale, il pulsante viene nascosto e il server rifiuta i nuovi pagamenti con `method_disabled` (HTTP 403). ::: tip Limiti di ricarica L'importo minimo e massimo per ricarica si trovano nella stessa pagina — vedi [Minimum top-up](https://nexcmp.com/it/docs/billing/minimum-top-up/). ::: ## Verifica {#verify} 1. Nella tabella di panoramica il canale mostra **Enabled** e **Configured**; la colonna **Last test** viene compilata dopo aver cliccato su **Test** nella scheda del canale. 2. Accedi al portale come cliente di test e apri **Billing › Deposit**. Il pulsante del canale è presente. 3. Effettua un piccolo pagamento (vedi l'articolo del canale per le carte di test o gli account sandbox). Il saldo aumenta, viene visualizzata una notifica di **Top-up received** e il pagamento è elencato in **Finance › Billing › Top-ups** (`/billing/deposits`). ## Limiti e note {#limits-notes} - **Colonne della panoramica:** *30 days* (numero di pagamenti, successi, fallimenti e volume), *Stuck 24h* (pagamenti ancora in sospeso dopo un giorno) e *Unmatched* (USDT o bonifici bancari arrivati ma non associati ad alcun ordine). La riga dei KPI aggiunge il volume a 30 giorni, il numero di canali difettosi (abilitati ma non configurati o con pagamenti bloccati) e il totale non abbinato. - **Eventi webhook** sono elencati in **Payment channels › Gateway events** (`/payments/events`). Stripe ha la sua scheda; PayPal e USDT ne condividono una. Un evento non riuscito può essere rieseguito: il registro del portafoglio è idempotente, quindi la riesecuzione non accredita mai due volte. - I **Resellers** possono avere i propri canali Stripe, PayPal, USDT e bancari. Le loro righe compaiono anche qui e il selettore del sito nell'intestazione li filtra. Vedi [Resellers](https://nexcmp.com/it/docs/customers/resellers/). - **Rimborsi:** i pagamenti Stripe e PayPal possono essere rimborsati dall'elenco dei pagamenti; i pagamenti USDT non possono essere rimborsati alla fonte (il server risponde con `usdt_no_refund`). - **Modalità di manutenzione:** accetta comunque i webhook del gateway, quindi un pagamento effettuato poco prima della manutenzione non va perso. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | Canale mancante nella schermata di deposito del cliente | Disattivato, non configurato o (banca vietnamita) l'interfaccia non è in vietnamita | Controlla **Fees & limits** e la scheda del canale; vedi [Bank transfer (Vietnam)](https://nexcmp.com/it/docs/billing/bank-transfer-vn/). | | Il KPI **Faulty channels** è superiore a 0 | Un canale è abilitato senza credenziali oppure i pagamenti sono in sospeso da più di 24 ore | Apri la riga e clicca su **Configure**; per i pagamenti bloccati apri **Gateway events** ed esegui nuovamente. | | Il cliente ha pagato ma il saldo non è cambiato | Il webhook non è arrivato | Controlla l'URL del webhook nella scheda del canale, quindi riesegui l'evento in **Gateway events**. | | Il server risponde con `method_disabled` | L'interruttore è disattivato | Attivalo in **Fees & limits** e salva. | | L'interruttore USDT è disabilitato (grigio) | Indirizzo di deposito non verificato | Clicca su **Test & verify address** nella scheda USDT. | --- # Stripe > **Dove nell'amministrazione:** Finance › Payment channels › Stripe (`/payments/stripe`). Interruttori e commissioni: Finance › Payment channels › Fees & limits (`/payments/fees`). ## Descrizione {#what-it-does} Stripe accetta pagamenti con carta per le ricariche del credito. Con lo stesso account puoi anche offrire **Apple Pay**, **Google Pay**, **Link** e **Alipay**, e consentire ai clienti di **salvare una carta** per la [ricarica automatica](https://nexcmp.com/it/docs/billing/auto-top-up/). Usalo come canale principale per i clienti internazionali. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Account Stripe | Un account Stripe in grado di accettare pagamenti in **USD**. Alipay viene addebitato in JPY e deve essere attivato da Stripe per il tuo account. | | Chiavi | Una chiave segreta (`sk_live_...` o `sk_test_...`) e una chiave pubblicabile (`pk_live_...` o `pk_test_...`). Il modulo accetta solo chiavi con questi prefissi. | | Rete | Il tuo pannello deve essere raggiungibile via HTTPS da Internet (Stripe chiama il webhook) e deve raggiungere `api.stripe.com` sulla porta 443. | | Dominio (solo crediti) | Il dominio utilizzato dai clienti deve servire `/.well-known/apple-developer-merchantid-domain-association` — NexCMP lo fa per te. | | Dipendenze | Nessuno. | ::: info Account Stripe condivisi NexCMP elabora solo gli eventi webhook per i pagamenti creati autonomamente, quindi puoi utilizzare un account Stripe che serve anche un'altra applicazione. ::: ## Prepara l'infrastruttura {#prepare-the-infrastructure} Sul lato Stripe: 1. Accedi alla [Stripe Dashboard](https://dashboard.stripe.com). Attiva o disattiva **Test mode** per decidere se stai effettuando una prova o l'attivazione in produzione. Le chiavi di una modalità non funzionano mai con l'altra. 2. Apri **Developers › API keys**. Copia la **Publishable key**, quindi rivela e copia la **Secret key**. Mantieni segreta la chiave segreta. 3. (Facoltativo) Apri **Settings › Payment methods** e attiva **Alipay** se desideri offrirlo. 4. Non **devi** creare il webhook manualmente — NexCMP può crearne uno per te (vedi il passaggio 5 di seguito). Se preferisci farlo manualmente, crea un endpoint in **Developers › Webhooks** con l'URL e gli eventi elencati in [Webhook](#webhook). ## Collega in NexCMP {#connect-in-nexcmp} 1. Apri **Finance › Payment channels › Stripe** (`/payments/stripe`). 2. Nella scheda **API keys** scegli **Mode** (`live` o `test`), incolla la **Secret key** e la **Publishable key**. 3. Fai clic su **Save**. Le chiavi vengono scritte in un file di configurazione sul server che solo l'account di servizio NexCMP può leggere. Non vengono mai reinviate al browser; successivamente la pagina mostra solo gli ultimi 4 caratteri. 4. Fai clic su **Check**. Una finestra di dialogo riporta la connessione, la modalità, il saldo disponibile e in sospeso, l'ID account, se gli addebiti sono abilitati, se esiste un webhook e se Alipay è disponibile. Una linea rossa indica che quella parte richiede attenzione. 5. Nella scheda **Webhook** fai clic su **Create webhook** e conferma. NexCMP chiede a Stripe di creare l'endpoint con tutti gli eventi richiesti e compila automaticamente **Webhook signing secret** (`whsec_...`). L'URL precompilato nel campo è `https:///v1/billing/stripe/webhook`, ad esempio `https://cloud.example.com/v1/billing/stripe/webhook`. 6. Apri **Fees & limits** (`/payments/fees`), tieni attivo **Card (Stripe)**, imposta **Stripe fee %** e **Stripe fixed fee (cents)** sulla tua tariffa reale e fai clic su **Save channels & fees**. Vedi [Payment channels](https://nexcmp.com/it/docs/billing/payment-channels/#switches-and-fees-fees-limits). ![Pagina di Stripe con modalità, chiave segreta e chiave pubblicabile compilate con valori di esempio](https://nexcmp.com/it/docs/images/billing/stripe-01-keys.webp) ### Webhook {#webhook} Il banner rosso "Missing webhook_secret" rimane visibile finché non viene salvato un segreto di firma. Senza di esso, le ricariche con Stripe **non vengono registrate**, anche se Stripe ha incassato i fondi. | Elemento | Valore | |---|---| | URL | `https:///v1/billing/stripe/webhook` | | Events | `checkout.session.completed`, `payment_intent.succeeded`, `payment_intent.payment_failed`, `charge.refunded`, `charge.dispute.created`, `charge.dispute.closed`, `radar.early_fraud_warning.created`, `refund.updated`, `refund.failed` | | Signature | Stripe `Stripe-Signature` header, HMAC-SHA256, tolleranza di 300 secondi. Le richieste con una firma non valida ricevono HTTP 400. | | Idempotency | Ogni ID evento viene memorizzato una sola volta; una consegna ripetuta non accredita mai due volte. | Se hai eseguito l'aggiornamento da una versione che registrava un numero inferiore di eventi, fai di nuovo clic su **Create webhook**: il vecchio endpoint viene mantenuto, quindi eliminalo manualmente in seguito nella Dashboard di Stripe. Le righe **24h events** e **Latest event** nella scheda Webhook indicano se Stripe sta raggiungendo il pannello. I singoli eventi sono elencati in **Payment channels › Gateway events** (`/payments/events`, scheda Stripe), dove ciascun evento può essere visualizzato (**Payload**) o rigiocato (**Replay**). ### Apple Pay, Google Pay e Link {#apple-pay-google-pay-and-link} 1. Nella scheda **Wallets (Apple Pay · Google Pay · Link) & Alipay**, il campo **Customer app Domain registered with Stripe** è precompilato con il nome host del tuo sito (ad esempio `cloud.example.com`). 2. Fai clic su **Register / verify domain** e conferma. NexCMP registra il dominio nei domini dei metodi di pagamento di Stripe e chiede a Stripe di validarlo. 3. Il risultato mostra lo stato di **Apple Pay**, **Google Pay** e **Link**. Apple Pay viene visualizzato solo quando lo stato è `active`. 4. In **Fees & limits** tieni **Apple Pay · Google Pay · Link** attivo. ![Scheda del portafoglio che mostra il dominio registrato e gli stati di Apple Pay, Google Pay e Link](https://nexcmp.com/it/docs/images/billing/stripe-03-wallets.webp) ::: tip Apple Pay rimane inattivo Apple Pay richiede che il file di associazione del dominio risponda con HTTP 200 sul tuo dominio pubblico. Se metti Cloudflare o un altro proxy davanti, non bloccare `/.well-known/`. ::: ### Alipay {#alipay} Alipay è facoltativo. Attivalo in **Stripe Dashboard › Settings › Payment methods**, fai clic su **Check** e attendi che la finestra di dialogo mostri che Alipay è disponibile, quindi attiva **Alipay (Stripe, JPY display)** in **Fees & limits**. Imposta **Alipay fee %**, **Alipay fixed fee**, il **tasso ¥/USD** (50–500) e lo **spread FX %** (0–20). Aggiorna regolarmente il tasso ¥/USD; la pagina avvisa quando è più vecchio di 7 giorni. ## Verifica {#verify} 1. In modalità di test, accedi al portale come cliente di test, apri **Billing**, fai clic su **Deposit**, scegli **Card** e paga l'importo minimo con la carta di test Stripe `4242 4242 4242 4242` (qualsiasi data futura, qualsiasi CVC). 2. Il saldo aumenta nel giro di pochi secondi e il pagamento compare in **Finance › Billing › Top-ups** con lo stato *Completed*. 3. Apri **Payment channels › Gateway events › Stripe**: dovresti vedere `checkout.session.completed` o `payment_intent.succeeded` con un'ora di elaborazione. 4. Tornando alla pagina di Stripe, **24h events** è superiore a 0. Prima di passare alla produzione, imposta **Mode** su `live`, incolla le chiavi live e fai di nuovo clic su **Create webhook** (i webhook della modalità di test e di produzione sono separati). ## Limiti e note {#limits-notes} - **Importi e valuta.** I portafogli sono in USD. I pagamenti con carta, portafoglio e link vengono addebitati in USD; Alipay viene mostrato al cliente in JPY e convertito al tuo tasso. - **Commissioni.** La commissione effettiva di Stripe non viene letta automaticamente indietro; la percentuale di commissione impostata determina ciò che vede il cliente e ciò che viene accreditato sul portafoglio. Scegli **Customer pays top-up fee** in *Fees & limits* per addebitare la commissione in aggiunta. - **Carte salvate.** Quando il cliente seleziona *Save card for auto top-up*, la carta viene memorizzata su Stripe, non sul tuo server. Vedi [Saved payment methods](https://nexcmp.com/it/docs/billing/saved-payment-methods/). - **Rimborsi.** Il rimborso sulla carta è un processo in due fasi: un amministratore crea una richiesta di rimborso per un pagamento completato (**Finance › Billing › Top-ups**, azione di rimborso sul pagamento) e poi l'approva in **Finance › Payouts › Card refunds** (`/billing/payouts`). I rimborsi Alipay sono asincroni; uno non riuscito (`refund.failed`) restituisce l'importo trattenuto al portafoglio. - **Contestazioni.** Su `charge.dispute.created` NexCMP blocca l'account del cliente, interrompe i suoi servizi prepagati (nulla viene eliminato) e invia un avviso all'amministratore. Se vinci (`charge.dispute.closed`), l'importo viene riaccreditato sul portafoglio. - **Pagamenti in attesa.** Se un webhook non arriva mai, NexCMP verifica autonomamente i pagamenti rimasti in sospeso per più di 10 minuti rispetto a Stripe e li completa. I pagamenti più vecchi di 7 giorni vengono ignorati. - I **Resellers** possono collegare il proprio account Stripe (webhook `https:///v1/billing/stripe/webhook/r/`); vedi [Resellers](https://nexcmp.com/it/docs/customers/resellers/). ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | "La chiave segreta deve iniziare con sk_live_/sk_test_" | Chiave errata incollata | Incolla la chiave segreta da **Developers › API keys**. | | "La chiave segreta non corrisponde alla modalità live/test" | Modo e chiave non corrispondono | Fai in modo che il **Mode** corrisponda al prefisso della chiave. | | "La chiave pubblicabile deve iniziare con pk_" | Chiave errata | Usa la chiave pubblicabile. | | Il controllo indica che la connessione non è riuscita | Chiave errata, chiave revocata oppure il server non riesce a raggiungere `api.stripe.com` | Incolla nuovamente la chiave; esegui un test con `curl -I https://api.stripe.com` dal server. | | Banner rosso "Missing webhook_secret" | Il segreto di firma non è salvato | Fai clic su **Create webhook** oppure incolla il `whsec_...` secret dalla Dashboard di Stripe e fai clic su **Save**. | | Denaro prelevato ma il saldo non è cambiato | Webhook non consegnato o firma non valida | Verifica che l'URL termini con `/v1/billing/stripe/webhook`, che il segreto corrisponda all'endpoint e riproduci l'evento in **Gateway events**. In Stripe, apri l'endpoint e controlla i tentativi di consegna (HTTP 400 indica un segreto di firma errato). | | Il fallimento di "Create webhook" | L'URL non è HTTPS o non è raggiungibile | Usa il tuo dominio `https://` pubblico. | | Stato Apple Pay non attivo | Dominio non convalidato | Fai di nuovo clic su **Register / verify domain** dopo che il file di associazione del dominio risponde con 200. | | Alipay non disponibile nella finestra di dialogo di controllo | Non attivato su Stripe | Attivalo nella Dashboard di Stripe, quindi fai clic su **Check**. | | Il cliente non vede alcun modulo per le carte | **Card (Stripe)** è disattivato o manca la chiave segreta | Attivalo in **Fees & limits** e salva le chiavi. | --- # PayPal > **Where in the admin:** Finance › Payment channels › PayPal (`/payments/paypal`). L'interruttore di attivazione/disattivazione e le commissioni si trovano in Finance › Payment channels › Fees & limits (`/payments/fees`). ## Descrizione {#what-it-does} Consente ai clienti di ricaricare il proprio portafoglio in USD con il saldo PayPal, il conto bancario o la carta associata a PayPal. I clienti possono anche consentire a NexCMP di ricordare il proprio account PayPal per la [automatic top-up](https://nexcmp.com/it/docs/billing/auto-top-up/). Usalo insieme a [Stripe](https://nexcmp.com/it/docs/billing/stripe/) per i clienti che preferiscono PayPal. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Account PayPal | Un account PayPal **Business** in grado di ricevere USD. | | App REST | Un'app REST nel PayPal Developer Dashboard (**Apps & Credentials**) che fornisce un **Client ID** e un **Client secret**. Usa la scheda **Sandbox** per i test, **Live** per la produzione. | | Rete | HTTPS raggiungibile da Internet (PayPal chiama il webhook) e accesso in uscita verso `api-m.paypal.com` (live) o `api-m.sandbox.paypal.com` (sandbox), porta 443. | | Permessi | L'app REST richiede le funzionalità di rimborso e webhook. La finestra di dialogo **Check** mostra se entrambe le autorizzazioni sono presenti. | | Dipendenze | Nessuno. | ## Prepara l'infrastruttura {#prepare-the-infrastructure} 1. Accedi a [developer.paypal.com](https://developer.paypal.com) con il tuo account Business e apri **Apps & Credentials**. 2. Scegli **Sandbox** (test) o **Live**, quindi **Create App**. Denominala ad esempio "NexCMP". 3. Copia il **Client ID** e il **Secret** dell'app. 4. Per i test, usa **Testing Tools › Sandbox Accounts** per trovare o creare un account sandbox *Personal* (acquirente). 5. Non è necessario creare il webhook manualmente; NexCMP lo crea con il pulsante **Create webhook**. ## Collega in NexCMP {#connect-in-nexcmp} 1. Apri **Finance › Payment channels › PayPal** (`/payments/paypal`). 2. In **API keys**, scegli **Mode**: `live` (denaro reale, `api-m.paypal.com`) o `sandbox` (`api-m.sandbox.paypal.com`). 3. Incolla il **Client ID** (almeno 20 caratteri) e il **Client secret**. 4. Clicca su **Check**. Vengono testate le credenziali inserite (il salvataggio non è richiesto) e vengono segnalati la connessione, l'App ID, la modalità, la presenza o meno degli scope per rimborsi e webhook e la durata del token. 5. Clicca su **Save**. 6. Nella scheda **Webhook** conferma che l'URL sia `https:///v1/billing/paypal/webhook` (deve essere `https`), quindi clicca su **Create webhook** e conferma. NexCMP chiede a PayPal di creare o aggiornare il webhook con 11 eventi e memorizza il **Webhook ID** restituito. Il pulsante utilizza le chiavi **salvate**; salva prima se le hai appena modificate. 7. Clicca di nuovo su **Check**: la riga **Webhook** dovrebbe mostrare "exists, 11 events". 8. Apri **Fees & limits**, attiva **PayPal**, imposta **PayPal fee %** (predefinito 4.4) e **PayPal fixed fee (cents)** (predefinito 30) in base alla tua tariffa e clicca su **Save channels & fees**. ![Pagina PayPal con modalità sandbox e credenziali di esempio inserite](https://nexcmp.com/it/docs/images/billing/paypal-01-keys.webp) ### Eventi webhook {#webhook-events} NexCMP registra questi 11 eventi: `CHECKOUT.ORDER.APPROVED`, `PAYMENT.CAPTURE.COMPLETED`, `PAYMENT.CAPTURE.PENDING`, `PAYMENT.CAPTURE.DECLINED`, `PAYMENT.CAPTURE.REFUNDED`, `PAYMENT.CAPTURE.REVERSED`, `CUSTOMER.DISPUTE.CREATED`, `CUSTOMER.DISPUTE.UPDATED`, `CUSTOMER.DISPUTE.RESOLVED`, `RISK.DISPUTE.CREATED`, `CHECKOUT.PAYMENT-APPROVAL.REVERSED`. Ogni webhook viene verificato chiamando l'API di verifica della firma di PayPal, salvato una volta ed elaborato in modo idempotente. NexCMP non si fida mai dell'importo nel corpo del webhook: prima di accreditare una cattura, recupera la cattura da PayPal. ## Verifica {#verify} 1. Mantieni **Mode** su `sandbox`. Nel portale, apri **Billing › Deposit**, scegli **PayPal**, clicca su **Continue on PayPal** (o sul pulsante PayPal) e accedi con l'account acquirente sandbox. 2. Approva il pagamento. Verrai reindirizzato al portale, il saldo aumenterà e il pagamento apparirà sotto **Finance › Billing › Top-ups** come *Completed*. 3. Apri **Payment channels › Gateway events › PayPal & USDT**: l'evento `PAYMENT.CAPTURE.COMPLETED` è elencato. 4. Quando tutto funziona, passa **Mode** a `live`, inserisci le credenziali live, fai clic su **Save**, quindi di nuovo su **Create webhook** (i webhook di sandbox e live sono separati). ## Limiti e note {#limits-notes} - **Come viene completato un pagamento.** L'ordine viene creato in USD; dopo che il cliente lo ha approvato, il **server** effettua la cattura (ID richiesta idempotente) e accredita il portafoglio esattamente una volta. Il webhook e un job di riconciliazione eseguito ogni 10 minuti costituiscono una rete di sicurezza nel caso in cui il cliente chiuda il browser. - **Ordini in sospeso e abbandonati.** Un ordine può rimanere aperto per 12 ore. Un cliente può avere al massimo 5 ordini in sospeso (il server risponde `too_many_pending`, HTTP 429). Un ordine non ancora catturato dopo 24 ore viene contrassegnato come fallito. - **Nessun webhook configurato.** Il pannello risponde HTTP 503 a ogni webhook di PayPal finché non viene salvato un Webhook ID. Le catture effettuate tramite il portale e la riconciliazione ogni 10 minuti accreditano comunque il portafoglio, ma nulla di ciò che PayPal segnala tramite webhook (contestazioni, storni, catture tardive) viene applicato: clicca su **Create webhook**. - **Account PayPal salvato.** Quando il cliente sceglie di salvare PayPal (o completa il primo deposito, attivando la [ricarica automatica](https://nexcmp.com/it/docs/billing/auto-top-up/)), PayPal memorizza il token di pagamento nel proprio vault. NexCMP conserva solo un identificativo e l'indirizzo e-mail PayPal. Vedi [Saved payment methods](https://nexcmp.com/it/docs/billing/saved-payment-methods/). - **Rimborsi e contestazioni** vengono gestiti come Stripe: le richieste di rimborso vengono approvate in **Finance › Payouts › Card refunds**; una contestazione blocca l'account del cliente e sospende i suoi servizi prepagati finché non la risolvi. - **Commissioni.** La commissione di PayPal non viene letta dinamicamente; la percentuale e la commissione fissa configurate determinano ciò che il cliente vede e ciò che viene accreditato. La tariffa reale dipende dal tuo paese (il modulo suggerisce il 4.4% per il Vietnam e il 3.49% per gli Stati Uniti). ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | "Client ID troppo breve" | Incollati meno di 20 caratteri | Copia il Client ID completo. | | "L'URL del webhook deve essere https" | URL digitato con `http://` | Usa il tuo dominio `https://` pubblico. | | Il controllo segnala un errore di connessione | Modalità errata (chiavi live in sandbox o viceversa), secret errato, nessun accesso in uscita | Corrispondi **Mode** al tipo di chiave; testa `curl -I https://api-m.paypal.com` dal server. | | Ambito rimborso / webhook mostra "no" | L'app REST non dispone delle funzionalità | Abilita le funzionalità sull'app nella dashboard per sviluppatori di PayPal. | | Banner "Chiave PayPal impostata, NESSUN webhook" | ID webhook mancante | Fai clic su **Create webhook**. | | "Webhook not found" nel controllo | Il webhook è stato eliminato su PayPal o appartiene a un'altra app | Fai clic di nuovo su **Create webhook**. | | Al cliente viene comunicato che PayPal ha rifiutato il pagamento | PayPal ha rifiutato quella fonte di finanziamento | Chiedi al cliente di scegliere un'altra fonte di pagamento. | | Il cliente visualizza "Too many pending requests" | 5 ordini aperti | Attendi che scadano o completali. | | Pulsante PayPal mancante | PayPal disattivato in **Fees & limits** o non configurato | Attivalo e salva le credenziali. | --- # USDT (Binance) {#usdt-binance} > **Dove nell'admin:** Finance › Payment channels › USDT (`/payments/usdt`). Interruttore ecommissioni: Finance › Payment channels › Fees & limits (`/payments/fees`). Depositi non abbinati: Finance › Payment channels › Gateway events › PayPal & USDT (`/payments/events?tab=gateways`). ## Descrizione {#what-it-does} I clienti inviano USDT al **tuo indirizzo di deposito Binance**; NexCMP legge la cronologia dei depositi tramite una chiave API Binance **di sola lettura** e accredita il wallet quando un deposito corrisponde a una richiesta aperta. Non ci sei commissioni di elaborazione dei pagamenti da parte tua oltre a quelle addebitate da Binance, e nessuna chiave privata viene mai trattenuta da NexCMP. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Account Binance | Un account Binance verificato con i depositi in USDT abilitati sulla rete scelta. | | Chiave API | Una chiave API Binance con solo **Enable Reading**. Le opzioni Enable Withdrawals, Internal Transfer e Spot/Margin Trading devono essere **disattivate**. | | Restrizione IP | Altamente consigliato: limita la chiave all'IP in uscita del server (la finestra di dialogo **Test & verify address** lo mostra). | | Rete | HTTPS in uscita verso `api.binance.com`. Non è necessaria alcuna porta in entrata. | | Reti supportate | `TRX` (Tron, TRC20), `BSC` (BNB Smart Chain, BEP20), `SOL` (Solana), `ETH` (Ethereum, ERC20). La coin è bloccata su USDT. | | Dipendenze | Nessuno. | ::: warning Scegli la rete una sola volta I clienti che inviano sulla rete sbagliata perdono i fondi. Scegli la rete con commissioni basse supportata dagli exchange dei tuoi clienti (TRX e BSC sono le scelte abituali) e non cambiarla spesso. ::: ## Prepara l'infrastruttura {#prepare-the-infrastructure} 1. In Binance apri **Account › API Management** e crea una nuova chiave API (generata dal sistema). Assegna un'etichetta come "NexCMP". 2. Modifica i permessi: lascia selezionato solo **Enable Reading**. Non abilitare prelievi, trasferimenti o trading. 3. In **Restrict access to trusted IPs only** aggiungi l'indirizzo IP pubblico del tuo server NexCMP. Se ancora non lo conosci, crea la chiave senza restrizioni, esegui il primo test in NexCMP (che stampa l'IP in uscita) e poi aggiungi l'IP. 4. Copia la **API key** e la **Secret key** (il segreto viene mostrato una sola volta). 5. Apri **Wallet › Deposit › Crypto**, scegli **USDT** e la **network** che utilizzerai, quindi copia l'**indirizzo di deposito** (ad esempio un indirizzo `T...` su TRX o `0x...` su BSC/ETH). ## Collega in NexCMP {#connect-in-nexcmp} 1. Apri **Finance › Payment channels › USDT** (`/payments/usdt`). 2. In **API key (Binance › API Management)** incolla la **API key** e l'**API secret**. Entrambe devono essere inserite insieme. 3. In **Deposit address** scegli la **Network** e incolla l'**indirizzo di deposito USDT sulla network selezionata**. Il formato viene verificato in base alla network (`T` + 33 caratteri per TRX, `0x` + 40 caratteri esadecimali per BSC ed ETH, base58 per SOL). 4. Clicca **Save**. La modifica dell'indirizzo o della network azzera la verifica e mette in pausa il canale finché non lo verifichi nuovamente; la pagina chiede di confermare. 5. Clicca **Test & verify address**. (Le modifiche non salvate vengono rifiutate — il controllo viene eseguito sulla configurazione salvata.) La finestra di dialogo mostra: - permessi della chiave (lettura, prelievi, trasferimento interno, trading, restrizione IP) — avvisi rossi per permessi pericolosi; - l'IP in uscita del server (da inserire in Binance); - la network (depositi aperti o chiusi, conferme richieste, dust); - l'indirizzo emesso da Binance per quella network e se **corrisponde** al tuo. 6. Quando l'indirizzo corrisponde, NexCMP registra l'ora della verifica. Solo allora puoi aprire **Fees & limits**, attivare **USDT (Binance)**, controllare **USDT fee %** (predefinito 1) e **USDT request expires after (mins)** (5–180, predefinito 30), e cliccare **Save channels & fees**. ## Come viene abbinato un pagamento {#how-a-payment-is-matched} 1. Il cliente inserisce un importo in **Billing › Deposit › USDT** e clicca **Get deposit address**. 2. NexCMP crea una richiesta e mostra l'indirizzo, la network e un **importo esatto** con sei decimali, ad esempio `19.173742`. Le ultime quattro cifre sono un nonce casuale che rende l'importo unico per quella richiesta. 3. Il cliente deve inviare **esattamente** quell'importo su quella network. Un pagamento che non corrisponde (importo arrotondato, network errata) non può essere assegnato automaticamente. 4. Ogni 60 secondi NexCMP legge gli ultimi 24 ore di depositi su Binance. Un deposito corrispondente sposta la richiesta nello stato *confirming* e, una volta che Binance ha ottenuto le conferme richieste, accredita il wallet. Una richiesta che ha registrato fondi non scade mai finché le conferme sono in sospeso. 5. Una richiesta non pagata entro il tempo di scadenza (predefinito 30 minuti) viene contrassegnata come scaduta. ## Verifica {#verify} 1. Dopo che l'indirizzo è stato verificato e gli USDT sono stati attivati, accedi come cliente di test e richiedi un piccolo deposito (la ricarica minima). 2. Invia l'importo esatto da un altro wallet o exchange. Attendi qualche minuto. 3. Il portale mostra *Transfer seen — confirming*, quindi *USDT received — balance updated*. 4. La pagina USDT mostra un orario recente in **Last poll** e **Unmatched** a 0. ## Limiti e note {#limits-notes} - **Tasso.** 1 USDT = 1.00 USD. La commissione in **USDT fee %** viene mostrata al cliente e detratta o aggiunta all'importo a seconda di **Customer pays top-up fee**. - **Nessun rimborso.** I pagamenti in USDT non vengono mai rimborsati alla fonte da NexCMP (HTTP 409 `usdt_no_refund`). Esegui il rimborso manualmente fuori dal sistema se necessario. - **Limite in sospeso.** Un cliente ha un numero limitato di richieste aperte; oltre questo limite il server risponde con `too_many_pending` (HTTP 429). - I **Resellers** possono utilizzare il proprio account Binance; vedi [Resellers](https://nexcmp.com/it/docs/customers/resellers/). - **Se condividi l'account Binance** con un altro sistema, assegna a ciascun sistema una rete differente in modo che due poller non vedano mai lo stesso deposito. ### Depositi non abbinati {#unmatched-deposits} Un deposito che non corrisponde a nessuna richiesta (importo errato, rete errata, richiesta scaduta) genera un `deposit.unmatched` evento e un avviso per l'amministratore. Apri **Payment channels › Gateway events › PayPal & USDT**, individua l'evento, verifica la transazione su Binance e fai clic sull'azione di assegnazione per accreditare il cliente corretto. Il contatore **Unmatched** nella pagina USDT e nella panoramica dei canali scende successivamente a 0. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | "La chiave API e il segreto devono essere inseriti insieme" | Un solo campo compilato | Compila entrambi. | | "L'indirizzo non è nel formato della rete ..." | L'indirizzo non corrisponde alla rete selezionata | Ricopialo da Binance per la stessa rete. | | "Modifiche non salvate — Salva prima e poi prova" | Il test viene eseguito sulle impostazioni salvate | Fai clic su **Save**, quindi esegui il test. | | Avviso "la chiave ha Abilita prelievi" | Permesso eccessivo | Rimuovilo in Binance API Management. | | Avviso "chiave non limitata all'IP" | `ipRestrict` è disattivato | Aggiungi l'IP in uscita del server mostrato nella finestra di dialogo. | | Avviso "la chiave non ha Abilita lettura" | Permesso mancante | Abilita Reading. | | Avviso "Binance ha disabilitato i depositi per USDT sulla rete" | Rete sospesa | Scegli un'altra rete o attendi. | | "PERICOLO: l'indirizzo configurato differisce dall'indirizzo emesso da Binance" | Indirizzo o rete errati | Copia nuovamente l'indirizzo da Binance per quella rete. | | Interruttore USDT disattivato in Fees & limits | Indirizzo non verificato | Esegui **Test & verify address** finché non corrisponde. | | Cliente ha pagato, nessun accredito | Importo arrotondato o rete errata | Individua l'evento in Gateway events e assegnalo manualmente. | | Deposito visto ma in attesa da molto tempo | Conferme insufficienti | Attendi; la richiesta non scade durante la conferma. | --- # Bonifico bancario (Vietnam) {#bank-transfer-vietnam} > **Dove trovarlo nell'amministrazione:** Finance › Payment channels › VN bank transfer (`/payments/bank`). Tasso di cambio: Finance › Payment channels › Exchange rates (`/payments/fx`). ## Descrizione {#what-it-does} Permette ai clienti di ricaricare il portafoglio USD tramite un normale bonifico bancario in dong vietnamiti. NexCMP mostra un codice VietQR, i dettagli del conto e una **causale di bonifico** univoca; [SePay](https://sepay.vn) monitora il tuo conto bancario e chiama un webhook quando i fondi arrivano, e NexCMP accredita il portafoglio. Usalo se vendi a clienti in Vietnam. ::: info Mostrato solo nell'interfaccia vietnamita L'opzione per le banche vietnamite viene proposta a un cliente solo quando il portale è visualizzato in **Vietnamese**. I clienti con qualsiasi altra lingua non la vedranno mai. ::: ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Conto bancario | Un conto bancario vietnamita (o un conto virtuale Sepay, **VA**) collegato a un account Sepay su [my.sepay.vn](https://my.sepay.vn). | | Sepay | Un account Sepay con integrazione webhook abilitata. | | Tasso di cambio | Deve esistere un tasso di cambio da USD a VND: aggiornalo prima in **Exchange rates**. Senza un tasso il canale risponde `fx_unavailable` e i clienti non possono avviare un trasferimento. | | Rete | Il tuo pannello deve essere raggiungibile tramite HTTPS affinché Sepay possa chiamare `https:///v1/billing/sepay/webhook`. | | Dipendenze | [Valuta e tassi di cambio](https://nexcmp.com/it/docs/catalog/currency-and-exchange-rates/). | ## Prepara l'infrastruttura {#prepare-the-infrastructure} Dal lato Sepay: 1. In [my.sepay.vn](https://my.sepay.vn) collega il tuo conto bancario (o crea un VA) e assicurati che le transazioni compaiano. 2. Decidi il **prefisso della causale** — da 2 a 5 lettere maiuscole, ad esempio `PAY`. NexCMP genera la causale come il prefisso seguito da 8 cifre casuali (ad esempio `PAY48210937`). Il prefisso non deve contenere `ORD` e non dovrebbe essere utilizzato da nessun altro sistema che riceve denaro sullo stesso conto. 3. Se il tuo account Sepay utilizza una *struttura del codice di pagamento*, registra lo stesso prefisso lì in modo che Sepay riconosca la causale. 4. Crea il webhook in un secondo momento, dopo che la pagina di NexCMP ti avrà fornito l'URL e la chiave (passaggio 7 di seguito). ## Collega in NexCMP {#connect-in-nexcmp} 1. Apri **Finance › Payment channels › Exchange rates** e fai clic su **Update exchange rates** se non è stato memorizzato alcun tasso. 2. Apri **Finance › Payment channels › VN bank transfer** (`/payments/bank`). 3. In **Receiving account** compila: | Campo | Esempio | Regola | |---|---|---| | Banca | `VCB` Vietcombank | Scegli dall'elenco; il BIN viene compilato automaticamente. | | Numero di conto | `0123456789` | 4–24 cifre o lettere maiuscole. | | Conto virtuale (VA — facoltativo) | | Se impostato, i clienti effettuano il bonifico sul VA e il QR lo mostra. | | Nome del titolare del conto | `NGUYEN VAN A` | Senza accenti, MAIUSCOLO, 2–60 caratteri. | | Prefisso causale bonifico | `PAY` | 2–5 lettere maiuscole, senza `ORD`. | 4. In **Webhook authentication** scegli **Auth method**: **HMAC-SHA256** (consigliato) o **API key**, e inserisci la **Webhook key / HMAC secret** (8–200 caratteri). Facoltativamente, inserisci il **userapi token** di Sepay; viene utilizzato solo per riconciliare i bonifici il cui webhook è andato perso. 5. In **Channel & limits** imposta i limiti (valori predefiniti tra parentesi): **Min / order** (10,000 VND), **Max / order** (200,000,000 VND), **Order expiry** (120 minuti, 15–1440), **Max pending orders / account** (3, 1–10), **Reconcile every** (10 minuti) e, opzionalmente, **Allowed webhook IPs** (separati da virgola; se vuoto, l'IP viene solo registrato). 6. Fai clic su **Save**. Il banner rosso "Sepay not configured" scompare non appena l'account, il nome, il prefisso e la chiave sono validi. 7. Copia **Webhook URL to paste into my.sepay.vn** (riporta `https:///v1/billing/sepay/webhook`) con **Copy**. In SePay apri l'integrazione webhook, incolla l'URL, seleziona gli stessi tipo e chiave di autenticazione e abilita l'evento "money in". 8. Fai clic su **Test connection**. Quindi attiva **Enable Sepay for clients (main site)** e **Save**. ![Pagina di bonifico bancario VN con conto di ricezione, prefisso causale e autenticazione webhook compilati con valori di esempio](https://nexcmp.com/it/docs/images/billing/bank-transfer-vn-01-config.webp) ![Scheda canale e limiti con l'interruttore Sepay attivato e i limiti predefiniti](https://nexcmp.com/it/docs/images/billing/bank-transfer-vn-02-limits.webp) ### Sicurezza dei webhook {#webhook-security} | Metodo | Cosa deve inviare Sepay | |---|---| | HMAC-SHA256 | Header `X-SePay-Signature: sha256=`, calcolato su `"."`; la marca temporale può differire di al massimo 300 secondi. | | Chiave API | Header `Authorization: Apikey `. | Vengono controllati solo gli header (mai il corpo o la query string) e il confronto è a tempo costante. Vengono utilizzati solo i trasferimenti in entrata (`transferType = in`) verso il conto o VA configurato. Ogni transazione Sepay viene memorizzata una sola volta, quindi un webhook ritentato non accredita mai due volte. NexCMP risponde `200 {"success":true}` anche quando ignora deliberatamente una transazione, e HTTP 5xx solo per errori temporanei in modo che Sepay riprovi. ## Come paga il cliente {#how-the-customer-pays} 1. In **Billing › Deposit** (interfaccia in vietnamita) il cliente sceglie l'opzione di bonifico bancario VN e un importo, quindi fa clic sul pulsante per creare il bonifico. 2. NexCMP converte l'importo in USD al tasso memorizzato (inclusi il margine e la fase di arrotondamento impostati in **Exchange rates**) e **arrotonda l'importo in VND per eccesso** alla fase di arrotondamento. 3. Il cliente visualizza un codice QR (VietQR, generato localmente) con numero di conto, banca, importo e causale. 4. Dopo il bonifico, Sepay chiama il webhook, NexCMP accredita `floor(VND received × 100 / rate)` centesimi. Il tasso viene bloccato alla creazione dell'ordine; se il denaro arriva dopo la scadenza dell'ordine, viene utilizzato il maggiore tra il tasso bloccato e quello corrente. 5. Gli ordini scadono dopo **Order expiry**; la riconciliazione viene eseguita ogni **Reconcile every** minuti come rete di sicurezza (richiede il token userapi). ## Verifica {#verify} 1. Crea un ordine di test come cliente sull'interfaccia vietnamita. Verifica che l'importo, il conto e la causale siano corretti. 2. Effettua il bonifico dell'importo minimo consentito con la causale esatta. 3. Entro un minuto il portale mostra il deposito come completato e il credito aumenta; la scheda **State** nella pagina della banca mostra l'ora dell'ultimo webhook. 4. Apri **Finance › Billing › Top-ups** e verifica che il pagamento sia elencato con l'importo in VND ricevuto. ## Limiti e note {#limits-notes} - **Minimo.** Il minimo in VND visualizzato da un cliente è il maggiore tra **Min / order** e il valore in VND del [minimum top-up](https://nexcmp.com/it/docs/billing/minimum-top-up/). - **Ordini in sospeso.** Un cliente può avere solo **Max pending orders / account** ordini aperti (predefinito 3). - **Stessa causale due volte.** Effettuare due bonifici con la stessa causale crea un secondo pagamento completato al tasso corrente. - **Nessun rimborso automatico** su un conto bancario. - **Commissione.** Il canale non ha una riga di commissione fissa in **Fees & limits**; il margine sul tasso è l'unico adeguamento. - I **Resellers** possono configurare il proprio conto; l'URL del loro webhook termina con `/v1/billing/sepay/webhook/r/`. ### Trasferimenti non abbinati {#unmatched-transfers} Il denaro arrivato sul conto ma privo di una causale valida compare in **Unmatched transactions** in fondo alla pagina (filtra per *All channel owners* o *Master*). Verifica il riferimento bancario con il cliente, quindi fai clic su **Assign** e seleziona il conto. Il portafoglio viene accreditato al tasso corrente. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | Banner "SePay non configurato" | Banca, conto, nome titolare, prefisso o chiave mancanti o non validi | Completa le schede **Receiving account** e **Webhook authentication**. | | Banner "Tasso USD/VND bloccato" (`fx_unavailable`) | Nessun tasso di cambio memorizzato | **Exchange rates › Update exchange rates**. | | `prefix: 2–5 capital letters, no ORD` | Prefisso non valido | Usa 2–5 lettere maiuscole senza `ORD`. | | Errore `account_name` | Accenti o lettere minuscole | Usa lettere MAIUSCOLE senza accenti, cifre, spazi, punti o trattini. | | `webhook_secret: 8–200 characters` | Chiave troppo corta | Usa almeno 8 caratteri stampabili. | | Il cliente non vede l'opzione | Non presente nell'interfaccia vietnamita, disattivato o nessun tasso | Controlla la lingua, l'interruttore e il tasso. | | Cliente ha pagato ma nessun accredito | Webhook non arrivato, causale modificata, importo errato | Controlla il log dei webhook di Sepay; il bonifico risulterà sotto **Unmatched transactions** se la causale era errata. | | Il webhook restituisce 401 o 403 | Metodo di autenticazione o chiave non corrispondenti | Usa lo stesso metodo e la stessa chiave in Sepay e NexCMP. | | Il cliente visualizza "Too many pending requests" | Limite ordini in sospeso raggiunto | Terminano o attendono la scadenza. | --- # Ricarica minima {#minimum-top-up} > **Dove nell'admin:** Finance › Payment channels › Fees & limits (`/payments/fees`), scheda **Wallet & top-up (Billing › Policy)**. ## Descrizione {#what-it-does} Ogni canale di pagamento rifiuta un importo inferiore alla **minimum top-up** o superiore alla **maximum top-up per transaction**. I valori predefiniti sono **$10.00** e **$5,000.00**. Usa il minimo per evitare piccoli pagamenti che costano più in commissioni di gateway di quanto valgano. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Ruolo | Un amministratore. | | Dipendenze | Nessuno. | ## Imposta i limiti {#set-the-limits} 1. Apri **Finance › Payment channels › Fees & limits** (`/payments/fees`). 2. Nella scheda **Wallet & top-up (Billing › Policy)** modifica **Min top-up (USD)** e **Max top-up per transaction (USD)**. 3. Fai clic su **Save Wallet & top-up**. ![Scheda portafoglio e ricarica con la ricarica minima 10.00 e la massima 5000.00](https://nexcmp.com/it/docs/images/billing/minimum-top-up-01-limits.webp) | Impostazione | Predefinito | Intervallo consentito | Regola | |---|---|---|---| | Min top-up (USD) | $10.00 | $0 a $10,000 | Deve essere inferiore o uguale al massimo. | | Ricarica massima per transazione (USD) | $5,000.00 | $1 a $1,000,000 | Deve essere almeno pari al minimo. | I valori sono memorizzati in centesimi (`min_topup_cents`, `max_topup_cents`). ## Dove si applicano i limiti {#where-the-limits-apply} | Contesto | Comportamento | |---|---| | Carta, Apple/Google Pay, Link, Alipay, PayPal, USDT | Gli importi al di fuori dell'intervallo vengono rifiutati dal server. Il portale mostra "Enter an amount between {min} and {max}". | | Bonifico bancario VN | L'importo in VND deve rientrare nei limiti di Sepay **e** il suo valore in USD (ciò che riceve il portafoglio) deve essere compreso tra il minimo e il massimo. Il portale mostra il maggiore dei due minimi in VND. Vedi [Bank transfer (Vietnam)](https://nexcmp.com/it/docs/billing/bank-transfer-vn/). | | [Ricarica automatica](https://nexcmp.com/it/docs/billing/auto-top-up/) | Ogni addebito automatico è almeno il minimo e al massimo il massimo. In modalità fissa l'importo del cliente deve essere compreso tra il minimo e $1,000. | | Codici di ricarica ([Vouchers](https://nexcmp.com/it/docs/billing/promotions/)) | Non interessato. | | Accredito / addebito amministratore | Non interessato. | | Ricarica portafoglio rivenditore | Un minimo separato (`rs_topup_min_cents`, predefinito $20) sotto Resellers › Defaults. | ## Limiti correlati {#related-floors} La ricarica minima non è l'unica regola di saldo. Queste si trovano in **Services › Virtual Machines › Policy** (`/vm/policy`): | Regola | Predefinito | Significato | |---|---|---| | Saldo minimo (`min_balance_cents`) | $5.00 | Il saldo del portafoglio minimo necessario a un cliente per creare una VM. | | Quote | Disattivato | Quando le **Quotas** sono attive, la creazione di una VM richiede anche un saldo che copra un certo numero di ore di quella VM. Vedi [Quotas](https://nexcmp.com/it/docs/billing/quotas/). | ## Verifica {#verify} 1. Nel portale apri **Billing › Deposit** e digita un importo appena sotto il tuo minimo. Il pulsante di pagamento viene disattivato e compare il messaggio sull'intervallo. 2. Inserisci il minimo e conferma l'avvio del pagamento. ## Limiti e note {#limits-notes} - Una modifica si applica ai nuovi pagamenti. Gli ordini già creati mantengono gli importi con cui sono stati creati. - Il suggerimento per il cliente ("Minimum $10.00, maximum $5,000.00") e i pulsanti con gli importi rapidi seguono automaticamente i nuovi limiti. - Se mostri i VND (la pagina **Exchange rates**), il minimo viene convertito al tasso memorizzato solo a scopo visivo; il portafoglio e i limiti restano in USD. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | Il "L'importo minimo di ricarica deve essere inferiore o uguale al massimo" | Valori invertiti | Abbassa il minimo o alza il massimo. | | Il cliente non può pagare un importo ridotto tramite bonifico bancario VN | Il minimo in VND di Sepay o il minimo in USD è superiore | Abbassa **Min / order** sulla pagina della banca o il minimo in USD. | | Errore del server `invalid_argument` durante una ricarica | Importo al di fuori dell'intervallo | Richiedi un importo compreso nell'intervallo visualizzato. | --- # Metodi di pagamento salvati {#saved-payment-methods} > **Dove nel portale:** Billing › Settings (`/billing?settings=1`). **Dove nell'amministrazione:** Customers › List › a customer › Overview (`/customers/`), scheda **Payment**, mostra il metodo salvato e la cronologia delle ricariche automatiche. ## Descrizione {#what-it-does} Un metodo di pagamento salvato consente a NexCMP di effettuare addebiti a un cliente **senza la sua presenza**, in modo che i suoi servizi non si interrompano mai per l'esaurimento del portafoglio. Viene utilizzato esclusivamente dalla [ricarica automatica](https://nexcmp.com/it/docs/billing/auto-top-up/). Ne esistono due tipi: una **carta** salvata su Stripe (incluse le carte utilizzate tramite Apple Pay, Google Pay o Link quando Stripe restituisce una carta riutilizzabile) e un **account PayPal** memorizzato nel caveau di PayPal. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Canali | [Stripe](https://nexcmp.com/it/docs/billing/stripe/) e/o [PayPal](https://nexcmp.com/it/docs/billing/paypal/) configurati e abilitati. | | Sito | Il sito principale o un sito rivenditore il cui canale di pagamento viene incassato dalla piattaforma. Un sito rivenditore che utilizza il proprio account Stripe non può salvare le carte. | | Cliente | Un account cliente che ha effettuato una ricarica con la carta o PayPal. | ## Come viene salvato un metodo {#how-a-method-gets-saved} 1. Il cliente apre **Billing**, fa clic su **Deposit** e paga con **Card** o **PayPal**. 2. Il pagamento viene creato in modo che il metodo possa essere riutilizzato in seguito: Stripe memorizza la carta associata al cliente su Stripe (utilizzo off-session), PayPal memorizza un token di vault. NexCMP conserva solo i riferimenti (un ID metodo di pagamento Stripe e un ID cliente, oppure l'ID vault PayPal) e un'etichetta descrittiva come `visa •••• 4242` o l'e-mail di PayPal. **I numeri di carta non toccano mai il tuo server.** 3. Al completamento del pagamento, la [ricarica automatica](https://nexcmp.com/it/docs/billing/auto-top-up/) viene attivata una sola volta se il cliente non ha mai scelto le impostazioni in precedenza. Non vi sono caselle di controllo aggiuntive o messaggi sullo schermo. Il server registra l'ora, l'indirizzo IP del cliente e il metodo come prova. 4. La volta successiva, la schermata di deposito offre **Saved card ...** nel menu a discesa delle carte e **Saved PayPal ...** per PayPal. ## Gestione e rimozione {#manage-and-remove} 1. Nel portale vai su **Billing** e fai clic su **Settings**. Il pannello mostra i metodi salvati (carta Stripe e/o PayPal) e le opzioni di ricarica automatica. 2. Per rimuovere una carta, fai clic su **Remove card** e conferma. Stripe scollega la carta e **il ricaricamento automatico viene disattivato**. 3. Per rimuovere PayPal, fai clic su **Remove saved PayPal** e conferma. ### Vista amministratore {#admin-view} Apri il cliente in **Customers › List**. La scheda **Payment** nella scheda **Overview** mostra le etichette dei metodi salvati (**Saved cards**), il gateway utilizzato per gli addebiti automatici, la prova di consenso memorizzata (ora, IP, metodo) e gli ultimi 20 tentativi di addebito automatico con relativo stato e motivo (**Auto top-up history**). ## Verifica {#verify} 1. Come cliente di test, effettua un deposito minimo con carta. Una volta completato il pagamento, apri **Billing › Settings**: la carta e l'interruttore del ricaricamento automatico (attivo) sono visibili. 2. Avvia un altro deposito: il menu a discesa offre la carta salvata. 3. Nell'area amministrativa, la scheda **Payment** del cliente mostra la stessa etichetta della carta. ## Limiti e note {#limits-notes} - **Stripe Link e portafogli.** Link, Apple Pay e Google Pay sono funzionalità di Stripe. NexCMP non memorizza nulla di specifico per Link; conserva solo il riferimento della carta restituito da Stripe. - **PayPal.** Ogni ricarica PayPal avviata dal cliente richiede un clic; il PayPal salvato viene utilizzato solo dal ricaricamento automatico, mai da altre funzionalità. - **Siti rivenditore.** Se un rivenditore utilizza il proprio account Stripe o PayPal, i metodi salvati sono nascosti e il ricaricamento automatico non è disponibile per quel sito. - **Contestazioni.** Una contestazione su qualsiasi pagamento blocca l'account e interrompe i servizi prepagati associati; vedi [Stripe](https://nexcmp.com/it/docs/billing/stripe/). - **La rimozione dell'ultimo metodo** disattiva il ricaricamento automatico; il cliente mantiene il saldo del portafoglio. - **Prova.** Il record di consenso viene scritto dal server (non modificabile dal cliente) e conservato per la gestione delle contestazioni. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | Il cliente non visualizza il pulsante Impostazioni o la carta salvata | Il sito utilizza un canale di pagamento di proprietà del rivenditore oppure non è ancora stato effettuato alcun pagamento con carta | Effettua una ricarica con carta o PayPal tramite il canale della piattaforma. | | "Saved card" mancante dopo un pagamento con Stripe | Il pagamento è stato effettuato con un metodo che non può essere riutilizzato (ad esempio Alipay) | Paga nuovamente con una carta. | | PayPal: "non è ancora possibile salvare questo account" | PayPal non ha restituito un token vault | Continua con un pagamento una tantum o prova un altro account PayPal. | | Il ricaricamento automatico si è fermato dopo la rimozione della carta | Previsto: la rimozione della carta lo disabilita | Salva un nuovo metodo con il prossimo deposito. | --- # Ricaricamento automatico {#auto-top-up} > **Dove nell'amministrazione:** Finance › Payment channels › Fees & limits (`/payments/fees`), scheda **Wallet & top-up (Billing › Policy)**, sezione **Auto top-up (Stripe / PayPal)**. **Dove nel portale:** Billing › Settings (`/billing?settings=1`). ## Descrizione {#what-it-does} Quando il saldo del portafoglio di un cliente scende troppo, NexCMP addebita il suo [metodo di pagamento salvato](https://nexcmp.com/it/docs/billing/saved-payment-methods/) e accredita il portafoglio, in modo che i servizi in esecuzione non vengano sospesi per mancanza di fondi. Un'attività in background controlla tutti i clienti abilitati **ogni 5 minuti**. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Canale | [Stripe](https://nexcmp.com/it/docs/billing/stripe/) e/o [PayPal](https://nexcmp.com/it/docs/billing/paypal/) configurati. | | Metodo salvato | Il cliente dispone di una carta o di un account PayPal salvati. | | Sito | Sito principale o sito rivenditore il cui canale Stripe/PayPal viene riscosso dalla piattaforma. | | Interruttore globale | **Auto top-up enabled** è attivo (predefinito attivo). | ## Come funziona {#how-it-works} Dopo la **prima ricarica Stripe o PayPal** di un cliente, il server salva il metodo di pagamento e attiva la ricarica automatica in modalità **By usage**, a condizione che il cliente non l'abbia mai configurata autonomamente. Non è presente alcuna casella di spunta aggiuntiva nella schermata di deposito; il server registra orario, indirizzo IP e metodo come prova. Se in seguito il cliente disattiva la ricarica automatica, questa non verrà mai riattivata autonomamente. | Modalità | Attivazione (quando il saldo è inferiore a...) | Importo addebitato | |---|---|---| | **By usage** (predefinita dopo la prima ricarica) | il costo delle successive 24 ore di esecuzione dei servizi (VM orarie più rinnovi prepagati in scadenza entro 24 ore), ma mai inferiore a **$5** | il costo calcolato sulle 24 ore arrotondato all'intero dollaro, pari almeno alla [ricarica minima](https://nexcmp.com/it/docs/billing/minimum-top-up/) e al massimo alla ricarica massima e al limite giornaliero | | **Fixed amount** | la soglia personalizzata del cliente (da $1 a $500) | importo scelto dal cliente (dalla ricarica minima a $1,000, superiore alla soglia) | Se non vi sono servizi in esecuzione in modalità **By usage**, non viene addebitato alcun importo. Il saldo confrontato con la soglia è il **denaro effettivo nel portafoglio**. I crediti di servizio derivanti da codici promozionali sono tenuti separati e non vengono conteggiati (vedi [Promotions](https://nexcmp.com/it/docs/billing/promotions/)). La commissione viene gestita come una normale ricarica: con **Customer pays top-up fee** attivo, alla carta viene addebitato l'importo più la commissione e il portafoglio riceve l'importo totale; con l'opzione disattivata, il portafoglio riceve l'importo al netto della commissione. ## Configurazione dei limiti globali {#configure-the-global-limits} 1. Apri **Finance › Payment channels › Fees & limits** (`/payments/fees`). 2. In **Auto top-up (Stripe / PayPal)** imposta: | Impostazione | Predefinito | Intervallo | Significato | |---|---|---|---| | Auto top-up enabled | On | attivo o disattivo | L'impostazione disattivata interrompe immediatamente qualsiasi addebito in background. | | Soglia di ricarica automatica predefinita (USD, fallback in modalità fissa) | $5.00 | $0 a $10,000 | Utilizzata solo come soglia di partenza in modalità fissa. | | Numero massimo di ricariche automatiche ogni 24 h per cliente | 3 | Da 1 a 50 | Conta i tentativi riusciti e in sospeso. | | Limite massimo di importo per le ricariche automatiche ogni 24 h per cliente (USD) | $500.00 | $0 a $1,000,000 | Totale degli addebiti automatici in un giorno mobile. | 3. Fai clic su **Save Wallet & top-up**. ![Sezione della ricarica automatica nella pagina Commissioni e limiti con l'interruttore globale e i limiti giornalieri](https://nexcmp.com/it/docs/images/billing/auto-top-up-01-limits.webp) ## Cosa vede il cliente {#what-the-customer-sees} 1. Nel portale il cliente apre **Billing** e fa clic su **Settings**. 2. Il pannello mostra il metodo o i metodi salvati, l'interruttore di attivazione/disattivazione, la modalità (**By usage** o **Fixed amount**), l'utilizzo corrente stimato, il prossimo addebito e le **Recent automatic top-ups**. 3. Passando a **Fixed amount** è possibile inserire la soglia e l'importo. Disattivando l'interruttore si bloccano gli addebiti. ![Impostazioni di fatturazione del cliente con ricarica automatica in modalità By usage e ultime ricariche automatiche](https://nexcmp.com/it/docs/images/billing/auto-top-up-02-portal.webp) ## Verifica {#verify} 1. Come cliente di prova, effettua una prima ricarica con una carta di test ([Stripe](https://nexcmp.com/it/docs/billing/stripe/#verify)). Apri **Billing › Settings**: la ricarica automatica è attiva. 2. Avvia una piccola VM per generare del traffico e riduci il saldo al di sotto della soglia (ad esempio tramite **Customers › customer › Credit / debit**). 3. Entro circa 5 minuti viene effettuato un addebito. Nella scheda **Overview › Payment** del cliente, **Auto top-up history** mostra il tentativo con stato *Done* e viene inviata una notifica di *Top-up received*. ## Limiti e note {#limits-notes} - **Un addebito per calo.** Dopo un addebito, il processo attende che il saldo torni a salire sopra la soglia o che termini il tempo di attesa: 1 ora dopo un successo, 24 ore dopo un addebito in sospeso, 30 minuti dopo un errore di sistema. - **Limiti giornalieri.** Quando viene raggiunto uno dei limiti giornalieri, non viene effettuato alcun addebito e viene registrata una riga *Daily limit reached* (al massimo una volta ogni 6 ore). - **Errori.** Una carta rifiutata, scaduta o con fondi insufficienti viene conteggiata come errore della carta. Il processo riprova dopo 1 ora, poi 6 ore, poi 24 ore. **Dopo 3 errori di carta consecutivi, la ricarica automatica viene disattivata** e il cliente riceve una notifica (*Auto top-up failed*). Un pagamento che richiede la conferma del cliente (ad esempio 3-D Secure) non viene conteggiato come errore; al cliente viene chiesto di confermarlo. - **Nessun doppio addebito.** Ogni addebito viene richiesto in modo atomico per ogni calo al di sotto della soglia e utilizza una chiave di idempotenza presso il gateway. - **La rimozione della carta** disattiva la ricarica automatica. - **Rivenditori.** Se un rivenditore utilizza il proprio canale di pagamento, il cliente non può abilitare la ricarica automatica (HTTP 403 `feature_disabled`). ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | Il cliente non può attivarla: "Top up once with a card or PayPal" | Nessun metodo salvato | Effettua prima una ricarica con carta o PayPal. | | Errore `no_card` (422) | Il gateway scelto non ha alcun metodo salvato | Scegli un gateway che ne ha uno o salva un metodo. | | Errore `invalid_argument` sull'importo | Modalità fissa al di fuori degli intervalli consentiti | Soglia $1–$500, importo compreso tra la ricarica minima e $1,000, importo superiore alla soglia. | | Non viene effettuato alcun addebito nonostante il saldo sia basso | Interruttore globale disattivato, nessun servizio in esecuzione in modalità A consumo, limite giornaliero raggiunto o addebito precedente ancora in attesa | Controlla l'interruttore, la cronologia e i limiti. | | "N tentativi falliti consecutivi — la ricarica automatica si disattiva dopo 3" | La carta continua a fallire | Il cliente sostituisce la carta con un nuovo deposito. | | Stato *Needs your confirmation* | La banca richiede il 3-D Secure | Il cliente completa una normale ricarica una volta. | --- # Fatture e registro {#invoices-and-ledger} > **Dove trovarlo nell'admin:** Finance › Billing (`/billing`) con le schede Overview, Transactions (`/billing/ledger`), Invoices (`/billing/invoices`), Top-ups (`/billing/deposits`), Payouts (`/billing/payouts`), Vouchers (`/billing/vouchers`) e Reports (`/billing/reports`). **Dove trovarlo nel portale:** Billing (`/billing`). ## Descrizione {#what-it-does} Ogni importo in NexCMP è memorizzato in centesimi di USD e registrato una sola volta. L'idea chiave: il **registro del portafoglio** è la fonte di verità per i saldi; fatture, pagamenti di ricarica e report sono viste create a partire da esso. Il registro è di **sola aggiunta** (append-only): un errore viene corretto aggiungendo una voce di storno, mai modificando la cronologia. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Ruolo | Un amministratore. | | Dettagli del venditore | Imposta ragione sociale, partita IVA, indirizzo, e-mail di contatto e prefisso del numero di fattura in **System › Settings › General**, scheda **Seller & invoicing** (`/settings?tab=seller`), scheda **Seller details (printed on invoices)**. | | Dipendenze | [Payment channels](https://nexcmp.com/it/docs/billing/payment-channels/) per i fondi in entrata. | ## I componenti {#the-pieces} | Scheda admin | Cosa elenca | Uso tipico | |---|---|---| | **Overview** | Ricavi di oggi e del mese, totali del registro per tipo (deposit, charge, refund, adjustment, voucher), fatture per stato, rimborsi in sospeso, collegamenti rapidi, spesa per servizio negli ultimi 30 giorni | Controllo giornaliero | | **Transactions** | Il registro del portafoglio, una riga per movimento | Spiegare il saldo di un cliente | | **Invoices** | Fatture e una seconda vista **Orders** con ogni acquisto di ciascun servizio | Trovare un documento, reinviare, contrassegnare come pagato | | **Top-ups** | Pagamenti ricevuti tramite i gateway | Controllare un pagamento, rimborsarlo | | **Payouts** | Rimborsi su carta, pagamenti di affiliazione, prelievi dei rivenditori | Approvare il denaro in uscita | | **Vouchers** | Codici di ricarica | Vedi [Promotions](https://nexcmp.com/it/docs/billing/promotions/) | | **Reports** | Ricavi, per servizio, per rivenditore | Contabilità | ### Transactions (registro) {#transactions-ledger} Colonne: ora, cliente, **kind**, servizio, importo (con segno), VM, riferimento, attore, nota. Filtri: kind, servizio, ID cliente, sito (quando si dispone di rivenditori), intervallo di date e un collegamento alla VM. | Tipo | Significato | |---|---| | `deposit` | Ricarica da un gateway | | `charge` | Denaro prelevato per un servizio (ordine, rinnovo, utilizzo orario ...) | | `refund` | Denaro restituito al portafoglio | | `adjust` | Credito o debito amministratore, e anche codici di ricarica (riferimento che inizia con `vch:`) — la panoramica mostra i voucher come una riga propria | Ogni riga ha un riferimento come `dep:stripe:`; lo stesso riferimento non può mai essere scritto due volte, motivo per cui un webhook ripetuto non può accreditare due volte. Usa **Customers › List › customer › Credit / debit** per aggiungere una correzione manuale: un motivo è obbligatorio, un importo positivo tenta anche di sbloccare le VM bloccate per mancanza di fondi e l'azione viene confermata in due passaggi. ![Transactions tab che mostra le righe del registro del portafoglio con tipo, servizio, importo e riferimento](https://nexcmp.com/it/docs/images/billing/invoices-and-ledger-01-ledger.webp) ### Invoices {#invoices} Viene creata automaticamente una fattura quando un cliente acquista o rinnova qualcosa pagato dal portafoglio, oppure per una ricarica. I numeri appaiono come `-<000001>` (ad esempio `NX202610-000042`); i siti dei rivenditori utilizzano un proprio prefisso e sequenza. I numeri esistenti non cambiano mai quando modifichi il prefisso. | Campo | Valori | |---|---| | Tipo | Receipt, Renewal, Top-up, Manual, Refund | | Stato | Unpaid, Paid, Overdue, Cancelled, Refunded | Azioni su una riga: | Action | Effetto | |---|---| | **View** / **Print** | Apre la fattura; il portale può anche stamparla o salvarla in PDF. | | **Mark paid** (solo per non pagate o scadute) | La contrassegna come pagata **senza movimentare il denaro del portafoglio** — usala quando il cliente ti ha pagato al di fuori di NexCMP. È richiesto un motivo. Per una fattura di rinnovo estende e sblocca anche la VM bloccata. | | **Cancel** (solo per non pagate o scadute) | Annulla la fattura. È richiesto un motivo. | | **Resend** | Invia nuovamente la fattura via e-mail. | **Create manual invoice** (pulsante in cima alla scheda): ID cliente, da 1 a 50 righe (descrizione, quantità, prezzo unitario), ID VM opzionale, giorni di scadenza opzionali (da 0 a 365, predefinito 7), nota opzionale. Viene creata come non pagata; il cliente la visualizza in **Billing › Invoice History**. Le fatture dei servizi non pagate vengono **regolarizzate automaticamente dal credito** non appena sono disponibili fondi, per cui l'azione del cliente consiste semplicemente nell'effettuare una ricarica. ### Ricariche (pagamenti) {#top-ups-payments} Una riga per tentativo: ora, cliente, **gateway e metodo**, tipo (ricarica o ricarica automatica), stato (in attesa, completato, fallito, rimborsato, contestato, annullato), importo pagato dal cliente, commissione, importo accreditato sul credito, riferimento del gateway e ora di completamento. I pagamenti completati con Stripe e PayPal dispongono di un'azione di **Refund**. Utilizza le pagine degli eventi del gateway per visualizzare i webhook ([Payment channels](https://nexcmp.com/it/docs/billing/payment-channels/)). ### Pagamenti {#payouts} Tre sottoschede: **Card refunds** (approva o rifiuta le richieste di rimborso; la richiesta viene generata da un pagamento completato), **Affiliate payouts** (prelievi di commissioni) e **Reseller withdrawals**. Ogni decisione è registrata nei log di controllo. ### Report {#reports} **Fatturato** (andamento a 30 giorni, mese per mese, clienti principali), **Per servizio** e **Per rivenditore**. ![Scheda dei report che mostra i KPI di fatturato e l'andamento a trenta giorni](https://nexcmp.com/it/docs/images/billing/invoices-and-ledger-03-reports.webp) ## Cosa vede il cliente {#what-the-customer-sees} In **Billing** il cliente dispone di **Balance**, **Deposit**, **Redeem code**, **Settings** (ricarica automatica) e di una cronologia con le schede **Invoice History**, **Payment Order**, **Ledger** e **Orders** (ciascun servizio in un unico elenco con filtri per servizio e tipo). Ciascuna fattura offre le opzioni **View**, **Print** e **Save as PDF**; gli importi sono in USD e opzionalmente visualizzati nella valuta di visualizzazione. ## Verifica {#verify} 1. Effettua una piccola ricarica come cliente di prova. 2. **Transactions** mostra una riga `deposit`, **Top-ups** mostra il pagamento come *Completed* e il fatturato nella schermata **Overview** aumenta. 3. Effettua un acquisto: viene visualizzata una riga `charge` e **Invoices** mostra una fattura di tipo *Receipt* o *Renewal* con i dettagli del venditore configurati. ## Limiti e note {#limits-notes} - **Sola aggiunta.** Non è possibile modificare o eliminare una riga del registro; è necessario aggiungere un rettificativo con una motivazione. - **Valuta.** Gli importi sono in USD; la valuta di visualizzazione è puramente estetica (vedi [Currency and exchange rates](https://nexcmp.com/it/docs/catalog/currency-and-exchange-rates/)). - **Refund to card** si articola in due passaggi (richiesta, quindi approvazione in Payouts); USDT e bonifici bancari non vengono rimborsati alla fonte. - **Tutto viene registrato nei log** in System › Logs › Admin actions con la motivazione inserita. - **Ordini rispetto alle fatture.** L'utilizzo orario non viene fatturato ora per ora; la visualizzazione Orders lo raggruppa per giorno per consentirne comunque la consultazione. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | Il saldo del cliente non sembra corretto | Un addebito, una rettifica o un voucher imprevisti | Filtra **Transactions** per ID cliente e leggi i riferimenti e le note. | | "La fattura è già pagata" (409) | Impostazione dello stato di pagamento su una fattura già pagata | Nessuna azione necessaria. | | Impossibile annullare una fattura | È possibile annullare solo le fatture non pagate o scadute | Per quelle pagate, utilizza un rimborso o una rettifica. | | Dettagli del venditore mancanti sulle fatture | Non compilati | Completa la sezione **Seller details** in System › Settings › General › Seller & invoicing. | | Carta di credito / debito rifiutata | L'importo è pari a zero o superiore a $100,000 | Usa un importo compreso tra 1 centesimo e $100,000. | | Un pagamento rimane nello stato *Pending* a lungo | Webhook mancante | Consulta **Gateway events** ed effettua il replay. | --- # Promozioni {#promotions} > **Dove trovarlo nell'admin:** Finance › Billing › Vouchers (`/billing/vouchers`). **Dove trovarlo nel portale:** Billing › Redeem code (anche all'interno del pannello dei depositi). ## Descrizione {#what-it-does} Un **codice di ricarica** (voucher) è un segreto usa e getta da fornire ai clienti. A seconda di come lo crei, può: | Tipo | Cosa riceve il cliente | Dove va il valore | |---|---|---| | **Bonus credit** per tutti i servizi | Denaro aggiunto al portafoglio | Saldo del portafoglio. Utilizzabile per qualsiasi cosa. | | **Bonus credit** per i servizi scelti | Un credito per i servizi | Un taschino separato che può pagare solo quei servizi. | | **Discount %** | Una percentuale di sconto sul primo ordine dei servizi scelti | Non viene accreditato nulla; lo sconto viene applicato al momento del pagamento. | Usali per campagne, crediti di cortesia, offerte per partner o sconti sul primo ordine. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Ruolo | Un amministratore. | | Clienti | I clienti riscattano i codici dopo aver effettuato l'accesso al portale (non come ospiti). Per impostazione predefinita il cliente deve avere un'e-mail verificata. | | Codici in VND | Un codice creato in VND viene convertito in USD al momento del riscatto utilizzando il tasso di cambio memorizzato (vedi [Currency and exchange rates](https://nexcmp.com/it/docs/catalog/currency-and-exchange-rates/)). | ## Crea un batch {#create-a-batch} 1. Apri **Finance › Billing › Vouchers** e fai clic su **Create vouchers**. 2. Compila il modulo. I valori di esempio sono tra parentesi. | Campo | Note | |---|---| | Nome del batch | 1–80 caratteri (`Spring welcome`). | | Destinazione | **Clienti del sito principale**, **Clienti di un singolo rivenditore** (richiede un elenco di clienti) o **Portafoglio rivenditore**. | | Utenti idonei | **All in target audience** o **Specified** — un'e-mail o un ID cliente per riga, fino a 1,000. Per i clienti di un reseller deve essere *Specified*. | | 1 codice per target | Con *Specified*, crea un codice per ciascun cliente elencato. | | Tipo di codice | **Bonus credit** o **Discount %**. | | Si applica a | Scegli uno o più servizi; vuoto = **All services**. | | Valuta, Valore nominale | USD a partire da $1.00 o VND da 10,000 in multipli di 1,000 (solo credito bonus). | | Sconto (%) | Da 1 a 100 (solo per Sconto %). | | Limite massimo di sconto (USD) | Richiesto per Sconto %, a partire da $1.00. Rappresenta inoltre l'importo massimo di perdita per ciascun riscatto. | | Ordine minimo (USD) | `0` = nessuno. Il primo ordine deve raggiungere almeno questo importo. | | Numero di codici | Da 1 a 1,000 codici casuali. | | Uszi per codice | Da 1 a 100,000. `1` indica una persona per codice; aumentalo per un codice condiviso. | | Uzi max per account | Almeno 1. Per Sconto % deve essere `1`. | | Ora di inizio (opzionale), Scadenza | La scadenza deve essere successiva a oggi e all'inizio, al massimo 2 anni nel futuro. | | Prefisso codice (0–6 caratteri) | Solo lettere; vuoto usa il prefisso del sito. | | Codice personalizzato (solo quando count = 1) | Da 6 a 32 caratteri A–Z e 0–9. Facile da condividere ma da indovinare: mantieni gli usi bassi. | | Richiedi email verificata | Attivo per impostazione predefinita. | | Nota interna, Motivo | Il motivo è obbligatorio e va nel registro di audit. | 3. Il modulo mostra **Maximum exposure** (valore nominale x codici x usi) per conoscere il caso peggiore. Clicca su **Generate codes**. 4. **Copia i codici adesso.** Vengono mostrati una sola volta: NexCMP memorizza solo un hash e gli ultimi 4 caratteri. Usa **Copy all** o **Download CSV**, spunta la conferma e chiudi la finestra. ## Come si comporta ciascun tipo {#how-each-type-behaves} ### Bonus portafoglio (nessun servizio selezionato) {#wallet-bonus-no-service-selected} Il portafoglio viene accreditato con una voce di **adjustment** (riferimento `vch:...`). Non è rimborsabile su carta, non genera commissioni di affiliazione, non crea fattura e conta come saldo del portafoglio per le quote. I codici in VND usano il tasso di cambio al momento del riscatto. ### Credito servizio (servizi selezionati) {#service-credit-services-selected} - Il credito si trova in un **pocket separato**, può pagare solo i costi dei servizi scelti (nuovi ordini, rinnovi, tariffe orarie o giornaliere, upgrade) e viene speso **prima** del portafoglio. - Non può essere prelevato, trasferito o convertito in denaro e scade con il codice. - Il registro mostra l'addebito completo più una riga di credito corrispondente, in modo che il ricavo per servizio rimanga corretto mentre il portafoglio diminuisce solo di quanto realmente pagato dal cliente. - Non **alza** un livello di [quota](https://nexcmp.com/it/docs/billing/quotas/) ed è ignorato dal [auto top-up](https://nexcmp.com/it/docs/billing/auto-top-up/). - Se viene rimborsato un addebito pagato con credito o uno sconto, la parte pagata dal codice viene ripresa dal rimborso del portafoglio e restituita al pocket di credito. ### Sconto % {#discount} 1. Il cliente inserisce il codice: diventa **activated**. Un codice percentuale può essere usato una sola volta per account. 2. Il **primo addebito** di un servizio selezionato che non sia una tariffa oraria e che raggiunga almeno il **Minimum order** viene scontato della percentuale, mai oltre il **Maximum discount cap**. 3. Lo sconto viene ricalcolato dal server al momento dell'addebito; l'importo nel browser viene ignorato. La riga di riscatto viene scritta quando il codice viene effettivamente utilizzato, con lo sconto reale. 4. Gli addebiti per l'utilizzo orario non usano mai il codice. ## Cosa fa il cliente {#what-the-customer-does} 1. Apri **Billing** nel portale e clicca su **Redeem code**, oppure usa **Have a top-up code?** nel pannello di deposito. 2. Digita il codice (non distingue tra maiuscole e minuscole; trattini opzionali) e clicca su **Check**. Il portale indica cosa offre, ad esempio *Valid code: +$5.00*, *$5.00 credit for VPN* o *20% off voucher for Virtual Machines (up to $5.00)*, e *Valid for orders from $10.00*. 3. Clicca su **Redeem** e conferma. Ciascun codice può essere usato una volta per account. I codici sono vincolati al sito: un codice di un sito non è "valido" su un altro, senza alcuna indicazione della sua esistenza altrove. I tentativi errati vengono limitati e, dopo diversi tentativi, l'account viene bloccato per qualche minuto ("N tentativi rimasti prima di un blocco temporaneo"). ## Traccia e interrompi {#track-and-stop} - **Batches** elenca ciascun batch con il suo stato (*active*, *disabled*, *expired*, *used up*), il conteggio dei riscatti e l'esposizione. Apri un batch per le schede **Codes** (mascherate) e **Redemptions**, e **Export CSV**. - **Redemptions** elenca ogni riscatto tra i vari batch; **Reseller quotas** mostra quanta parte del limite di emissione mensile di ciascun rivenditore è stata utilizzata; **Settings** attiva o disattiva i codici dei rivenditori e imposta il limite mensile predefinito. - **Disable batch** interrompe tutti i codici non utilizzati; i riscatti già effettuati rimangono validi. È anche possibile disabilitare un singolo codice. ## Verifica {#verify} 1. Crea un batch di 1 codice: Sconto % 20, limite $5, ordine minimo $10, servizio Virtual Machines. 2. Riscatta il codice come cliente di test. Il portale indica che è attivato. 3. Ordina una VM che costa almeno $10 (ciclo mensile): la fattura mostra lo sconto (al massimo $5). 4. Nel batch, il codice mostra 1 riscatto con lo sconto effettivo. ## Limiti e note {#limits-notes} - I codici sono vincolati all'**audience** e al **site** al momento della creazione; non possono essere spostati in un secondo momento. - I rivenditori possono emettere codici per i propri clienti entro un limite di esposizione mensile; vedi [Resellers](https://nexcmp.com/it/docs/customers/resellers/). - Le diapositive promozionali della barra laterale per i clienti (**Marketing › Promo slides**) sono una funzione separata e non offrono alcun tipo di sconto. - Poiché il codice in chiaro non viene mai memorizzato, un batch smarrito non può essere recuperato: disabilitalo e creane uno nuovo. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | "Codici percentuali: un utilizzo per account" (`percent_one_per_account`) | Utilizzi massimi per account superiori a 1 per Sconto % | Impostalo su `1`. | | Il modulo indica che il limite massimo è obbligatorio | Sconto % senza limite massimo di sconto | Inserisci almeno $1.00. | | Clienti non trovati | Un'e-mail o un ID nell'elenco non esiste | Correggi l'elenco (l'errore indica le voci sconosciute). | | Il cliente riceve il messaggio "codice non valido" | Sito errato, scaduto, disabilitato, esaurito, cliente non destinatario o e-mail non verificata | Verifica il batch e il cliente. | | Il credito non è stato utilizzato | L'addebito appartiene a un altro servizio | Il credito paga solo i servizi scelti nel batch. | | Sconto non applicato | Ordine inferiore al minimo, addebito orario o codice attivato per un altro servizio | Effettua un primo ordine idoneo. | | Cliente bloccato dal riscatto | Troppi tentativi errati | Attendi la scadenza del blocco. | --- # Quote {#quotas} > **Dove nell'admin:** Services › Virtual Machines › Policy › Quota tab (`/vm/policy?tab=quota`). Per cliente: Customers › List › a customer › Overview (`/customers/`), card **Quota**. **Dove nel portale:** Client › Quotas (`/client/quotas`). ## Descrizione {#what-it-does} Le quote proteggono dagli abusi da parte dei nuovi account: maggiore è il denaro reale inserito da un cliente nel portafoglio, maggiori saranno le risorse che potrà creare. Esistono due livelli: - **Risorse per VM e Kubernetes**: vCPU, RAM e disco totali, e numero di VM. I livelli corrispondono ai tuoi piani fissi. - **Quote di servizio**: quanti IP, cluster, VPC, GB di storage e così via, suddivisi in cinque livelli (da L0 a L4) in base ai fondi depositati. Le quote vengono verificate **prima** di qualsiasi addebito. Una richiesta che supera il limite viene rifiutata con un errore HTTP 403 `quota_exceeded` e un messaggio che indica al cliente quanto ricaricare. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Ruolo | Un amministratore. | | Interruttore | **Enable quota** (`quota_enabled`) è **disattivato** per impostazione predefinita. Nulla di quanto segue si applica finché non lo attivi. | | Piani fissi | Almeno un piano non personalizzato (vedi [Plans](https://nexcmp.com/it/docs/catalog/plans/)): i livelli di risorsa sono i tuoi piani fissi. Senza alcun piano si applica solo la regola del numero di VM. | | Dipendenze | Le righe delle quote di servizio esistono solo per i prodotti abilitati nella tua installazione (VPN, proxy IPv6, Kubernetes, Private Cloud, Immagini, Object Storage, Dedicated). | ## Come viene calcolata la base {#how-the-basis-is-calculated} NexCMP non considera solo i pagamenti con carta. La **base** è il **saldo del portafoglio contabilizzato** del cliente: le ricariche tramite gateway, i crediti amministrativi (**Credit / debit**) e i voucher per il portafoglio riscattati concorrono una sola volta, tramite il registro del portafoglio. Gli sconti sugli ordini e i crediti di servizio derivanti da codici promozionali non costituiscono denaro del portafoglio e non vengono conteggiati. La base più alta raggiunta da un cliente viene **conservata** (per sito): la spesa o i rimborsi non abbassano mai un livello già sbloccato. ### Risorse per VM e Kubernetes {#vm-and-kubernetes-resources} 1. I livelli sono i piani fissi del sito, ordinati in base al costo di esecuzione per 24 ore. 2. Un cliente si trova nel livello più alto il cui costo sulle 24 ore non supera la sua base. Il limite è costituito da vCPU, RAM e disco di quel piano. Un cliente che non può permettersi nemmeno il piano più economico riceve comunque le risorse del piano più economico. 3. L'utilizzo conteggiato ai fini del limite comprende ogni VM attiva (incluse quelle bloccate), i volumi di dati acquistati (anche se scollegati) e i nodi worker e di controllo di Kubernetes (i worker contano anche come VM). 4. **Numero di VM:** fino a **Max VMs at 24h tier** (predefinito 2). Dalla VM successiva in poi, il saldo *attuale* del portafoglio del cliente deve coprire **30 giorni (720 ore)** di tutte le VM esistenti più quella nuova, fino a **Max VMs when meeting 30-day threshold** (predefinito 10). 5. **La creazione di una VM** richiede inoltre un saldo di almeno **N ore** di quella VM (**Create VM: balance ≥ N hours**, predefinito 2) e il saldo minimo della piattaforma. 6. La riduzione delle dimensioni di una VM non viene mai bloccata. Viene controllata solo la dimensione in crescita, quindi un cliente che supera il limite del disco può comunque aggiungere vCPU se il limite di vCPU lo consente. ## Configurazione {#configure} 1. Apri **Services › Virtual Machines › Policy** e seleziona la scheda **Quota**. 2. Attiva l'interruttore **Enable quota**. 3. Verifica i tre valori numerici (tutti modificabili): | Campo | Predefinito | Intervallo | |---|---|---| | Crea VM: saldo ≥ N ore | 2 | Da 1 a 720 | | Max VMs at 24h tier | 2 | Da 1 a 100 | | VM massime al raggiungimento della soglia di 30 giorni | 10 | Da 1 a 1000 (non inferiore al campo precedente) | 4. In **Tier-based service quotas** modifica la tabella sottostante. 5. Clicca su **Save**. NexCMP richiederà un **motivo**, che verrà registrato nel log di audit insieme ai valori vecchi e nuovi. La modifica si applica a tutti i clienti. ![Scheda Quota con l'interruttore di abilitazione, i limiti delle VM e la tabella delle quote di servizio basate sui livelli](https://nexcmp.com/it/docs/images/billing/quotas-01-policy.webp) ### Tabella delle quote di servizio {#service-quota-table} La tabella ha cinque livelli. Le celle di intestazione da **L0** a **L4** contengono la **soglia di deposito in centesimi**: i valori predefiniti `0, 1000, 5000, 20000, 100000` significano L0 per un nuovo account, L1 da $10, L2 da $50, L3 da $200 e L4 da $1,000. La prima soglia deve rimanere `0`. Ogni riga definisce la quota di una chiave per livello; **-1 significa illimitato**. | Key | Significato | L0 | L1 | L2 | L3 | L4 | |---|---|---|---|---|---|---| | `vpn.ips` | VPN IPs | 2 | 10 | 30 | 100 | 500 | | `proxy6.ips` | IPv6 proxy IPs | 500 | 2000 | 10000 | 50000 | -1 | | `dedicated.servers` | Bare-metal servers | 1 | 2 | 5 | 20 | 50 | | `s3.storage_gb` | Object Storage GB allocated | 2048 | 4096 | 10240 | 51200 | -1 | | `k8s.clusters` | Kubernetes clusters | 1 | 2 | 5 | 10 | 30 | | `k8s.workers` | Kubernetes worker nodes | 3 | 9 | 18 | 50 | 200 | | `vpc.count` | Private Cloud networks | 1 | 2 | 5 | 10 | 30 | | `images.gb` | Spazio di archiviazione immagini personalizzate in GB | 50 | 100 | 200 | 500 | 2000 | La tabella elenca anche alcune righe per prodotti non inclusi in questa versione; lasciale invariate. Una chiave il cui prodotto è disattivato viene nascosta e non viene mai applicata. Un valore deve essere `-1` o compreso tra `0` e `10,000,000`. Le quote di servizio seguono la **base dei fondi**, come i livelli delle VM: il saldo del portafoglio più alto raggiunto, non il totale dei pagamenti con carta. I clienti rivenditori utilizzano le stesse impostazioni predefinite e il rivenditore può solo visualizzarle. ## Per-customer overrides {#per-customer-overrides} 1. Apri **Customers › List**, quindi il cliente. In **Overview** trova la scheda **Quota**. 2. **Risorse VM:** fai clic su **Quota override** e scegli una delle opzioni - **Per saldo di ricarica (rimuovi override)** — comportamento predefinito; - **Illimitato (incluso il conteggio delle VM)** — rimuove ogni limite per questo cliente; - **un livello del piano** — fissa il limite delle risorse a quel piano; la regola sul conteggio delle VM continua ad aplicarsi. Inserisci un motivo. Gli amministratori della piattaforma possono impostare qualsiasi livello; un override impostato da un rivenditore non può superare la base trattenuta del cliente. 3. **Servizi:** la tabella nella sezione *Service quotas* mostra ciascuna chiave con *In use*, il limite effettivo e la relativa *Source* (livello o override). Fai clic su **Edit** su una riga, digita il valore **New quota** (`-1` = illimitato, vuoto = torna al livello predefinito) e un motivo. ![Scheda della quota cliente con il livello, l'utilizzo delle risorse e la tabella delle quote di servizio con un override](https://nexcmp.com/it/docs/images/billing/quotas-02-customer.webp) Ogni override viene registrato nel registro di audit con l'amministratore, il motivo e i valori precedenti/successivi. ## Cosa vede il cliente {#what-the-customer-sees} **Client › Quotas** (`/client/quotas`) mostra il **livello attuale** del cliente, vCPU, RAM, disco e conteggio VM usati e totali (suddivisi tra VM e Kubernetes), il **saldo del portafoglio idoneo**, la **base di risorse trattenute** (che non diminuisce quando spendono) e quanto ricaricare per il livello successivo. Un cursore consente loro di scegliere un livello di destinazione e passare direttamente alla schermata di deposito. La scheda **Service Quotas** elenca ciascun servizio con la quota, la quantità utilizzata, il relativo livello (da L0 a L4), quanto altro depositare per il livello successivo e un pulsante **Request increase** che apre una bozza di ticket di supporto. Un pulsante **Quota policy** spiega le regole. ![Pagina delle quote del portale con il livello corrente, l'utilizzo delle risorse e le quote di servizio](https://nexcmp.com/it/docs/images/billing/quotas-03-portal.webp) ## Verifica {#verify} 1. Attiva **Enable quota** e usa un nuovo cliente di prova con un saldo di $0. 2. Prova a creare una VM più grande del tuo piano più economico. La richiesta viene rifiutata con `quota_exceeded` e il messaggio "Exceeds the resources of tier ... Top up $X more to unlock tier ...". 3. Ricarica l'importo indicato. Il livello cambia immediatamente e la stessa richiesta va a buon fine. 4. Acquista IP VPN oltre il limite L0: HTTP 403 `quota_exceeded` con `"scope":"service"` e un link a `/client/quotas`. 5. Nella scheda Quota del cliente, **Source** mostra *tier*; imposta un override e vedi che cambia in *override*. ## Limiti e note {#limits-notes} - **Disattivato significa disattivato.** Con `quota_enabled` disattivato, la vecchia regola `new_account_max_vms` (**Services › Virtual Machines › Policy › Sales**) limita i nuovi account a 2 VM finché i loro depositi non raggiungono $10. Quando la quota è attiva, tale regola non si applica più. - setItems("**Le macchine virtuali create dagli admin non sono bloccate.**"), - setItems("**Gli errori bloccano il processo.** Se lo stato della quota non può essere letto, la richiesta viene rifiutata con `quota_unavailable` anziché essere consentita."), - setItems("**Le richieste API, CLI e MCP** usano gli stessi gestori, quindi si applicano gli stessi limiti."), - setItems("**Il credito promozionale** non fa salire di livello (vedi [Promotions](https://nexcmp.com/it/docs/billing/promotions/))."), - setItems("**Le soglie dei livelli sono in centesimi**, non in dollari."), ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | setItems("`quota_exceeded`, motivo `resources`"), | setItems("Il nuovo totale di vCPU/RAM/disco supera il livello"), | setItems("Ricarica l'importo indicato nel messaggio o imposta un override."), | | setItems("`quota_exceeded`, motivo `vm_30d`"), | setItems("Superiore al conteggio VM del livello 24h e il portafoglio non copre ancora 30 giorni della flotta"), | setItems("Ricarica l'importo mostrato."), | | setItems("`quota_exceeded`, motivo `vm_max`"), | setItems("Il limite massimo assoluto di VM è stato raggiunto"), | setItems("Aumenta **Max VMs when meeting 30-day threshold** o usa un override."), | | `quota_exceeded`, `scope: service` | setItems("Un limite per servizio è stato raggiunto"), | setItems("Aumenta il valore nella tabella o sovrascrivi quella chiave per il cliente."), | | `quota_unavailable` | setItems("Lo stato della quota non ha potuto essere verificato"), | setItems("Riprova; controlla il log del server se il problema persiste."), | | setItems("\"quota_max_vms_30d must be >= quota_max_vms_24h\" al salvataggio"), | setItems("Valori invertiti"), | setItems("Rendi il numero a 30 giorni almeno pari a quello a 24 ore."), | | setItems("Il cliente segnala che il livello è sceso"), | setItems("Non scende; confronta la **Held resource basis** con il costo del piano"), | setItems("Controlla il listino prezzi del piano: un aumento del prezzo può spostare le soglie."), | --- # Gestione dei clienti {#managing-customers} > setItems("**Dove nell'admin:** Customers › Customers › List (`/customers`), Deletion requests (`/customers/requests`), Service transfers (`/customers/transfers`) e API keys (`/customers/apikeys`)."), ## Descrizione {#what-it-does} setItems("L'area Clienti consente al personale di supporto di cercare un account, visualizzarne portafoglio, servizi, ticket e cronologia degli accessi, e intervenire: bloccare, sbloccare, verificare l'e-mail, reimpostare la password, aggiungere o rimuovere credito, impersonare, creare una VM o chiudere l'account."), ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Ruolo | setItems("Un amministratore. Ogni azione di scrittura richiede un motivo e viene registrata nel log di audit (System › Logs › Admin actions)."), | | setItems("E-mail"), | setItems("Le e-mail di reset della password e di invito richiedono una [SMTP configuration](https://nexcmp.com/it/docs/administration/smtp-and-emails/) funzionante."), | ## setItems("L'elenco dei clienti"), {#the-customer-list} setItems("Apri **Customers › List**. I clienti sono gli account del tuo sito principale; compaiono anche gli account dei rivenditori, filtrabili per sito."), setItems("![Elenco clienti con filtri e colonne per paese, origine referral, saldo e conteggio VM](https://nexcmp.com/it/docs/images/customers/managing-customers-01-list.webp)"), | setItems("Colonna"), | Significato | |---|---| | setItems("**Email** (e nome)"), | setItems("Clicca per aprire il cliente."), | | setItems("**State**"), | setItems("*Active*, *Locked* o *Deleted*, oltre a e-mail *verified* o *unverified*. Passa il mouse su un tag di blocco per leggerne il motivo."), | | setItems("**Login**"), | setItems("Metodi di accesso del cliente: password, Google, GitHub, passkey."), | | setItems("**Country**"), | setItems("Bandiera e nome derivati dall'**IP address**: il paese dell'IP di registrazione o, se sconosciuto, dell'ultimo accesso. Il tooltip indica quale è stato usato."), | | **Origine referral** | *Referral* con il link al referente e il codice di riferimento quando il cliente si è iscritto tramite un link di affiliazione; altrimenti "Non registrato". | | **Balance**, **VM** | Saldo del portafoglio (valori negativi in rosso) e numero di VM attive. | | **IP registrato / ultimo** | L'IP utilizzato durante la registrazione e all'ultimo accesso, con il paese a due lettere. Usalo per individuare più account da un unico indirizzo. | | **Tenant** | L'ID tenant interno del cliente. | | **Creato**, **Ultimo accesso** | Tempi relativi. | | **Site** | Mostrato quando si dispone di rivenditori. | **Search** accetta e-mail, nome o IP. **Filtri:** stato (tutti, attivi, bloccati, eliminati), metodo di accesso (qualsiasi, Google, GitHub, passkey, nessun password ancora) e sito. I filtri vengono mantenuti nell'URL, consentendo di aggiungere un elenco filtrato ai preferiti o di condividerlo con un collega. **L'ordinamento è globale.** Facendo clic sull'intestazione di *Email*, *State*, *Balance*, *VMs*, *Created* o *Last login* viene ordinata l'**intera** base di clienti sul server e non solo la pagina visualizzata, e il numero di pagina torna a 1. **L'elenco si aggiorna automaticamente.** Si aggiorna ogni pochi secondi mentre lo consulti (va in pausa se una finestra di dialogo è aperta o mentre scrivi), quindi le nuove registrazioni e le variazioni di saldo compaiono senza ricaricare la pagina. La pagina del cliente si aggiorna ogni 30 secondi circa quando è visibile; ogni scheda carica i propri dati alla prima apertura. ### Crea un cliente {#create-a-customer} 1. Fai clic su **Create customer**. 2. Inserisci l'**e-mail**, un **display name** opzionale, una **password** opzionale (vuota = il cliente la imposta tramite il link di invito) e scegli se **send the invitation e-mail**. 3. Conferma. Un account creato manualmente viene considerato verificato quando invii l'invito. ## La pagina di un cliente {#a-customer-s-page} Fai clic su una riga. La pagina presenta otto schede; la scheda selezionata viene mantenuta nell'URL per consentirti di aggiungerla ai preferiti. Le schede si caricano alla prima apertura e mantengono il loro stato quando passi a un'altra. | Scheda | Contenuto | |---|---| | **Overview** | Identità, informazioni di registrazione e ultimo accesso, riepilogo del wallet e dei servizi | | **Services** | Una tabella per i servizi del cliente, con filtri per tipo e stato, ricerca, ordinamento lato server e paginazione | | **Billing** | Wallet e credito, registro contabile, fatture, pagamenti, rimborsi, metodo di pagamento salvato e ricarica automatica | | **Quota** | Limiti di risorse e override; vedi [Quote](https://nexcmp.com/it/docs/billing/quotas/) | | **Security** | Sessioni, autenticazione, metodi di accesso, cronologia accessi e chiavi API; vedi [Chiavi API](https://nexcmp.com/it/docs/developers/api-keys/) | | **Support** | Ticket recenti | | **Affiliate** | Stato del programma di affiliazione | | **Log** | Cronologia delle attività e di audit | Pulsanti di azione nell'intestazione (nascosti per gli account eliminati): | Pulsante | Descrizione | |---|---| | **Lock account** / **Unlock** | Blocca l'accesso e l'uso dell'API. Facoltativamente arresta anche tutte le VM (senza eliminarle). Vengono arrestati anche i servizi prepagati diversi dalle VM (Kubernetes, Private Cloud, VPN e così via). Le VM bloccate da un amministratore devono essere sbloccate separatamente nella pagina della VM. | | **Verify email** | Contrassegna l'e-mail come verificata senza che il cliente debba fare clic su un link. | | **Send reset link** | Invia via e-mail un link per la reimpostazione della password (valido 1 ora, monouso). Se l'SMTP non è configurato, il link viene mostrato una sola volta per poterlo inviare autonomamente. Un amministratore non vede mai la password. | | **Impersonate** | Effettua l'accesso come cliente per un'ora. Vedi [Log in as a customer](https://nexcmp.com/it/docs/customers/login-as/). | | **Credit / debit** | Aggiunge o rimuove fondi dal portafoglio tramite una rettifica contabile. Vedi [Invoices and ledger](https://nexcmp.com/it/docs/billing/invoices-and-ledger/). | | **Revoke sessions** | Disconnette il cliente ovunque; i token dell'app smettono di funzionare. | | **Create VM** | Crea una VM per il cliente. | | **Soft delete** | Chiude l'account. È necessario digitare l'e-mail per confermare. | ### Gestire un singolo servizio {#manage-an-individual-service} Apri la scheda **Services** del cliente, individua un servizio per nome, ID, IP o configurazione e utilizza le azioni di riga. Le stesse azioni sono disponibili nell'elenco di amministrazione del servizio. La finestra di dialogo propone solo le azioni supportate da tale servizio e dal suo stato attuale. | Action | Effetto | |---|---| | **Lock** | Arresta il servizio conservandone i dati. Il cliente lo vede come bloccato e non può gestirlo. L'esecuzione di una ricarica non rimuove il blocco applicato da un amministratore; il rinnovo automatico rimane bloccato per tutta la durata del blocco. | | **Unlock** | Annulla il blocco impostato dall'amministratore. Non rimuove un blocco indipendente per abuso o per altre protezioni. | | **Cancel without refund** | Annulla il servizio senza creare una voce di rimborso nel registro contabile. Il messaggio di conferma avverte che l'annullamento non può essere revocato. | | **Cancel and refund** | Mostra i pagamenti originali, la loro ripartizione tra wallet e credito, i rimborsi precedenti e l'importo massimo rimborsabile. Verifica l'importo prima di confermare. | Inserisci un motivo per ogni azione. Il motivo è riservato agli amministratori; il cliente riceve una notifica o un evento di servizio neutro. Il denaro rimborsato nel wallet torna nel wallet, mentre il credito o le allocazioni promozionali tornano al credito. Questa azione non restituisce denaro tramite Stripe, bonifico bancario o PayPal. Per più servizi dello stesso tipo, seleziona fino a 50 righe e scegli un'azione massiva. Il risultato mostra l'esito positivo o negativo per ciascuna riga. I rimborsi massivi utilizzano l'importo suggerito di ciascun servizio; i servizi per cui il rimborso suggerito è pari a zero vengono ignorati in modalità di rimborso e richiedono una verifica individuale o la cancellazione senza rimborso. DDoS Shield, dischi e backup sono qui righe di sola lettura. Gli add-on di larghezza di banda seguono il rispettivo servizio principale. L'accesso a AI Models può essere bloccato, ma non ha un abbonamento da annullare. Per bloccare un server Bare Metal noleggiato, intervieni sul relativo abbonamento anziché sull'ordine. ### Chiusura di un account (soft delete) {#closing-an-account-soft-delete} L'account viene impostato come *eliminato*, bloccato, le sue sessioni vengono revocate e le commissioni di referral non ancora pagate vengono stornate. Fatture e registro contabile rimangono a fini contabili. L'azione viene rifiutata se il cliente possiede ancora **qualsiasi servizio attivo** (VM, Kubernetes, Private Cloud, Dedicated, VPN, proxy IPv6), un account S3 o un utilizzo S3 non saldato. Eliminali prima. ## Richieste di eliminazione {#deletion-requests} Un cliente può richiedere l'eliminazione dalla pagina del proprio account. Le richieste compaiono in **Customers › Deletion requests** (filtro predefinito: in sospeso) con il cliente, il motivo, il numero di VM attive, il saldo e l'ora della richiesta. - **Approve deletion** è possibile solo quando il cliente non ha alcuna VM attiva. Digita l'e-mail per confermare. L'account viene eliminato tramite soft delete; **il saldo residuo del portafoglio non viene rimborsato automaticamente** — crea prima un rimborso se è dovuto. - **Reject** richiede una motivazione. ## Trasferimenti di servizi {#service-transfers} **Customers › Service transfers** elenca le richieste di spostamento di una **VM o di un abbonamento VPN** da un account a un altro **sullo stesso sito**. - La schermata è di sola lettura e creazione: puoi creare una richiesta per conto di un cliente o annullarla. Deliberatamente **non** è presente alcun pulsante per approvarla da parte del proprietario o del destinatario. - Flusso: il proprietario conferma tramite un link e-mail monouso (valido 30 minuti, con TOTP se abilitato), quindi il destinatario effettua l'accesso e accetta (il destinatario si assume gli obblighi di pagamento). Una richiesta non accettata entro 7 giorni scade. - Regole: il servizio deve essere attivo, senza fatture non pagate e senza processi in esecuzione; il destinatario deve essere un cliente attivo con un'e-mail verificata sullo stesso sito. Il trasferimento di una VM rimuove la chiave SSH e disattiva il rinnovo automatico; il trasferimento di una VPN modifica le password di connessione. - Le fatture già emesse rimangono al precedente proprietario; il nuovo proprietario può leggere la cronologia di fatturazione del servizio con i dati del precedente proprietario nascosti. - I clienti possono creare le proprie richieste in **Transfers** nel portale (5 richieste all'ora e 3 aperte contemporaneamente). ## Verifica {#verify} 1. Crea un cliente con un'e-mail di invito. Il nuovo account viene visualizzato in cima all'elenco nel giro di pochi secondi. 2. Ordina per **Balance**: l'ordine copre tutti i clienti. 3. Blocca il cliente: l'etichetta dello stato diventa *Locked* e il cliente non può più effettuare l'accesso. Sbloccalo. ## Limiti e note {#limits-notes} - La colonna del paese è un'indicazione basata sull'IP, non una prova di residenza. Gli indirizzi privati o sconosciuti non restituiscono alcun paese. - Il blocco di un account non rimborsa nulla e non elimina le VM a meno che tu non decida anche di arrestarle. - Lo sblocco dell'account non sblocca le VM bloccate da un amministratore; sbloccale separatamente nella pagina della VM. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | "Il cliente ha ancora servizi attivi... arresta/elimina prima" | Il cliente ha servizi attivi o un account S3 | Rimuovili, quindi procedi con l'eliminazione soft. | | L'approvazione dell'eliminazione indica "N VMs alive" | Stesso motivo | Elimina prima le VM. | | Viene mostrato il link di reset anziché "e-mail queued" | SMTP non configurato | Configura l'e-mail o invia il link tu stesso. | | Impossibile rimuovere un metodo di accesso (`last_login_method`) | È l'unico modo per il cliente di effettuare l'accesso | Aggiungi prima un altro metodo. | | Il blocco non interrompe i servizi prepagati | Sono stati segnalati errori di arresto | Leggi il messaggio dopo il blocco; il sistema tenta nuovamente l'arresto in modo automatico. | | Impossibile creare un trasferimento | Fattura non pagata, operazione in corso, destinatario su un altro sito o non verificato | Risolvi la condizione e riprova. | --- # Accedi come cliente {#log-in-as-a-customer} > **Dove nell'admin:** Customers › Customers › List › a customer › header button **Impersonate** (`/customers/`). ## Descrizione {#what-it-does} **Impersonate** (accesso come) consente a un amministratore del supporto di visualizzare il portale esattamente come lo vede un cliente, per riprodurre un problema o ricevere assistenza con un ordine. La sessione dura un'ora ed è chiaramente separata da una sessione normale: tutto ciò che potrebbe dare accesso duraturo all'account è bloccato e ogni utilizzo viene registrato. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Ruolo | Un amministratore ha effettuato l'accesso alla console di amministrazione. | | Cliente | L'account deve essere **attivo**. Un account bloccato o eliminato risponde con "account is not active" (HTTP 409). | | Motivo | Un motivo è obbligatorio; viene scritto nel registro di audit. | | Browser | Consenti i popup per l'indirizzo di amministrazione: il portale si apre in una nuova finestra. | ## Passaggi {#steps} 1. Apri **Customers › List** e fai clic sul cliente. 2. Fai clic su **Impersonate**. Una finestra di dialogo spiega che il sito del cliente si apre impersonando il cliente per un'ora e che ogni azione viene registrata. 3. Digita il **motivo** (ad esempio "Ticket 1234 — cannot create VM") e fai clic su **Open app**. 4. Si apre una nuova finestra sul sito del cliente che mostra la dashboard con `?impersonated=1`. Se il browser ha bloccato la finestra, consenti i popup e fai clic di nuovo. ![Finestra di dialogo Impersonate con il campo del motivo compilato](https://nexcmp.com/it/docs/images/customers/login-as-01-dialog.webp) Per il cliente di un rivenditore, la finestra si apre sul **dominio del rivenditore**, poiché il link funziona solo sul sito del cliente. ## Come funziona {#how-it-works} 1. L'azione amministrativa crea un **token monouso** valido per un'ora e scrive `customer.login_as` (amministratore, IP, motivo, sito) nel registro di audit. 2. La nuova finestra si apre `https:///v1/portal/impersonate/`. Una prima richiesta mostra solo una pagina di piccole dimensioni e **non** consuma il token (in modo che il prefetching del browser non possa esaurirlo); la pagina conferma quindi con una richiesta POST. 3. La richiesta POST consuma il token. Un secondo utilizzo, o un utilizzo dopo un'ora, risponde con "The impersonation link has expired or was already used". 4. NexCMP crea una sessione cliente che dura **un'ora** (una sessione normale dura 30 giorni), registra una voce di accesso con il metodo `impersonate` e registra `customer.login_as.used`. 5. Il token funziona solo sul sito del cliente; su un altro host risponde con 404. ## Cosa viene bloccato in una sessione impersonata {#what-is-blocked-in-an-impersonated-session} Qualsiasi operazione che conceda accesso oltre l'ora o modifichi la sicurezza del cliente restituisce HTTP 403 `impersonate_forbidden`: | Bloccato | Motivo | |---|---| | Modifica di password, TOTP, collegamento o scollegamento di Google/GitHub, modifica delle passkey | Credenziali del cliente | | Eliminazione dell'account | Irreversibile | | Creazione o modifica di **API keys** | Accesso a lungo termine | | Approvazione di un accesso CLI, desktop o MCP (collegamento dispositivo) | Accesso a lungo termine | | Creazione di accesso Kubernetes, S3 keys, SSH keys, password di root, link di condivisione console, credenziali VPN o proxy | Segreti che sopravvivono alla sessione | | Riscatto di codici di ricarica | Campagne monetarie | | Prelievo o modifica del pagamento delle commissioni di affiliazione | Denaro in uscita dal sistema | | Modifica di chiavi AI, budget o e-mail di avviso | Configurazione del cliente | Tutto il resto funziona: puoi leggere le pagine, creare o gestire VM, effettuare ordini e così via. Le azioni vengono eseguite con l'identità del cliente e utilizzano il suo credito; le voci di audit sopra indicate mostrano che un amministratore era dietro la sessione. ## Verifica {#verify} 1. Impersona un cliente di test. Il portale si apre e mostra i dati di quel cliente. 2. Prova a cambiare la password: ricevi "forbidden" (impersonazione). 3. In **System › Logs › Admin actions**, trova `customer.login_as` con il tuo nome, il motivo e il sito, seguito da `customer.login_as.used`. 4. Chiudi la finestra, riapri lo stesso link: "link expired or already used". ## Limiti e note {#limits-notes} - Il limite di un'ora è fisso (3600 secondi). Per continuare, impersona di nuovo. - Preferisci la lettura e la riproduzione; evita azioni che spendono denaro a meno che il cliente non te lo abbia chiesto. - Revoca anticipatamente la sessione con **Revoke sessions** nella pagina del cliente (questo disconnette anche il cliente). - I rivenditori hanno la propria impersonazione **Sign in to partner console** (60 minuti) da Resellers; vedi [Resellers](https://nexcmp.com/it/docs/customers/resellers/). ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | "Account non attivo" | Account bloccato o eliminato | Sbloccalo prima o visualizza la pagina del cliente. | | Il browser blocca la finestra | Blocco pop-up | Consenti i pop-up per l'indirizzo dell'amministratore e riprova. | | "Link scaduto o già utilizzato" | Limite di un'ora o riutilizzo | Impersona di nuovo. | | Si apre "Not found" | Il link è stato utilizzato sull'host errato | Usa la finestra aperta dal dialogo; non incollare il link altrove. | | Un'azione dice "forbidden" | Bloccato nelle sessioni impersonate | Chiedi al cliente di farlo o usa le schermate di amministrazione. | --- # Resellers (white-label) {#resellers-white-label} > **Dove trovarlo nell'amministrazione:** Customers › Resellers › List (`/resellers`), Domains & SSL (`/resellers/domains`), Permissions & wholesale (`/resellers/entitlements`), Defaults (`/resellers/settings`). Slot rivenditore: System › Admin › License & updates (`/license`). ## Descrizione {#what-it-does} Un **rivenditore** ottiene una copia brandizzata del portale clienti sul **proprio dominio**, con i propri clienti, portafoglio, prezzi e (facoltativamente) canali di pagamento. Acquista da te a prezzo all'ingrosso e vende al proprio prezzo. I suoi clienti non vedranno mai il tuo brand e il dominio del rivenditore non potrà mai aprire la tua console di amministrazione. Il rivenditore gestisce la propria attività dalla **console partner** all'indirizzo `https://partner.`. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Licenza | Uno **slot per dominio rivenditore** sulla tua licenza per ogni dominio rivenditore personalizzato. La pagina della licenza mostra `used/max` slot e un link per acquistarne altri. Senza uno slot libero, l'aggiunta di un dominio fallisce con l'errore "Out of license reseller domain slots". | | DNS | Ogni dominio rivenditore deve essere puntato al tuo server (vedi sotto). | | Server web e TLS | Il nome host deve raggiungere il pannello NexCMP tramite il tuo reverse proxy con un certificato valido per quel nome. | | setItems("E-mail"), | SMTP configurato per le e-mail di invito e notifica. | | Interruttore principale | **Reseller settings › General › `rs_enabled`** è attivo per impostazione predefinita. | ## Prepara l'infrastruttura {#prepare-the-infrastructure} 1. Decidi l'indirizzo pubblico del server: il suo indirizzo IPv4 e, se preferisci i CNAME, un nome host che punta ad esso (ad esempio `sites.cloud.example.com`). 2. Apri **Customers › Resellers › Defaults** (`/resellers/settings`), gruppo **Domains & SSL** e imposta: | Key | Significato | |---|---| | `rs_server_ipv4` | L'IPv4 pubblico a cui i record A dei rivenditori devono puntare. | | `rs_cname_target` | Il nome host a cui i record CNAME dei rivenditori devono puntare. | | `rs_master_hosts` | Nomi host che appartengono al tuo sito principale (non possono essere assegnati ai rivenditori). | | `rs_platform_domain` | Dominio padre opzionale per i **sottodomini della piattaforma** (ad esempio `partners.cloud.example.com` per assegnare ai rivenditori `acme.partners.cloud.example.com`). Se vuoto, disabilita l'opzione. | | `rs_sites_stale_minutes` | Minuti prima che il servizio di certificati venga considerato obsoleto (predefinito 15). | | `rs_ssl_fail_hours` | Ore di tentativi falliti prima che venga generato un errore (predefinito 48). | ::: warning Verifica questi valori prima di inviare le istruzioni `rs_server_ipv4`, `rs_cname_target` e `rs_master_hosts` contengono valori di esempio. Sostituiscili con il tuo server e dominio **prima** di fornire le istruzioni DNS a un rivenditore, altrimenti le istruzioni a schermo punteranno nel posto sbagliato. ::: 3. Fai clic su **Save** (viene richiesto un motivo). 4. Assicurati che il tuo reverse proxy inoltri i nomi host dei rivenditori al pannello NexCMP e serva un certificato per Ognuno di essi. Il programma di installazione configura nginx e Let's Encrypt solo per il dominio principale (e i nomi `admin.` e `partner.` che si risolvono). Se usi Cloudflare, fai da proxy per il nome host e usa la modalità Full SSL. ## Collega in NexCMP {#connect-in-nexcmp} ### Crea il rivenditore {#create-the-reseller} 1. Apri **Customers › Resellers › List** e fai clic su **New reseller**. La procedura guidata prevede 8 passaggi e effettua il provisioning di tutto alla fine; ogni passaggio può essere ripetuto in sicurezza. | Passaggio | Compila | |---|---| | **Reseller** | Nome legale o commerciale, **slug** (4–31 caratteri a–z, 0–9 o `-`, che inizia con una lettera; è anche il prefisso della fattura), nome del contatto, e-mail e telefono, lingua predefinita, dati di fatturazione del rivenditore (come acquirente di ricariche del portafoglio). | | **Console account** | Nome utente, e-mail dell'account, nome completo; **Send a one-time invite link by e-mail** (valido 72 ore, consigliato) o mostra una password temporanea una sola volta. | | **Brand** | Nome del brand, nome breve, slogan, colori primari, e-mail e telefono di supporto, nome del venditore stampato sulle fatture dei clienti, loghi (sfondo chiaro e scuro), icona quadrata e favicon: PNG, JPEG, WEBP o ICO fino a 256 KB, **no SVG**. | | **Domini** | I domini del cliente con **anche www**, quale è primario, un **dominio di test** (sslip.io) e l'opzione **dry-run**, oppure un sottodominio della piattaforma. La procedura guidata mostra **DNS OK / DNS not ready** e i record da creare. | | **Prezzi e portafoglio** | Sconto all'ingrosso (%), soglia al dettaglio (% del listino), ricarico predefinito (%), limite di credito, saldo iniziale, avviso di saldo basso, limiti su clienti, VM e domini, funzioni del sito (registrazione clienti, protezione DDoS, ticket di supporto, piano personalizzato, ridimensionamento, Auto Scaling). | | **Canali di pagamento** | Chi riscuote i pagamenti dei clienti (vedi sotto) e la gestione opzionale di un conto PayPal proprio o di un bonifico bancario vietnamita. | | **Email** | Nome del mittente e Reply-To. L'indirizzo From rimane quello della piattaforma finché non viene configurato il DKIM per il dominio del rivenditore. | | **Riepilogo** | Controlla tutto e fai clic su **Provision everything**, oppure **Save draft (provision later)**. | 2. Il provisioning continua in background (ogni 30 secondi). Apri il rivenditore per visualizzare i progressi e usa **Continue provisioning** o **Retry** se un passaggio non è riuscito. ![Procedura guidata per il nuovo rivenditore al primo passaggio con valori di esempio](https://nexcmp.com/it/docs/images/customers/resellers-01-wizard.webp) ### Puntare i DNS (il rivenditore esegue questa operazione) {#point-dns-the-reseller-does-this} Il rivenditore (o tu) crea i record indicati nella scheda **Domains & SSL**: | Record | Name | Valore | |---|---|---| | TXT (proprietà, solo la prima volta) | `_site-verify.` | `sv=` mostrato a schermo | | A (dominio principale come `shop.example.net`) | il dominio | il tuo `rs_server_ipv4` | | CNAME (sottodominio come `cloud.example.net`) | il dominio | il tuo `rs_cname_target` (o un record A verso `rs_server_ipv4`) | | CNAME (opzionale) | `www.` | il tuo `rs_cname_target` | Inoltre: - Rimuovi qualsiasi record **AAAA** (IPv6) a meno che il tuo server non risponda su quell'indirizzo IPv6. - Disattiva il proxy CDN (**off**, nuvola grigia) mentre il dominio viene verificato. - Se il dominio dispone di record **CAA**, consenti `letsencrypt.org`. Il token nel record TXT è diverso per ogni dominio; copialo dallo schermo. Il sistema verifica nuovamente i DNS ogni 5 minuti per le prime 48 ore, poi ogni ora, e rilascia un nome il cui record TXT risulta ancora mancante dopo 72 ore. ### Stati dei domini {#domain-states} In **Customers › Resellers › Domains & SSL** (tutti i rivenditori) e nella scheda **Domains & SSL** di un rivenditore: | Stato | Significato | |---|---| | `pending_verify` | In attesa del record TXT. | | `pending_dns` / `verifying` | In attesa che il record A o CNAME punti a te. | | `issuing` | Certificato in fase di emissione. | | `active` | In corso di erogazione del sito del rivenditore. | | `cert_expiring` | Certificato prossimo alla scadenza; rinnovo previsto. | | `dns_lost` | I DNS hanno smesso di puntare a te; dopo 30 giorni il dominio viene rimosso. | | `error` | Visualizza il codice di errore; **Retry** dopo la correzione. | | `removing` / `removed` | In fase di rimozione; lo slot di licenza viene restituito. | Azioni riga: **Check now**, **Retry**, **Make primary**, **Test mode** (per un dominio di test), **Remove**. ## Permessi e listino all'ingrosso {#permissions-wholesale} **Customers › Resellers › Permissions & wholesale** (`/resellers/entitlements`) è una matrice: una riga per rivenditore, con **discount** e **markup** all'ingrosso e un interruttore per servizio (ad esempio DDoS Shield e VPN). Un interruttore è modificabile quando la funzione a livello di piattaforma è attiva; altrimenti la cella è di sola lettura e rimanda all'impostazione. La scheda secondaria **Top-up codes** definisce quanti codici ogni rivenditore può emettere al mese (vedi [Promotions](https://nexcmp.com/it/docs/billing/promotions/)). Regole di prezzo: - Prezzo all'ingrosso = prezzo di listino x (1 - discount), e può essere sovrascritto per piano e per ciclo di fatturazione nella scheda **Wholesale pricing** del rivenditore. - Il rivenditore stabilisce i prezzi al dettaglio e non può scendere sotto la **floor** (percentuale del listino). - Il **wallet** del rivenditore paga il prezzo all'ingrosso quando i suoi clienti acquistano. Il wallet ha un limite di credito, un periodo di tolleranza e un tetto di scoperto (vedi Defaults). ## Defaults {#defaults} **Customers › Resellers › Defaults** (`/resellers/settings`) sono le `rs_*` chiavi applicate a ogni rivenditore. Ogni modifica richiede una motivazione e viene registrata. | Group | Key | Predefinito | Significato | |---|---|---|---| | General | `rs_enabled` | 1 | Programma rivenditori attivo. | | | `rs_platform_collect_enabled` | 0 | Consente alla piattaforma di riscuotere i pagamenti dei clienti per conto dei rivenditori. **Abilitare solo dopo una revisione legale.** | | | `rs_totp_required` | 1 | Gli account della console rivenditore devono utilizzare l'autenticazione a due fattori. | | | `rs_agreement_version` | 1 | Versione dell'accordo di rivendita che devono accettare. | | Default pricing | `rs_default_discount_bp` | 2000 (20 %) | Sconto all'ingrosso per i nuovi rivenditori (punti base, da 0 a 9000). | | | `rs_default_markup_bp` | 2500 (25 %) | Markup predefinito (da 0 a 50000). | | | `rs_default_floor_bp` | 9000 (90 %) | Soglia minima al dettaglio (da 0 a 20000). | | | `rs_default_max_domains` | 3 | Domini consentiti per rivenditore. | | Wallet and payouts | `rs_grace_hours` | 72 | Periodo di tolleranza prima che i servizi dei clienti siano influenzati da un wallet rivenditore vuoto. | | | `rs_overdraft_cap_cents` | 5000 | Scoperto consentito sul wallet. | | | `rs_retention_days` | 14 | Giorni prima che le VM di un rivenditore chiuso vengano eliminate. | | | `rs_payout_hold_days` | 30 | Giorni in cui una commissione viene trattenuta prima di poter essere prelevata. | | | `rs_payout_min_cents` | 5000 | Prelievo minimo. | | | `rs_topup_min_cents` | 2000 | Ricarica minima del wallet da parte di un rivenditore. | | Payments and mail | `rs_webhook_base` | empty | URL di base pubblico per i webhook dei gateway rivenditore (vuoto = usa l'URL del sito). | | | `rs_mail_from` | empty | Indirizzo From per le e-mail dei rivenditori. | | | `rs_invoice_show_processor` | 1 | Mostra il processore di pagamento sulle fatture. | | | `rs_gw_stripe_enabled`, `rs_gw_usdt_enabled` | 1 | Indica se i rivenditori possono configurare il proprio Stripe o USDT. | ## Chi riscuote i pagamenti dei clienti {#who-collects-customer-payments} | Modalità | Significato | |---|---| | **Reseller collects (own channels)** — predefinito | Il rivenditore collega il proprio account Stripe, PayPal, USDT o bancario. I suoi webhook sono `https:///v1/billing//webhook/r/`. Le carte salvate e l'[auto top-up](https://nexcmp.com/it/docs/billing/auto-top-up/) non sono disponibili per questi siti. | | **Platform collects** | I tuoi canali vengono mostrati sul sito del rivenditore. Bloccato fino a `rs_platform_collect_enabled = 1`. | | **Mixed** | Una combinazione scelta per canale. | ## Cosa vede il rivenditore {#what-the-reseller-sees} La console partner all'indirizzo `https://partner.` include Overview, Reports, Customers, VMs, Tickets, Orders, Payments, Prices, Brand, Landing & legal, Domains & SSL, Email, Wallet e Payment channels. Gli account della console hanno il ruolo *reseller* (completo) o *staff* (sola lettura). Per visualizzarla tu stesso, apri il rivenditore e clicca su **Sign in to partner console**: accederai per 60 minuti, ogni scrittura sarà registrata con il tuo nome sia nel registro amministrativo sia in quello del rivenditore e le operazioni finanziarie richiederanno una seconda conferma. ## Verifica {#verify} 1. Dopo il provisioning, la riga del rivenditore mostra *active* e una colonna **Provisioning** verde. 2. Apri il dominio del rivenditore in un browser: compare la pagina di accesso del rivenditore con il suo marchio. `https:///admin` risponde 404. 3. Registra un cliente di prova su quel dominio: il cliente compare sotto **Customers › List** con il rivenditore nella colonna **Site**. 4. La pagina della licenza mostra uno slot utilizzato in più. ## Limiti e note {#limits-notes} - Uno slot di licenza per ogni dominio personalizzato o di prova; i sottodomini della piattaforma non consumano alcuno slot. - La sospensione di un rivenditore mantiene i dati; **Close reseller** restituisce tutti gli slot di dominio e la distruzione delle VM è consentita solo dopo il periodo di conservazione. - I clienti dei rivenditori compaiono nel tuo elenco clienti e possono essere impersonati come qualsiasi altro (il link si apre sul dominio del rivenditore). - I rivenditori non possono vedere o modificare i tuoi canali di pagamento, le quote predefinite o altri rivenditori. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | "Slot di dominio rivenditore esauriti" | All slots used | Libera uno slot (rimuovi un dominio) o acquistane altri nella pagina della licenza. | | Domain stuck in `pending_verify` | TXT record missing | Crea il record TXT esattamente come mostrato; usa **Check now**. | | Domain stuck in `pending_dns` | A/CNAME non puntato correttamente, record AAAA o proxy CDN attivo | Correggi il DNS, disattiva il proxy, quindi **Check now**. | | `error` state | Vedi il codice nella riga (ad esempio CAA che blocca Let's Encrypt, limite di richieste) | Correggi e fai clic su **Retry**. | | Il browser indica che l'host è sconosciuto o "421" | Il nome host non è presente nella licenza o non è instradato verso il pannello | Aggiungi il dominio tramite il rivenditore (consuma uno slot) e correggi il reverse proxy. | | Le istruzioni mostrano un IP o un host errato | `rs_server_ipv4` / `rs_cname_target` contengono ancora i valori di esempio | Set them in Defaults. | | Il rivenditore non può abilitare la riscossione della piattaforma | Locked | Imposta `rs_platform_collect_enabled` dopo una revisione legale. | --- # Branding {#branding} > **Dove si trova nel pannello admin:** System › Settings › Brand (`/settings/branding`). Argomenti correlati: System › Settings › General (`/settings`) per gli URL e i dati del venditore stampati sulle fatture. ## Descrizione {#what-it-does} NexCMP è una soluzione white-label: il prodotto non riporta alcun nome di fornitore e tutto ciò che i tuoi clienti vedono è il **tuo** marchio. Le impostazioni del brand si applicano alle pagine di accesso e registrazione, al portale, alla console di amministrazione e alle email. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Ruolo | Un amministratore. | | Files | Logos: SVG, PNG, JPEG, WEBP or ICO, **up to 512 KB each**. | | Dipendenze | Nessuno. | ## Passaggi {#steps} 1. Open **System › Settings › Brand**. 2. Nella scheda **Identity** compila: | Campo | Note | |---|---| | **Brand name** (required) | Fino a 60 caratteri. Mostrato nel portale, nelle email, nelle fatture e nelle pagine legali. | | **Nome del venditore sulle fatture** | Fino a 120 caratteri. Se vuoto, viene usato il nome del brand. | | **Brand color** | Un colore `#rrggbb`; il piccolo pulsante accanto al campo lo ripristina a quello predefinito. | | **Site currency** | **USD**: i prezzi e i saldi sono mostrati solo in USD, senza alcun selettore di valuta. **VND**: mostra anche l'importo convertito al tasso di cambio memorizzato (vedi [Currency and exchange rates](https://nexcmp.com/it/docs/catalog/currency-and-exchange-rates/)). | 3. Clicca su **Save**. 4. Nella scheda **Logo & favicon** carica le tre immagini — **Logo (light background)**, **Logo (dark background)** e **Favicon** — con **Upload** (o **Replace**); **Remove** ne elimina una. ![Pagina del brand con i campi identificativi e le tre immagini caricate](https://nexcmp.com/it/docs/images/customers/branding-01-brand.webp) ### Impostazioni correlate in General {#related-settings-in-general} **System › Settings › General** ha due schede che completano il quadro: | Scheda | Campi | |---|---| | **Branding & URLs** | Nome del brand (e-mail, fatture), lingua predefinita (inglese o vietnamita), **Customer app URL**, **Console URL**, **Admin URL** (link di impersonificazione del rivenditore) e **Partner console URL** (link di invito, e-mail del rivenditore). La procedura guidata di installazione li riempie con `https://`, `https:///admin` e `https:///console`. | | **Seller & invoicing** | Nome dell'entità legale, partita IVA, indirizzo, e-mail di contatto e prefisso del numero di fattura. Vedi [Invoices and ledger](https://nexcmp.com/it/docs/billing/invoices-and-ledger/). | Il nome **From name** delle e-mail è impostato in **System › Settings › Email** ([SMTP and e-mails](https://nexcmp.com/it/docs/administration/smtp-and-emails/)). ## I file caricati vengono controllati {#uploaded-files-are-checked} - Le immagini raster vengono riconosciute dal loro contenuto (non dal nome del file) e misurate. - **I file SVG vengono ricostruiti** da un elenco sicuro di forme. Un file contenente script, `foreignObject`, attributi di evento, link esterni, `url(...)` che puntano all'esterno, un DOCTYPE o entità viene **rifiutato** (`svg_unsafe`). - Un file troppo grande viene rifiutato con `asset_too_large`, un tipo errato con `asset_type`, dimensioni errate con `asset_dimensions`. - I file vengono serviti dal tuo dominio con intestazioni di sicurezza rigorose. ## Verifica {#verify} 1. Apri la pagina di accesso del portale in una finestra privata: compaiono logo, nome e colore. 2. Controlla la scheda del browser per la favicon (i browser memorizzano nella cache le favicon; ricarica con la cache pulita se vedi ancora quella vecchia). 3. Attiva un'e-mail di test (ad esempio **Send reset link** per un cliente di prova) e controlla il nome del brand nell'oggetto e nel footer. ## Limiti e note {#limits-notes} - Il logo per lo sfondo scuro viene utilizzato quando il cliente o l'amministratore passa al tema scuro. - I rivenditori hanno il proprio brand; caricano PNG, JPEG, WEBP o ICO fino a 256 KB (senza SVG). Vedi [Resellers](https://nexcmp.com/it/docs/customers/resellers/). - Una modifica al colore o al logo del brand viene visualizzata al caricamento della pagina successiva; le e-mail già inviate non vengono modificate. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | Caricamento rifiutato: `svg_unsafe` | Il file SVG contiene script, link o riferimenti esterni | Esporta un SVG semplice (senza script, senza immagini esterne) o usa PNG. | | `asset_too_large` | File superiore a 512 KB | Comprimi o ridimensiona l'immagine. | | `asset_type` | Non è SVG, PNG, JPEG, WEBP o ICO | Converti il file. | | `invalid_argument: primary` | Il colore non è `#rrggbb` | Usa un valore esadecimale a sei cifre. | | Vecchio logo ancora visibile | Cache del browser | Ricaricamento forzato; le favicon possono richiedere più tempo. | | I prezzi vengono mostrati solo in USD | La valuta del sito è USD | Passa a VND e assicurati che sia memorizzato un tasso di cambio. | --- # Pagine legali {#legal-pages} > **Dove si trova nell'amministrazione:** System › Settings › Legal (`/settings/legal`). **Dove li vedono i clienti:** `https:///terms` e `/privacy`, collegati dalla registrazione e dal checkout. ## Descrizione {#what-it-does} La tua installazione pubblica due pagine: **Terms of Service** e **Privacy Policy**. Finché non scrivi le tue, NexCMP mostra un **testo neutro predefinito** che non menziona il fornitore del software e non promette alcun servizio particolare. Sostituiscilo con un testo revisionato dal tuo legale prima di iniziare a vendere. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Ruolo | Un amministratore. | | Contenuto | Markdown semplice, fino a **50 KB** per pagina e lingua. | | Dipendenze | Il nome del brand e i dettagli del venditore ([Branding](https://nexcmp.com/it/docs/customers/branding/)) vengono inseriti nel testo predefinito. | ## Passaggi {#steps} 1. Apri **System › Settings › Legal**. Ciascuna delle due pagine ha una propria scheda con il tag *Using the default text* o *Using your text*. 2. Scegli la scheda della lingua, **English** o **Tiếng Việt**. 3. Digita il tuo testo. Finché il campo è vuoto, il testo predefinito viene mostrato sbiadito come segnaposto. Per partire da esso, fai clic su **Start from the default text**, quindi modifica. 4. Fai clic su **Save**. Il contatore delle dimensioni mostra `used / 50 KB`. 5. Fai clic su **View on the customer site** per aprire `/terms` o `/privacy`. 6. Per tornare all'impostazione predefinita per una lingua, fai clic su **Clear, back to default** e salva. ![Impostazioni legali con la scheda Terms of Service che mostra il testo predefinito come punto di partenza](https://nexcmp.com/it/docs/images/customers/legal-01-terms.webp) ## Cosa contengono le pagine predefinite {#what-the-default-pages-contain} Il testo predefinito è memorizzato nel prodotto come `legal_default.json` e completato con il nome del tuo brand, il nome del venditore, l'URL del sito e l'e-mail di contatto (da **Seller & invoicing** in System › Settings › General; se non è impostata alcuna e-mail, punta al tuo team di supporto). | Pagina | Sezioni | |---|---| | **Terms of Service** | 1 Il servizio · 2 Account e verifica · 3 Prezzi e fatturazione · 4 Rimborsi · 5 I tuoi dati · 6 Uso consentito · 7 Disponibilità e supporto · 8 Sospensione e risoluzione · 9 Responsabilità · 10 Modifiche e legge applicabile (la legge del luogo di attività del venditore) | | **Privacy Policy** | 1 Cosa raccogliamo · 2 Perché lo usiamo · 3 Cookie e archiviazione locale · 4 Chi altro lo vede · 5 Conservazione · 6 I tuoi diritti · 7 Contatti | ::: warning Non è una consulenza legale Il testo predefinito è un modello neutro. Fallo revisionare prima di usarlo con clienti reali, in particolare le sezioni su rimborsi, responsabilità e legge applicabile. ::: ## Regole Markdown {#markdown-rules} - Supportati: intestazioni (`# 1. Title`), paragrafi, elenchi puntati e numerati, **grassetto** e link `[text](https://example.com)`. - I link devono iniziare con `http://` o `https://`. - **L'HTML grezzo viene rifiutato** (qualsiasi ``, ` # Panoramica del portale clienti {#customer-portal-overview} > **Dove nel portale:** `https:///` — i clienti effettuano l'accesso su `/login`. Gli amministratori usano `/admin`; lo stesso login apre entrambi quando l'account è di tipo amministratore. Il portale è lo strumento che i tuoi clienti usano ogni giorno. È brandizzato con il tuo nome, logo e colori ([Branding](https://nexcmp.com/it/docs/customers/branding/)) e mostra solo i servizi che hai attivato ([Modules](https://nexcmp.com/it/docs/infrastructure/modules/)). ## La dashboard {#the-dashboard} Dopo l'accesso, la **Dashboard** mostra: | Blocco | Significato | |---|---| | Saldo del portafoglio | Credito attuale e stima dei giorni di autonomia al ritmo di consumo attuale | | Spesa del mese | Addebiti finora e previsione per la fine del mese | | Macchine virtuali | Ogni VM con stato, IP, CPU e RAM, e azioni rapide (Console, Restart) | | Banda | Traffico in entrata/uscita per 1 h, 6 h, 24 h, 7 d, 30 d | | Attività recente | Ultimi eventi sull'account | | Avvio rapido | Una checklist: crea una VM, aggiungi una chiave SSH, ricarica, abilita la ricarica automatica, verifica l'e-mail | ![La dashboard cliente con saldo del portafoglio, previsione di spesa, una macchina virtuale in esecuzione e la checklist di avvio rapido](https://nexcmp.com/it/docs/images/portal/overview-01-dashboard.webp) ## Navigazione {#navigation} Il menu raggruppa i servizi per tipo. Un servizio disabilitato (o la cui sorgente non è connessa) non viene visualizzato. | Area | Pagina | |---|---| | Instances | [Virtual machines](https://nexcmp.com/it/docs/portal/virtual-machines/) e relative pagine di dettaglio | | Deploy | [Ordering](https://nexcmp.com/it/docs/portal/ordering/) — crea una risorsa | | Storage | Snapshot, backup e volumi quando abilitati — [Snapshots](https://nexcmp.com/it/docs/portal/snapshots/) | | Billing | [Wallet and top-ups](https://nexcmp.com/it/docs/portal/sign-up-and-wallet/), fatture, ordini, quote | | Account | Profilo, accesso e sicurezza, preferenze, ricarica automatica | | Support | Widget di chat e ticket — [Support](https://nexcmp.com/it/docs/portal/support/) | | Documenti API | `/apidoc` — [API](https://nexcmp.com/it/docs/developers/api/) | ## Account {#account} **Account** ha quattro schede: **Profile** (nome, e-mail, ID cliente, richiesta di eliminazione dell'account), **Sign-in & security** (password, passkeys, Google/GitHub collegati), **Preferences** (lingua, valuta di visualizzazione) e **Auto top-up** ([Auto top-up](https://nexcmp.com/it/docs/billing/auto-top-up/)). Un cliente non può eliminare direttamente l'account: preme **Request account deletion**; dopo che tutte le macchine virtuali sono state eliminate, un operatore esamina la richiesta (Customers › Deletion requests) e il cliente può revocarla finché è in sospeso. ## Lingua e valuta {#language-and-currency} Il portale è disponibile in 16 lingue e mostra i prezzi nella valuta di visualizzazione scelta in base alla lingua; vedi [Currency and exchange rates](https://nexcmp.com/it/docs/catalog/currency-and-exchange-rates/). I clienti possono cambiare entrambe in **Preferences**. ## Quote cliente {#customer-quotas} **Billing › Quotas** mostra quanta parte di ciascuna risorsa (CPU, memoria, spazio di archiviazione, IP, VM) il cliente può utilizzare, in base a quanto ha pagato — vedi [Quotas](https://nexcmp.com/it/docs/billing/quotas/). --- # Registrazione, portafoglio e ricarica {#sign-up-wallet-and-top-up} > **Dove nel portale:** `/register`, `/login`, Billing (`/billing`). ## Crea un account {#create-an-account} 1. Il cliente apre `https:///register` e inserisce e-mail e password (almeno 10 caratteri con lettere e cifre), oppure utilizza **Google**, **GitHub** o una **passkey** se le hai abilitate — vedi [Security](https://nexcmp.com/it/docs/administration/security/#customer-sign-in). 2. Se il captcha è abilitato, lo completa. 3. Viene inviata un'e-mail di verifica tramite il tuo [SMTP](https://nexcmp.com/it/docs/administration/smtp-and-emails/). La verifica è obbligatoria prima di creare una VM se le tue impostazioni di vendita lo richiedono. ![La pagina di registrazione con i campi e-mail e password](https://nexcmp.com/it/docs/images/portal/sign-up-and-wallet-01-register.webp) ::: tip Senza un SMTP funzionante, i clienti non possono verificare la propria e-mail o reimpostare una password. Configura prima [SMTP](https://nexcmp.com/it/docs/administration/smtp-and-emails/). ::: ## Il portafoglio {#the-wallet} Tutto viene pagato dal saldo del **wallet** nella valuta di fatturazione. La pagina **Billing** mostra: | Sezione | Significato | |---|---| | Potere di spesa | Saldo più ricariche in sospeso | | Addebiti in corso | Servizi orari consumati nel ciclo corrente, non ancora saldati | | Saldo insoluto | Eventuale importo dovuto | | Cronologia di fatturazione | Schede **Invoice History**, **Payment Order**, **Ledger**, **Orders** | ![La pagina Billing con potere di spesa, addebiti in corso e le schede della cronologia](https://nexcmp.com/it/docs/images/portal/sign-up-and-wallet-02-billing.webp) ## Aggiungi credito {#add-credit} 1. Fai clic su **Deposit**. 2. Inserisci l'importo. Il minimo è la tua [minimum top-up](https://nexcmp.com/it/docs/billing/minimum-top-up/). 3. Scegli un canale di pagamento (carta, PayPal, USDT o bonifico bancario quando l'interfaccia è in vietnamita) — i canali sono quelli che hai abilitato in [Payment channels](https://nexcmp.com/it/docs/billing/payment-channels/). 4. Paga. Il saldo si aggiorna quando il fornitore di pagamento conferma. Le carte salvate, Stripe Link e PayPal possono essere riutilizzate e impiegate per il [auto top-up](https://nexcmp.com/it/docs/billing/auto-top-up/); vedi [Saved payment methods](https://nexcmp.com/it/docs/billing/saved-payment-methods/). ## Riscatta un codice {#redeem-a-code} **Redeem code** aggiunge credito da un voucher emesso da te (Finance › Billing › Vouchers) o applica un codice promozionale — vedi [Promotions](https://nexcmp.com/it/docs/billing/promotions/). ## Invoices {#invoices} Ogni ordine pagato genera una fattura che mostra i dati del venditore ([General settings](https://nexcmp.com/it/docs/administration/general-settings/)). I clienti la aprono da **Invoice History** e la stampano o la salvano in PDF dal browser. ## Addebiti orari {#hourly-charges} I servizi orari vengono addebitati per ogni ora in cui la risorsa esiste; gli importi si accumulano e un'ora singola può arrotondare a $0.00. Quando il saldo non è sufficiente, i servizi vengono sospesi secondo le regole di fatturazione e il cliente viene avvisato via e-mail (`low_balance`). --- # Ordinare un servizio {#ordering-a-service} > **Dove nel portafoglio:** Deploy (`/deploy/vm`). **Dove nell'amministrazione** controlli ciò che appare qui: Services (plans, prices) e System › Admin › License & updates (moduli). La pagina degli ordini è un modulo a scorrimento con passaggi numerati. Scegliere un altro servizio al passaggio 1 mantiene la pagina e modifica i passaggi sottostanti. ## Passaggi {#steps} 1. **Service** — Cloud Servers e gli altri servizi abilitati (Kubernetes, Object Storage, Images, Private Cloud, VPN …). 2. **Location** — la [zone](https://nexcmp.com/it/docs/infrastructure/zones/). I prezzi e il traffico incluso possono variare in base alla posizione. 3. **Plan** — un piano fisso (vCPU, RAM, disco NVMe, prezzo orario) o **Custom** (il cliente sceglie vCPU, RAM e disco; tariffato per risorsa). I piani provengono da [Plans](https://nexcmp.com/it/docs/catalog/plans/). 4. **Billing cycle** — **Hourly** o cicli prepagati mensili/annuali con sconto (ad esempio 1 anno −10%, 2 anni −15%, 3 anni −20%). 5. **Operating system** — un elenco di template, **My Images** (caricamenti personali del cliente) e la versione. 6. **Hostname & quantity** — un nome (o **Randomize**) e il numero di server. ![La pagina degli ordini che mostra i passaggi di servizio, posizione e piano](https://nexcmp.com/it/docs/images/portal/ordering-01-plan.webp) ![I passaggi del ciclo di fatturazione e del sistema operativo della pagina degli ordini](https://nexcmp.com/it/docs/images/portal/ordering-02-cycle-os.webp) ## Invio dell'ordine {#placing-the-order} Il riepilogo mostra il prezzo. L'ordine viene addebitato sul portafoglio **prima** del provisioning, dopo le regole di [quota check](https://nexcmp.com/it/docs/billing/quotas/) e [minimum balance](https://nexcmp.com/it/docs/billing/minimum-top-up/). Una VM di solito raggiunge lo stato *Running* in circa un minuto; il cliente vede le fasi di deploy nella scheda **Activity** della VM e riceve l'e-mail "VM ready" con la password iniziale (visibile una sola volta per 10 minuti). ## Cosa può bloccare un ordine {#what-can-stop-an-order} | Messaggio / causa | Soluzione | |---|---| | Saldo insufficiente | Ricarica — [Sign-up, wallet and top-up](https://nexcmp.com/it/docs/portal/sign-up-and-wallet/) | | Quota superata | Aumenta la quota — [Quotas](https://nexcmp.com/it/docs/billing/quotas/) | | E-mail non verificata | Il cliente verifica l'e-mail | | Nessun piano per la posizione scelta | Rendi disponibile un piano in quella zona — [Plans](https://nexcmp.com/it/docs/catalog/plans/) | | Licenza non valida | I clienti non possono creare nuovi servizi — [License](https://nexcmp.com/it/docs/getting-started/license-and-purchase/#if-the-license-is-not-valid) | --- # Macchine virtuali {#virtual-machines} > **Dove nel portafoglio:** Instances (`/vms`) e pagina della VM (`/vms/`). **Instances** elenca le VM di un cliente con nome, sistema operativo, stato, IP, specifiche e costo. Cliccane una per aprire la sua pagina. ## La pagina della VM {#the-vm-page} Schede: **Overview**, **Console**, **AI SSH Agent** (quando il modulo AI è attivo), **Monitoring**, **Storage**, **Network**, **Configuration**, **Billing**, **Activity**. ![Panoramica di una macchina virtuale con stato, specifiche, IP, grafico della larghezza di banda e registro delle azioni](https://nexcmp.com/it/docs/images/portal/virtual-machines-01-overview.webp) ### Azioni {#actions} | Action | Effetto | |---|---| | Console | Apre la console del browser — [Console](https://nexcmp.com/it/docs/portal/console/) | | Riavvio / Arresto / Arresto forzato | Controllo alimentazione | | Reimposta password | Genera una nuova password, mostrata una sola volta | | Reinstalla OS | Ricostruisce da un template; i dati vengono persi | | Cambia IP | Sostituisce l'IP pubblico (ove supportato dalla sorgente) | | Abilita Auto Scaling | Ridimensiona CPU/RAM sotto carico quando abilitato | | Elimina | Distrugge la VM; la fatturazione oraria si interrompe | ### Informazioni mostrate {#information-shown} Uptime, costo del mese corrente, vCPU/RAM/disco con utilizzo in tempo reale, IP pubblico e privato, nome utente, grafico di banda, registro delle azioni e riepilogo di fatturazione (piano, ciclo, ore, residuo). ::: info I campi dipendono dalla sorgente Una pagina di VM mostra solo ciò che la sua sorgente supporta. Ad esempio, una VM Proxmox VE non dispone di port forwarding o cambio IP e il suo elenco di OS segue il set di template del proprio cluster. Consulta la tabella delle capacità in [Proxmox VE](https://nexcmp.com/it/docs/infrastructure/proxmox/). ::: ## Scheda Fatturazione {#billing-tab} Mostra piano, ciclo, ore totali, tempo rimanente e registro di fatturazione. Le VM orarie maturano costi fino all'eliminazione. Un cliente può **cambiare ciclo** per prepagare un periodo più lungo a un prezzo scontato. ## Per gli amministratori {#for-administrators} La stessa VM è visibile in Services › Virtual Machines nella console di amministrazione, da cui è possibile agire per conto del cliente o [effettuare il login come](https://nexcmp.com/it/docs/customers/login-as/) esso. --- # Console {#console} > **Dove si trova nel portale:** nella pagina di una VM → scheda **Console**. **Dove si trova nell'amministrazione:** System › Admin › License & updates → moduli (SSH web). ## Descrizione {#what-it-does} La scheda **Console** apre una sessione grafica (VNC) verso la VM all'interno del browser, anche quando la rete interna alla VM non è funzionante. Un terminale **SSH web** è disponibile come seconda opzione quando il modulo SSH è abilitato. ## Requisiti {#requirements} | Elemento | Console VNC | SSH web | |---|---|---| | CloudStack | VM proxy della console (CPVM) raggiungibile dal pannello — vedi [CloudStack](https://nexcmp.com/it/docs/infrastructure/cloudstack/) | Una porta SSH raggiungibile sulla VM | | Proxmox VE | Funziona tramite il pannello (noVNC tramite API Proxmox; l'impronta digitale TLS è bloccata) — vedi [Proxmox VE](https://nexcmp.com/it/docs/infrastructure/proxmox/) | Stesso | | Pannello | URL della console impostato in [General settings](https://nexcmp.com/it/docs/administration/general-settings/) | Il servizio `ssh-proxy` e il flag del modulo `feature_ssh_web`; disattivo di default — vedi [Modules](https://nexcmp.com/it/docs/infrastructure/modules/) | Se il modulo SSH web è disattivato, la scheda mostra **VNC only**. ## Utilizzo {#use-it} 1. Apri la VM → **Console**. 2. Fai clic su **Console** (o **Open in new window**). Viene emesso un ticket di breve durata e la console si apre su `https:///console`. 3. Accedi con il nome utente e la password della VM (visibili nella scheda Overview; ripristinali se persi). ![La scheda Console di una macchina virtuale](https://nexcmp.com/it/docs/images/portal/console-01-tab.webp) ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | "Disconnected" immediato | Il browser ha mantenuto un vecchio percorso della console | Cancella i dati del sito per il dominio e riprova | | Schermo nero | La VM è arrestata o in fase di avvio | Avvia la VM e attendi | | La console non si apre su CloudStack | VM proxy della console non in esecuzione o non raggiungibile | Controlla le macchine virtuali di sistema in CloudStack | | Nessuna opzione SSH | Modulo Web SSH disattivato | Abilitalo solo dopo aver installato `ssh-proxy` | --- # Snapshots e backups {#snapshots-and-backups} > **Dove nel portale:** Snapshots (`/snapshots`), Snapshot schedules (`/snapshots/schedules`), Backups (`/backups`). Visibili solo quando la funzione è abilitata nell'amministrazione. ## Descrizione {#what-it-does} Uno snapshot salva lo stato del disco di una VM per consentire il ripristino dopo un errore. Gli Snapshots si creano manualmente o su pianificazione. ## Disponibilità {#availability} | Source | Snapshots | Note | |---|---|---| | CloudStack | Sì | Snapshot di volumi; storage fatturato come configurato | | Proxmox VE | Sì | Fino a **5 per VM**; crea, elenca, ripristina ed elimina | La voce di menu compare solo quando la funzione snapshot è attiva e il cliente possiede una VM la cui origine la supporta. ## Utilizzo {#use-it} 1. Apri **Snapshots**, clicca **Create**, seleziona la VM e assegna un nome. 2. Attendi che lo stato diventi *ready*. 3. Per tornare indietro, scegli **Restore** sullo snapshot e conferma: la VM tornerà a quello stato (e verrà riavviata se necessario). 4. Elimina gli snapshot di cui non hai più bisogno. ::: warning Il ripristino elimina tutto ciò che è stato scritto dopo lo snapshot. Le VM protette non possono essere ripristinate o eliminate dal portale. ::: --- # Supporto per i clienti {#support-for-customers} > **Dove nel portale:** il fumetto della chat su ogni pagina, `/chat` e Support tickets. **Dove nell'amministrazione:** Customers › Support › Tickets (`/support/tickets`), scheda **Settings**. ## Per i clienti {#for-customers} - **Fumetto della chat** (angolo inferiore di ogni pagina): fai una domanda; la [AI Chat](https://nexcmp.com/it/docs/ai/ai-chat/) risponde utilizzando la tua documentazione e i dati dell'account del cliente. **Expand** apre la stessa conversazione su `/chat`. - **Parla con lo staff**: trasferisce la conversazione al tuo team (tramite il tuo gruppo Telegram amministrativo). - **Pulsanti Telegram / Zalo**: compaiono solo dopo aver impostato i link nelle impostazioni del supporto. - **Ticket**: per problemi più complessi; le risposte vengono inviate via email (`ticket_reply`). ## Per te {#for-you} 1. Apri **Customers › Support › Tickets**; i nuovi ticket e le chat compaiono qui con la conversazione. 2. Rispondi nella discussione. Il cliente riceve un'email tramite il tuo [SMTP](https://nexcmp.com/it/docs/administration/smtp-and-emails/). 3. Nella scheda **Settings** attiva o disattiva il widget della chat, imposta il link di Telegram e il link di Zalo (solo https) e scegli se l'IA risponde automaticamente — vedi [AI Chat](https://nexcmp.com/it/docs/ai/ai-chat/). 4. Collega [Telegram alerts](https://nexcmp.com/it/docs/administration/telegram-notifications/) in modo che il tuo team riceva notifiche per le nuove chat. --- # Provider IA {#ai-provider} > **Dove nell'amministrazione:** System › Settings › AI provider (`/settings/ai`). L'interruttore del modulo IA si trova lì e in System › Admin › License & updates (`/license`), scheda **Module**. ## Descrizione {#what-it-does} AI Chat (chat di supporto automatico) e AI Agent (amministrazione delle VM in linguaggio naturale) non includono un modello integrato. Scegli **il tuo provider**: qualsiasi servizio che offra una API `chat/completions` **compatibile con OpenAI**, ad esempio OpenAI, OpenRouter, un gateway LiteLLM o il tuo server vLLM. NexCMP memorizza l'endpoint e la chiave API (cifrata) e li utilizza per tutte le funzionalità di intelligenza artificiale. Paghi direttamente il provider. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Endpoint | Un URL di base compatibile con OpenAI (`https://api.openai.com/v1`, `https://ai.example.com/v1`). NexCMP aggiunge `/chat/completions` a un URL che termina con `/v1`; per qualsiasi altro URL aggiunge `/v1/chat/completions`; un URL che termina già con `/chat/completions` viene utilizzato così com'è. | | Modello | Un modello che supporta la **chiamata di strumenti (funzioni)**. Sia l'AI Chat che l'Agent dipendono da esso. | | Chiave API | Una chiave per quell'endpoint. È preferibile una chiave con un **limite di spesa** lato provider (ad esempio una chiave virtuale LiteLLM con un budget mensile). | | Rete | Il server del pannello deve raggiungere l'endpoint tramite HTTP(S). Un URL inserito nel modulo può puntare solo a Internet sulle porte 80, 443, 8080 o 8443; per utilizzare un indirizzo interno, salva prima il provider ed esegui il test in un secondo momento. | | Dipendenze | Il modulo **AI** attivo. Per l'Agent vedi [AI Agent](https://nexcmp.com/it/docs/ai/ai-agent/#requirements). | ## Prepara l'infrastruttura {#prepare-the-infrastructure} 1. Registrati presso il provider e crea una chiave API. Se il provider supporta budget o limiti di frequenza, imposta un limite mensile. 2. Prendi nota dell'**URL di base** e del **nome esatto del modello** (e, facoltativamente, fino a quattro modelli di fallback). 3. Testalo dal server NexCMP prima di inserirlo: ```bash curl -s https://ai.example.com/v1/chat/completions \ -H "Authorization: Bearer XXXX" -H "Content-Type: application/json" \ -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Reply with one word: OK"}]}' ``` Una risposta JSON con `choices[0].message.content` indica che l'endpoint funziona. ## Collega in NexCMP {#connect-in-nexcmp} 1. Apri **System › Settings › AI provider**. 2. Nella scheda **Module AI** attiva il modulo **on**. Finché non è attivo, i clienti non vedono l'AI Chat o l'AI Agent nel portale. (Puoi attivarlo anche in **License & updates**.) 3. Nella scheda **Connection** compila: | Campo | Esempio | Note | |---|---|---| | Usa questo provider | on | Richiede un URL di base, un modello e una chiave per essere attivato. | | Nome visualizzato | `LiteLLM` | Fino a 60 caratteri. | | URL di base (compatibile con OpenAI) | `https://ai.example.com/v1` | `http://` o `https://`, fino a 300 caratteri, senza spazi. | | Chiave API del provider | `sk-XXXX` | Memorizzata crittograficamente; in seguito vengono mostrati solo gli ultimi 4 caratteri. Lascia vuoto per mantenere la chiave salvata. | | Modello predefinito | `gpt-4o-mini` | Lettere, cifre e `- _ . / : @`. | | Modelli di fallback | `gemini-2.5-flash` | Separati da virgola, fino a 4. Utilizzati quando il modello predefinito fallisce. | | Livello di ragionamento | Predefinito (non inviato) | `Minimal`, `Low`, `Medium` o `High`. Per i modelli di ragionamento (Gemini, serie o) un livello basso risponde molto più velocemente. Lascia su Default per i modelli normali. | 4. Clicca su **Save**, quindi su **Test connection**. Il test invia una breve domanda e mostra `Connected — , ms` o l'errore restituito dal provider. ![Pagina del provider AI con il modulo AI attivato e il modulo di connessione compilato con valori di esempio](https://nexcmp.com/it/docs/images/ai/ai-providers-01-connection.webp) ### Cosa comporta il salvataggio {#what-saving-does} - Le impostazioni del provider vengono salvate come un'unica voce di configurazione e la chiave viene crittografata con AES-256-GCM, vincolata a questo scopo, utilizzando la chiave master dell'installazione. - Le impostazioni di supporto **Primary model** e **Fallback model** (utilizzate da AI Chat) vengono impostate automaticamente sul tuo modello predefinito e sul primo modello di fallback. - La modifica viene registrata nel registro di audit (endpoint, modello, indicazione se la chiave è cambiata — mai la chiave). ## Verifica {#verify} 1. **Test connection** diventa verde. 2. Accedi al portale come cliente di prova: il menu ora offre **AI Chat** (o la bolla della chat) e **AI Agent**. 3. Chiedi all'AI Chat "What is my balance?". Una risposta che riporta il tuo saldo reale dimostra che il provider gestisce correttamente le chiamate agli strumenti. ## Limiti e note {#limits-notes} - **Un unico provider.** NexCMP utilizza un singolo provider configurato per Chat, Agent e analisi dei ticket. I modelli di fallback offrono resilienza all'interno di quel provider. - **Sicurezza della chiave.** La chiave salvata viene inviata esclusivamente all'endpoint salvato. Se modifichi l'URL di base, devi reinserire la chiave prima di eseguire il test. - **Limiti per cliente.** AI Chat è riservata ai clienti autenticati, con limiti di messaggi al minuto e per chat. L'Agent ha una quota giornaliera di chiamate per account. Vedi [AI Chat](https://nexcmp.com/it/docs/ai/ai-chat/) e [AI Agent](https://nexcmp.com/it/docs/ai/ai-agent/). - **Privacy.** Le domande dei clienti e i dati letti dall'IA per quel cliente (in sola lettura) vengono inviati al tuo provider. Specificatelo nella vostra [privacy policy](https://nexcmp.com/it/docs/customers/legal/). - **Controllo dei costi.** NexCMP non conteggia i costi dell'IA; utilizza le funzionalità di budget del provider. - Il modulo può essere disattivato in qualsiasi momento: le voci di menu AI scompaiono e le route AI rispondono con 404 `module_disabled`. Alcuni job in background di AI Chat (analisi ticket, risposte differite) applicano la modifica al riavvio successivo del pannello. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | `base_url must be an http(s) URL` | Schema mancante o spazi | Usa `https://host/v1`. | | `api_key is required to enable the provider` | Nessuna chiave memorizzata | Inserisci la chiave e salva. | | `base_url and model are required to enable the provider` | Campo vuoto | Compila entrambi. | | "Base URL bloccato: solo http(s) pubblico, porte 80/443/8080/8443" | Test di un indirizzo interno non salvato o di un'altra porta | Salva prima il provider, quindi esegui il test. | | `api_key is required (enter the key again when you change the endpoint)` | Il Base URL differisce da quello salvato | Reinserisci la chiave. | | `model: letters, digits and - _ . / : @` | Carattere non valido | Usa l'ID modello esatto del provider. | | `fallback_models: up to 4 model names` | Troppi | Mantieni quattro o meno. | | Il test fallisce con 401 | Chiave errata | Controlla la chiave e l'endpoint. | | Il test fallisce con 404 o "model not found" | Percorso o modello errato | Controlla il base URL (`/v1`) e l'ID del modello. | | `Too many tests — wait a minute` (429) | Più di 10 test al minuto | Attendi. | | Il portale non mostra ancora alcun menu IA | Modulo disattivato o provider non "in use" | Attiva il modulo e abilita il provider. | --- # AI Chat {#ai-chat} > **Dove nel pannello admin:** Customers › Support › Ticket, scheda **AI settings** (`/support/tickets?tab=settings`). Provider e modulo: System › Settings › AI provider (`/settings/ai`). **Dove nel portale:** il pulsante chat mobile e la pagina `/chat` (modalità **Ask AI**). ## Descrizione {#what-it-does} L'AI Chat risponde alle domande dei clienti a qualsiasi ora, consulta i dati del *loro* account (saldo, servizi, pagamenti, errori recenti) e può agire per loro — creare una VM, cambiare un piano — previa conferma del cliente. Quando l'assistente non è in grado di aiutare, il cliente clicca su **Talk to a human**: la chat viene inoltrata al tuo staff su Telegram e, se nessuno risponde in tempo, si trasforma in un ticket. Le stesse impostazioni dell'IA consentono inoltre al sistema di **analizzare i ticket** per il tuo staff. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Modulo e provider | Il modulo **AI** attivo e un [AI provider](https://nexcmp.com/it/docs/ai/ai-providers/) salvato e in uso. Senza un provider, l'assistente comunica che non è configurato. | | Clienti | **Solo clienti autenticati.** In un'installazione di NexCMP non esiste un sito pubblico, pertanto un visitatore non autenticato visualizzerà "Sign in to use AI Chat". | | Canale dello staff (opzionale) | Un bot e una chat Telegram per gli avvisi amministrativi (vedi [Telegram notifications](https://nexcmp.com/it/docs/administration/telegram-notifications/)). Lo stesso canale riceve i trasferimenti di chat e le bozze dei ticket. | | Dipendenze | [AI provider](https://nexcmp.com/it/docs/ai/ai-providers/). | ## Prepara l'infrastruttura {#prepare-the-infrastructure} Non richiesto oltre al provider IA. Se desideri il passaggio allo staff: 1. Crea un bot Telegram con @BotFather e prendi nota del token. 2. Crea un gruppo o usa la tua chat privata con il bot e prendi nota dell'ID della chat. 3. Inserisci entrambi in System › Settings › Admin alerts (vedi [Telegram notifications](https://nexcmp.com/it/docs/administration/telegram-notifications/)). Le funzioni di supporto riutilizzano quel bot e quella chat. ## Collega in NexCMP {#connect-in-nexcmp} 1. Assicurati che il modulo IA sia attivo e che il provider restituisca un test verde ([AI provider](https://nexcmp.com/it/docs/ai/ai-providers/)). 2. Apri **Customers › Support › Ticket** e seleziona la scheda **AI settings**. La parte superiore della scheda di sinistra mostra tre etichette: *AI provider: configured*, *Telegram: channel present* e *On shift* oppure *Off shift*. 3. Scheda sinistra **AI + Telegram**: | Interruttore o campo | Predefinito | Significato | |---|---|---| | L'IA analizza i ticket automaticamente | On | Per un nuovo ticket o messaggio, l'IA legge i dati del cliente (in sola lettura) e scrive la causa probabile e una bozza di risposta come **nota interna**. Non viene mai inviata al cliente. | | Avvisi Telegram agli amministratori | On | La nota arriva su Telegram con i pulsanti Send, Edit e Skip. | | Risposta automatica IA | Disattivato | Invia autonomamente semplici risposte di supporto o commerciali quando sono soddisfatte tutte le condizioni di sicurezza (confidenza dell'85% o superiore, nessun avviso); inviata dopo 3 minuti e annullabile su Telegram. | | Categorie abilitate alla risposta automatica | `how_to`, `sales` | Solo queste. | | Modello primario, Modello di fallback | impostato dal provider | Normalmente lascia quanto salvato dalla pagina del provider IA. | | ID utente Telegram autorizzato ad agire | empty | Se vuoto, indica la chat del canale di avviso. | 4. Scheda destra **Live chat (customer widget)**: | Campo | Predefinito | Significato | |---|---|---| | Abilita widget chat | On | La bolla della chat e la pagina `/chat`. | | Orario di supporto (ora del Vietnam) | `08:00-22:00` | Quando ci si aspetta che il personale risponda su Telegram. Al di fuori di questi orari, o quando non esiste alcun canale Telegram, **Talk to a human** trasforma immediatamente la chat in un ticket. | | Attesa massima per il personale (minuti), quindi converti in ticket | 10 | Da 1 a 240. | | Interazioni IA / giorno / cliente | 40 | Da 1 a 1000. Raggiunto il limite, l'assistente invita il cliente a parlare con un operatore umano. | | Nuove chat / ora / IP | 20 | Da 1 a 1000. | | **Link Zalo OA** | empty | `https://zalo.me/...` Mostra il pulsante **Chat on Zalo** (con codice QR) nella chat. Se vuoto, viene nascosto. | | **Link Telegram** | empty | `https://t.me/...` Mostra un pulsante **Telegram**. Se vuoto, viene nascosto. | | Limite giornaliero complessivo di interazioni IA, clienti registrati | 2000 | | | Limite giornaliero complessivo, ospiti | 500 | Pool dedicato; non utilizzato fintanto che gli ospiti non possono chattare. | | Limite giornaliero complessivo di analisi automatiche dei ticket | 200 | | | Percorso amministratore (il pulsante Telegram "Open admin") | empty | Il tuo URL di amministrazione, ad esempio `https://cloud.example.com/admin`. | Ciascun interruttore o campo viene salvato non appena viene modificato. 5. In basso, **Reply templates** (titolo, lingua VI/EN/ZH, testo fino a 4,000 caratteri) offrono allo staff risposte predefinite. ![Scheda AI settings con gli interruttori IA e Telegram, i limiti della live chat e i collegamenti rapidi](https://nexcmp.com/it/docs/images/ai/ai-chat-01-settings.webp) ![Pagina di chat del cliente con l'assistente, i pulsanti di scelta rapida Zalo e Telegram e l'opzione per parlare con un operatore umano](https://nexcmp.com/it/docs/images/ai/ai-chat-02-portal.webp) ## Cosa può e non può fare l'assistente {#what-the-assistant-can-and-cannot-do} - **Lettura:** cerca nella tua knowledge base e nella documentazione pubblica, e legge i dati del cliente autenticato tramite strumenti di sola lettura. Non può vedere un altro cliente. - **Azione:** usa i permessi API del cliente. Una *lettura* si avvia subito. Qualsiasi modifica o spesa genera una **scheda di conferma** ("Needs your confirmation", con etichette *Costs money* o *Delete*); nulla viene eseguito finché il cliente non clicca su **Confirm**. Una chat ammette al massimo 3 schede in sospeso e un account al massimo 10 azioni di scrittura confermate all'ora. - **Mai:** non può aprire console, creare token SSH o di console, scaricare file di accesso Kubernetes, reimpostare password o mostrare segreti come password proxy o segreti S3. I segreti non vengono mai inseriti nel contesto del modello o nella cronologia della chat. - **Sicurezza:** le sue risposte passano attraverso un filtro di output; il testo del cliente e i risultati degli strumenti vengono trattati come dati, non come istruzioni. - **Banner di trasparenza:** la chat mostra "Risposta generata da un assistente AI — potrebbe non essere perfetta. Per qualsiasi questione critica, rivolgiti a un operatore umano." ## Passaggio all'operatore {#staff-hand-off} 1. Il cliente fa clic su **Talk to a human** e può lasciare un'e-mail. 2. Un messaggio con la conversazione arriva nella chat Telegram dello staff. Lo staff risponde rispondendo a quel messaggio; la risposta appare nella chat del cliente come "[brand] Support". 3. Se nessuno risponde entro il tempo di attesa (predefinito 10 minuti), la chat diventa un ticket in **Customers › Support › Ticket**. La stessa cosa accade immediatamente al di fuori dell'orario di supporto o quando Telegram non è configurato, e viene comunicato al cliente che è stato aperto un ticket. 4. Gli amministratori vedono inoltre le chat attive nella scheda **Live chat**. ## Verifica {#verify} 1. Accedi come cliente di test, apri la chat e fai una domanda sui tuoi servizi. L'assistente risponde. 2. Chiedigli di creare qualcosa che comporta dei costi: appare una scheda di conferma e non viene creato nulla finché non fai clic su **Confirm**. 3. Fai clic su **Talk to a human**. Il messaggio arriva nella tua chat Telegram (se configurata) o, dopo l'attesa, compare un ticket. 4. Con i collegamenti a Zalo e Telegram inseriti, entrambi i pulsanti di scelta rapida compaiono nella chat. ## Limiti e note {#limits-notes} - **Limiti di frequenza (per IP):** 20 messaggi al minuto e un numero limitato di passaggi di consegne all'ora; **40 messaggi per conversazione**. Questi valori sono fissi. - **Costo:** ogni interazione con l'AI chiama il tuo provider. Riduci **AI turns / day / customer** per limitare la spesa. - **La risposta automatica è disattivata per impostazione predefinita.** Attivala solo dopo aver osservato le bozze per un po' di tempo. - **Lingue:** l'assistente risponde nella lingua del cliente; il vietnamita viene rilevato dal testo. - **Rivenditori:** i siti dei rivenditori utilizzano i ticket anziché il widget. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | I clienti non visualizzano la chat | Modulo AI disattivato oppure **Enable chat widget** disattivato | Attivali entrambi. | | "Accedi per usare l'AI Chat" | Il visitatore non ha effettuato l'accesso | Comportamento previsto in NexCMP: effettuare prima l'accesso. | | L'assistente indica che non è configurato alcun provider AI | Provider mancante, non in uso o chiave mancante | Completa [AI provider](https://nexcmp.com/it/docs/ai/ai-providers/). | | L'AI risponde "parla con un operatore umano" dopo alcune domande | Limite giornaliero per cliente raggiunto | Aumenta **AI turns / day / customer**. | | Il tag Telegram mostra "no channel" | Bot o ID chat non configurati | Configura le [notifiche Telegram](https://nexcmp.com/it/docs/administration/telegram-notifications/). | | Pulsante Zalo o Telegram mancante | Il campo del link è vuoto | Inserisci il link. | | "Troppe richieste" nella chat | Più di 20 messaggi al minuto da un singolo IP | Attendi un minuto. | | Conversazione della chat piena | Raggiunti 40 messaggi | Avvia una nuova conversazione. | --- # AI Agent {#ai-agent} > **Dove nell'admin:** System › Settings › AI provider (`/settings/ai`) — interruttore del modulo e provider; System › Admin › License & updates (`/license`) — interruttore del modulo. **Dove nel portale:** AI Agent (`/ai/agent`) e la pagina `/chat/agent`, o la modalità **Agent** all'interno della chat. ## Descrizione {#what-it-does} L'AI Agent si connette alla VM Linux di un cliente tramite SSH ed esegue attività descritte in linguaggio naturale: "controlla lo stato del sistema", "installa Docker", "trova gli errori recenti", "libera spazio su disco". Mostra ogni comando che propone e il relativo output. I comandi in sola lettura possono essere eseguiti automaticamente; qualsiasi azione che modifichi il server richiede che il cliente prema **Run**. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Modulo AI e provider | Il modulo **AI** attivo e un [AI provider](https://nexcmp.com/it/docs/ai/ai-providers/) funzionante. L'Agent richiede inoltre un modello che supporti il tool calling. | | `openssh-client` sul server del pannello | L'Agent esegue i comandi con il programma `ssh` nativo del pannello (`/usr/bin/ssh`). L'installer installa `openssh-client`; verifica con `ssh -V`. Senza di esso l'Agent segnala "ssh client is not installed on the panel server". | | Nessun gateway SSH separato | Nell'installazione predefinita viene utilizzato l'SSH integrato e il terminale web `ssh-proxy` **non** è necessario. Solo quando la funzione opzionale *web SSH* (`feature_ssh_web`) è stata abilitata e il servizio `ssh-proxy` è installato, l'Agent passa attraverso `ssh-proxy`. | | Rete | Il server del pannello deve raggiungere l'IP della VM sulla sua porta SSH (22 per impostazione predefinita). Verifica i firewall e i gruppi di sicurezza tra il pannello e la rete guest. | | VM | Di proprietà del cliente, **in esecuzione**, non bloccata, **Linux** (le VM Windows vengono rifiutate), con un indirizzo IP pubblico o raggiungibile. | | Credenziali SSH | L'utente e la password di accesso della VM memorizzati da NexCMP (salvati al momento della creazione della VM o del ripristino della password, crittografati), o la chiave di operazioni del pannello se installata. Se nessuno dei due è presente, l'Agent indica di non potersi connettere. | ## Prepara l'infrastruttura {#prepare-the-infrastructure} 1. Verifica il client SSH sul server del pannello: ```bash ssh -V sudo apt-get install -y openssh-client # only if missing ``` 2. Verifica che il server del pannello possa aprire una connessione SSH verso una VM guest: ```bash nc -vz 198.51.100.10 22 ``` Sostituisci l'indirizzo con l'IP di una VM di test. Se questo passaggio fallisce, risolvi prima il routing o il firewall. 3. Assicurati che il guest consenta l'accesso tramite password per l'utente memorizzato da NexCMP (alcune immagini cloud lo disabilitano) o che la chiave di operazioni del pannello sia installata sul guest. ## Collega in NexCMP {#connect-in-nexcmp} 1. Completa [AI provider](https://nexcmp.com/it/docs/ai/ai-providers/): modulo attivo, provider salvato, **Test connection** verde. 2. Nient'altro è configurato dal lato admin. L'interruttore del modulo fa apparire le voci **AI Agent** nel portale clienti. 3. Come cliente: apri **AI Agent**, seleziona un server in esecuzione e fai clic su **Choose server**. La pagina esegue prima un test SSH con un comando fisso e sicuro (senza chiamate AI) e mostra *SSH connected* o il motivo del fallimento. 4. Digita un'attività o scegli un avvio rapido (*Check system health*, *Install Docker*, *Install Nginx*, *Find recent errors*, *Security check*, *Free up disk space*). ## Come esegue i comandi {#how-it-runs-commands} - **Da dove:** dal server del pannello, con il client di sistema `ssh`, un comando non interattivo alla volta. La destinazione è sempre l'IP della VM **preso dal database**, mai dalla richiesta; è possibile raggiungere solo la VM in esecuzione e sbloccata del proprietario. - **Autenticazione:** la password memorizzata viene passata tramite un helper one-shot `SSH_ASKPASS` nell'ambiente di processo — non viene scritta su disco né inserita sulla riga di comando. Le chiavi host non vengono bloccate (le VM vengono reinstallate con nuove chiavi). L'output per comando è limitato a 200 KB e ciascun comando ha un limite di tempo (60 secondi). - **Ciclo dell'agente:** l'IA propone i comandi e legge gli output; un turno termina dopo al massimo **10 passaggi**. - **Modalità:** | Modalità | Comportamento | |---|---| | **Confirm** | Ogni comando attende **Run**. | | **Auto** | Solo i comandi che superano un severo elenco di autorizzazioni in sola lettura vengono eseguiti autonomamente (ad esempio `df -h`, `ps`, `journalctl`). Qualsiasi altra cosa, e tutto ciò che il parser non è in grado di analizzare con certezza (variabili, sostituzione di comandi, reindirizzamenti a file), attende **Run**. | - **Etichette di rischio:** i comandi che sovrascrivono o eliminano file, scrivono su dischi, modificano account o SSH Keys, inviano dati a un server esterno, aprono connessioni di rete grezze, eseguono codice offuscato, scaricano ed eseguono uno script, spengono o riavviano la macchina o raggiungono altri server mostrano sempre **Needs confirmation**, anche in modalità Auto. - **Output non attendibile:** l'output del comando viene mostrato al modello come dato non attendibile; le istruzioni in esso contenute non vengono seguite. ## Verifica {#verify} 1. Scegli una VM di test in esecuzione. La pagina mostra *SSH connected*. 2. Chiedi "Check CPU, RAM and disk". In modalità Auto i comandi in sola lettura vengono eseguiti e la risposta li riassume. 3. Chiedi "Install Nginx". Il comando di installazione viene visualizzato con **Run** e **Skip**; nulla viene eseguito finché non premi **Run**. 4. Il contatore in alto mostra il numero di chiamate IA utilizzate oggi (ad esempio `3/300`). ## Limiti e note {#limits-notes} - **Limite giornaliero:** 300 chiamate IA per cliente al giorno (UTC); si azzera alle 00:00 UTC. Quando viene esaurito, l'Agent risponde "Daily AI quota reached". - **Concorrenza:** al massimo 2 esecuzioni dell'Agent per cliente contemporaneamente; una sessione esegue un turno alla volta. - **Sessioni:** fino a 100 messaggi per sessione, 4,000 caratteri per messaggio. Una sessione appartiene a una sola VM; se la VM viene eliminata o trasferita, la vecchia sessione diventa di sola lettura. - **VM bloccata o arrestata, o Windows:** la VM viene mostrata come *Locked*, *Stopped*, *Windows* o *No address* e non può essere scelta. - **Impersonificazione:** un amministratore che impersona un cliente non può utilizzare le funzioni di credenziali dell'Agent (vedi [Log in as a customer](https://nexcmp.com/it/docs/customers/login-as/)). - **Responsabilità:** l'Agent può commettere errori. Il portale invita i clienti a esaminare i comandi prima di eseguirli. Specifica nei termini di servizio che i clienti sono responsabili dei comandi che approvano. - La disattivazione del modulo IA rimuove le voci dell'Agent e le rotte rispondono con 404 `module_disabled`. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | "client ssh non installato sul server del pannello (apt install openssh-client)" | Nessun binario `ssh` | `sudo apt-get install -y openssh-client`. | | "Impossibile accedere all'Agent" / `ssh: no saved credentials for this VM` | Nessuna password memorizzata e nessuna chiave di operations | Reimposta la password della VM nel portale in modo che venga salvata di nuovo, oppure installa la chiave di operations. | | "Il server non ha risposto in tempo" | Firewall, SSH non in ascolto, VM occupata | Testa `nc -vz 22` dal server del pannello; avvia `sshd` nella VM. | | "Impossibile raggiungere SSH su questo server" | Routing o gruppo di sicurezza | Consenti al server del pannello di raggiungere la VM sulla porta 22. | | "VM non in esecuzione" / "Accesso negato" | VM spenta, bloccata, eliminata o non appartenente al cliente | Avviala, sbloccala o scegline un'altra. | | "Non disponibile: N (arrestata, bloccata o Windows)" | Motivi elencati sopra | La VM deve essere Linux e in esecuzione. | | "Il gateway SSH è temporaneamente non disponibile" | Funzione Web SSH abilitata ma `ssh-proxy` non è attivo | Avvia `ssh-proxy` o disattiva la funzione Web SSH per utilizzare l'SSH integrato. | | "L'IA risponde troppo lentamente (più di 90 secondi)" | Provider lento | Usa un modello più veloce o un **Reasoning effort** inferiore. | | "Quota giornaliera AI esaurita" | 300 chiamate utilizzate | Attendi fino alle 00:00 UTC. | | "Questa sessione è ancora in esecuzione" | Un altro turno in corso | Attendi o premi **Stop**. | --- # REST API > **Dove nel portale:** Riferimento API su `https:///apidoc` (pubblico) e chiavi API su `/api-keys`. **Dove nell'amministrazione:** Customers › API keys (`/customers/apikeys`) elenca le chiavi create dai clienti. ## Descrizione {#what-it-does} Ogni azione che un cliente può compiere nel portale — elencare e gestire VM, leggere fatture, gestire chiavi SSH, Kubernetes, storage, ticket di supporto — è disponibile tramite un'API REST con controllo di versione sotto `https:///v1/`. I clienti la chiamano da script e CI con una **API key** con ambito limitato. La stessa API alimenta lo strumento a riga di comando [`cmp` command-line tool](https://nexcmp.com/it/docs/developers/cmp-cli/) e il server [MCP server](https://nexcmp.com/it/docs/developers/mcp/), e il riferimento viene generato dall'installazione in esecuzione, quindi elenca sempre esattamente le funzionalità che hai attivato. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Indirizzo HTTPS pubblico | L'API è servita sul tuo dominio principale (e sul dominio di ciascun rivenditore). | | Una chiave API | Creata dal cliente nel portale; vedi [API keys](https://nexcmp.com/it/docs/developers/api-keys/). | | Dipendenze | Nessuno. Gli endpoint di un modulo che non hai abilitato (ad esempio Kubernetes o Object Storage) sono nascosti dal riferimento e rifiutati. | ## Prepara l'infrastruttura {#prepare-the-infrastructure} Nulla da installare. Se un proxy inverso si trova davanti a NexCMP, inoltra `/v1/`, `/mcp`, `/cli/` e `/apidoc` al pannello (la configurazione nginx del programma di installazione lo fa già). ## Collega in NexCMP {#connect-in-nexcmp} ### Il riferimento interattivo {#the-interactive-reference} Apri `https://cloud.example.com/apidoc` (sostituisci l'host con il tuo dominio; i clienti di un rivenditore vedono il riferimento sul dominio del rivenditore, con il nome del rivenditore). Dispone di documentazione sugli endpoint con esempi di richiesta e risposta in curl, `cmp` CLI, JavaScript, Python e Go, una casella di ricerca (Ctrl o Cmd + K) e un pannello **Try it**. Try it invia richieste solo allo stesso sito, con una chiave incollata dal visitatore (mantenuta nella sessione del browser); è di sola lettura per impostazione predefinita e le chiamate di scrittura o a pagamento richiedono un interruttore aggiuntivo e una conferma. ### Download e documenti leggibili da macchina {#downloads-and-machine-readable-documents} Tutti sono pubblici, non richiedono chiavi e sono generati per sito: | URL | Contenuto | |---|---| | `/apidoc` | Riferimento interattivo. | | `/v1/public/openapi.json` | Documento OpenAPI 3.1. | | `/v1/public/openapi.yaml` | Stesso, YAML. | | `/v1/public/postman.json` | Raccolta Postman. | | `/v1/public/insomnia.json` | Esportazione Insomnia. | | `/v1/public/api.md` | Il riferimento come singolo file Markdown. | | `/v1/public/api-catalog` | JSON leggero: brand, URL di base, prefisso della chiave, ogni ambito ed ogni endpoint con metodo, percorso, ambito e se richiede un `Idempotency-Key`. | ```bash curl -s https://cloud.example.com/v1/public/api-catalog | python3 -m json.tool | head -40 curl -sO https://cloud.example.com/v1/public/openapi.yaml ``` In Postman seleziona **Import › Link** e incolla `https://cloud.example.com/v1/public/postman.json`. La pagina di riferimento offre anche client API a file singolo per JavaScript e Python. ### Autenticazione {#authentication} Invia la chiave nell'intestazione `Authorization`: ```bash curl -s https://cloud.example.com/v1/billing/wallet \ -H "Authorization: Bearer vk_XXXX" ``` - Le chiavi dei clienti iniziano con `vk_`. Le chiavi sono **vincolate al sito**: una chiave creata su `cloud.example.com` non funziona sul dominio di un rivenditore. - I token di sessione del browser (`pt_...`) sono riservati al portale; usa una chiave per l'automazione. - Gli **ambiti** della chiave determinano cosa può chiamare; un ambito mancante risponde con HTTP 403 `scope_required`. Vedi [API keys](https://nexcmp.com/it/docs/developers/api-keys/). - Verifica una chiave con `GET /v1/apikeys/self`: restituisce il nome, gli ambiti, la scadenza e il residuo del limite di velocità della chiave chiamante (ciascuna chiave può chiamarla). ### Esempi {#examples} ```bash # List virtual machines curl -s "https://cloud.example.com/v1/vm?page=1" -H "Authorization: Bearer vk_XXXX" # Start one (needs vm:write) curl -s -X POST https://cloud.example.com/v1/vm/3f2a1c9e-0000-4000-8000-000000000000/start \ -H "Authorization: Bearer vk_XXXX" # Create a VM (paid: needs vm:create and an Idempotency-Key) curl -s -X POST https://cloud.example.com/v1/vm \ -H "Authorization: Bearer vk_XXXX" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d @vm.json ``` Prendi i campi di richiesta esatti di ciascuna operazione da `/apidoc`. ### Errori {#errors} Ogni errore è in formato JSON con un `code` stabile e un `message` leggibile dall'utente: ```json {"error": {"code": "scope_required", "message": "Key lacks scope vm:write"}} ``` | HTTP | Tipico `code` | Significato | |---|---|---| | 401 | `unauthenticated`, `key_invalid`, `key_revoked`, `key_expired`, `key_ip_denied`, `site_mismatch`, `api_keys_disabled` | Chiave mancante o sconosciuta, revocata, scaduta, IP del chiamante al di fuori dell'elenco consentito della chiave, chiave proveniente da un altro sito o chiavi API disattivate. | | 403 | `scope_required`, `endpoint_not_public`, `account_blocked`, `quota_exceeded`, `impersonate_forbidden` | La chiave non ha l'ambito; l'endpoint non è disponibile per le chiavi; l'account è bloccato; è stata raggiunta una [quota](https://nexcmp.com/it/docs/billing/quotas/); azione non consentita in una sessione impersonata. | | 404 | `not_found` | Non trovato — restituito anche per risorse che appartengono a qualcun altro. | | 422 | `invalid_argument` | Errore di validazione (campo specificato nella risposta). | | 429 | `rate_limited` | Troppe richieste; attendi per `Retry-After`. | | 503 | `maintenance` | La modalità di manutenzione è attiva: le letture funzionano, le scritture vengono rifiutate. | ### Limiti di velocità {#rate-limits} | Limite | Predefinito | |---|---| | Per chiave | 120 richieste al minuto | | Per account (tutte le chiavi insieme) | 300 richieste al minuto | Ogni risposta contiene `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset`; un errore 429 aggiunge `Retry-After`. ### Idempotency {#idempotency} I comandi che comportano costi o non possono essere ripetuti (creazione, cambio piano, acquisto, eliminazione...) **richiedono** un'intestazione `Idempotency-Key` (qualsiasi stringa fino a 200 caratteri; un UUID funziona bene). Invia nuovamente la stessa chiave dopo un timeout e il server restituirà il risultato **originale** (con `Idempotency-Replayed: 1`) anziché ripetere l'operazione. Il riutilizzo di una chiave per un comando diverso risponde con 422; una richiesta ancora in corso risponde con 409/`Retry-After`. Senza l'intestazione, una chiamata a pagamento viene rifiutata. ## Verifica {#verify} 1. Crea una chiave con ambito `vm:read` nel portale (**API keys › Create key**). 2. Esegui: ```bash curl -i https://cloud.example.com/v1/apikeys/self -H "Authorization: Bearer vk_XXXX" ``` Ricevi HTTP 200 e le intestazioni relative al limite di velocità. 3. `curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"` elenca le macchine virtuali dell'account. Nel portale, la colonna **Last used** della chiave e il **Key usage log** mostrano le chiamate. ## Limiti e note {#limits-notes} - **Mai accessibili con una chiave:** ricariche, prelievi, modifica delle carte o ricarica automatica, modifica della password, e-mail o 2FA, eliminazione dell'account, creazione, modifica o revoca di altre chiavi. Queste operazioni richiedono una sessione browser attiva. - **Moduli nascosti:** il riferimento e il documento OpenAPI elencano solo le funzionalità abilitate su quel sito. - **Dimensione della risposta e paginazione:** gli endpoint di elenco sono paginati (`page`, `per_page`); leggi il documento OpenAPI per ogni endpoint. - **Tempo e denaro:** gli importi sono espressi in centesimi di USD, salvo diversa indicazione nel nome del campo. - **API di amministrazione:** la console di amministrazione ha la sua pagina **System › Admin › API** e chiavi di amministratore (`ofw_...`) per la gestione; sono separate dalle API per i clienti descritte qui. - **Controllo delle versioni:** il prefisso del percorso `/v1` è stabile; è possibile che vengano aggiunti nuovi campi alle risposte. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | 401 su una nuova chiave | Chiave proveniente da un altro dominio, scaduta o inserita con spazi | Crea la chiave sul dominio che chiami; verifica l'header `Authorization: Bearer vk_...`. | | 403 `scope_required` | Scope mancante | Modifica la chiave nel portale e aggiungi lo scope. | | 401 `key_ip_denied` o `site_mismatch` | Chiave limitata ad altri IP ("allowed IPs") o creata su un altro dominio | Aggiungi l'IP del tuo server agli IP consentiti della chiave oppure chiama il dominio su cui è stata creata. | | 404 su una VM esistente | La VM appartiene a un altro account | Usa una chiave del proprietario. | | 400/422 con richiesta di `Idempotency-Key` | Operazione a pagamento senza l'header | Aggiungi `Idempotency-Key: `. | | 429 | Limite superato | Riduci la frequenza; usa `Retry-After`. | | `/apidoc` mostra meno del previsto | Modulo disattivato | Attiva il modulo in License & updates. | --- # Chiavi API e ambiti {#api-keys-and-scopes} > **Dove nel portale:** API keys (`/api-keys`). **Dove nell'amministrazione:** Customers › Customers › API keys (`/customers/apikeys`). ## Descrizione {#what-it-does} Una **API key** consente a uno script, a un job CI, alla [`cmp` CLI](https://nexcmp.com/it/docs/developers/cmp-cli/) o a un assistente IA ([MCP](https://nexcmp.com/it/docs/developers/mcp/)) di chiamare la [REST API](https://nexcmp.com/it/docs/developers/api/) per conto di un cliente, con i soli permessi (**scopes**) concessi. Le chiavi dei clienti iniziano con `vk_`. Possono leggere e gestire i servizi ma **non** possono mai toccare denaro o l'account stesso. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Cliente | Una sessione di portale attiva (una chiave non può creare o modificare altre chiavi, e un amministratore che impersona un cliente non può farlo). | | Interruttore | Le chiavi API sono attive per impostazione predefinita. Se disattivate, le chiamate restituiscono 401 `api_keys_disabled`. | | Dipendenze | Gli ambiti di un prodotto compaiono solo quando quel prodotto è abilitato sul sito. | ## Crea una chiave (cliente) {#create-a-key-customer} 1. Accedi al portale e apri **API keys**. 2. Fai clic su **Create key**. 3. Compila il modulo: | Campo | Regola | |---|---| | **Nome chiave** | Obbligatorio, fino a 60 caratteri ("deploy server", "backup script"). | | **Cosa può fare questa chiave** | Seleziona gli ambiti necessari — almeno uno. Una chiave di sola lettura non dovrebbe avere ambiti di scrittura. Fai attenzione agli ambiti che comportano costi o eliminazione di dati. | | **Expiry** | Mai, 30 giorni, 90 giorni o 1 anno (l'API accetta da 1 a 3650 giorni). | | **Consenti chiamate solo da questi IP** | Un IP o intervallo CIDR per riga, fino a 20 (IPv4 o IPv6). Vuoto significa qualsiasi IP. Associa l'IP del tuo server quando possibile. | 4. Conferma il modulo. La chiave viene mostrata **una sola volta** in una finestra "Key created — shown ONCE". Copiala e fai clic su **I saved the key**. Viene memorizzato solo un hash SHA-256, quindi nemmeno un amministratore può leggerla di nuovo; se la perdi, revocala e creane una nuova. 5. Il portale mostra anche un comando `curl` pronto per testare la chiave. Una chiave appare come `vk_` seguita da una lunga stringa casuale. L'elenco mostra solo i primi caratteri (ad esempio `vk_a1b2c3d4`), gli ambiti, la scadenza, l'ultimo utilizzo, il conteggio delle richieste e lo stato (*Active*, *Expired*, *Revoked*). ### Modifica, revoca, audit {#edit-revoke-audit} - **Edit** modifica il nome, gli ambiti, gli IP consentiti e la scadenza. Non è consentito durante una sessione impersonata. - **Revoke** interrompe immediatamente la chiave e l'azione non può essere annullata. La riga viene conservata per mantenere disponibile il registro di utilizzo. - **Key usage log** mostra i comandi di scrittura e ogni errore degli ultimi 60 giorni: ora, richiesta, chiave, risultato e IP di origine. - Un account può contenere al massimo **10 chiavi attive** per impostazione predefinita. - Le chiavi create tramite l'accesso CLI o MCP compaiono sotto **Connected apps & devices** e possono essere revocate lì. ## Ambiti {#scopes} I nomi degli ambiti hanno la forma `area:action`. Quali vengono offerti dipende dai prodotti abilitati. | Ambito | Consente | |---|---| | `catalog:read` | Leggere i piani e il catalogo. | | `vm:read` | Leggere VM, metriche e fatture delle VM. | | `vm:write` | Azioni di alimentazione, modifiche minori, firewall, snapshot rapidi. | | `vm:create` | **Creare VM (comporta costi).** | | `vm:plan` | **Cambiare piano o ridimensionare (comporta costi).** | | `vm:destroy` | **Eliminare VM.** | | `vm:restore` | **Ripristinare una VM da uno snapshot (sovrascrive il disco).** | | `vm:console` | Aprire ticket per la console VNC. | | `sshkey:read`, `sshkey:write` | Leggere, aggiungere e rimuovere chiavi SSH. | | `volume:read`, `volume:write`, `volume:create`, `volume:destroy` | Volumi di dati (creazione e ampliamento comportano costi, la distruzione comporta la perdita di dati). | | `backup:read`, `backup:write`, `backup:restore` | Backups (il ripristino sovrascrive il disco). | | `billing:read` | Portafoglio, fatture, cronologia dei pagamenti — **solo lettura**. | | `bandwidth:buy` | **Acquistare un componente aggiuntivo di banda (comporta costi).** | | `account:read`, `account:write` | Profilo, panoramica, attività, notifiche; `account:write` segna solo le notifiche come lette. | | `apikey:read` | Elencare le chiavi dell'account e il registro di utilizzo (non è possibile creare, modificare o revocare). | | `apikey:self` | Implicito su ogni chiave: ispezionare la chiave chiamante (`GET /v1/apikeys/self`). | | `ticket:read`, `ticket:write` | Ticket di supporto. | | `aff:read`, `transfer:read` | Programma di affiliazione e trasferimenti di servizi — solo lettura. | | `k8s:read`, `k8s:write`, `k8s:create`, `k8s:scale`, `k8s:destroy`, `k8s:kubeconfig` | Kubernetes (creazione e ridimensionamento comportano costi; kubeconfig è cluster-admin). | | `vpc:read`, `vpc:write`, `vpc:create`, `vpc:destroy` | Private Cloud. | | `image:read`, `image:write` | Immagini OS e ISO (lo storage viene fatturato a ore). | | `s3:read`, `s3:write`, `s3:create`, `s3:destroy`, `s3:keys` | Object Storage (il segreto S3 viene mostrato una sola volta). | | `vpn:read`, `vpn:detail`, `vpn:write`, `vpn:create`, `vpn:destroy` | VPN e proxy IPv6 (i dettagli di connessione includono le password dei proxy). | | `dedicated:read`, `dedicated:write`, `dedicated:console`, `dedicated:create`, `dedicated:destroy` | Server dedicati (creazione di ordini dal portafoglio; la distruzione reinstalla il sistema operativo). | | `shield:read`, `shield:write`, `shield:agent` | DDoS Shield, solo quando quel modulo è abilitato. | Una chiamata al di fuori degli ambiti della chiave risponde con **403 `scope_required`**; un percorso che nessuna chiave può chiamare risponde con **403 `endpoint_not_public`**. ### Cosa una chiave non può mai fare {#what-a-key-can-never-do} Nessun ambito consente di: ricaricare o prelevare denaro, modificare carte o ricarica automatica, cambiare password, e-mail o 2FA, eliminare l'account, creare, modificare o revocare altre chiavi. Queste operazioni richiedono sempre un browser con sessione attiva. Nemmeno una chiave trafugata può accedere al denaro o all'account del cliente. ## Regole su cui fare affidamento {#rules-you-can-rely-on} | Regola | Dettaglio | |---|---| | Vincolata al sito | Una chiave funziona solo sul sito (dominio) in cui è stata creata. | | Limiti di velocità | Per chiave e per account: rispettivamente 120 e 300 richieste al minuto per impostazione predefinita. | | Idempotency | Le operazioni che comportano costi o non possono essere ripetute richiedono un'intestazione `Idempotency-Key`. | | Quote | Una chiave è soggetta alle stesse [quotas](https://nexcmp.com/it/docs/billing/quotas/) del cliente. | | Account bloccato | Le chiavi di un cliente bloccato smettono di funzionare (403 `account_blocked`). | | Audit | La revoca da parte di un amministratore viene registrata nel log di audit amministrativo. | ## Vista amministratore {#administrator-view} 1. Apri **Customers › API keys** (`/customers/apikeys`). La tabella mostra il nome della chiave e i primi caratteri, il proprietario, gli ambiti, lo stato, l'ultimo utilizzo (ora, conteggio richieste, IP) e la scadenza. 2. Filtra per sito se disponi di rivenditori. Cerca per nome, ID o inizio della chiave. 3. Fai clic su **Revoke** per interrompere una chiave attiva, oppure su **Log** per visualizzarne l'utilizzo. 4. Gli amministratori **visualizzano e revocano** le chiavi ma non possono leggerle o crearle per i clienti. ![Elenco amministrativo delle chiavi API dei clienti con ambiti, stato, ultimo utilizzo e pulsante Revoca](https://nexcmp.com/it/docs/images/developers/api-keys-02-admin.webp) ## Verifica {#verify} 1. Crea una chiave con il solo ambito `vm:read`. 2. `curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"` restituisce l'elenco delle VM. 3. `curl -s -X POST .../v1/vm//start -H "Authorization: Bearer vk_XXXX"` risponde con 403 `scope_required`. 4. Revoca la chiave; la prima chiamata ora risponde con 401 `key_revoked`. ## Limiti e note {#limits-notes} - La chiave non viene più mostrata. Trattala come una password e memorizzala in un secret manager o nel secret di una CI. - Preferisci una chiave per script, permessi minimi, una breve scadenza e un elenco di IP consentiti; esegui la rotazione creando una nuova chiave e revocando quella vecchia. - Le chiavi per l'accesso da dispositivo (CLI, MCP) hanno una durata predefinita di 90 giorni. - Risorse eliminate o trasferite non subiscono modifiche dalla revoca di una chiave. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | Errore `too_many_keys` (422) | Il limite di chiavi attive (10 per impostazione predefinita) è stato raggiunto | Revoca una chiave vecchia. | | Errore `invalid_argument`: nessun permesso scelto | Nessun permesso spuntato | Seleziona almeno un permesso. | | Errore `invalid_argument` sugli IP consentiti | Una voce non è un IP o un intervallo, la lunghezza del prefisso non è corretta o ci sono più di 20 voci | Un IP o CIDR per riga, ad esempio `203.0.113.0/24`. | | La creazione viene rifiutata durante l'impersonificazione | `impersonate_forbidden` | Chiedi al cliente di creare la chiave. | | 401 `key_expired` | Data di scadenza superata | Crea una nuova chiave. | | 401 `key_ip_denied` | IP del chiamante non incluso nell'elenco degli IP consentiti | Aggiungi l'IP o svuota l'elenco. | | 401 `api_keys_disabled` | Funzione disattivata | Rivolgiti al tuo amministratore (impostazione `api_keys_enabled`). | --- # Strumento a riga di comando `cmp` {#cmp-command-line-tool} > **Dove nel portale:** i comandi di installazione si trovano nella documentazione delle API (`https:///apidoc`, sezione Command-line interface). Approvazione di un accesso: `https:///link`. Dispositivi connessi: API keys (`/api-keys`) › Connected apps & devices. ## Descrizione {#what-it-does} `cmp` è un piccolo programma a riga di comando per i tuoi clienti (e per te) che trasforma **ogni operazione API in un comando**: `cmp vm list`, `cmp vm start `, `cmp billing invoice list`. Viene generato dal documento OpenAPI della **tua** installazione al momento del rilascio, in modo che i comandi corrispondano alle funzioni abilitate. Si tratta di un unico eseguibile statico per Linux, macOS e Windows (amd64 e arm64) che non richiede altro. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Server | Niente di extra. I pacchetti di rilascio si trovano all'interno della release di NexCMP e vengono serviti dal pannello a `https:///cli/`. | | Macchina del cliente | Linux, macOS o Windows (PowerShell 5.1+). `ssh-keygen` (OpenSSH 8.0+) serve solo per verificare la firma. | | Credenziali | Accesso via browser con codice monouso o una [API key](https://nexcmp.com/it/docs/developers/api-keys/). | | Rete | HTTPS verso il pannello. La CLI rifiuta di inviare una chiave su connessioni non protette `http://`, eccetto verso `localhost`. | ## Prepara l'infrastruttura {#prepare-the-infrastructure} Nulla. Il pannello distribuisce questi file da `/cli/` (senza alcuna compilazione o caricamento): | File | Scopo | |---|---| | `install.sh`, `install.ps1` | Programmi di installazione per Linux/macOS e Windows; contengono l'indirizzo del tuo pannello. | | `latest.json` | Versione corrente, elenco dei file, dimensioni, sha256. | | `v/cmp___.tar.gz` o `.zip` | I programmi: linux amd64/arm64, darwin amd64/arm64/universal, windows amd64/arm64. | | `v/SHA256SUMS`, `SHA256SUMS.sig` | Checksum e relativa firma ed25519. | | `cmp-cli.pub` | La chiave pubblica della release. | ## Installazione (cliente) {#install-customer} macOS e Linux: ```bash curl -fsSL https://cloud.example.com/cli/install.sh | sh ``` Windows PowerShell: ```powershell irm https://cloud.example.com/cli/install.ps1 | iex ``` L'installer seleziona il pacchetto per il sistema operativo e la CPU, scarica `SHA256SUMS` e la sua firma, verifica la firma con la chiave integrata nello script, verifica l'hash del pacchetto e installa `cmp` in `/usr/local/bin` (come root) o in `~/.local/bin`; su Windows in `%LOCALAPPDATA%\cmp\bin` (aggiunto alla variabile `PATH` dell'utente). Se un controllo fallisce, non viene installato nulla. | Variabile | Significato | |---|---| | `CMP_VERSION` | Installa questa versione invece della più recente. | | `CMP_INSTALL_DIR` | Cartella di installazione. | | `CMP_REQUIRE_SIGNATURE` | `1` = interrompe l'operazione se la firma non può essere verificata. | | `CMP_BASE_URL` | Base di download (per i mirror). | Download manuale e verifica: ```bash curl -fsSLO https://cloud.example.com/cli/latest.json sha256sum --check --ignore-missing SHA256SUMS ``` ![Sezione di riferimento API con il comando di installazione di cmp per macOS e Linux](https://nexcmp.com/it/docs/images/developers/cmp-cli-01-install.webp) ## Accesso {#log-in} ```bash cmp login ``` 1. La CLI stampa un **codice** monouso e un link (`https://cloud.example.com/link?code=WDJB-MJHT`), apre il browser e rimane in attesa. 2. Nel browser accedi al portale, controlla il nome del client, il dispositivo, l'IP e il paese, seleziona i permessi (scope) e scegli la durata della chiave (predefinita 90 giorni). I permessi che comportano costi o eliminano dati sono inizialmente deselezionati. Fai clic su approva. 3. La CLI riceve la **propria chiave**, separata da quelle create manualmente dal cliente, e la memorizza in `~/.config/cmp/config.json` (modalità `0600`; `%APPDATA%\cmp` su Windows). Viene visualizzata in **API keys › Connected apps & devices** e può essere revocata da lì. Il codice scade dopo 10 minuti. L'approvazione richiede una sessione autenticata reale nel portale con un'e-mail verificata — non un'altra chiave né una sessione impersonata. Flag utili: `--scopes vm:read,billing:read`, `--name "build server"`, `--no-browser`, `--profile`, `--api-url`. Per la CI o per server senza browser, usa una chiave del portale: ```bash printf %s "$KEY" | cmp login --with-token export CMP_TOKEN=vk_XXXX # nothing is written to disk cmp whoami ``` ## Uso dei comandi {#using-commands} ```text cmp [subgroup] [ ...] [flags] ``` - I parametri di percorso sono argomenti posizionali; i parametri di query e i campi del body diventano flag in kebab-case (`--start-port 443`). - `--data '{"a":1}'`, `--data @file.json` o `--data -` invia un intero body JSON; i flag ne sovrascrivono i campi. - `cmp help vm firewall add` (o `--help`) mostra i dettagli di qualsiasi comando. ```bash cmp catalog plans cmp vm list --state active --per-page 50 cmp vm get 3f2a1c9e-0000-4000-8000-000000000000 cmp vm start 3f2a1c9e-0000-4000-8000-000000000000 cmp vm firewall add 3f2a1c9e-... --protocol tcp --start-port 22 --cidr-list 203.0.113.0/24 cmp billing wallet cmp api GET /v1/vm --query page=2 # raw call to any endpoint ``` Comandi integrati: `login`, `logout`, `whoami`, `config`, `api`, `completion`, `version`, `update`, `help`. Tutto il resto proviene dal documento API. Flag globali: | Flag | Significato | |---|---| | `-o, --output json\|table\|yaml` | Formato. Predefinito `table` su terminale e `json` se reindirizzato tramite pipe. | | `--profile`, `--api-url` | Quale accesso memorizzato e quale sito. | | `-y, --yes` | Ignora la conferma per i comandi distruttivi o a pagamento. | | `--idempotency-key ` | Scegli la chiave di un comando a pagamento. | | `--retry ` | Su HTTP 429 attende `Retry-After` e riprova fino a n volte. | | `--timeout ` | Secondi di attesa per gli header di risposta (predefinito 60). | | `--debug` | Mostra lo scambio HTTP su stderr, con le chiavi mascherate. | I comandi che **addebitano il portafoglio o eliminano dati** richiedono una conferma e, se a pagamento, inviano un codice generato automaticamente `Idempotency-Key` (stampato su stderr, in modo da poter riprovare in sicurezza con `--idempotency-key`). Senza un terminale vengono rifiutati a meno che non venga fornito `--yes`. ### Codici di uscita {#exit-codes} | Codice | Significato | |---|---| | 0 | Successo | | 1 | Altro errore (rete, HTTP 4xx/5xx non elencati) | | 2 | Errore di utilizzo | | 3 | Non autorizzato (401/403) | | 4 | Non trovato (404) | | 5 | Limite di richieste superato (429) | | 6 | Conferma richiesta o rifiutata | | 130 | Interrotto | ### Profili e ambiente {#profiles-and-environment} `cmp config` elenca i profili; `cmp config use ` effettua il passaggio; i clienti di un rivenditore usano il proprio dominio: `cmp login --api-url https://shop.example.net --profile shop`. Precedenza: flag, ambiente, file di configurazione. Variabili: `CMP_TOKEN`, `CMP_PROFILE`, `CMP_API_URL`, `CMP_OUTPUT`, `CMP_CONFIG_DIR`, `CMP_ALLOW_HTTP`, `CMP_UPDATE_URL`. GitHub Actions: ```yaml - name: Install cmp run: | curl -fsSL https://cloud.example.com/cli/install.sh | CMP_INSTALL_DIR="$RUNNER_TEMP/bin" sh echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH" - name: List running VMs env: CMP_TOKEN: ${{ secrets.CMP_TOKEN }} # a read-only key run: cmp vm list -o json | jq -r '.items[] | select(.cs_state=="Running") | .hostname' ``` Completamento della shell: `cmp completion bash|zsh|fish|powershell`. ## Aggiornamento e disinstallazione {#update-and-uninstall} ```bash cmp version cmp update --check cmp update ``` `cmp update` scarica `latest.json`, `SHA256SUMS` e la firma, verifica la firma con la chiave pubblica **incorporata nel binario in esecuzione**, verifica l'hash del pacchetto e solo allora si sostituisce. Un downgrade richiede `--force`. Quando aggiorni NexCMP, il pannello fornisce la versione della CLI inclusa nella nuova versione. Per disinstallare, elimina il binario `cmp` e la directory di configurazione (`cmp config path` la mostra). Revoca la chiave in **API keys** se la macchina viene smarrita. ## Verifica {#verify} 1. `cmp version` stampa la versione e la versione del documento API. 2. `cmp login`, approva nel browser, quindi `cmp whoami` mostra il profilo e l'URL del tuo pannello. 3. `cmp vm list` restituisce le tue VM; `cmp vm list -o json | jq .` mostra il JSON grezzo. ## Limiti e note {#limits-notes} - L'elenco dei comandi dipende dalla tua build: i pacchetti vengono generati dal documento OpenAPI della tua installazione al momento della compilazione della release, quindi un prodotto disabilitato nella tua release non ha alcun comando. Usa `cmp api` per un percorso che la CLI non riconosce. - La CLI è distribuita sotto licenza MIT. - Ciascun pacchetto è firmato con una chiave ed25519; la chiave di firma è fissata all'interno del programma di installazione e del binario, non recuperata al momento dell'aggiornamento. - Le chiavi sono limitate per chiave e per account (vedi [REST API](https://nexcmp.com/it/docs/developers/api/#rate-limits)). ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | `curl .../cli/install.sh` restituisce 404 | La release sul server non ha alcuna cartella CLI, oppure l'host non è incluso nella licenza | Controlla `https:///cli/latest.json` e il dominio; aggiorna NexCMP. | | "impossibile verificare la firma" | `ssh-keygen` mancante o troppo vecchio | Installa OpenSSH 8.0+ oppure imposta `CMP_REQUIRE_SIGNATURE=0` solo se accetti il rischio. | | `cmp login` indica che il codice è scaduto | Sono trascorsi 10 minuti | Esegui di nuovo `cmp login`. | | Codice di uscita 3 | La chiave non ha un ambito, è scaduta o è stata revocata | `cmp whoami`; crea o riapprova con più ambiti. | | Codice di uscita 6 in uno script | Comando a pagamento o distruttivo senza un terminale | Aggiungi `--yes` (e il tuo `--idempotency-key`). | | "rifiuta di inviare una chiave su http" | URL API HTTP in chiaro | Usa `https://` oppure `CMP_ALLOW_HTTP=1` solo per un ambiente di test. | | Il browser apre il sito sbagliato | `--api-url` non impostato per un rivenditore | `cmp login --api-url https://`. | --- # Server MCP {#mcp-server} > **Dove nel portale:** API reference › Tools (`https:///apidoc`) mostra l'endpoint e gli snippet per il client; le chiavi vengono create in API keys (`/api-keys`). Non ci sono impostazioni nell'amministrazione: l'endpoint fa parte del pannello. ## Descrizione {#what-it-does} Il **Model Context Protocol (MCP)** consente a un assistente IA di richiamare strumenti. NexCMP offre un endpoint MCP su `https:///mcp`. Ogni operazione API pubblica diventa un singolo **strumento** (`vm_list`, `vm_start`, `billing_wallet`, ...), permettendo a un cliente di chiedere al proprio assistente "quali delle mie VM sono in esecuzione?" o "arresta la VM di staging". L'assistente agisce esclusivamente con la chiave API e i permessi del cliente stesso. ::: tip Configurare NexCMP con l'IA? Questa pagina riguarda l'endpoint MCP del **cliente** (`/mcp`). Per consentire a un assistente IA di configurare il tuo pannello come amministratore, consulta [Configure with AI](https://nexcmp.com/it/docs/configure-with-ai/mcp-admin/) (endpoint `/mcp/admin`, chiavi admin `ak_`). ::: ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Server | Nulla da installare: l'endpoint è gestito dal pannello ed è raggiungibile ovunque si trovi il pannello stesso. Il tuo reverse proxy deve inoltrare `/mcp` al pannello. | | Cliente | Una [API key](https://nexcmp.com/it/docs/developers/api-keys/) (`vk_...`) con gli ambiti (scopes) necessari all'assistente. | | Client | Un client MCP che supporta il trasporto **Streamable HTTP** e un'intestazione `Authorization` personalizzata: Claude Code, Claude Desktop (tramite il bridge `mcp-remote`), Cursor, VS Code con modalità agente Copilot e simili. | | Versioni del protocollo | 2025-11-25, 2025-06-18 e 2025-03-26. | ## Prepara l'infrastruttura {#prepare-the-infrastructure} Nulla, oltre ad assicurarsi che `https:///mcp` non sia bloccato da un firewall o da una regola di proxy. Un client MCP basato su browser proveniente da un'origine diversa viene rifiutato a meno che tale origine non sia consentita; i client da riga di comando e desktop non inviano alcuna intestazione `Origin` e funzionano così come sono. ## Connessione (lato cliente) {#connect-customer-side} 1. Crea una chiave API nel portale (**API keys › Create key**) limitandola solo agli ambiti che vuoi siano usati dall'assistente, con una breve scadenza e, se possibile, una restrizione IP. 2. Aggiungi il server al tuo client. Sostituisci `cloud.example.com` e la chiave. **Claude Code** ```bash claude mcp add --transport http cloud https://cloud.example.com/mcp \ --header "Authorization: Bearer vk_XXXX" ``` **Cursor** (`~/.cursor/mcp.json` o `.cursor/mcp.json`; imposta `CLOUD_API_KEY` nell'ambiente da cui si avvia Cursor): ```json { "mcpServers": { "cloud": { "url": "https://cloud.example.com/mcp", "headers": { "Authorization": "Bearer ${env:CLOUD_API_KEY}" } } } } ``` **Claude Desktop** (richiede Node.js 18+; `claude_desktop_config.json`), tramite il bridge `mcp-remote`: ```json { "mcpServers": { "cloud": { "command": "npx", "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp", "--header", "Authorization:${CLOUD_AUTH_HEADER}"], "env": { "CLOUD_AUTH_HEADER": "Bearer vk_XXXX" } } } } ``` Scrivi l'intestazione senza alcuno spazio dopo i due punti e inserisci l'intero valore nella variabile d'ambiente, come indicato sopra. 3. Riavvia il client e chiedigli di elencare i tuoi strumenti. Verifica la connessione senza un client: ```bash curl -s https://cloud.example.com/mcp \ -H "Authorization: Bearer vk_XXXX" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` ## Come funziona {#how-it-works} | Elemento | Dettaglio | |---|---| | Endpoint | `POST /mcp` con un messaggio JSON-RPC 2.0; la risposta è `application/json`. `GET /mcp` risponde con 405 (nessun flusso da server a client); `DELETE /mcp` termina la sessione. | | Autenticazione | Solo `Authorization: Bearer vk_...` (i token di sessione, i cookie e le chiavi di amministrazione vengono rifiutati con un errore 401 e un'intestazione `WWW-Authenticate: Bearer`). | | Sessione | `Mcp-Session-Id` viene rilasciato da `initialize`, associato a tale chiave e ha una validità di 24 ore; al massimo 16 sessioni per chiave. | | Strumenti | Una per ogni operazione API pubblica visibile alla chiave. Il nome dello strumento corrisponde al comando CLI con `_` al posto di spazi e trattini (`vm firewall add` diventa `vm_firewall_add`) e coincide con il campo `operationId` di OpenAPI. Uno strumento viene elencato solo quando la chiave dispone del relativo ambito e il modulo è abilitato. | | Funzionalità | Solo strumenti (nessuna risorsa o prompt). | | Dimensione | Corpo della richiesta fino a 1 MB; testo del risultato dello strumento fino a circa 100 KB (il resto viene troncato con una nota); una chiamata richiede al massimo 55 secondi. | ### Regole di sicurezza {#safety-rules} - **Stesso controllo di REST.** Ogni `tools/call` passa attraverso la pipeline di richieste del pannello: vengono applicati scope, sito, restrizioni IP, rate limit, idempotenza, controlli di proprietà (404 per le risorse di altri) e quote. MCP non può concedere nulla che la chiave non possieda. - **Conferma.** Gli strumenti che comportano costi, eliminano dati o restituiscono credenziali (ticket per la console, kubeconfig, segreti S3 o SSH, reset delle password, nuove chiavi) richiedono l'argomento `confirm: true`. La descrizione dello strumento indica all'assistente di passarlo solo dopo l'approvazione dell'utente, in modo che un'istruzione nascosta in una pagina web o in un log non possa attivarla autonomamente. - **Idempotenza.** Gli strumenti a pagamento accettano `idempotency_key`; se omesso, viene ricavata una chiave stabile dal nome dello strumento e dagli argomenti, impedendo che un tentativo identico venga addebitato due volte. - **Non esposti come strumenti:** endpoint di streaming (la chat dell'AI Agent), ticket WebSocket temporanei per SSH o console, download binari e gli endpoint dell'app VPN (`/v1/ext/*`). - **Mai possibile:** l'API non consente mai ricariche, modifiche della password, eliminazione dell'account o creazione di chiavi, quindi nessun assistente può eseguirli. ### Limiti {#limits} | Limite | Predefinito | |---|---| | Chiamate agli strumenti per chiave | 60 al minuto | | Richieste MCP per chiave | 240 al minuto | | Oltre ai normali limiti di chiave e account | Vedi [REST API](https://nexcmp.com/it/docs/developers/api/#rate-limits) | Oltre il limite, l'endpoint risponde con HTTP 429, un errore JSON-RPC e `Retry-After`. ## Verifica {#verify} 1. Il comando `curl` sopra restituisce un risultato JSON-RPC con un elenco `tools`. Vengono visualizzati solo gli strumenti corrispondenti agli scope della chiave. 2. Nel tuo client chiedi "elenca le mie VM": l'assistente chiama `vm_list` e mostra il risultato. 3. Nel portale, il timestamp **Last used** della chiave viene aggiornato e le chiamate in scrittura compaiono nel **Key usage log**. ## Limiti e note {#limits-notes} - **Accesso tramite browser (OAuth).** La pagina di riferimento descrive anche l'accesso tramite browser per i client che supportano MCP OAuth. In un'installazione di NexCMP, il metodo supportato e testato è la chiave API (o `cmp login` per la CLI). - **I siti dei rivenditori** non mostrano la sezione MCP; i loro clienti utilizzano il dominio del rivenditore per le API. - **Minimo privilegio.** Crea una chiave dedicata per ciascun assistente assegnando inizialmente solo gli scope in lettura; aggiungi gli scope in scrittura solo quando necessario. - Revoca la chiave in **API keys** per interrompere immediatamente l'accesso dell'assistente. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | 401 con `WWW-Authenticate: Bearer` | Nessuna chiave, chiave errata o token di sessione | Invia `Authorization: Bearer vk_...`. | | 403 su `Origin` | Una pagina del browser su un'altra origine | Usa un client desktop o CLI oppure chiedi all'amministratore di autorizzare l'origine (`mcp_allowed_origins`). | | 404 su una richiesta con `Mcp-Session-Id` | La sessione appartiene a un'altra chiave oppure è scaduta | Esegui di nuovo `initialize`. | | 405 su `GET /mcp` | Previsto: il server non dispone di uno stream di eventi | Usa solo POST (i client lo fanno automaticamente). | | L'elenco degli strumenti è breve | Scope della chiave o moduli | Aggiungi gli scope alla chiave; abilita il modulo. | | Lo strumento risponde che è necessario `confirm: true` | Strumento a pagamento, di eliminazione o sensibile | L'assistente deve impostare `confirm` dopo la tua approvazione. | | 429 | Rate limit di MCP o della chiave | Attendi `Retry-After`. | | Il client non riesce a connettersi con un'intestazione | Client privo di supporto per intestazioni personalizzate | Usa il bridge `mcp-remote`. | --- # Configura con l'IA {#configure-with-ai} > **Dove nell'admin:** AI Chat (`/agent`) e System › Settings › API & AI agents (`/agent/keys`). Tutto in queste pagine è riservato agli amministratori. ## Descrizione {#what-it-does} A partire da NexCMP 1.4.0 puoi chiedere a un assistente IA di configurare il pannello per te: connettere Proxmox VE o CloudStack, creare una zona, generare una tabella dei piani dai tuoi costi, configurare email, pagamenti e branding, trovare un cliente o esportare l'intera configurazione. L'assistente opera tramite un set fisso di **strumenti di amministrazione**. Non ottiene mai una shell, non legge file sul server e non vede mai password o API key memorizzate. Usalo quando desideri una prima configurazione in pochi minuti invece di cliccare su una dozzina di pagine, o quando gestisci più installazioni e vuoi mantenere la loro configurazione in un file. ## Tre modi per usarlo {#three-ways-to-use-it} | Modalità | Chi parla con l'IA | Dove viene eseguito | Inizia qui | |---|---|---|---| | **AI Chat nell'admin** | Tu, nell'admin di NexCMP | La sorgente IA che scegli: una API key di OpenAI, Anthropic, Gemini o OpenRouter, il provider IA del tuo pannello o una CLI IA ufficiale a cui hai effettuato l'accesso | [AI Chat nell'admin](https://nexcmp.com/it/docs/configure-with-ai/ai-chat-in-admin/) | | **Il tuo client IA tramite MCP** | Tu, in Claude Code, Codex CLI, Gemini CLI, Cursor, Claude Desktop, claude.ai o ChatGPT | Sul tuo computer o nell'app del fornitore, connesso al tuo pannello su `https://cloud.example.com/mcp/admin` | [Connect an AI client](https://nexcmp.com/it/docs/configure-with-ai/mcp-admin/) | | **Configurazione come codice** | Tu o uno script | Un file YAML e il comando `nexcmp config` sul server (o la pagina Import/Export) | [Configuration as code](https://nexcmp.com/it/docs/configure-with-ai/config-as-code/) | Tutti e tre richiamano gli stessi strumenti e passano attraverso lo stesso livello di sicurezza, quindi puoi combinarli: abbozza una configurazione con un assistente, esportala come YAML, esaminala nel tuo editor e applicala in seguito. ## Modello di sicurezza {#safety-model} | Regola | Cosa significa per te | |---|---| | **Ambiti** | Una chiave o una connessione è limitata agli ambiti che spunti (`admin:read`, `catalog:write`, `infra:write`, `billing:write`, `customers:write`, `settings:write`, `ai:write`, `secrets:write`). Senza un ambito la chiamata viene rifiutata. Vedi [Admin API keys](https://nexcmp.com/it/docs/configure-with-ai/admin-api-keys/#scopes). | | **Expiry** | Ogni chiave e connessione scade: da 1 a 90 giorni per le chiavi che crei, 30 giorni per impostazione predefinita. I token di accesso OAuth durano un'ora. | | **Restrizione IP e limite di frequenza** | Una chiave può essere limitata agli intervalli IP e a un numero di chiamate al minuto (120 per impostazione predefinita). | | **Conferma in due passaggi** | Le azioni che muovono denaro, eliminano dati, modificano le credenziali di pagamento o la sicurezza di accesso restituiscono prima un'anteprima e non fanno nulla finché non approvi. All'interno di AI Chat ogni modifica è una scheda di conferma che premi tu stesso. | | **Azioni che le chiavi non possono mai compiere** | Creare amministratori, modificare la 2FA, creare o revocare chiavi, accedere come cliente, effettuare backup, ripristinare o aggiornare il pannello e simili. Queste operazioni richiedono la tua presenza nell'admin. | | **Registro attività** | Ogni chiamata, consentita o rifiutata, viene registrata con la chiave, il client, lo strumento, l'IP e il risultato. Vedi System › Settings › API & AI agents › Activity. | | **I dati riservati non vengono mai restituiti** | Password, chiavi API e token possono essere impostati ma non letti. Le risposte visualizzate dall'IA li mostrano mascherati. | | **Le installazioni demo sono di sola lettura** | In un pannello demo ogni operazione di scrittura viene rifiutata con `demo_read_only`. | ::: important Cosa può leggere l'IA Con `admin:read` un assistente può leggere nomi di clienti, indirizzi e-mail, saldi e registri di fatturazione. Quando utilizzi una sorgente di IA eseguita presso un fornitore (OpenAI, Anthropic, Google, OpenRouter), tali dati vengono inviati a tale fornitore per rispondere alla tua domanda. Assegna a un assistente il set di ambiti minimo necessario e scegli una sorgente di cui ti fidi per questi dati. ::: ## Avvio rapido {#quick-start} 1. Accedi all'area amministrativa e apri **AI Chat**. Se non è ancora connessa alcuna sorgente di IA, apri **System › Settings › AI accounts** e connettine una (vedi [AI accounts and subscriptions](https://nexcmp.com/it/docs/configure-with-ai/ai-accounts-and-subscriptions/)). 2. Digita "Check my setup progress" e premi Invio. L'assistente legge la [Setup progress checklist](https://nexcmp.com/it/docs/configure-with-ai/setup-checklist/) e ti indica cosa manca. 3. Chiedigli di eseguire il passaggio successivo. Esamina ogni scheda di conferma e premi **Confirm** per applicarla. Per una prima panoramica delle domande da porre, vedi [Example prompts](https://nexcmp.com/it/docs/configure-with-ai/example-prompts/). ![Pagina AI Chat con una conversazione, il risultato di uno strumento e una scheda di conferma](https://nexcmp.com/it/docs/images/configure-with-ai/overview-01-ai-chat.webp) ## Limiti e note {#limits-notes} - **Demo e sola lettura.** Le pagine sono visibili su un pannello demo, ma non è possibile salvare nulla. - **Nessuna shell.** L'assistente può richiamare solo gli strumenti di amministrazione elencati in [Connect an AI client](https://nexcmp.com/it/docs/configure-with-ai/mcp-admin/#tools). Non può eseguire comandi sul server. - **I moduli di rete e routing** (BGP, XDP, interfacce, NAT e simili) sono di sola lettura per l'IA, mentre le aree sensibili come account amministrativi, backup e aggiornamenti sono interamente precluse alle chiavi. - **I prezzi** sono in USD: i prezzi dei piani in dollari all'ora, i saldi in centesimi. - **Costo.** Le risposte dell'IA vengono pagate alla sorgente di IA connessa (utilizzo API o abbonamento personale). In AI Chat puoi impostare un limite di spesa giornaliero. Per il modello di licenza di NexCMP vedi https://nexcmp.com/pricing. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | AI Chat indica che non è connessa alcuna sorgente di IA | Nessuna sorgente configurata per il tuo account amministratore | Apri System › Settings › AI accounts e connettine una. | | Un assistente risponde `insufficient_scope` | La chiave o la connessione non dispone dell'ambito per quello strumento | Crea una chiave con l'ambito necessario oppure ricollegati e selezionala nella schermata di consenso. Vedi [Admin API keys](https://nexcmp.com/it/docs/configure-with-ai/admin-api-keys/#errors). | | Ogni modifica mostra una scheda di conferma | Comportamento previsto in AI Chat | Premi **Confirm** per applicare o **Reject** per annullare. | | Le scritture falliscono con `demo_read_only` | Il pannello è in modalità demo | Utilizza un'installazione non demo. | --- # AI Chat nell'amministrazione {#ai-chat-in-the-admin} > **Dove si trova nell'amministrazione:** AI Chat (`/agent`, una voce di menu dedicata) e il pulsante mobile **Ask AI** su ogni pagina di amministrazione. Le sorgenti delle risposte vengono configurate in System › Settings › AI accounts (`/agent/accounts`). ## Descrizione {#what-it-does} AI Chat è un assistente integrato nell'amministrazione. Descrivi ciò che desideri ("connetti il mio cluster Proxmox", "configura l'email"), l'assistente legge lo stato corrente tramite gli strumenti di amministrazione, propone le modifiche e le mostra ciascuna come **scheda di conferma**. Nulla viene applicato finché non premi **Confirm**. Il pannello **Ask AI** corrisponde alla stessa chat in un pannello laterale ridotto, consentendoti di fare domande mentre consulti una pagina. Pulsanti come **Do it for me** (nella [Setup progress checklist](https://nexcmp.com/it/docs/configure-with-ai/setup-checklist/) e negli elenchi vuoti) lo aprono con una domanda predefinita. Non si tratta di [AI Chat](https://nexcmp.com/it/docs/ai/ai-chat/) e [AI Agent](https://nexcmp.com/it/docs/ai/ai-agent/) rivolti ai clienti, che servono i tuoi utenti. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Ruolo | Un amministratore autenticato. Chat, chiavi e preferenze appartengono al tuo account amministratore; gli altri amministratori non possono vederli. | | Una fonte di risposta | Almeno una connessa: una chiave API, un accesso, il provider IA del pannello stesso o una CLI IA a cui hai effettuato l'accesso. Vedi [AI accounts and subscriptions](https://nexcmp.com/it/docs/configure-with-ai/ai-accounts-and-subscriptions/). | | Demo | Su un pannello demo è possibile leggere le vecchie chat ma non inviare messaggi. | ## Scegli da dove provengono le risposte {#choose-where-answers-come-from} Scegli la fonte nel selettore sotto l'input (elenca le fonti che hai connesso). **System › Settings › AI accounts** ti permette anche di impostare una fonte predefinita, un modello predefinito e il limite giornaliero. | Source | Come connetterla | Note | |---|---|---| | OpenAI (modelli ChatGPT) | Incolla una chiave API da platform.openai.com | Fatturato da OpenAI in base all'utilizzo. | | Anthropic (Claude) | Incolla una chiave API da console.anthropic.com | Fatturato da Anthropic in base all'utilizzo. | | Google Gemini | Incolla una chiave API da aistudio.google.com, oppure **Sign in with Google** | L'accesso con Google richiede un client OAuth che **tu** crei nel tuo progetto Google Cloud. | | OpenRouter | Incolla una chiave, oppure **Sign in with OpenRouter** | Un account per molti modelli. | | Provider IA del pannello | Già impostato in System › Settings › AI provider | Lo stesso provider utilizzato da AI Chat dei tuoi clienti. [AI provider](https://nexcmp.com/it/docs/ai/ai-providers/). | | Abbonamento Claude, ChatGPT o Gemini | CLI ufficiale installata e con accesso effettuato sul server del pannello | Vedi [AI accounts and subscriptions](https://nexcmp.com/it/docs/configure-with-ai/ai-accounts-and-subscriptions/). | Le chiavi che incollascish sono memorizzate in modo crittografato solo per il tuo account amministratore. Non vengono mai mostrate di nuovo e nessun altro amministratore può decifrarle. ## Usa la chat {#use-the-chat} 1. Apri **AI Chat** (o fai clic su **Ask AI**). 2. Fai clic su **New chat** o aprine una precedente dall'elenco a sinistra. 3. Digita la tua richiesta e premi Invio (Shift+Enter avvia una nuova riga). Puoi allegare immagini o file di testo (fino a 4 per messaggio, 3 MB ciascuno) per mostrare un errore o incollare un documento. 4. Osserva la risposta arrivare in streaming. Ogni strumento richiamato dall'assistente appare come una scheda comprimibile con il nome dello strumento, i suoi argomenti e un breve risultato. 5. Premi **Stop** per annullare una risposta in corso. È attiva una sola risposta alla volta per amministratore. ![AI Chat con l'elenco delle conversazioni, una risposta contenente schede di strumenti e l'input con selettore di origine e campo Secret](https://nexcmp.com/it/docs/images/configure-with-ai/ai-chat-in-admin-01-chat.webp) Per ogni messaggio vengono eseguiti fino a 10 cicli di strumenti. L'assistente ricorda gli ultimi 30 messaggi della chat. I risultati degli strumenti vengono passati al modello contrassegnati come dati, non come istruzioni. ## Schede di conferma {#confirmation-cards} In AI Chat **ogni modifica è una scheda**, non solo le azioni finanziarie. L'assistente propone; tu decidi. Una scheda mostra: - Un titolo che spiega perché richiede attenzione, ad esempio "changes a customer balance". - La chiamata: metodo e percorso. - Una tabella dei campi che cambiano: il valore attuale e quello nuovo. I valori segreti appaiono come `••••`. - Un conto alla rovescia (le schede scadono dopo 5 minuti). - **Confirm** e **Reject**. **Confirm** fa sì che il pannello stesso applichi la modifica, quindi comunica all'assistente cosa è successo. L'assistente non può premere il pulsante, non può approvare tramite l'API e riceve l'istruzione di non dichiarare mai che una modifica è stata applicata prima che sia confermata. Se ricarichi la pagina, le schede ancora valide compaiono di nuovo.compaiono anche in cima a **System › Settings › API & AI agents** sotto "Waiting for your confirmation". ![Scheda di conferma che mostra la modifica del saldo, il conto alla rovescia e i pulsanti Confirm e Reject](https://nexcmp.com/it/docs/images/configure-with-ai/ai-chat-in-admin-02-confirm.webp) ## Segreti {#secrets} Password e chiavi API non devono transitare nel testo della chat. Usa il campo **Secret** (icona del lucchetto) accanto all'input: 1. Fai clic sull'icona del lucchetto e inserisci un **nome** (lettere, cifre e trattino basso, ad esempio `smtp_password`) e il **valore**. 2. Nel messaggio fai riferimento al nome: "use the secret smtp_password as the SMTP password". 3. L'assistente vede sempre e solo un segnaposto che rappresenta il segreto, scritto in questo modo: ```text {{secret:smtp_password}} ``` Il pannello lo sostituisce con il valore reale nel momento in cui esegue lo strumento. Il valore non viene salvato nella cronologia della chat e non viene inviato all'origine AI. Se incolli per errore nel messaggio qualcosa che sembra una chiave, il pannello la sposta nello stesso archivio protetto e la maschera nella cronologia, ma consideralo come una rete di sicurezza, non come un metodo. I segreti rimangono solo nella memoria del pannello, per la conversazione in cui sono stati inseriti e fino a un'ora dopo l'ultimo messaggio; il riavvio del pannello li cancella anche. Inseriscili di nuovo se l'assistente lo richiede. L'impostazione di un segreto richiede anche il permesso `secrets:write` per la sessione di chat (vedi sotto). ## Permessi della chat {#permissions-of-the-chat} Ogni messaggio viene eseguito con una chiave temporanea che esiste per la durata della risposta (al massimo 15 minuti), funziona solo dal server del pannello e può essere utilizzata solo tramite le schede di conferma. I suoi ambiti (scopes) sono quelli spuntati in **System › Settings › AI accounts › Chat session permissions**. `admin:read` è sempre attivo. Tutti gli ambiti tranne `secrets:write` sono attivi per impostazione predefinita; spunta `secrets:write` se vuoi che l'assistente possa impostare password e chiavi (tramite il campo Secret). Su un pannello demo la chat è di sola lettura. ## Limite di spesa giornaliero {#daily-spending-cap} AI Chat somma il costo stimato delle risposte provenienti dalle origini API. Il limite predefinito è **5 USD per amministratore al giorno**. Imposta un importo diverso (0 significa nessun limite) in **AI accounts › Defaults for AI Chat**. La pagina mostra "used today". Quando viene raggiunto il limite, la chat rifiuta i nuovi messaggi (`daily_cap`) fino al giorno successivo o finché non aumenti il limite. Le origini che sono abbonamenti AI CLI non vengono conteggiate, poiché sono fatturate dal tuo abbonamento. ## Verifica {#verify} 1. In **AI accounts** fai clic su **Test** sull'origine. Risponde con il nome del modello e il tempo in millisecondi. 2. In AI Chat chiedi "Check my setup progress". La risposta elenca i passaggi della [checklist](https://nexcmp.com/it/docs/configure-with-ai/setup-checklist/) e compare una `setup_checklist` scheda strumento. 3. Chiedi una piccola modifica, ad esempio "Set the brand name to Example Cloud". Viene visualizzata una scheda di conferma; premi **Confirm** e controlla la pagina Branding. 4. **API & AI agents › Activity** elenca le chiamate con il canale `chat`. ## Limiti e note {#limits-notes} - L'assistente non ha una shell e non può leggere i file sul server. Chiama solo gli [admin tools](https://nexcmp.com/it/docs/configure-with-ai/mcp-admin/#tools). - Le modifiche che le chiavi non possono mai fare ([list](https://nexcmp.com/it/docs/configure-with-ai/admin-api-keys/#what-a-key-can-never-do)) non possono essere fatte neanche da AI Chat. - Controlla il lavoro del modello. Una scheda di conferma mostra esattamente cosa verrà inviato; legalo con attenzione, soprattutto prezzi e importi. - Le risposte API vengono fatturate dal fornitore di IA. Il limite è una stima; imposta un limite di spesa anche presso il fornitore. - Una risposta CLI si interrompe dopo 5 minuti. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | "Raggiunto il limite di spesa IA odierno" (`daily_cap`) | Hai raggiunto il limite giornaliero | Aumentalo negli account IA o attendi domani. | | "È già in esecuzione un'altra risposta - attendi o premi Stop" (`busy`) | Una sola risposta alla volta per amministratore | Premi **Stop** o attendi. | | La sorgente non compare nel selettore | Non è connessa oppure (Claude CLI) l'interruttore "I understand" è disattivato | Connettila negli account IA. | | "non sembra una chiave API" | La chiave incollata contiene spazi o è troppo lunga | Incolla solo la chiave. | | Il test non è riuscito | Chiave errata, credito esaurito o fornitore non disponibile | Verifica la chiave e la fatturazione presso il fornitore. | | L'assistente indica di non poter eseguire un'operazione | La sessione di chat non dispone dei permessi o l'azione è preclusa all'IA | Spunta i permessi negli account IA o eseguila nell'amministrazione. | | Una scheda indica che è scaduta | Sono trascorri più di 5 minuti | Chiedi all'assistente di proporre nuovamente la modifica. | | La sorgente CLI segnala "usage limit" o "not logged in" | Il limite del tuo abbonamento o la sessione | Accedi nuovamente o attendi; vedi [AI accounts and subscriptions](https://nexcmp.com/it/docs/configure-with-ai/ai-accounts-and-subscriptions/). | --- # Account e abbonamenti IA {#ai-accounts-and-subscriptions} > **Dove si trova nell'amministrazione:** System › Settings › AI accounts (`/agent/accounts`), schede **Accounts** e **Use your own AI subscription**. Il terminale opzionale è AI Console (`/agent/console`), che appare sotto AI Chat solo quando è attivo. ## Descrizione {#what-it-does} AI Chat ha bisogno di qualcosa con cui rispondere. Questa pagina ti permette di connettere tale sorgente per il tuo account amministratore: - **Sorgenti API**: OpenAI, Anthropic (Claude), Google Gemini e OpenRouter, con una chiave API o un accesso. - **Il provider IA del pannello**, se ne hai già configurato uno in System › Settings › AI provider. - **Il tuo abbonamento IA** (Claude, ChatGPT, Gemini) tramite lo **strumento a riga di comando ufficiale** del fornitore, sul server del pannello o sul tuo computer. Tutto ciò che connetti appartiene al tuo account amministratore. Chiavi e token sono memorizzati crittografati solo per te; nessun altro amministratore può usarli. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Ruolo | Un amministratore con sessione attiva. In un pannello demo non è possibile connettere o rimuovere nulla. | | Sorgenti API | Un account e una chiave API presso il fornitore (la scheda include un link **Get API key** che apre la pagina del fornitore). | | CLI sul server del pannello | AI Console attivata (vedi sotto), traffico HTTPS in uscita dal server verso il fornitore, `nodejs.org` e il registro npm, e **2 GB di RAM o più** (una CLI richiede circa 1 GB libero durante l'esecuzione; il programma di installazione avvisa sotto i 2 GB). Viene usato Node.js 20 o superiore se presente, altrimenti il programma di installazione scarica Node.js 22 verificando il checksum. | | CLI sul tuo computer | Node.js 20 o superiore per installare la CLI e il tuo abbonamento. | ## Connetti una sorgente API {#connect-an-api-source} 1. Apri **System › Settings › AI accounts** e rimani su **Accounts**. 2. Sulla card della sorgente fai clic su **Connect**. La pagina delle chiavi del fornitore si apre in una nuova scheda; crea una chiave lì. 3. Incolla la chiave nel campo e salva. La card mostra lo stato connesso con gli ultimi quattro caratteri. 4. Scegli il **default model** se ne desideri uno diverso, quindi clicca su **Test**. Un buon risultato recita "Connected - example-model, 850 ms". ![Pagina degli account AI con le schede delle sorgenti API, una scheda OpenAI connessa e la scheda del provider Panel AI](https://nexcmp.com/it/docs/images/configure-with-ai/ai-accounts-and-subscriptions-01-accounts.webp) | Source | Alternativa di accesso | |---|---| | OpenRouter | **Sign in with OpenRouter** apre OpenRouter in un popup o in una scheda; autorizza e tornerai a questa pagina con la connessione attiva. | | Google Gemini | **Sign in with Google** compare dopo il salvataggio, sotto **Set up Google sign-in (optional)** sulla scheda, di un client OAuth creato nel **tuo** progetto Google Cloud (ID client che termina con `.apps.googleusercontent.com`, più la relativa chiave segreta). NexCMP non include alcun client Google condiviso. | | Provider IA del pannello | Utilizza il provider già configurato in System › Settings › AI provider ([AI provider](https://nexcmp.com/it/docs/ai/ai-providers/)). Nulla da incollare. | Per disconnettere una sorgente, clicca su **Remove** sulla sua scheda. Verrà eliminata la chiave memorizzata per il tuo account. ### Valori predefiniti, limite giornaliero e autorizzazioni {#defaults-daily-cap-and-permissions} In fondo alla scheda **Accounts**, **Defaults for AI Chat** presenta tre impostazioni: | Impostazione | Significato | |---|---| | Sorgente e modello predefiniti | Il valore utilizzato per le nuove chat. Puoi comunque cambiare la sorgente per singolo messaggio. | | Limite di spesa giornaliero (USD, 0 = nessun limite) | Predefinito 5. La pagina mostra "used today". Vedi [AI Chat in the admin](https://nexcmp.com/it/docs/configure-with-ai/ai-chat-in-admin/#daily-spending-cap). | | Autorizzazioni sessione chat | Gli ambiti che l'assistente può utilizzare. `admin:read` è sempre attivo; `secrets:write` è disattivato per impostazione predefinita. Vedi [Admin API keys](https://nexcmp.com/it/docs/configure-with-ai/admin-api-keys/#scopes). | Clicca su **Save defaults**. ## Usa il tuo abbonamento AI {#use-your-own-ai-subscription} Puoi pilotare NexCMP con un piano Claude, ChatGPT o Gemini per cui paghi già, senza una chiave API separata. Ci sono due modi. ### Modo 1 (consigliato): la CLI sul tuo computer {#way-1-recommended-the-cli-on-your-own-computer} Usi lo strumento proprietario del fornitore sul tuo computer ed effettui l'accesso con il tuo account nel modo consueto del fornitore. NexCMP riceve solo chiamate MCP firmate con una chiave a breve scadenza. Apri **AI accounts › Use your own AI subscription**; mostra tre passaggi per strumento. 1. Clicca su **Create a 7-day key** e scegli il livello: **Read only** (`admin:read`) o **Read + configuration** (`admin:read`, `catalog:write`, `infra:write`, `settings:write`). I comandi sottostanti conterranno quindi la chiave reale. 2. Installa la CLI ed effettua l'accesso. La chiave viene mostrata solo in questa pagina e una sola volta. | Strumento | Installa | Accedi | |---|---|---| | Claude Code | `npm install -g @anthropic-ai/claude-code` | esegui `claude`, quindi `/login` | | Codex CLI | `npm install -g @openai/codex` | `codex login` | | Gemini CLI | `npm install -g @google/gemini-cli` | esegui `gemini`, scegli "Login with Google" | 3. Collegalo al tuo pannello con un singolo comando o blocco, copiato dalla pagina: ```bash # Claude Code claude mcp add --transport http nexcmp https://cloud.example.com/mcp/admin \ --header "Authorization: Bearer ak_XXXX" ``` ```toml # Codex CLI: ~/.codex/config.toml, then: export NEXCMP_KEY=ak_XXXX [mcp_servers.nexcmp] url = "https://cloud.example.com/mcp/admin" bearer_token_env_var = "NEXCMP_KEY" ``` ```json // Gemini CLI: ~/.gemini/settings.json { "mcpServers": { "nexcmp": { "httpUrl": "https://cloud.example.com/mcp/admin", "headers": { "Authorization": "Bearer ak_XXXX" } } } } ``` 4. Avvia lo strumento e chiedi, ad esempio, "what is left to set up in nexcmp?". Tutti i dettagli della connessione MCP sono in [Connect an AI client](https://nexcmp.com/it/docs/configure-with-ai/mcp-admin/). La stessa scheda mostra l'URL per i connettori **claude.ai** e **ChatGPT**, che effettuano l'accesso tramite OAuth e non richiedono alcuna chiave: [OAuth connectors](https://nexcmp.com/it/docs/configure-with-ai/oauth-connectors/). ![Scheda Use your own AI subscription con il pulsante della chiave a 7 giorni e i comandi di installazione, accesso e connessione per tre CLI](https://nexcmp.com/it/docs/images/configure-with-ai/ai-accounts-and-subscriptions-02-subscription.webp) ### Modo 2: la CLI sul server del pannello (pulsanti Installa / Accedi) {#way-2-the-cli-on-the-panel-server-install-login-buttons} Le schede sotto "Sottoscrizione tramite CLI (Claude, ChatGPT, Gemini)" permettono a NexCMP di installare la CLI ufficiale sul server del pannello e di avviare il proprio flusso di accesso, in modo che **AI Chat** possa rispondere utilizzando la tua sottoscrizione. **Come viene isolata.** Le CLI vengono eseguite in un processo separato (`nexcmp-ai.service`) come utente di sistema dedicato `nexcmp-ai`, senza sudo, senza accesso alle cartelle di dati e configurazione di NexCMP e con un limite di memoria. Per ogni messaggio di AI Chat la CLI viene avviata consentendo solo gli strumenti MCP di NexCMP (gli strumenti di shell e file sono disattivati) e con una chiave valida solo dal server. NexCMP non legge né copia i dati di accesso della CLI: la CLI li conserva in una cartella privata per il tuo account amministratore. Non c'è nulla da attivare: il pannello configura l'utente `nexcmp-ai` e il servizio al momento dell'installazione o dell'aggiornamento alla versione 1.4.0, quindi le schede sono pronte all'uso. **Installa e accedi (per ciascun amministratore):** 1. Sulla scheda della CLI fai clic su **Login**. Se la CLI non è ancora installata, il pannello provvede prima all'installazione: una barra di avanzamento e un registro sintetico mostrano il download (Node.js se necessario, seguito dalla CLI). Viene visualizzato un avviso se il server dispone di meno di 2 GB di RAM. 2. La scheda mostra le informazioni richieste dalla CLI: - **Codex CLI**: fai clic su **Open the sign-in page** e digita il codice monouso visualizzato sulla scheda. (L'accesso tramite dispositivo di OpenAI deve essere abilitato nelle impostazioni di sicurezza di ChatGPT.) - **Claude Code e Gemini CLI**: fai clic su **Open the sign-in page**, effettua l'accesso, quindi incolla il codice di verifica mostrato dalla pagina del fornitore nel campo **Paste the verification code here** e fai clic su **Send code**. 3. La scheda passa allo stato "Signed in" indicando l'account e la versione. Un accesso non completato entro 10 minuti viene annullato; fai nuovamente clic su **Login**. 4. In **AI Chat** la sorgente compare ora nel selettore (ad esempio "ChatGPT (via Codex CLI)"). 5. **Disconnetti** rimuove le credenziali di accesso della CLI per il tuo account. Per Claude, la scheda include un'opzione aggiuntiva, **Comprendo e accetto i termini del fornitore per l'utilizzo di una sottoscrizione in questo modo**, disattivata per impostazione predefinita. La sorgente non viene proposta in AI Chat finché questa opzione non è attiva. ![Schede di sottoscrizione CLI con pulsanti Installa e Accedi, un codice monouso sulla scheda Codex e l'interruttore di accettazione sulla scheda Claude](https://nexcmp.com/it/docs/images/configure-with-ai/ai-accounts-and-subscriptions-03-cli.webp) ### Termini dei fornitori di IA {#terms-of-the-ai-vendors} L'accesso con una sottoscrizione consumer è regolato dai termini dei singoli fornitori, che sono soggetti a modifiche. Le note seguenti costituiscono un riepilogo di quanto pubblicato dai fornitori a ottobre 2026 e non rappresentano né una consulenza legale né una dichiarazione per conto del fornitore. Si consiglia di leggere le pagine aggiornate prima di attivare questa funzione. | Fornitore | Contenuto della pagina del fornitore | Source | |---|---|---| | Anthropic (Claude) | L'accesso a Claude Code non modificato con il proprio piano è incluso. L'utilizzo di una sottoscrizione tramite altri prodotti, o la raccolta e trasmissione dei dati di accesso da parte di un prodotto, è disciplinato in modo differente e i limiti del piano presuppongono un utilizzo individuale ordinario. Per questo motivo la scheda Claude include una nota e l'interruttore **I understand**, e il Modo 1 rappresenta la scelta più pulita. | https://code.claude.com/docs/en/legal-and-compliance | | OpenAI (Codex) | Codex supporta l'accesso tramite account ChatGPT o chiave API. OpenAI consiglia l'uso di chiavi API per l'automazione e raccomanda di non esporre Codex in ambienti non attendibili o pubblici. Utilizza la scheda esclusivamente per uso personale. | https://developers.openai.com/codex/auth | | Google (Gemini CLI) | Supporta l'accesso con Google, chiave API e Vertex AI; i termini variano in base alla modalità di accesso scelta e si applicano le quote del tuo piano. | https://geminicli.com/docs/get-started/authentication | Se vuoi evitare del tutto la questione, usa una sorgente **API key** o il Metodo 1 sul tuo computer. ## AI Console {#ai-console} AI Console è una pagina terminale opzionale per eseguire una delle CLI con sessione avviata sul server del pannello. È **disattivata per impostazione predefinita**. - Attivala o disattivala e gestisci le CLI sul server: ```bash sudo nexcmp ai-console enable # turn on (also creates the nexcmp-ai user and service) sudo nexcmp ai-console disable # turn off sudo nexcmp ai-console status # runner, console state and installed CLIs sudo nexcmp ai-console install claude # or codex, or gemini ``` `status` stampa se il socket del runner IA è pronto, se AI Console è abilitata o disabilitata e, per ciascuna CLI, "installed" o "not installed". `sudo nexcmp status` mostra anche "AI runner: active". - Una volta abilitata, compare una scheda **AI Console** sotto AI Chat. Scegli una CLI con sessione avviata, reinserisci la password di amministratore (e il codice 2FA se lo usi) e apri una sessione. Un banner ricorda che i comandi qui presenti possono gestire NexCMP solo tramite i suoi strumenti MCP; gli strumenti per shell e file sono disabilitati. - Le installazioni demo non creano mai l'utente `nexcmp-ai`. ![Schermata iniziale di AI Console con il selettore CLI, il campo password e il banner di avviso esclusivo per MCP](https://nexcmp.com/it/docs/images/configure-with-ai/ai-accounts-and-subscriptions-04-console.webp) ## Verifica {#verify} 1. **Test** su una sorgente API restituisce il nome del modello. 2. Sulla scheda della CLI lo stato riporta "Signed in" con l'account. 3. Sul server: `sudo nexcmp ai-console status` elenca la CLI come installata e `systemctl is-active nexcmp-ai` stampa `active`. 4. In AI Chat scegli la sorgente, chiedi "Check my setup progress" e compare una scheda strumento. ## Limiti e note {#limits-notes} - La risposta di una CLI è limitata a 5 minuti e a una risposta alla volta per amministratore. Il limite giornaliero non conteggia le risposte della CLI. - Qualsiasi modifica da una sorgente CLI rimane una scheda di conferma in AI Chat; la CLI non può applicare modifiche autonomamente. - I piani di abbonamento hanno i propri limiti di utilizzo. Quando il fornitore indica "usage limit" o "not logged in", la chat mostra tale messaggio. - La rimozione di una sorgente non elimina le conversazioni. - Tieni il server aggiornato: le CLI vengono installate dai pacchetti pubblici dei fornitori nel momento in cui fai clic su Install. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | Il login è disabilitato e la scheda indica "AI tools are not ready on the server yet" | Il servizio `nexcmp-ai` non è in esecuzione | Aggiorna il pannello all'ultima versione, quindi controlla `sudo nexcmp status`. Sulla demo in sola lettura questo comportamento è previsto. | | "Gli strumenti di IA non sono ancora installati su questo server" | Il servizio `nexcmp-ai` non è in esecuzione (pannello meno recente o pannello demo) | Aggiorna il pannello, quindi `sudo nexcmp ai-console install claude` (o `codex`, `gemini`). | | Avviso sulla RAM inferiore a 2 GB | Il server è di piccole dimensioni | L'installazione potrebbe essere lenta o non riuscire; aggiungi memoria o usa il Metodo 1. | | "Node.js download checksum mismatch" o "download failed" | Il server non riesce a raggiungere nodejs.org oppure un proxy ha alterato il download | Consenti il traffico HTTPS in uscita e riprova. | | L'installazione termina con un errore | npm non è riuscito a installare il pacchetto | Leggi il log sulla scheda, verifica l'accesso in uscita verso il registry di npm e riprova. | | Il login termina con un errore o scade per timeout | La finestra di 10 minuti è scaduta oppure il codice era errato | Fai di nuovo clic su **Login** e completalo più velocemente. | | La sorgente Claude risulta mancante in AI Chat | L'interruttore **I understand** è disattivato oppure la CLI non ha effettuato l'accesso | Attiva l'interruttore dopo aver letto la pagina del fornitore, quindi effettua l'accesso. | | "Sign in with Google" è mancante su Gemini | Nessun client OAuth Google salvato finora | Crea il client nel tuo progetto Google Cloud e salvalo sotto **Set up Google sign-in (optional)** sulla scheda, oppure incolla una chiave API. | | "Sign in with OpenRouter" restituisce un errore | Hai annullato oppure il popup è stato bloccato | Consenti i popup e riprova. | | La risposta CLI indica "usage limit" | La quota del piano è esaurita | Attendi o cambia origine. | --- # Chiavi API amministrative {#admin-api-keys} > **Dove nel pannello admin:** System › Settings › API & AI agents (`/agent/keys`), scheda **API keys**. La stessa pagina include le schede **Connect an AI**, **Connected apps** e **Activity**. ## Descrizione {#what-it-does} Una chiave API amministrativa (prefisso `ak_`) consente a un client IA o a uno script di gestire il tuo pannello con esattamente i permessi assegnati. Funziona sull'API admin in `/v1/admin/` e sull'endpoint MCP admin in `/mcp/admin`. Non funziona altrove. ::: info Diverse dalle chiavi cliente I clienti creano chiavi che iniziano con `vk_` nel portale clienti ([API keys and scopes](https://nexcmp.com/it/docs/developers/api-keys/)). Queste raggiungono solo l'API cliente e `/mcp`. Una chiave `ak_` viene rifiutata sull'API cliente e una chiave `vk_` viene rifiutata sull'API admin. ::: ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Ruolo | Devi aver effettuato l'accesso come amministratore. Le chiavi non possono crearne altre. | | Demo | Su un pannello demo la pagina è di sola lettura: non è possibile creare o revocare alcuna chiave. | | Raggiungibilità | Il client deve raggiungere `https://cloud.example.com/mcp/admin` o `/v1/admin/...` sul tuo pannello (controlla il firewall se utilizzi restrizioni IP). | ## Crea una chiave {#create-a-key} 1. Apri **System › Settings › API & AI agents** e rimani sulla scheda **API keys**. 2. Fai clic su **Create new key**. 3. Compila il modulo: | Campo | Regole | |---|---| | Name | Fino a 60 caratteri, ad esempio "Claude Code sul mio portale". | | Ambiti | Seleziona almeno uno. Vedi [Scopes](#scopes). Inizia solo con `admin:read`. | | Scadenza | 1, 7, 30, 60 o 90 giorni. Predefinito 30. Massimo 90. Non è possibile creare una chiave senza scadenza. | | Intervalli IP (opzionale) | Un indirizzo IPv4 o IPv6 oppure CIDR per riga, ad esempio `203.0.113.0/24` o `2001:db8::/48`. Al massimo 32. Lascia vuoto per consentire qualsiasi IP. | | Chiamate al minuto | Da 1 a 6000. Predefinito 120. | 4. Fai clic su **Create key**. Un riquadro mostra la chiave una sola volta, ad esempio `ak_XXXX`. **Copia ora**: NexCMP memorizza solo un hash e non potrà più mostrarla. 5. Fai clic su **I have saved the key**. Apri la scheda **Connect an AI** per ottenere comandi pronti all'uso che contengono già la chiave appena creata (solo su questa pagina, fino al ricaricamento). ![Finestra di dialogo Nuova chiave con nome, caselle di ambito, scadenza e intervallo IP compilati](https://nexcmp.com/it/docs/images/configure-with-ai/admin-api-keys-01-create.webp) ![Finestra di dialogo che mostra la nuova chiave una volta con un pulsante Copia e un avviso](https://nexcmp.com/it/docs/images/configure-with-ai/admin-api-keys-02-shown-once.webp) ## Ambiti {#scopes} Una chiave può utilizzare solo gli strumenti e gli endpoint consentiti dai suoi ambiti. Gli ambiti di scrittura non includono l'accesso in lettura: una chiave che deve leggere e scrivere necessita anche di `admin:read`. | Ambito | Cosa consente | |---|---| | `admin:read` | Leggere impostazioni, catalogo, clienti, fatturazione e log. I dati sensibili non vengono mai restituiti. | | `catalog:write` | Piani, template OS, quote, codici sconto. | | `infra:write` | Origini infrastruttura (CloudStack, Proxmox), zone, server. | | `billing:write` | Gateway di pagamento, valuta, fatture, saldi. Le azioni monetarie richiedono conferma. | | `customers:write` | Clienti e rivenditori. | | `settings:write` | Impostazioni generali, branding, email, pagine legali, moduli, notifiche. | | `ai:write` | Il provider IA e le funzioni IA. | | `secrets:write` | Scrivi password e chiavi API. Possono essere impostate ma mai lette. | ::: tip L'impostazione di un segreto richiede due ambiti Qualsiasi chiamata che trasporti una password, una chiave API o un valore di token (una password SMTP, una chiave di pagamento, un token bot di Telegram, una chiave del provider IA, credenziali CloudStack o Proxmox) richiede `secrets:write` **e** l'ambito dell'area (ad esempio `settings:write` per SMTP). Se preferisci digitare tu stesso i segreti, lascia disattivato `secrets:write` e inseriscili nell'admin. ::: ## Revoca una chiave {#revoke-a-key} 1. Trova la chiave nella tabella (stato **Active**, **Expired** o **Revoked**; **Last used** mostra l'ora e il client). 2. Fai clic su **Revoke** e conferma. La chiave smette di funzionare immediatamente. La revoca è permanente; creane una nuova se ti serve di nuovo. ## Cosa una chiave non può mai fare {#what-a-key-can-never-do} Una chiave non può mai raggiungere queste aree, indipendentemente dai suoi ambiti. Richiedono l'accesso come amministratore. - Crea o modifica utenti amministratori, 2FA e sicurezza di accesso, sessioni admin e token API admin. - Crea, elenca o revoca chiavi admin, connessioni OAuth e account IA, oppure usa la Console IA. - Esegui il backup o il ripristino del pannello, aggiornalo o modifiane la licenza. - Accedi come cliente o rivenditore, apri la console di un cliente, leggi credenziali di VM o kubeconfig, imposta chiavi SSH oppure invia o reimposta password. - Modifica i moduli di rete e routing (BGP, FRR, RTBH, XDP, interfacce, route statiche e di policy, NAT) o agenti esterni e integrazione del portale. Questi sono di sola lettura. - Modifica impostazioni quali `demo_*`, `admin_*`, elenchi host, passkey, riautenticazione e segreti captcha. Tutto ciò che non è coperto da una regola è chiuso per impostazione predefinita per le scritture e leggibile con `admin:read` per le letture. ### Azioni che richiedono la tua conferma {#actions-that-need-your-confirmation} Queste vanno a buon fine solo dopo aver approvato un'anteprima (vedi [Two-step confirmation](#two-step-confirmation)): - Modifica del saldo di un cliente o del portafoglio di un rivenditore, erogazione di denaro, registri di fatturazione, tasso di cambio. - Modifica dei prezzi (prezzi dei piani, creazione massiva di piani, prezzi di immagini e storage) e creazione di codici sconto o promozionali. - Salvataggio delle credenziali del gateway di pagamento o della connessione CloudStack. - Eliminazione di qualsiasi elemento, blocco o eliminazione di un cliente, modifica dei limiti di un cliente, sospensione o chiusura di un rivenditore. - Intervento sui server dei clienti o creazione di un server a pagamento per un cliente. - Modifica di interruttori globali del sito, impostazioni di sicurezza dell'accesso o impostazioni di pagamento tramite le impostazioni generali. ## Conferma in due passaggi {#two-step-confirmation} Quando una chiamata richiede una conferma, nulla cambia ancora. La risposta è HTTP **428** con `confirm_required`, un `confirm_token`, un `preview` (metodo, percorso, motivo, i nuovi valori e, quando disponibili, i valori correnti) e `expires_in: 300`. 1. Il client ti mostra l'anteprima. 2. Dopo l'approvazione, ripete la **stessa** richiesta (stesso metodo, percorso e corpo) con l'intestazione `X-Confirm-Token: `. Gli strumenti MCP accettano invece l'argomento `confirm_token`. 3. Il token funziona una volta e scade dopo 5 minuti. Le chiavi create nell'area amministrativa per AI Chat possono essere confermate solo a schermo: la risposta indica `confirm_in: "ui"` e compare una scheda di conferma nell'amministrazione. L'intelligenza artificiale non può approvarla. ## Limiti di frequenza e regole IP {#rate-limit-and-ip-rules} - Oltre il limite al minuto, una chiamata restituisce `rate_limited` (HTTP 429) con `Retry-After: 60`. - Con intervalli IP impostati, le chiamate da qualsiasi altro indirizzo restituiscono `ip_not_allowed` (HTTP 403). ## Registro attività {#activity-log} La scheda **Activity** elenca tutte le chiamate effettuate con una chiave, dalla più recente: ora, chiave, cliente, modalità di arrivo (`http`, `mcp`, `chat`, `cli`, `confirm`, `preview`), metodo e percorso, strumento, stato HTTP, IP e i dettagli (mascherati). Puoi cercare per percorso, strumento o nome della chiave, mostrare solo gli errori (HTTP 400 e superiori) o solo le chiamate in attesa di conferma (428 e superiori) e limitare il periodo all'ultima ora, 24 ore o 7 giorni. NexCMP conserva le ultime 200,000 voci. Le modifiche effettuate tramite una chiave compaiono anche in Logs › Admin actions con il nome `ak:/`. ![Scheda Activity che elenca le chiamate con stato, client, tool e IP](https://nexcmp.com/it/docs/images/configure-with-ai/admin-api-keys-03-activity.webp) ## Verifica {#verify} Testa una chiave di sola lettura da qualsiasi macchina che si trovi all'interno dell'intervallo IP: ```bash curl -s https://cloud.example.com/v1/admin/agent/tools \ -H "Authorization: Bearer ak_XXXX" ``` Ottieni un elenco JSON dei tool consentiti dai tuoi ambiti. Esegui uno: ```bash curl -s -X POST https://cloud.example.com/v1/admin/agent/tools/system_health \ -H "Authorization: Bearer ak_XXXX" \ -H "Content-Type: application/json" -d '{}' ``` Il tempo **Last used** della chiave si aggiorna e la chiamata compare in **Activity**. L'elenco completo dei tool e una descrizione OpenAPI (`/v1/admin/openapi.json`) sono descritti in [Connect an AI client](https://nexcmp.com/it/docs/configure-with-ai/mcp-admin/). ## Errori {#errors} Gli errori sono in formato JSON: `{"error": {"code": "...", "message": "..."}}`. | HTTP | `code` | Significato | Soluzione | |---|---|---|---| | 401 | `invalid_key` | La chiave è mancante, non valida o sconosciuta. Viene restituito anche quando viene utilizzata una chiave `ak_` su un percorso non amministrativo. | Controlla la chiave; usala solo su `/v1/admin/` e `/mcp/admin`. | | 401 | `key_expired` | La scadenza della chiave è superata. | Crea una nuova chiave. | | 401 | `key_revoked` | La chiave è stata revocata. | Crea una nuova chiave. | | 403 | `ip_not_allowed` | L'IP del chiamante si trova al di fuori degli intervalli IP della chiave. | Effettua la chiamata da un IP consentito o crea una chiave con l'intervallo corretto. | | 403 | `local_only_key` | Una chiave creata per AI Chat o la CLI del server è stata utilizzata da un'altra macchina. | Queste chiavi funzionano solo sul server del pannello. | | 403 | `insufficient_scope` | La chiave non ha un ambito; la risposta include `required_scope`. | Crea una chiave con quell'ambito. | | 403 | `forbidden_for_keys` | L'endpoint, o l'impostazione che hai provato a modificare, è chiuso alle chiavi. | Esegui l'azione nell'area di amministrazione. | | 403 | `demo_read_only` | Il pannello è in modalità demo e la chiamata esegue una scrittura. | Usa un pannello non in modalità demo. | | 403 | `confirm_in_ui` | Questa azione deve essere confermata a schermo nell'interfaccia di amministrazione. | Approva la scheda di conferma. | | 428 | `confirm_required` | Un'anteprima è pronta; nulla è stato modificato. Include `confirm_token`. | Mostra l'anteprima, quindi ripeti con `X-Confirm-Token`. | | 409 | `confirm_expired` | Il token risale a più di 5 minuti fa. | Invia nuovamente la richiesta per ottenere una nuova anteprima. | | 409 | `confirm_mismatch` | Il token appartiene a una richiesta diversa (metodo, percorso o corpo differenti). | Ripeti la richiesta identica. | | 409 | `confirm_invalid` | Token sconosciuto o già utilizzato. | Invia nuovamente la richiesta per ottenere una nuova anteprima. | | 429 | `rate_limited` | Troppe chiamate in questo minuto. | Attendi `Retry-After`. | | 400 | `invalid_path` | Il percorso contiene sequenze non consentite. | Usa un percorso semplice. | | 413 | `too_large` | Il corpo supera i 10 MB. | Invia meno dati. | | 400 | `invalid_argument` | Un argomento del tool è mancante, sconosciuto o ha il tipo errato; il messaggio lo specifica. | Correggi l'argomento. | ## Limiti e note {#limits-notes} - Mantieni le chiavi di breve durata e con permessi limitati. Preferisci una chiave per client in modo da poter revocarne una singola. - Una chiave è potente quanto i suoi ambiti. `secrets:write` unito a `billing:write` è la combinazione più sensibile; le azioni finanziarie si fermano comunque a un'anteprima. - Le chiavi create automaticamente (per AI Chat, la CLI del server) durano solo pochi minuti e funzionano esclusivamente dal server del pannello. - Per disattivare immediatamente un client AI, revoca la sua chiave. Le connessioni OAuth vengono revocate nella scheda **Connected apps** ([OAuth connectors](https://nexcmp.com/it/docs/configure-with-ai/oauth-connectors/)). --- # Connettere un client AI (MCP) {#connect-an-ai-client-mcp} > **Dove nel pannello admin:** System › Settings › API & AI agents (`/agent/keys`), la scheda **Connect an AI** mostra l'URL dell'endpoint e uno snippet pronto da copiare per ogni client, compilato con la chiave appena creata. ## Descrizione {#what-it-does} Il protocollo **Model Context Protocol (MCP)** consente a un client AI di richiamare strumenti. Il tuo pannello ospita un server MCP admin su `https://cloud.example.com/mcp/admin`. Collega il tuo strumento AI e chiedi in linguaggio naturale: "cosa resta da configurare?", "aggiungi il mio cluster Proxmox", "crea piani con un margine del 40%". Il client richiama gli strumenti di amministrazione sottostanti; il pannello verifica i permessi, ti chiede conferma prima di qualsiasi operazione rischiosa e registra ogni chiamata. ::: info Due endpoint MCP `/mcp` è l'endpoint **cliente** (chiavi API cliente, `vk_`; vedi [MCP server](https://nexcmp.com/it/docs/developers/mcp/)). `/mcp/admin` è l'endpoint **admin** descritto qui (chiavi admin `ak_` o OAuth). I due non si mescolano mai: gli strumenti admin non sono visibili su `/mcp` e `/mcp/admin` accetta solo chiavi admin. ::: ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Endpoint | `https://cloud.example.com/mcp/admin` sul dominio del tuo pannello. Copia l'URL esatto dalla scheda **Connect an AI**. La stessa pagina elenca un URL locale (`http://127.0.0.1:/mcp/admin`) per gli strumenti in esecuzione sul server stesso. | | Credenziali | Una [admin API key](https://nexcmp.com/it/docs/configure-with-ai/admin-api-keys/) (`ak_...`) con i permessi desiderati, **oppure** l'accesso OAuth per i connettori web ([OAuth connectors](https://nexcmp.com/it/docs/configure-with-ai/oauth-connectors/)). | | Client | Qualsiasi client MCP che supporta il trasporto **Streamable HTTP** e un'intestazione `Authorization` personalizzata. Versioni del protocollo 2025-11-25, 2025-06-18 e 2025-03-26. | | Rete | Se inserisci un tuo reverse proxy davanti al pannello, questo deve inoltrare `/mcp/admin`. I connettori web (claude.ai, ChatGPT) si collegano dai server del fornitore, quindi l'URL deve essere raggiungibile da internet. | ## Prepara l'infrastruttura {#prepare-the-infrastructure} Nessuna installazione richiesta sul server. Se limiti la chiave per IP, assicurati che l'indirizzo da cui si collega il client rientri nell'intervallo. Testa prima la raggiungibilità: ```bash curl -i -X POST https://cloud.example.com/mcp/admin ``` Una risposta pari a `401` con un'intestazione `WWW-Authenticate: Bearer ... resource_metadata=...` indica che l'endpoint è attivo e richiede le credenziali. ## Collega in NexCMP {#connect-in-nexcmp} 1. Crea una chiave: **System › Settings › API & AI agents › API keys › New key**. Per un primo test usa solo `admin:read`; aggiungi i permessi di scrittura quando ti servono. Vedi [Admin API keys](https://nexcmp.com/it/docs/configure-with-ai/admin-api-keys/). 2. Apri la scheda **Connect an AI**. Finché la finestra di dialogo "chiave creata" è ancora aperta, ogni snippet sottostante contiene già la tua chiave reale. In caso contrario, mostra il placeholder `ak_YOUR_KEY`. 3. Copia lo snippet per il tuo client ed eseguilo o incollalo come descritto di seguito. ![Scheda Connect an AI con l'URL MCP e una scheda con il pulsante di copia per ciascun client](https://nexcmp.com/it/docs/images/configure-with-ai/mcp-admin-01-connect.webp) ### Claude Code {#claude-code} ```bash claude mcp add --transport http nexcmp https://cloud.example.com/mcp/admin \ --header "Authorization: Bearer ak_XXXX" ``` Quindi avvia `claude` e chiedi "list the tools from nexcmp" o "what is left to set up?". Verificato il 30/10/2026 con Claude Code 2.1: `claude mcp add --transport http …` scrive sul server (aggiungi `-s project` per conservarlo nel file `.mcp.json` del progetto — Claude Code chiede di approvare i server di progetto la prima volta). Per gli script, `claude -p "…" --mcp-config .mcp.json --strict-mcp-config --allowedTools "mcp__nexcmp__*"` viene eseguito senza la richiesta di approvazione e consente a Claude di utilizzare solo gli strumenti del pannello. ### Claude Desktop {#claude-desktop} Richiede Node.js 18 o versioni successive. Aggiungi questo a `claude_desktop_config.json` (utilizza il bridge `mcp-remote`) e riavvia Claude Desktop: ```json { "mcpServers": { "nexcmp": { "command": "npx", "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp/admin", "--header", "Authorization:Bearer ak_XXXX"] } } } ``` Se il tuo sistema altera lo spazio nell'argomento dell'intestazione, inserisci l'intero valore in una variabile d'ambiente, esattamente come per l'endpoint cliente: `"args": [..., "--header", "Authorization:${NEXCMP_AUTH_HEADER}"]` con `"env": { "NEXCMP_AUTH_HEADER": "Bearer ak_XXXX" }`. ### claude.ai (connettore personalizzato) {#claude-ai-custom-connector} Nessuna chiave necessaria: effettua l'accesso con OAuth. In claude.ai apri le impostazioni dei connettori, aggiungi un connettore personalizzato, incolla `https://cloud.example.com/mcp/admin`, accedi con il tuo account admin di NexCMP e seleziona le autorizzazioni nella schermata di consenso. Dettagli: [OAuth connectors](https://nexcmp.com/it/docs/configure-with-ai/oauth-connectors/). ### ChatGPT (modalità sviluppatore) {#chatgpt-developer-mode} Nessuna chiave necessaria. In ChatGPT attiva la modalità sviluppatore, aggiungi un connettore MCP con l'URL `https://cloud.example.com/mcp/admin`, seleziona OAuth e accedi con il tuo account admin di NexCMP. Dettagli: [OAuth connectors](https://nexcmp.com/it/docs/configure-with-ai/oauth-connectors/). ### Codex CLI {#codex-cli} Aggiungi a `~/.codex/config.toml`: ```toml [mcp_servers.nexcmp] url = "https://cloud.example.com/mcp/admin" bearer_token_env_var = "NEXCMP_KEY" ``` Quindi esporta la chiave nella shell che avvia Codex: ```bash export NEXCMP_KEY=ak_XXXX codex codex mcp list # shows nexcmp with "Bearer token" auth ``` ::: tip Non interattivo `codex exec` In `codex exec` (script, CI) Codex non chiede conferma prima di chiamare gli strumenti e salta quelli che modificano i dati. Aggiungi `default_tools_approval_mode = "approve"` sotto `[mcp_servers.nexcmp]` per consentirne la chiamata; il pannello restituisce comunque un'anteprima e chiede conferma per le azioni relative a denaro, sicurezza ed eliminazione. Verificato con Codex CLI 0.166 il 30/10/2026. ::: ### Gemini CLI {#gemini-cli} Aggiungi a `~/.gemini/settings.json`: ```json { "mcpServers": { "nexcmp": { "httpUrl": "https://cloud.example.com/mcp/admin", "headers": { "Authorization": "Bearer ak_XXXX" } } } } ``` Gemini CLI disattiva i server MCP nelle cartelle che non considera attendibili. Avvialo in una cartella di cui ti fidi (o considerala attendibile quando richiesto), quindi verifica con `gemini mcp list`: viene mostrato `nexcmp … Connected`. Puoi tenere la chiave fuori dal file usando `"Authorization": "Bearer $NEXCMP_KEY"`. Verificato con Gemini CLI 0.66 il 30/10/2026. ### Cursor {#cursor} Aggiungi a `~/.cursor/mcp.json` (o a `.cursor/mcp.json` in un progetto): ```json { "mcpServers": { "nexcmp": { "url": "https://cloud.example.com/mcp/admin", "headers": { "Authorization": "Bearer ak_XXXX" } } } } ``` ::: tip Mantieni la chiave fuori dai file di configurazione Dove il client lo supporta, leggi la chiave da una variabile d'ambiente anziché scriverla nel file: Codex lo fa per impostazione predefinita (`bearer_token_env_var`) e Cursor accetta `"Bearer ${env:NEXCMP_KEY}"`. Non effettuare mai il commit di un file che contiene una chiave. ::: ### OpenAI Agents SDK (Python) {#openai-agents-sdk-python} ```python from agents.mcp import MCPServerStreamableHttp nexcmp = MCPServerStreamableHttp( params={"url": "https://cloud.example.com/mcp/admin", "headers": {"Authorization": "Bearer ak_XXXX"}}, name="nexcmp", ) ``` Un'esecuzione completa (verificata con `openai-agents` 0.24 il 30/10/2026 — uno strumento di lettura, seguito da una modifica del saldo che ha restituito l'anteprima di conferma ed è stata applicata alla seconda chiamata con `confirm_token`): ```python import asyncio from agents import Agent, Runner from agents.mcp import MCPServerStreamableHttp async def main(): async with MCPServerStreamableHttp(params={"url": "https://cloud.example.com/mcp/admin", "headers": {"Authorization": "Bearer ak_XXXX"}}, name="nexcmp") as nexcmp: agent = Agent(name="admin", model="gpt-5", mcp_servers=[nexcmp], instructions="You operate a hosting panel through the nexcmp tools. Ask me before confirming money actions.") result = await Runner.run(agent, "Run system_health and summarise it in one line.") print(result.final_output) asyncio.run(main()) ``` ### OpenAI Responses API {#openai-responses-api} Passa il server come strumento di tipo `mcp`. Tieni `require_approval` su `always` affinché il programma chieda conferma prima di ogni chiamata: ```json { "type": "mcp", "server_label": "nexcmp", "server_url": "https://cloud.example.com/mcp/admin", "headers": { "Authorization": "Bearer ak_XXXX" }, "require_approval": "always" } ``` ### Qualsiasi altra cosa (HTTP semplice) {#anything-else-plain-http} Un client senza MCP può chiamare gli stessi strumenti tramite HTTP. `GET /v1/admin/agent/tools` li elenca, `POST /v1/admin/agent/tools/` ne esegue uno con un corpo JSON di argomenti e `GET /v1/admin/openapi.json` restituisce una descrizione OpenAPI 3.1 (ciascun strumento corrisponde a un'operazione). Tutti richiedono `Authorization: Bearer ak_...`. ## Verifica {#verify} 1. Senza un client, elenca gli strumenti: ```bash curl -s https://cloud.example.com/mcp/admin \ -H "Authorization: Bearer ak_XXXX" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` La risposta è un risultato JSON-RPC con gli strumenti consentiti dai tuoi ambiti. 2. Nel client chiedi "run system_health". Restituisce gli avvisi, lo stato di salute dell'infrastruttura connessa, i pagamenti, l'email, l'IA e lo stato della licenza. 3. Apri **API & AI agents › Activity**: le chiamate vengono elencate con il nome del client e `mcp`. 4. Sul server, `sudo nexcmp status` stampa la riga "MCP admin" che indica `ready` quando l'endpoint risponde (lo stato HTTP 401 senza chiave indica il corretto funzionamento). ## Strumenti {#tools} Il server offre 58 strumenti. Un client vede solo quelli consentiti dagli ambiti della sua chiave: gli strumenti di lettura richiedono `admin:read`, quelli di scrittura necessitano del proprio ambito. Gli strumenti di scrittura accettano anche un argomento facoltativo `confirm_token` (vedi [Confirmation](#confirmation-confirm-token)). Gli argomenti vengono verificati rispetto allo schema di ogni strumento: quelli sconosciuti o digitati in modo errato vengono rifiutati con un messaggio che ne specifica il nome. I prezzi sono in USD: i prezzi dei piani in dollari all'ora (`hourly_usd`), i saldi in centesimi. I segreti possono essere impostati ma non vengono mai restituiti. ### Panoramica e log {#overview-and-logs} | Strumento | Descrizione | Ambito | Modifica dati | Chiede conferma | |---|---|---|---|---| | `system_health` | Avvisi che richiedono attenzione, salute dell'infrastruttura, pagamenti, email, IA, licenza e stato degli aggiornamenti. | `admin:read` | No | No | | `setup_checklist` | Cosa è configurato e cosa manca: licenza, infrastruttura, zona, template OS, piani, pagamenti, email, brand, note legali, ordine di test. | `admin:read` | No | No | | `license_status` | Stato della licenza e presenza di una versione di NexCMP più recente. | `admin:read` | No | No | | `audit_search` | Cerca nel registro di audit amministrativo e nel registro delle chiavi API. | `admin:read` | No | No | ### Impostazioni, brand, note legali, moduli {#settings-branding-legal-modules} | Strumento | Descrizione | Ambito | Modifica dati | Chiede conferma | |---|---|---|---|---| | `settings_get` | Leggi le impostazioni generali (filtri `keys`; un finale in `*` corrisponde a un prefisso). | `admin:read` | No | No | | `settings_update` | Modifica le impostazioni generali da un oggetto `values` flat. Sono accettate solo le chiavi elencate da `settings_get`. | `settings:write` | Sì | Quando una chiave influisce su pagamenti, sicurezza di accesso, interruttori globali o prezzi | | `branding_get` | Nome del brand, colore, valuta di visualizzazione, nome del venditore, URL del logo e della favicon. | `admin:read` | No | No | | `branding_update` | Imposta il nome del brand (fino a 60 caratteri), il colore (`#rrggbb`), la valuta di visualizzazione (`usd` o `vnd`) e il nome del venditore. | `settings:write` | Sì | No | | `branding_logo_set` | Carica un logo chiaro o scuro o una favicon da un URL https o base64 (PNG, JPEG, WEBP, ICO o SVG, fino a 512 KB). | `settings:write` | Sì | No | | `legal_get` | Termini di servizio e informativa sulla privacy (inglese e vietnamite) e i valori predefiniti neutrali. | `admin:read` | No | No | | `legal_update` | Imposta i testi dei termini e della privacy (markdown semplice, niente HTML, fino a 50 KB ciascuno). Una stringa vuota ripristina il valore predefinito. | `settings:write` | Sì | No | | `modules_get` | Quali moduli facoltativi sono attivi e quali possono essere attivati. | `admin:read` | No | No | | `module_set` | Attiva o disattiva un modulo facoltativo (`key` deve essere uno tra `settable`). | `settings:write` | Sì | No | ### Email e avvisi {#email-and-alerts} | Strumento | Descrizione | Ambito | Modifica dati | Chiede conferma | |---|---|---|---|---| | `smtp_get` | Impostazioni email in uscita (password mascherata) e stato della coda. | `admin:read` | No | No | | `smtp_configure` | Imposta il server SMTP. La modifica di host, porta o sicurezza richiede nuovamente la password. | `settings:write` (+ `secrets:write` per la password) | Sì | No | | `smtp_test` | Invia una vera email di test con le impostazioni salvate. | `settings:write` | Invia un'email | No | | `telegram_get` | Canali di notifica amministrativi (id chat; i token dei bot non vengono mai restituiti). | `admin:read` | No | No | | `telegram_configure` | Aggiungi o aggiorna il canale di avviso Telegram (token del bot e id chat) e attiva o disattiva gli avvisi amministrativi. | `settings:write` (+ `secrets:write` per il token) | Sì | No | | `telegram_test` | Invia un messaggio di test al canale Telegram. | `settings:write` | Invia un messaggio | No | ### Pagamenti e valuta {#payments-and-currency} | Strumento | Descrizione | Ambito | Modifica dati | Chiede conferma | |---|---|---|---|---| | `payments_get` | Stato di Stripe, PayPal, criptovalute (USDT) e bonifico bancario, oltre a canali abilitati e commissioni. | `admin:read` | No | No | | `payment_configure` | Imposta le credenziali di un gateway (`stripe`, `paypal`, `crypto` o `bank`). | `billing:write` (+ `secrets:write`) | Sì | Sempre | | `payment_test` | Verifica le credenziali salvate di un gateway presso il provider. | `billing:write` | No | No | | `currency_get` | Valuta di visualizzazione e tasso da USD a VND (automatico o manuale). | `admin:read` | No | No | | `currency_set` | Imposta la valuta di visualizzazione e/o un tasso manuale (0 significa automatico, altrimenti da 15000 a 50000). | `billing:write` | Sì | Quando modifichi il tasso manuale | ### Infrastruttura e zone {#infrastructure-and-zones} | Strumento | Descrizione | Ambito | Modifica dati | Chiede conferma | |---|---|---|---|---| | `cloudstack_get` | Endpoint CloudStack salvato e ID di zona e rete (chiavi mascherate). | `admin:read` | No | No | | `cloudstack_test` | Testa un endpoint con chiave API e segreto senza salvare; elenca le zone. | `infra:write` (+ `secrets:write`, poiché passi le chiavi) | No | No | | `cloudstack_connect` | Salva la connessione CloudStack. | `infra:write` (+ `secrets:write`) | Sì | Sempre | | `proxmox_list` | Cluster Proxmox VE aggiunti come sorgenti, con relativo stato di salute. | `admin:read` | No | No | | `proxmox_add` | Aggiungi un cluster Proxmox VE con un token API (`user@realm!tokenid`) e il relativo segreto. | `infra:write` (+ `secrets:write`) | Sì | No | | `proxmox_test` | Connettiti a un cluster tramite ID; il primo successo memorizza il suo certificato TLS. | `infra:write` | Sì | No | | `proxmox_attach_zone` | Vendi un cluster Proxmox in una zona esistente, opzionalmente con un nodo come regione. | `infra:write` | Sì | No | | `zones_list` | Zone (posizioni) che i clienti possono scegliere. | `admin:read` | No | No | | `zone_create` | Crea una zona. | `infra:write` | Sì | No | ### Catalogo e piani {#catalog-and-plans} | Strumento | Descrizione | Ambito | Modifica dati | Chiede conferma | |---|---|---|---|---| | `templates_list` | Template OS che i clienti possono installare. | `admin:read` | No | No | | `templates_sync` | Importa template OS da CloudStack. | `catalog:write` | Sì | No | | `template_update` | Abilita o nascondi un template, rinominalo, imposta l'utente di login o l'ordine. | `catalog:write` | Sì | No | | `offerings_list` | Offerte di servizio CloudStack (CPU, memoria, disco di root) su cui basare i piani. | `admin:read` | No | No | | `plans_list` | Piani con prezzo orario e mensile, dimensioni, zona e numero di server che li utilizzano. | `admin:read` | No | No | | `plan_create` | Crea un piano. Prezzo come `hourly_usd`. I piani CloudStack richiedono `cs_offering_id`; i piani Proxmox richiedono `backend_id`. | `catalog:write` | Sì | No | | `plan_update` | Rinomina, mostra o nascondi, abilita o disabilita o modifica il prezzo di un piano. Le modifiche alle dimensioni di un piano in uso richiedono una copia. | `catalog:write` | Sì | Quando il prezzo cambia | | `plans_from_offerings` | Crea una tabella di piani iniziali dalle offerte (o dimensioni di Proxmox) usando i costi e una percentuale di margine. Restituisce un'anteprima; richiama con `apply=true` per creare i piani. | `catalog:write` | Con `apply=true` | Sempre attivo all'applicazione | | `quota_defaults_get` | Limiti predefiniti dei clienti. | `admin:read` | No | No | | `quota_defaults_set` | Modifica le impostazioni di `quota_*`. | `catalog:write` | Sì | No | | `coupons_list` | Lotti di codici sconto e regalo. | `admin:read` | No | No | | `coupon_create` | Crea un lotto di codici: tipo `money` (valore nominale in centesimi di USD) o `percent` (da 1 a 100, con uno sconto massimo). | `catalog:write` | Sì | Sempre | ### Clienti e rivenditori {#customers-and-resellers} | Strumento | Descrizione | Ambito | Modifica dati | Chiede conferma | |---|---|---|---|---| | `customers_search` | Trova clienti tramite e-mail, nome o IP. | `admin:read` | No | No | | `customer_get` | Account, saldo, server e fatturazione recente di un cliente. | `admin:read` | No | No | | `customer_adjust_balance` | Aggiunge (positivo) o rimuove (negativo) credito in centesimi di USD. È richiesto un motivo. | `billing:write` | Sì | Sempre | | `customer_block` | Blocca un cliente, interrompendo facoltativamente i suoi server. È richiesto un motivo. | `customers:write` | Sì | Sempre | | `customer_unblock` | Sblocca un cliente. | `customers:write` | Sì | No | | `resellers_list` | Rivenditori con portafoglio e stato. | `admin:read` | No | No | | `reseller_get` | Sito, portafoglio, utenti e gateway di un rivenditore. | `admin:read` | No | No | ### Provider IA {#ai-provider} | Strumento | Descrizione | Ambito | Modifica dati | Chiede conferma | |---|---|---|---|---| | `ai_provider_get` | Il provider compatibile con OpenAI utilizzato dall'AI Chat e dall'AI Agent del cliente (chiave mascherata). | `admin:read` | No | No | | `ai_provider_set` | Imposta il provider: URL di base, modello, chiave API, modelli di fallback, livello di ragionamento, abilitato. | `ai:write` (+ `secrets:write` per la chiave) | Sì | No | | `ai_provider_test` | Pone una domanda al provider salvato per verificarne il corretto funzionamento. | `ai:write` | No | No | ### File di configurazione {#configuration-files} | Strumento | Descrizione | Ambito | Modifica dati | Chiede conferma | |---|---|---|---|---| | `config_export` | Esporta la configurazione come YAML (i segreti diventano riferimenti `secret://`). | `admin:read` | No | No | | `config_plan` | Confronta una configurazione YAML con il pannello attivo ed elenca ciò che cambierebbe. | `admin:read` | No | No | | `config_apply` | Applica una configurazione YAML sezione per sezione. Ogni modifica segue le normali regole di ambito e conferma. | `admin:read` + l'ambito di ogni modifica | Sì | Per ogni modifica | Vedi [Configuration as code](https://nexcmp.com/it/docs/configure-with-ai/config-as-code/) per il formato del file. ## Prompt {#prompts} Il server offre anche tre prompt predefiniti che i client possono mostrare come scorciatoie: | Prompt | Argomento | Cosa chiede di fare all'IA | |---|---|---| | `initial-setup` | nessuno | Chiama `setup_checklist`, spiega ogni fase aperta in una frase, chiede le informazioni necessarie, esegue la fase con lo strumento corrispondente, mostra un'anteprima delle modifiche a denaro o sicurezza e termina con `system_health`. | | `add-proxmox` | `endpoint` (facoltativo, `https://host:8006`) | Chiede il token API, quindi `proxmox_add`, `proxmox_test`, gli strumenti di zona e `proxmox_attach_zone`; poi propone i piani con `plans_from_offerings` e attende l'approvazione. | | `launch-pricing` | `margin_pct` (facoltativo, predefinito 40) | Chiede il costo mensile per vCPU, per GB di RAM e per GB di disco, mostra una tabella di anteprima con costi, prezzo mensile e prezzo orario, e crea i piani dopo l'approvazione. | ## Conferma (`confirm_token`) {#confirmation-confirm-token} Le azioni che muovono denaro, eliminano dati, modificano le credenziali di pagamento o la sicurezza degli accessi avvengono in due passaggi: 1. La prima chiamata non modifica nulla. Il risultato dello strumento inizia con "CONFIRMATION REQUIRED" e include un'**anteprima** (cosa verrà chiamato, perché è un'operazione sensibile, i nuovi valori e quelli attuali) e un `confirm_token`. 2. Il client deve mostrare l'anteprima. Solo dopo l'approvazione viene richiamato lo stesso strumento con gli stessi argomenti più `confirm_token`. 3. Il token funziona una sola volta, esclusivamente per quella richiesta specifica, e scade dopo 5 minuti. Le istruzioni del server dicono all'IA di trattare i risultati dei tool come dati e non come istruzioni, e di non ripetere mai una chiamata con un token che non hai approvato. Tu sei la salvaguardia: leggi l'anteprima. ::: warning Non approvare automaticamente Alcuni client possono approvare automaticamente ogni chiamata a un tool. Per i tool di scrittura, mantieni attiva l'approvazione per singola chiamata o usa una chiave di sola lettura, in modo che un piano errato dell'IA non possa raggiungere il tuo pannello senza essere visto. ::: ## Come funziona {#how-it-works} | Elemento | Dettaglio | |---|---| | Trasporto | `POST /mcp/admin` con un messaggio JSON-RPC 2.0; la risposta è `application/json`. Fino a 20 messaggi in un batch. `GET /mcp/admin` risponde con 405 (nessuno stream del server); `DELETE /mcp/admin` termina una sessione. | | Autenticazione | `Authorization: Bearer ak_...` (una chiave manuale o un token di accesso OAuth). Credenziali mancanti o errate restituiscono 401 con `WWW-Authenticate: Bearer ... resource_metadata=...`, il che consente ai client OAuth di avviare l'accesso autonomamente. | | Sessioni | `Mcp-Session-Id` viene emesso da `initialize`, associato a tale chiave e valido per 24 ore. | | Funzionalità | Tool e prompt. Nessuna risorsa. | | Dimensione | Corpo della richiesta fino a 1 MB; il risultato di un tool viene troncato dopo circa 100 KB. | | Origine | Una richiesta che trasporta un'intestazione `Origin` da un altro sito viene rifiutata (`origin_not_allowed`). I client da riga di comando e desktop non ne inviano alcuna. | | Stesso filtro del REST | Ogni chiamata a un tool viene reinviata attraverso la pipeline di richieste del pannello con la tua chiave, pertanto ambiti, intervalli IP, limite di frequenza, conferma e registro attività si applicano esattamente come per le chiamate API dirette. | ## Limiti e note {#limits-notes} - Un tool che non riesci a vedere è un ambito che non hai concesso. Aggiungi l'ambito a una nuova chiave. - Impostare una password o una chiave API tramite un client IA significa che il segreto passa attraverso quell'IA. Se preferisci, lascia disattivato `secrets:write` e inserisci tu stesso i segreti nell'amministrazione, oppure usa il campo **Secret** di AI Chat ([AI Chat in the admin](https://nexcmp.com/it/docs/configure-with-ai/ai-chat-in-admin/#secrets)) o i riferimenti `secret://` ([Configuration as code](https://nexcmp.com/it/docs/configure-with-ai/config-as-code/#secrets)). - I client non condividono le sessioni: ogni connessione inizia con `initialize`. - Revoca la chiave in **API & AI agents** per isolare immediatamente un client IA. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | 401 `invalid_key` | Chiave errata, troncata o non amministrativa (ad esempio una chiave `vk_`) | Usa una chiave `ak_`. | | 401 `key_expired` o `key_revoked` | La chiave è scaduta o è stata revocata | Crea una nuova chiave. | | 403 `ip_not_allowed` | Il tuo indirizzo IP è al di fuori degli intervalli IP della chiave | Connettiti da un IP consentito. | | 403 `origin_not_allowed` | Una pagina del browser su un'altra origine ha chiamato l'endpoint | Usa un client desktop o CLI. | | 404 su una richiesta con `Mcp-Session-Id` | La sessione appartiene a un'altra chiave oppure è scaduta | Invia di nuovo `initialize`. | | 400 unsupported `MCP-Protocol-Version` | Il client utilizza una versione che il server non riconosce | Aggiorna il client; supportate: 2025-11-25, 2025-06-18, 2025-03-26. | | L'elenco degli strumenti è breve | Ambiti della chiave | Crea una chiave con più ambiti. | | `insufficient_scope` su una chiamata | Un tool richiede un secondo ambito, ad esempio `secrets:write` | Aggiungi l'ambito a una nuova chiave. | | 429 `rate_limited` | Più chiamate al minuto di quelle consentite dalla chiave | Attendi `Retry-After` o aumenta il limite su una nuova chiave. | | claude.ai o ChatGPT non riescono a connettersi | L'URL non è raggiungibile da internet o un proxy blocca `/mcp/admin` o `/oauth-admin/` | Verifica DNS, TLS e reverse proxy. | Per tutti i codici di errore, vedi [Admin API keys](https://nexcmp.com/it/docs/configure-with-ai/admin-api-keys/#errors). --- # Connettori claude.ai e ChatGPT {#claude-ai-and-chatgpt-connectors} > **Dove si trova nell'amministrazione:** System › Settings › API & AI agents (`/agent/keys`), scheda **Connected apps**. La schermata di consenso si apre su `/agent/consent` quando un connettore richiede l'accesso (non si trova nel menu). ## Descrizione {#what-it-does} Le app di IA web non possono leggere una chiave dal tuo disco. Si connettono tramite **OAuth**: aggiungi l'URL MCP del pannello, l'app ti reindirizza alla tua amministrazione per accedere, scegli cosa l'app può fare e per quanto tempo, e l'app riceve token di breve durata. Nessuna chiave viene copiata o incollata. Puoi interrompere l'app in qualsiasi momento. Usa questa funzione per i connettori personalizzati di claude.ai, i connettori in modalità sviluppatore di ChatGPT e qualsiasi altro client MCP che supporta OAuth con registrazione dinamica del client. Gli strumenti da riga di comando possono usare lo stesso flusso, ma una [chiave API amministrativa](https://nexcmp.com/it/docs/configure-with-ai/admin-api-keys/) risulta più semplice per essi. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | URL | `https://cloud.example.com/mcp/admin`, raggiungibile da Internet (i server del fornitore vi si connettono). | | Reverse proxy | Se metti il tuo proxy davanti al pannello, questo deve inoltrare i percorsi `/mcp/admin`, `/oauth-admin/` e `/.well-known/` al pannello. | | Tu | Connesso all'amministrazione di NexCMP **nello stesso browser** che usi per la schermata di consenso. | | Client | Supporta MCP su Streamable HTTP, OAuth 2.1 con PKCE (S256) e registrazione dinamica del client. | ## Connessione {#connect} 1. Nell'app di IA, aggiungi un connettore MCP personalizzato e incolla `https://cloud.example.com/mcp/admin`. In claude.ai questo si trova nelle impostazioni dei connettori (aggiungi connettore personalizzato); in ChatGPT si trova in modalità sviluppatore (aggiungi un connettore MCP, autenticazione OAuth). 2. Scegli **Sign in** (o "Connect") nell'app. Il tuo browser apre la schermata di consenso dell'amministrazione di NexCMP. Se non hai effettuato l'accesso, fallo prima; la schermata continuerà subito dopo. 3. Leggi la scheda: "**Example AI app** wants to manage this NexCMP admin" (il nome dell'app che sta richiedendo l'accesso), con l'indirizzo a cui verrai reindirizzato. 4. Spunta i permessi da concedere. Quelli richiesti dall'app sono pre-spuntati; se non ne ha richiesti, solo `admin:read` è spuntato. Vedi [Scopes](https://nexcmp.com/it/docs/configure-with-ai/admin-api-keys/#scopes). 5. Scegli la durata della connessione: **7**, **30** o **90** giorni (predefinito 30). 6. Fai clic su **Allow**. Il browser torna all'app, che ora risulta connessa. Fai clic su **Deny** per rifiutare. ![Schermata di consenso che chiede di autorizzare un'app di IA, con caselle di selezione dei permessi, scelta della durata e pulsanti Allow e Deny](https://nexcmp.com/it/docs/images/configure-with-ai/oauth-connectors-01-consent.webp) ::: important Scegli i permessi come faresti per una chiave Concedi l'insieme minimo necessario per svolgere il compito. Azioni relative a denaro, eliminazione e sicurezza si fermano comunque a un'anteprima e richiedono la tua approvazione, ma una connessione con `settings:write` può comunque modificare il tuo brand e la tua email. ::: ## Gestione e revoca {#manage-and-revoke} Apri **System › Settings › API & AI agents › Connected apps**. La tabella elenca ogni app che hai connesso: applicazione, permessi, momento della connessione, scadenza e ultimo utilizzo. Per interrompere un'app, fai clic su **Revoke** e conferma. I suoi token smettono di funzionare immediatamente; l'app dovrà ripetere la procedura di consenso per riconnettersi. ![Scheda Connected apps che elenca un'app di IA con i suoi permessi, la scadenza e un pulsante Revoke](https://nexcmp.com/it/docs/images/configure-with-ai/oauth-connectors-02-connected-apps.webp) ## Come funziona il flusso {#how-the-flow-works} | Passaggio | Dettaglio | |---|---| | Rilevamento | L'app legge `/.well-known/oauth-protected-resource/mcp/admin` e poi `/.well-known/oauth-authorization-server/oauth-admin`. L'emittente è `https://cloud.example.com/oauth-admin`. | | Registrazione | L'app registra se stessa (`POST /oauth-admin/register`, RFC 7591). Sono supportati solo i client pubblici (nessun segreto client). L'indirizzo di reindirizzamento deve essere `https`, oppure `http` sullo stesso computer (loopback). | | Autorizzazione | `GET /oauth-admin/authorize` con metodo PKCE `S256`. Un parametro `resource`, se inviato, deve corrispondere all'URL `/mcp/admin` di questo pannello. La richiesta è valida per 10 minuti ed è associata al browser che l'ha avviata. | | Consenso | Scegli gli ambiti (scope) e la durata (sopra). Il codice di autorizzazione è valido per 60 secondi e funziona una sola volta. | | Token | `POST /oauth-admin/token` restituisce un **token di accesso** (un `ak_o...` chiave, valido 1 ora o fino alla fine della connessione, a seconda di quale evento si verifichi per primo) e un **token di aggiornamento** (`akr_...`). Ogni aggiornamento restituisce un nuovo token di aggiornamento; quello vecchio smette di funzionare. La connessione termina dopo i giorni scelti. | | Revoca | **Revoke** in App connesse, oppure l'app chiama `POST /oauth-admin/revoke` (RFC 7009). | Il token di accesso si comporta come una chiave amministrativa con gli ambiti concessi: stesse regole di ambito, conferma, limite di frequenza e registro attività. Le sue chiamate compaiono nella scheda **Activity**. ## Verifica {#verify} 1. Nell'app, chiedi "run system_health" (o "what tools do you have?"). L'app elenca gli strumenti consentiti dai tuoi ambiti ([the tool list](https://nexcmp.com/it/docs/configure-with-ai/mcp-admin/#tools)). 2. Apri **Connected apps**: **Last used** si aggiorna. 3. Apri **Activity**: le chiamate sono elencate con il nome dell'app e `mcp`. ## Limiti e note {#limits-notes} - Se l'app chiede nuovamente di effettuare l'accesso dopo un'ora, è normale quando un client non esegue il refresh; riconnettiti. - Un token di refresh utilizzato due volte viene considerato rubato: l'intera connessione viene revocata. Riconnettiti dall'app. - Un codice di autorizzazione utilizzato due volte viene rifiutato (`invalid_grant`) e i token già emessi a partire da esso vengono revocate. - L'accesso OAuth non concede mai più di quanto consentito dalle regole di ambito: [what a key can never do](https://nexcmp.com/it/docs/configure-with-ai/admin-api-keys/#what-a-key-can-never-do) si applica anche alle app connesse. - I vendor modificano i propri menu e le funzionalità supportate. Se l'app di un vendor non offre connettori personalizzati sul tuo piano, usa una [admin API key](https://nexcmp.com/it/docs/configure-with-ai/admin-api-keys/) con un client desktop o a riga di comando. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | La schermata di consenso mostra "Wrong browser" | La richiesta è stata avviata in un browser diverso da quello in cui hai effettuato l'accesso | Riavvia la connessione dall'app AI nello stesso browser. | | La schermata di consenso indica che la richiesta è scaduta o mancante | Sono trascorsi più di 10 minuti oppure il link è stato aperto due volte | Riavvia la connessione dall'app AI. | | Pagina "Unknown client" o "redirect address does not match" | La registrazione dell'app non è aggiornata oppure utilizza un indirizzo di reindirizzamento non registrato | Rimuovi il connettore nell'app e aggiungilo di nuovo. | | `invalid_target` | Il `resource` inviato non corrisponde all'URL `/mcp/admin` di questo pannello | Usa l'URL esatto mostrato nella scheda **Connect an AI**. | | `invalid_request` su PKCE | Il client non invia `code_challenge_method=S256` | Usa un client che supporta OAuth 2.1 con PKCE. | | L'app si connette ma una chiamata restituisce `insufficient_scope` | Non hai selezionato quell'ambito | Revoca la connessione e connettiti di nuovo selezionando l'ambito. | | L'app non riesce a raggiungere l'URL | DNS, TLS o il reverse proxy bloccano `/mcp/admin`, `/oauth-admin/` o `/.well-known/` | Verifica le regole del proxy. | --- # 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 `. ## 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 ` | 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 ` | Applica solo questa sezione. Ripeti l'opzione per più sezioni. | | `-o ` | 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_`, 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. | --- # Prompt di esempio {#example-prompts} > **Dove si trova nell'admin:** AI Chat (`/agent`) o il pulsante mobile **Ask AI** in qualsiasi pagina di amministrazione. Gli stessi prompt funzionano in qualsiasi client AI connesso tramite [MCP](https://nexcmp.com/it/docs/configure-with-ai/mcp-admin/). ## Descrizione {#what-it-does} Questi prompt mostrano come fare richieste. Ognuno elenca cosa fa l'assistente dietro le quinte, gli ambiti necessari (per un client esterno o una chiave) e dove viene chiesta l'approvazione. Sostituisci i valori di esempio con i tuoi. ::: tip Non digitare mai un segreto nel testo della chat Per password, chiavi API e token, usa il campo **Secret** accanto all'input di AI Chat ([details](https://nexcmp.com/it/docs/configure-with-ai/ai-chat-in-admin/#secrets)). L'AI vede solo un segnaposto che rappresenta il segreto, non il valore. Con un client AI esterno il segreto passa attraverso quel client, quindi è preferibile inserirlo nell'amministrazione. ::: ## Verifica dove ti trovi {#check-where-you-are} ```text Check my setup progress and tell me the next three things to do, in order. ``` L'assistente chiama `setup_checklist` e `system_health` (ambito `admin:read`) e risponde basandosi sullo stato reale. Vedi [Setup progress checklist](https://nexcmp.com/it/docs/configure-with-ai/setup-checklist/). ## Prima configurazione {#first-setup} ```text Help me finish the initial setup. Go through the checklist, explain each open step in one sentence, ask me for what you need, and show me every change before it is applied. ``` Questo corrisponde al prompt MCP `initial-setup`. Richiede `admin:read` più gli ambiti dei passaggi accettati. Aspettati una scheda di conferma per ogni modifica in AI Chat. ## Aggiungi un cluster Proxmox VE {#add-a-proxmox-ve-cluster} ```text I want to sell servers from my Proxmox VE cluster at https://pve.example.com:8006. Add it, test the connection, create a zone called "New York" in the US, attach the cluster to it, and then propose starter plans. ``` Cosa succede: 1. L'assistente richiede l'ID del token API (`user@realm!tokenid`) e il relativo segreto. Inserisci il segreto nel campo **Secret**. Crea prima un token limitato: [Proxmox VE](https://nexcmp.com/it/docs/infrastructure/proxmox/). 2. Chiama `proxmox_add`, `proxmox_test`, `zone_create` e `proxmox_attach_zone`. 3. Propone piani con `plans_from_offerings` e attende la tua approvazione (vedi l'esempio successivo). Ambiti: `infra:write`, `secrets:write`, `catalog:write`, `admin:read`. ## Crea una tabella di piani con un margine del 40% {#create-a-plan-table-with-a-40-margin} ```text Suggest a starter plan table from my CloudStack offerings. My costs are $4 per vCPU per month, $2 per GB of RAM per month and $0.08 per GB of disk per month. Use a 40% margin, show me the table with cost, price per month and price per hour, and create the plans only after I approve. ``` L'assistente chiama `plans_from_offerings` con `margin_pct` 40 e i tuoi costi. Il margine è la quota del prezzo di vendita che rappresenta il profitto: al 40%, un piano che ti costa $60 viene venduto a $100. La prima chiamata restituisce solo un'anteprima. Quando approvi, chiama nuovamente lo strumento con `apply=true`, che crea i piani in un unico passaggio e richiede una sola conferma poiché sono coinvolti dei prezzi. Per Proxmox utilizza `backend_id` e un elenco di dimensioni predefinito (1, 2, 2 e 4 vCPU). Ambiti: `catalog:write`, `admin:read`. Vedi [Plans](https://nexcmp.com/it/docs/catalog/plans/). ![Risposta di AI Chat che mostra una tabella di anteprima dei piani con costo, prezzo mensile e prezzo orario](https://nexcmp.com/it/docs/images/configure-with-ai/example-prompts-01-plan-preview.webp) ## Configura l'email e invia un messaggio di prova {#configure-email-and-send-a-test-message} ```text Configure outgoing email with smtp.example.com, port 587, STARTTLS, user "mailer@example.com", sender name "Example Cloud", sender address "no-reply@example.com". Use my Secret field for the password "smtp_password". Then send a test email to admin@example.com. ``` L'assistente chiama `smtp_get`, `smtp_configure` e `smtp_test` e comunica se il messaggio è stato accettato. Ambiti: `settings:write`, `secrets:write`. Vedi [SMTP and e-mail templates](https://nexcmp.com/it/docs/administration/smtp-and-emails/). ## Configura Stripe {#set-up-stripe} ```text Set up Stripe in test mode. My publishable key is pk_test_XXXX. Use the secret key and the webhook secret from my Secret field (names stripe_secret_key and stripe_webhook_secret). Then test the credentials and tell me which webhook URL I must add in Stripe. ``` `payment_configure` è sempre un'azione in due passaggi: vedi un'anteprima con i valori segreti mascherati e la approvi. Dopodiché `payment_test` verifica le credenziali con Stripe. Ambiti: `billing:write`, `secrets:write`. Passa alla modalità live solo dopo un pagamento di prova. Vedi [Stripe](https://nexcmp.com/it/docs/billing/stripe/). ## Attiva gli avvisi Telegram {#turn-on-telegram-alerts} ```text Add my Telegram chat 123456789 for admin alerts. The bot token is in my Secret field as telegram_bot_token. Send a test message. ``` L'assistente chiama `telegram_configure` e `telegram_test`. Ambiti: `settings:write`, `secrets:write`. Vedi [Telegram notifications](https://nexcmp.com/it/docs/administration/telegram-notifications/). ## Trova un cliente e aggiungi credito {#find-a-customer-and-add-credit} ```text Find the customer with e-mail customer@example.com, show me their balance and servers, and add $10.00 of credit because of the outage on Monday. ``` L'assistente chiama `customers_search` e `customer_get` (sola lettura), quindi `customer_adjust_balance` con `delta_cents` 1000 e una motivazione. Questo richiede **sempre** la tua approvazione: la scheda di conferma indica "changes a customer balance" e mostra l'importo e la motivazione che verranno registrati nel log di audit. Ambiti: `admin:read`, `billing:write`. ## Esporta la mia configurazione {#export-my-configuration} ```text Export my whole configuration as YAML. Do not include secrets. Then tell me which settings differ from a typical new installation. ``` L'assistente chiama `config_export`. I segreti vengono sostituiti da riferimenti `secret://`. Salva il risultato come `nexcmp.yaml` e conservalo nel controllo di versione. Vedi [Configuration as code](https://nexcmp.com/it/docs/configure-with-ai/config-as-code/). Ambito: `admin:read`. ## Scrivi buoni prompt {#write-good-prompts} - Fornisci l'obiettivo e i fatti: nomi, prezzi, indirizzi e-mail. Non incollare segreti. - Chiedi prima un'anteprima per qualsiasi cosa che costi denaro o elimini dati. - Chiedi all'assistente di "leggere il valore corrente prima di modificarlo". Le istruzioni integrate lo dicono già. - Se una risposta sembra errata, chiedi "quale strumento hai richiamato e con quali argomenti?". Le schede degli strumenti in AI Chat mostrano entrambi. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | L'assistente dice di non avere uno strumento per qualcosa | L'ambito per quello strumento non è concesso o l'azione è preclusa all'AI | Controlla [Admin API keys](https://nexcmp.com/it/docs/configure-with-ai/admin-api-keys/#what-a-key-can-never-do), oppure fallo nell'amministrazione. | | Ti chiede di incollare una password | Il modello ha ignorato le istruzioni | Rifiuta; usa il campo Secret o inserisci il valore nell'amministrazione. | | Nulla cambia dopo "fallo" | Le modifiche sono in attesa della tua conferma | Scorri fino alla scheda di conferma e premi **Confirm**. | | I piani sono stati creati a un prezzo che non ti aspettavi | I costi o il margine nel prompt erano errati | Modifica i piani nella pagina dei piani o chiedi all'assistente di ricalcolarne il prezzo; le variazioni di prezzo richiedono conferma. | --- # Elenco di controllo per la configurazione {#setup-progress-checklist} > **Dove nell'amministrazione:** Overview › Dashboard (`/`), la scheda **Setup progress** in alto. Gli elenchi vuoti su Plans, Customers, Zones, Payments e Infrastructure mostrano lo stesso aiuto. ## Descrizione {#what-it-does} Una nuova installazione richiede dieci elementi prima che il primo cliente possa ordinare e pagare. La scheda **Setup progress** li verifica per te in base alla configurazione effettiva, mostra quanti ne sono stati completati, indica il **passaggio successivo** e collega alla pagina in cui eseguirlo. Se hai una sorgente AI connessa, **Do it for me** apre l'[AI assistant](https://nexcmp.com/it/docs/configure-with-ai/ai-chat-in-admin/) con una domanda pronta per quel passaggio. L'assistente (e qualsiasi client AI tramite [MCP](https://nexcmp.com/it/docs/configure-with-ai/mcp-admin/)) può leggere lo stesso elenco con il `setup_checklist` strumento. ## I dieci passaggi {#the-ten-steps} | # | Passaggio | Si considera completato quando | Dove lo fai | |---|---|---|---| | 1 | Licenza attiva | La licenza è attivata per il tuo dominio | System › Admin › License & updates (`/license`). Vedi [License and purchase](https://nexcmp.com/it/docs/getting-started/license-and-purchase/). | | 2 | Connetti una sorgente di infrastruttura | CloudStack è connesso oppure è stato aggiunto almeno un cluster Proxmox VE | Infrastructure › Cloud provider › Providers (`/infra/providers`). Vedi [CloudStack](https://nexcmp.com/it/docs/infrastructure/cloudstack/) e [Proxmox VE](https://nexcmp.com/it/docs/infrastructure/proxmox/). | | 3 | Crea una zona | Esiste almeno una zona | Infrastructure › Datacenter › Zone (`/infra/zones`). Vedi [Zones](https://nexcmp.com/it/docs/infrastructure/zones/). | | 4 | Template OS | Almeno un template è abilitato | Services › Virtual Machines › Plans & pricing, scheda Templates (`/vm/catalog?tab=templates`). Vedi [OS templates](https://nexcmp.com/it/docs/infrastructure/templates/). | | 5 | Crea piani | Almeno un piano è abilitato | Services › Virtual Machines › Plans & pricing (`/vm/catalog`). Vedi [Plans and pricing](https://nexcmp.com/it/docs/catalog/plans/). | | 6 | Configura i pagamenti | Stripe, PayPal, criptovalute o bonifico bancario sono configurati | Finance › Payment channels (`/payments`). Vedi [Payment channels](https://nexcmp.com/it/docs/billing/payment-channels/). | | 7 | Email (SMTP) | Le email in uscita sono configurate | System › Settings › Email (`/settings/email`). Vedi [SMTP and e-mail templates](https://nexcmp.com/it/docs/administration/smtp-and-emails/). | | 8 | Branding | È stato caricato un logo o il nome del brand è stato modificato rispetto a quello predefinito | System › Settings › Brand (`/settings/branding`). Vedi [Branding](https://nexcmp.com/it/docs/customers/branding/). | | 9 | Termini e privacy | Almeno un testo legale è stato compilato | System › Settings › Legal (`/settings/legal`). Vedi [Legal pages](https://nexcmp.com/it/docs/customers/legal/). | | 10 | Effettua un ordine di prova | Esiste almeno un ordine | Effettua un ordine come cliente nel portale clienti per verificare che tutto funzioni end-to-end; la card rimanda alla pagina Billing (`/billing`). | La card mostra `done/total` (ad esempio 6/10), una barra di avanzamento, il passaggio successivo con **Open** e, quando è connessa una sorgente AI, **Do it for me**. Clicca su un passaggio per passare alla sua pagina relativa. Accanto a un passaggio, un piccolo link apre la pagina di documentazione corrispondente; alcuni passaggi mostrano anche un dettaglio come "2 zone(s)". ![Card di avanzamento della configurazione sulla panoramica con tre passaggi su dieci completati e i pulsanti Open e Do it for me](https://nexcmp.com/it/docs/images/configure-with-ai/setup-checklist-01-card.webp) ## Utilizzo {#use-it} 1. Apri la panoramica. La card si trova in alto. Usa la freccia per comprimerla; il pannello memorizza la tua scelta nel browser. 2. Clicca su **Open** per andare alla pagina del passaggio successivo, oppure clicca su **Do it for me**. 3. Con **Do it for me** l'assistente si apre con una richiesta del tipo "Suggerisci una tabella di piani iniziali dalle mie offerte con un margine del 40%, mostrami l'anteprima prima di crearla." Rispondi alle sue domande, quindi rivedi e **Confirm** ogni card. Vedi [AI Chat in the admin](https://nexcmp.com/it/docs/configure-with-ai/ai-chat-in-admin/). 4. Quando tutti e dieci i passaggi sono completati, la card scompare. ### Elenchi vuoti {#empty-lists} Quando Plans, Customers, Zones, Payments o Infrastructure sono vuoti, la pagina mostra un blocco **Next step** con una spiegazione, un pulsante per l'azione, **Do it for me** e un link alla documentazione, in modo da non incontrare mai una tabella vuota. ![Pagina Plans vuota con una spiegazione del passaggio successivo e il pulsante Do it for me](https://nexcmp.com/it/docs/images/configure-with-ai/setup-checklist-02-empty.webp) ## Richiedilo con parole tue {#ask-for-it-in-your-own-words} La card non è necessaria. In AI Chat o in qualsiasi client AI connesso puoi chiedere: ```text Check my setup progress and take me through the open steps, one at a time. ``` Questo è anche il prompt MCP `initial-setup`. L'assistente chiama `setup_checklist`, spiega perché ogni passaggio aperto è importante, chiede le informazioni di cui ha bisogno e utilizza lo strumento corrispondente. Ambiti necessari: `admin:read` per leggere l'elenco, più l'ambito del passaggio che desideri completare. Vedi [Example prompts](https://nexcmp.com/it/docs/configure-with-ai/example-prompts/). ## Verifica {#verify} 1. Dopo aver completato un passaggio, il conteggio della card aumenta al successivo caricamento della panoramica. 2. Nell'assistente, `setup_checklist` restituisce gli stessi numeri, con `done: true` sul passaggio completato. ## Limiti e note {#limits-notes} - I controlli verificano ciò che è salvato, non se funziona. Un gateway configurato viene conteggiato come completato anche se il suo test fallisce. Usa i pulsanti **Test** su ogni pagina e lo strumento `system_health` per i problemi. - La card è riservata esclusivamente agli amministratori. - **Do it for me** richiede una sorgente AI connessa in System › Settings › AI accounts; senza di essa viene mostrato solo **Open**. - I dieci passaggi sono gli stessi per ogni installazione; un passaggio che non prevedi di utilizzare (ad esempio i pagamenti su un cloud privato) viene comunque conteggiato come aperto. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | La card è mancante | Tutti e dieci i passaggi sono completati oppure la card non è stata caricata | Ricarica la panoramica. Chiedi `setup_checklist` in AI Chat per visualizzare lo stato. | | Un passaggio rimane aperto dopo che lo hai completato | Il salvataggio non è stato completato o la condizione non è ancora soddisfatta (ad esempio un template esiste ma è disabilitato) | Apri la pagina del passaggio e controlla la tabella sopra. | | Il branding rimane aperto dopo aver cambiato il logo | Il branding viene conteggiato quando esiste un logo o il nome del brand differisce da quello predefinito "NexCMP" | Carica un logo o imposta il tuo nome. | | **Do it for me** non fa nulla | Nessuna fonte AI connessa o pannello demo | Collega una fonte in AI accounts. | --- # SMTP e template email {#smtp-and-e-mail-templates} > **Dove nell'admin:** System › Settings › Email (`/settings/email`) — tab **SMTP** e **Email templates**. Registro di consegna: Overview › Support › Sent emails (`/support/emails`). ## Descrizione {#what-it-does} NexCMP invia email per la verifica della registrazione, il reset della password, "VM ready" (con la password iniziale), fatture, credito in esaurimento, rinnovi, ricariche, risposte del supporto e altro ancora. Tutte passano attraverso **un account SMTP fornito da te**. I messaggi e i template sono disponibili in 16 lingue; viene utilizzata la lingua del cliente. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Server SMTP | Host, porta e credenziali di qualsiasi provider (il tuo server, Brevo, Amazon SES, Mailgun, Google Workspace …) | | Rete | TCP in uscita dal server NexCMP verso l'host e la porta SMTP (587 STARTTLS, 465 TLS o 25) | | Dominio mittente | Un dominio di tua proprietà, con **SPF e DKIM** pubblicati per il provider e un record DMARC | | Permesso | L'account SMTP deve essere autorizzato a inviare come indirizzo **From** | ::: warning Divergenza di consegna Le email come "VM ready" contengono password. Se SPF/DKIM/DMARC del dominio mittente non corrispondono al provider SMTP, finiscono nello spam. La pagina te lo ricorda. ::: ## Prepara il provider email {#prepare-the-e-mail-provider} 1. Nel pannello del tuo provider aggiungi e verifica il tuo dominio di invio (ad esempio `example.com`). 2. Pubblica i record DNS SPF, DKIM e DMARC indicati dal provider. 3. Crea un utente SMTP (o una chiave API-SMTP) e annota host, porta, nome utente e password. ## Collega in NexCMP {#connect-in-nexcmp} 1. Apri **System › Settings › Email**, tab **SMTP**. 2. Compila il modulo: | Campo | Esempio | Note | |---|---|---| | Host | `smtp.example.net` | Server SMTP | | Porta | `587` | | | Sicurezza | STARTTLS (587) | Scegli la modalità richiesta dal tuo provider | | Username | `smtp-user` | | | Password | (nascosto) | Sola scrittura: la pagina mostra solo se ne è impostato uno | | From email | `no-reply@example.com` | Deve essere autorizzato presso il provider | | From name | `Example Cloud` | Utilizza come predefinito il nome del tuo brand | | Reply-To (facoltativo) | `support@example.com` | Dove arrivano le risposte dei clienti | ![La tab SMTP di Settings, Email con host, porta, sicurezza, nome utente, campi mittente e il pulsante Send test](https://nexcmp.com/it/docs/images/administration/smtp-and-emails-01-smtp.webp) 3. Fai clic su **Save**, quindi su **Send test** e inserisci il tuo indirizzo. Le impostazioni sono salvate in un file ad accesso limitato (`smtp.json`, modalità 0600) e solo il worker in background `nexcmp-vmd` invia la posta; il servizio web si limita ad accodarla. ## Verifica {#verify} - Il messaggio di test arriva nella casella di posta (controlla anche lo spam). Nel codice sorgente del messaggio, conferma `dkim=pass` e `spf=pass`. - Apri **Support › Sent emails**: ogni messaggio ha uno stato (accodato, inviato, fallito) e il risultato della consegna. Per i messaggi falliti vengono effettuati fino a 3 tentativi. - Registra un cliente di prova nel portale e conferma che l'e-mail di verifica arrivi. ## Modifica i modelli di e-mail {#edit-e-mail-templates} La scheda **Email templates** elenca ogni modello per chiave, indicando le lingue in cui è disponibile (ad esempio `verify_email`, `reset_password`, `vm_ready`, `invoice_paid`, `low_balance`, `topup_received`, `ticket_reply`, `scale_up` …). 1. Fai clic su un modello e scegli una lingua. 2. Modifica l'oggetto e il corpo. I segnaposto vengono compilati quando un messaggio viene accodato. 3. Salva. La modifica si applica **immediatamente** ai messaggi accodati successivamente. ![La schermata dei modelli di e-mail con l'elenco delle chiavi e delle relative lingue](https://nexcmp.com/it/docs/images/administration/smtp-and-emails-02-templates.webp) ## Limiti e note {#limits-and-notes} - Un account SMTP per installazione. I clienti dei rivenditori ricevono le e-mail tramite lo stesso account, a meno che il rivenditore non sia configurato diversamente. - Si applicano i limiti di invio del provider; NexCMP non effettua limitazioni oltre ai nuovi tentativi. - Senza SMTP il pannello funziona, ma la verifica della registrazione e il ripristino della password non possono essere completati dai clienti. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | L'e-mail di test non arriva mai | Credenziali errate, porta bloccata, mittente non autorizzato | Controlla `journalctl -u nexcmp-vmd` per l'errore SMTP; prova la porta 587 con STARTTLS; verifica l'indirizzo From presso il provider. | | I messaggi finiscono nello spam | SPF/DKIM/DMARC mancanti o non allineati | Pubblica i record del provider e invia da quel dominio. | | "failed" in Email inviate | Il provider ha rifiutato il messaggio | Apri la riga per visualizzare la risposta del provider. | | Il campo della password sembra vuoto dopo il salvataggio | Per scelta progettuale (sola scrittura) | L'etichetta mostra "current: set" una volta memorizzata una password. | --- # Telegram e avvisi amministratore {#telegram-and-admin-alerts} > **Dove nel pannello di controllo:** System › Settings › Admin alerts (`/settings/alerts`). Scorciatoie di supporto: Customers › Support › Tickets (`/support/tickets`), scheda **Settings**. ## Descrizione {#what-it-does} NexCMP avvisa **te** — l'operatore — quando qualcosa richiede attenzione, e quando un cliente si registra o un deposito viene accreditato. Gli avvisi vengono inviati a uno o più **canali**: Telegram, un webhook o e-mail. Gli eventi inviati ai canali amministrativi includono: errore di distribuzione, VM mancante, rete non attiva, IP liberi inferiori a 30, un elemento in scadenza (avviso di 1 ora), una controversia Stripe, un worker non attivo, RAM del cluster superiore alla soglia, nuova registrazione di un cliente e depositi accreditati. Gli eventi dei clienti vengono accodati in modo persistente e ripetuti con ritardo crescente (da 30 secondi fino a 1 ora) finché Telegram non li accetta. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Telegram | Un bot creato con **@BotFather** (token) e il **chat ID** del gruppo o dell'utente che deve ricevere i messaggi | | Rete | HTTPS in uscita verso `api.telegram.org` | | Webhook (alternativa) | Un endpoint HTTPS che accetta il payload dell'avviso | ## Prepara Telegram {#prepare-telegram} 1. Su Telegram apri **@BotFather**, invia `/newbot`, scegli un nome; copia il **bot token** (`123456789:AA...`). 2. Crea un gruppo, aggiungi il bot al gruppo e invia un messaggio qualsiasi. 3. Trova la **chat ID**: apri `https://api.telegram.org/bot/getUpdates` in un browser e leggi `chat.id` (gli ID dei gruppi iniziano con `-`). ## Collega in NexCMP {#connect-in-nexcmp} 1. Apri **System › Settings › Admin alerts**. 2. In **Add channel** scegli **Type: Telegram**, imposta **Destination** sulla chat ID e **Secret (bot token)** sul token. Fai clic su **Add**. 3. Assicurati che l'interruttore **Send admin Telegram (VM module)** sia attivo; la riga *VM module status (read-only)* mostra "on". ![La pagina Admin alerts con il modulo Add channel impostato su Telegram](https://nexcmp.com/it/docs/images/administration/telegram-notifications-01-channel.webp) ## Verifica {#verify} Il canale appare sotto **Configured channels**. Attiva un evento (ad esempio registra un cliente di prova) e il messaggio arriverà nel gruppo. Se nessun canale è configurato, la pagina avvisa "Without a channel, attacks will go unnoticed" e, nel log, gli eventi di Telegram vengono registrati solo localmente. ## Scorciatoie di supporto per i clienti {#support-shortcuts-for-customers} Il widget di supporto per i clienti può mostrare i pulsanti **Telegram** e **Zalo**. Rimangono nascosti finché non vengono configurati nelle impostazioni di supporto: inserisci un `https://t.me/...` link per Telegram e il link o QR di Zalo. Sono accettati solo i link `https://`. La chat di supporto può anche notificare al tuo gruppo Telegram la domanda e una bozza di risposta — vedi [AI Chat](https://nexcmp.com/it/docs/ai/ai-chat/). ## Limiti e note {#limits-and-notes} - Il bot token viene memorizzato con il canale e non viene più mostrato. - Gli eventi di Telegram utilizzano il primo canale Telegram abilitato che dispone sia di una destinazione che di un token. ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | Nessun messaggio in arrivo | Chat ID errata, bot non presente nel gruppo o nessun messaggio inviato in precedenza al bot | Verifica nuovamente l'ID con `getUpdates`; invia prima un messaggio al bot o al gruppo. | | Funziona per un po' e poi si ferma | Token revocato in BotFather | Crea un nuovo token e aggiorna il canale. | | `Telegram: no channel` nei log | Nessun canale Telegram abilitato | Aggiungine uno come descritto sopra. | --- # Log di controllo e attività {#audit-log-and-activity} > **Dove nell'admin:** System › Logs › Activity (`/logs`), Admin actions (`/logs/admin`), Console (`/logs/console`), Login (`/logs/logins`), VM events (`/logs/vm-events`); Overview › Support › Sent emails. NexCMP registra ogni azione significativa. Utilizza la pagina **Activity** come timeline unica e le altre schede per filtrare. ## Schede {#tabs} | Scheda | Contenuto | |---|---| | **Activity** | Timeline unificata di tutte le origini: azioni amministrative, eventi delle VM, login, affiliazioni ed errori di sistema | | **Admin actions** | Modifiche effettuate dagli amministratori (ad esempio `customer.block`, `customer.delete`), con l'IP dell'amministratore | | **Console** | Accessi alla console di amministrazione e richieste di sistema, come una richiesta di aggiornamento | | setItems("**Login**"), | Accessi dei clienti e relativi tentativi falliti | | **VM events** | Fasi di distribuzione, creazione, password, eliminazione e altri eventi del ciclo di vita per singola macchina virtuale | ## Lettura di una riga {#reading-a-row} Colonne: **Time**, **Source**, **Level**, **Actor** (chi), **Target**, **Services**, **Action** (codice evento come `customer.delete`) e **Details**. Fai clic su **Open** per il record completo. ![La pagina Activity con i filtri di sorgente, sito e servizio sopra la timeline](https://nexcmp.com/it/docs/images/administration/audit-log-01-activity.webp) ## Filtra e cerca {#filter-and-search} 1. Seleziona un **source**, un **site** e un **service** dai menu a tendina. 2. Imposta un intervallo **From date** / **To date**. 3. Digita un codice evento (ad esempio `customer.block` o `destroy`) nella casella di ricerca: la ricerca attività corrisponde al codice evento. ## Conservazione ed esportazioni {#retention-and-exports} I record risiedono nei database di NexCMP in `/var/lib/nexcmp` e sono inclusi nei [backup](https://nexcmp.com/it/docs/getting-started/backup-and-restore/). La retention dipende dal log: i tentativi di accesso dei clienti più vecchi di 180 giorni e i log delle richieste API-key dei clienti più vecchi di 60 giorni vengono ripuliti. L'audit delle API-key admin conserva fino a circa 200,000 record recenti. Questi limiti non implicano la stessa retention per la timeline unificata delle attività. ## Utilizzi comuni {#common-uses} | Domanda | Dove cercare | |---|---| | Chi ha sospeso questo cliente? | Azioni amministratore, ricerca `customer.block` | | Perché è scomparsa una VM? | Eventi VM, filtra per ID della VM; anche Activity | | Il cliente ha ricevuto l'e-mail? | Overview › Support › Sent emails | | Quando è stato richiesto l'ultimo aggiornamento? | Scheda Console | --- # Sicurezza {#security} > **Dove nell'amministrazione:** System › Admin › Console security (`/account`), Admin users (`/users`); System › Settings › Customer logins (`/settings/login`). ## Console di amministrazione {#admin-console} ### Autenticazione a due fattori (TOTP) {#two-factor-authentication-totp} La console è raggiungibile da Internet, quindi attiva il TOTP. 1. Apri **System › Admin › Console security**. 2. In **Two-factor authentication (TOTP)** fai clic su **Start setup**. 3. Scansiona il codice QR con Google Authenticator, Authy, 1Password o Bitwarden, quindi inserisci il codice a 6 cifre. ### Intervalli IP consentiti per la console {#allowed-console-ip-ranges} In **Allowed console IP ranges** inserisci un IP o un CIDR (IPv4 o IPv6) per riga. **Il campo vuoto significa ovunque.** Al di fuori dell'intervallo, sia l'accesso che le API di amministrazione vengono bloccati. ::: warning Non bloccare il tuo accesso La pagina mostra il tuo IP attuale e richiede che il nuovo elenco lo includi. Usa **+ Add my IP**. Se vieni comunque bloccato, usa l'[emergency access](https://nexcmp.com/it/docs/getting-started/cli-reference/#emergency-access) dal server. ::: ### Modifica password {#change-password} Compila **Current password**, **New password** e **Confirm new password**. Usa una password lunga e univoca (12 caratteri o più; la procedura guidata di configurazione ne richiede 12 per il primo amministratore). ### Account amministratore e ruoli {#administrator-accounts-and-roles} Apri **System › Admin › Admin users** e usa **+ Create account**. | Ruolo | Accesso | |---|---| | `admin` | Accesso completo alle API di amministrazione | | `staff` | Sola lettura nell'intero sistema | | `user` | Vista di sola lettura delle risorse di un singolo cliente | L'account root è quello creato nella [setup wizard](https://nexcmp.com/it/docs/getting-started/setup-wizard/). Azioni sulle righe: **Edit**, **Reset PW**, **Key**, **Delete**. Le password vengono memorizzate come hash con salt; la modifica o il blocco di un account termina immediatamente le sue sessioni. ## Accesso cliente {#customer-sign-in} Apri **System › Settings › Customer logins**. | Impostazione | Descrizione | |---|---| | **Google sign-in** | Abilita e inserisci l'ID client e il segreto OAuth. Copia l'**Callback URL** mostrata nella pagina in *Google Cloud Console › APIs & Services › Credentials › OAuth client ID › Authorized redirect URIs*. Usa **Test configuration**. | | **GitHub login** | Lo stesso, con *GitHub › Settings › Developer settings › OAuth Apps › Authorization callback URL* | | **Passkey** | Accesso tramite impronta digitale, PIN o chiave hardware; attivo per impostazione predefinita. Le passkey sono vincolate al dominio; ogni dominio di rivenditore funziona autonomamente. Inserisci un vecchio dominio in *Legacy passkey Domain* dopo un rebranding per offrire un utile suggerimento ai clienti | | **Riautenticati quando aggiungi metodi di accesso** | Richiedi nuovamente la password prima di aggiungere una passkey o collegare Google/GitHub (disattivato per impostazione predefinita) | | **Captcha** | Cloudflare Turnstile o Google reCAPTCHA al momento della registrazione: abilita, scegli il provider, inserisci la chiave del sito e la chiave segreta | | **Block e-mail domains** | Un dominio per riga (max 2000). Gli indirizzi corrispondenti vengono rifiutati in fase di registrazione con `email_domain_blocked` | ![La pagina di accesso dei clienti che mostra il login Google con il relativo URL di callback](https://nexcmp.com/it/docs/images/administration/security-01-customer-logins.webp) ### Criteri integrati {#built-in-policies} | Policy | Valore | |---|---| | Password del cliente | Almeno 10 caratteri, lettere e cifre | | Sessione cliente | 30 giorni; le sessioni "accedi come cliente" durano 1 ora | | Verifica e-mail | Richiesta prima di creare una VM quando *require e-mail verified* è attivo nelle impostazioni di vendita | | Anti-carding | Gli account con un credito inferiore alla ricarica minima possono creare solo un numero limitato di VM | ## Rafforzamento del server {#server-hardening} - La porta 3000 viene chiusa dopo l'installazione e TLS; vedi [Installation](https://nexcmp.com/it/docs/getting-started/installation/#the-panel-port-3000). - Il servizio viene eseguito come utente non privilegiato `nexcmp` con una sandbox systemd limitata. - Chiavi API, credenziali di pagamento e password SMTP sono memorizzate crittografate; la chiave principale si trova in `/var/lib/nexcmp/secrets` — proteggi i [backups](https://nexcmp.com/it/docs/getting-started/backup-and-restore/). - Le release vengono verificate con SHA-256 e una firma Ed25519 prima dell'installazione. --- # Impostazioni generali {#general-settings} > **Dove nell'amministrazione:** System › Settings › General (`/settings`). Le modifiche hanno effetto immediato (cache di 30 secondi). La pagina è composta da tre sezioni. ## Brand e URL {#branding-urls} | Campo | Scopo | |---|---| | Nome del brand (e-mail, fatture) | Mostrato in e-mail e fatture. Logo e colori si trovano in [Branding](https://nexcmp.com/it/docs/customers/branding/) | | Lingua predefinita | Lingua per i nuovi visitatori | | URL dell'app cliente | Indirizzo pubblico del portale, ad esempio `https://cloud.example.com` | | URL della console | Indirizzo del servizio console delle VM | | URL amministratore | Link utilizzato quando effettui il login come cliente di un rivenditore | | URL della console partner | Utilizzato nei link di invito, nelle e-mail dei rivenditori e nel reindirizzamento dopo una ricarica | Il wizard li compila a partire dal tuo dominio; modificali solo se sposti il portale. ## Venditore e fatturazione {#seller-invoicing} Stampato su ogni fattura: | Campo | Esempio | |---|---| | Nome entità legale | Example Cloud Ltd | | Partita IVA | `TAX-000000` | | Indirizzo | 1 Example Street, New York | | E-mail di contatto | `billing@example.com` | | Prefisso numero fattura | `INV` (1–8 caratteri, A–Z e 0–9) | Le fatture esistenti mantengono i dettagli del venditore e il numero con cui sono state emesse; le modifiche riguardano solo le **nuove** fatture. ## Manutenzione e area geografica {#maintenance-region} Attiva **Customer app MAINTENANCE** per mostrare un banner e **bloccare tutte le azioni di scrittura dei clienti** mentre la console di amministrazione continua a funzionare. Inserisci il **Maintenance message** che vedranno i clienti. Utilizza questa funzione durante gli aggiornamenti della tua infrastruttura. ![La pagina delle impostazioni generali con i campi per nome del brand, lingua predefinita e URL](https://nexcmp.com/it/docs/images/administration/general-settings-01-general.webp) ## Altre pagine di impostazioni {#other-settings-pages} | Pagina | Guida | |---|---| | Brand | [Branding](https://nexcmp.com/it/docs/customers/branding/) | | Legal | [Legal](https://nexcmp.com/it/docs/customers/legal/) | | Customer logins | [Security](https://nexcmp.com/it/docs/administration/security/) | | Email | [SMTP e modelli di email](https://nexcmp.com/it/docs/administration/smtp-and-emails/) | | Admin alerts | [Telegram e avvisi amministrativi](https://nexcmp.com/it/docs/administration/telegram-notifications/) | | Provider IA | [AI providers](https://nexcmp.com/it/docs/ai/ai-providers/) | --- # Segnala un bug {#report-a-bug} > **Dove nell'admin:** Top bar › **Report a bug** (accanto a Docs; visibile solo all'amministratore principale). Hai riscontrato un difetto in NexCMP? Clicca su **Report a bug**, descrivi il problema e invialo. La segnalazione raggiunge il team di NexCMP come ticket sul tuo account di licenza in un unico passaggio, senza dover accedere altrove né copiare a mano i file di log. È utilizzabile con qualsiasi piano: NexCMP Free include la risoluzione dei bug, così come NexCMP Source. ::: info Le segnalazioni di bug non sono richieste di supporto NexCMP Free non include il supporto tecnico, quindi usa questo modulo solo per i difetti del software. L'assistenza per la configurazione e le migrazioni fa parte di [NexCMP Source](https://nexcmp.com/pricing). ::: ## Requisiti {#requirements} | Elemento | Requisiti | |---|---| | Versione | NexCMP 1.5.2 o successivo | | Chi può inviare | L'account amministratore principale. Gli account dello staff (sola lettura), le console reseller, i clienti e la demo in sola lettura non possono inviare | | Licenza | Una licenza attiva (Free o Source) non sospesa | | Rete | Il server deve poter raggiungere `https://nexcmp.com` tramite HTTPS (lo stesso indirizzo utilizzato per la verifica delle licenze e gli aggiornamenti) | ## Invia una segnalazione {#send-a-report} 1. Fai clic su **Report a bug** nella barra superiore. Da smartphone, apri il menu e scegli **Report a bug**. 2. Inserisci un breve **Subject**. 3. In **What happened**, descrivi cosa hai fatto, cosa hai riscontrato e cosa ti aspettavi. 4. Facoltativamente, elenca gli **Steps to reproduce**. 5. Scegli l'**Impact**: **Blocking** (lavoro bloccato), **Major** (funzionalità principale non funzionante) o **Minor** (problema minore o cosmetico). 6. Lascia abilitato **Attach diagnostics** (consigliato) e consulta il riquadro **What will be sent**. 7. Fai clic su **Send report**. Nella versione 1.6.1 il corpo del modulo scorre mentre i pulsanti di azione rimangono visibili, anche da smartphone. I valori delle password che seguono `password:` o `password=` vengono mascherati senza rimuovere il resto della segnalazione. Controlla il testo prima dell'invio ed escludi dati dei clienti e credenziali. ![La finestra di dialogo Report a bug con titolo, descrizione, impatto e l'elenco dei dati inviati](https://nexcmp.com/it/docs/images/administration/report-a-bug-01-dialog.webp) Quando la segnalazione viene accettata, la finestra di dialogo mostra il numero del ticket e un link. Le eventuali risposte del team verranno inviate all'indirizzo email del tuo account di licenza su nexcmp.com; inoltre, il ticket sarà visibile nella sezione **Support** dopo aver effettuato l'accesso come titolare della licenza. ## Cosa viene inviato {#what-is-sent} Il riquadro **What will be sent** mostra esattamente queste informazioni prima di fare clic su Send: | Dati inviati | Dettagli | |---|---| | Il tuo testo | Titolo, descrizione, passaggi e impatto | | Versione, piano, dominio | La tua versione di NexCMP, Free o Source, e il dominio dell'installazione | | Pagina corrente | La pagina su cui ti trovi nell'admin, senza nulla dopo `?` o `#` | | Browser | Lo user-agent del tuo browser (nome, versione e sistema operativo), troncato a 200 caratteri | | Errori recenti | Fino agli ultimi 5 errori in questa scheda del browser. Per un errore di script viene inviato solo il messaggio; per una richiesta non riuscita, solo il metodo, il percorso e il codice di stato | Puoi disattivare **Attach diagnostics**; in tal caso verranno inviati solo il testo inserito, la versione, il piano e il dominio. ## Cosa non viene mai inviato {#what-is-never-sent} - Password, token, cookie e chiavi API. Tutto ciò che ne ha l'aspetto nel testo o in un messaggio di errore viene mascherato (mostrato come `***` o `[redacted]`) sul tuo server prima dell'invio. - Il contenuto di richieste e risposte — le richieste non riuscite vengono registrate solo come metodo, percorso e stato. - I dati dei tuoi clienti (nomi, email, ordini, fatture) e i loro indirizzi IP. - L'indirizzo IP del tuo browser e qualsiasi file dal tuo server. Come per ogni controllo della licenza, il server delle licenze vede l'indirizzo IP da cui il tuo server si connette. Il ticket è collegato alla tua installazione tramite il token di licenza già presente sul server, pertanto la versione, il dominio e l'installazione sono impostati dal server e non possono essere modificati dal browser. ## Limiti {#limits} | Limite | Valore | |---|---| | Oggetto | 150 caratteri | | Descrizione più passaggi | 8 KB complessivi | | Report | 5 all'ora e 20 al giorno per l'intera installazione | L'invio della stessa segnalazione due volte (ad esempio dopo un errore di rete) non crea un secondo ticket. ## Troubleshooting {#troubleshooting} | Messaggio | Causa | Soluzione | |---|---|---| | Attiva prima la licenza | L'installazione non ha una licenza attivata | Apri **License & updates** e attiva, quindi invia di nuovo | | Impossibile raggiungere il server delle licenze | Il server non riesce a raggiungere `nexcmp.com` | Verifica HTTPS e DNS in uscita dal server, quindi premi nuovamente **Send report** — il testo viene mantenuto | | Troppe segnalazioni di bug da questa installazione | Hai raggiunto 5 all'ora o 20 al giorno | Attendi e riprova; aggiungi invece i nuovi riscontri al ticket aperto | | Questa licenza è sospesa | La licenza è sospesa o rimborsata | Vedi [Licenza e acquisto](https://nexcmp.com/it/docs/getting-started/license-and-purchase/) | | Questa installazione è stata revocata | L'installazione è stata revocata nel portale delle licenze | Attivala di nuovo da **License & updates** | | Impossibile rinnovare il token di licenza | Il server non è riuscito a rinnovare il proprio token di licenza | Apri **License & updates**, premi **Refresh**, quindi invia di nuovo | | Nessun pulsante Report a bug | Hai effettuato l'accesso con un account staff, reseller o cliente, oppure sulla demo di sola lettura | Accedi come amministratore principale | ::: tip Per l'assistente AI e le chiavi API L'assistente nell'admin e le chiavi API admin non possono inviare segnalazioni di bug per tuo conto: il pulsante richiede l'accesso di una persona come amministratore principale. ::: --- # Errori di installazione {#installation-errors} L'installatore si ferma al primo problema bloccante e stampa una riga rossa che inizia con `✗`. Risolvi la causa ed **esegui nuovamente lo stesso comando**; l'installatore può essere ripetuto in sicurezza. Le righe informative iniziano con `•`, i passaggi riusciti con `✓`. ## Controlli della macchina {#machine-checks} | Messaggio | Causa | Soluzione | |---|---|---| | `must be run as root (sudo)` | Esecuzione non come root | Anticipa il comando con `sudo` oppure esegui come root. | | `only Ubuntu 22.04/24.04 is supported (this host: …)` | Altra distribuzione o versione | Utilizza un server Ubuntu 22.04 o 24.04. | | `only x86_64 is supported` | ARM o altra CPU | Utilizza un server x86_64. | | `requires ≥ 2 GB RAM (host has … MB)` | Memoria insufficiente | Aggiungi RAM. | | `requires ≥ 8 GB free disk space on / (… GB available)` | File system root quasi pieno | Libera spazio o espandi `/`. | | `missing --license` / `missing --domain` | Prima installazione senza questi parametri | Passa entrambi — vedi [Installation](https://nexcmp.com/it/docs/getting-started/installation/#parameters). | | `unknown argument: …` | Errore di digitazione in un parametro | Verifica l'ortografia; esegui con `--help`. | | `apt-get failed (another apt/dpkg process, e.g. unattended-upgrades, may still be running)` | Il gestore pacchetti è bloccato | Attendi qualche minuto (un'Ubuntu appena installata esegue gli aggiornamenti automatici dopo il boot) e riavvia. | | `… is a symlink — aborting` | `/opt/nexcmp` o `/etc/nexcmp` è un collegamento simbolico | Sostituiscilo con una directory reale; per motivi di sicurezza, il programma di installazione rifiuta i link simbolici. | ## Attivazione della licenza {#license-activation} | Messaggio | Causa | Soluzione | |---|---|---| | `cannot connect to https://nexcmp.com` | Nessuna connessione HTTPS in uscita verso il server di licenza | Verifica DNS, firewall e proxy sul server: `curl -I https://nexcmp.com`. | | `license activation failed (HTTP …): ` | Il server di licenza ha rifiutato la chiave | Leggi il messaggio: chiave errata, dominio non corrispondente alla licenza, licenza sospesa o revocata. Controlla la pagina della licenza su [nexcmp.com/licenses](https://nexcmp.com/licenses). | | `no release available for this license yet` | La licenza non ha alcuna release scaricabile | Contatta l'ufficio vendite; consulta [Support](https://nexcmp.com/it/docs/troubleshooting/support/). | ## Download e verifica {#download-and-verification} | Messaggio | Causa | Soluzione | |---|---|---| | `failed to download release X` | Problema di rete durante il download | Riavvia. | | `sha256 mismatch (… ≠ …)` | Il file è arrivato danneggiato o è stato alterato | Riavvia; se il problema persiste, un proxy potrebbe alterare i download — prova da un'altra rete. | | `release X is unsigned — refusing to install` | Il server non ha fornito alcuna firma | Non ignorarla mai; contatta il supporto. | | `INVALID SIGNATURE for version X — aborting` | La firma Ed25519 non è verificabile | Non installare **mai**. Contatta il supporto: significa che il file non è una release ufficiale. | | `openssl failed to read public key` | OpenSSL molto vecchio o danneggiato | Aggiorna il pacchetto `openssl`. | | `invalid version: …` | Dati inattesi dal server | Riavvia; contatta il supporto se il problema persiste. | ## Avvio del servizio {#service-start} | Messaggio | Causa | Soluzione | |---|---|---| | `service failed to start — check: journalctl -u nexcmp -n 50` | Il pannello non ha risposto a `/healthz` entro 3 minuti | Leggi il journal. Cause comuni: la porta (predefinita 3000) è già in uso (`ss -ltnp | grep 3000`) — re-installa con `--port`; file di proprietà di root in `/var/lib/nexcmp` — esegui `sudo nexcmp fix-owner`. | ## nginx e TLS {#nginx-and-tls} | Messaggio | Causa | Soluzione | |---|---|---| | `DNS does not point to (nor to Cloudflare) — skipping nginx/TLS` | Il record A/AAAA è mancante o errato | Consulta [DNS and Cloudflare](https://nexcmp.com/it/docs/getting-started/dns-and-cloudflare/), quindi riavvia. | | `certbot could not get a certificate yet — re-run the installer once DNS has settled` | Validazione Let's Encrypt non riuscita (porta 80 bloccata, DNS non propagato, limite di richieste) | Apri la porta 80, attendi la propagazione del DNS e riavvia. Controlla `/var/log/letsencrypt/letsencrypt.log`. | | `certbot could not renew now — keeping the existing certificate` | Errore di rinnovo temporaneo | Ininfluente; riavvia più tardi. | | `nginx rejected the HTTPS configuration — kept the previous one (check: nginx -t)` | Conflitto con un altro sito nginx (stesso `server_name`, impostazioni duplicate) | Esegui `sudo nginx -t` e risolvi il conflitto, quindi riavvia. | | `apt-get could not install nginx` / `certbot` oppure `E: Failed to fetch … 404 Not Found` | Package manager bloccato o indice dei pacchetti del server non aggiornato (tipico di un'immagine di un template non aggiornata da tempo) | Esegui `sudo apt-get update`, attendi il completamento di eventuali altri processi apt, quindi riavvia l'installazione. | | `openssl could not create the self-signed certificate` | Problema con OpenSSL | Aggiorna `openssl` e riavvia. | ## Dopo l'installazione {#after-installation} | Sintomo | Causa | Soluzione | |---|---|---| | Il browser non riesce ad aprire `https://` | DNS o TLS non pronti | `sudo nexcmp status`; usa [emergency access](https://nexcmp.com/it/docs/getting-started/cli-reference/#emergency-access). | | `ERR_TOO_MANY_REDIRECTS` | Modalità SSL di Cloudflare **Flexible** | Imposta su **Full (strict)** — [dettagli](https://nexcmp.com/it/docs/getting-started/dns-and-cloudflare/). | | Il wizard indica che il codice di configurazione non è corretto | Errore di battitura o codice di un'installazione precedente | Esegui `sudo nexcmp status` e copia il codice corrente. | | La licenza restituisce HTTP 421 | File in `/var/lib/nexcmp` di proprietà di root | `sudo nexcmp fix-owner`, poi `sudo systemctl restart nexcmp`. | --- # Errori di aggiornamento {#update-errors} > **Dove nel pannello di amministrazione:** System › Admin › License & updates (`/license`) Gli aggiornamenti sono descritti in [Updating NexCMP](https://nexcmp.com/it/docs/getting-started/updating/). Quando la scheda Aggiorna o `sudo nexcmp update` segnala un errore: | Messaggio | Causa | Soluzione | |---|---|---| | `update plan expired — renew on the license page to receive this feature release` | La data "aggiornamenti fino a" è precedente alla data di rilascio. Le correzioni di sicurezza vengono comunque ricevute, le nuove funzioni no | Rinnova su [nexcmp.com/licenses](https://nexcmp.com/licenses) ($99 all'anno per NexCMP Free), quindi controlla di nuovo. Nel frattempo il software continua a funzionare. | | `sha256 mismatch (downloaded …, expected …)` | Download danneggiato o alterato | Riprova. Se il problema persiste, controlla i proxy lungo il percorso. | | `downgrade/same version rejected: X is not newer than Y` | La versione selezionata non è più recente di quella in esecuzione | Nessuna operazione necessaria: il software è aggiornato. | | `extraction failed / main binary missing` | Archivio danneggiato o disco pieno | Controlla `df -h`; riprova. | | `systemctl restart failed` | Impossibile riavviare il servizio dopo la sostituzione del file binario | `journalctl -u nexcmp -n 80`; il file binario precedente viene conservato come `/opt/nexcmp/bin/nexcmp.bak` — vedi il rollback sotto. | | Errore del server durante il contatto con il server di aggiornamento | Nessuna route verso `nexcmp.com` o token di licenza scaduto | Controlla l'HTTPS in uscita; fai clic su **Check now** nella scheda della licenza. | ## Rollback {#roll-back} Se una nuova versione non si comporta correttamente: ```bash sudo systemctl stop nexcmp-vmd nexcmp sudo cp /opt/nexcmp/bin/nexcmp.bak /opt/nexcmp/bin/nexcmp echo | sudo tee /opt/nexcmp/VERSION sudo systemctl start nexcmp nexcmp-vmd ``` Se è già stata eseguita una migrazione del database, ripristina anche il [backup](https://nexcmp.com/it/docs/getting-started/backup-and-restore/) effettuato prima dell'aggiornamento. ## `sudo nexcmp update` indica che non è possibile trovare il programma di installazione {#sudo-nexcmp-update-says-it-cannot-find-the-installer} `nexcmp update` esegue il programma di installazione incluso nella release installata (`/opt/nexcmp/releases//share/install.sh`). Se quel file manca, esegui nuovamente il comando di installazione dalla pagina della licenza. --- # FAQ {#faq} ## Licenze {#licensing} **Cosa succede se la licenza scade o il server perde la connessione a Internet?** Il token rimane valido per 14 giorni e si rinnova quotidianamente. Dopodiché, i clienti non possono creare **nuovi** servizi; i servizi in esecuzione, la fatturazione e i login continuano a funzionare. Vedi [License and purchase](https://nexcmp.com/it/docs/getting-started/license-and-purchase/). **Continuo a ricevere le correzioni di sicurezza dopo la scadenza del diritto di aggiornamento?** Sì, le release di sicurezza vengono sempre rilasciate, mentre le release di nuove funzioni richiedono un diritto attivo. **Posso eseguire NexCMP su un secondo server o dominio?** Attivalo con la chiave e il dominio registrati sulla licenza — vedi [License and purchase](https://nexcmp.com/it/docs/getting-started/license-and-purchase/#moving-to-a-new-server-or-domain). ## Installazione {#installation} **NexCMP richiede Docker, PostgreSQL o Redis?** No. È un singolo programma con database SQLite, eseguito da systemd come utente senza privilegi. Vedi [Requirements](https://nexcmp.com/it/docs/getting-started/requirements/). **Posso installare senza un dominio pubblico?** Sì, usa `--no-nginx` e un tunnel SSH — vedi [Installation](https://nexcmp.com/it/docs/getting-started/installation/#installing-without-a-public-domain-lab-or-test). **Perché la porta 3000 è chiusa dopo la configurazione?** Per motivi di sicurezza, il pannello rimane in ascolto su `127.0.0.1` una volta completato il wizard e attivato il TLS. Usa `sudo nexcmp open-port` per le emergenze. ## Infrastruttura {#infrastructure} **Posso usare insieme CloudStack e Proxmox VE?** Sì. Una zona può averli entrambi; ogni piano sceglie la sua origine. Vedi [Proxmox VE](https://nexcmp.com/it/docs/infrastructure/proxmox/) e [Zones](https://nexcmp.com/it/docs/infrastructure/zones/). **Ho bisogno della chiave API ROOT di CloudStack?** No, e non dovresti usarla. Crea un account dedicato — [CloudStack](https://nexcmp.com/it/docs/infrastructure/cloudstack/). **Perché alcune schede o pulsanti non compaiono su una macchina virtuale?** Le pagine mostrano solo ciò che la sorgente della VM supporta (ad esempio, Proxmox VE non ha il port forwarding). Vedi la tabella delle funzionalità in [Proxmox VE](https://nexcmp.com/it/docs/infrastructure/proxmox/). ## Operations {#operations} **Come posso spostare NexCMP su un altro server?** Esegui un backup, installa la stessa versione sul nuovo server con la stessa licenza, ripristina — vedi [Backup and restore](https://nexcmp.com/it/docs/getting-started/backup-and-restore/). **Dove si trovano i log?** `journalctl -u nexcmp -u nexcmp-vmd`, `/var/log/nexcmp` e la console di amministrazione alla voce System › Logs. Vedi [Audit log](https://nexcmp.com/it/docs/administration/audit-log/). **Posso vedere il portale clienti prima di installare?** Sì. Le pagine dei servizi su [nexcmp.com](https://nexcmp.com/platform/) mostrano il portale clienti scheda per scheda con dati di esempio; apri *View demo* per il visualizzatore a schermo intero. Per vedere un'installazione reale, scrivi al team vendite. --- # Support {#support} ## Contact {#contact} Non è presente alcun modulo di contatto. Invia un'e-mail a **sales@nexcmp.com** per questioni relative a licenze, rinnovi, domini e domande tecniche. La pagina della tua licenza su [nexcmp.com/licenses](https://nexcmp.com/licenses) rimanda anch'essa allo stesso indirizzo. ## Prima di scrivere {#before-you-write} 1. Cerca in questa documentazione (premi `/`) e consulta [Installation errors](https://nexcmp.com/it/docs/troubleshooting/installation-errors/) e [Update errors](https://nexcmp.com/it/docs/troubleshooting/update-errors/). 2. Raccogli le informazioni elencate di seguito: consentiranno al supporto di rispondere in un'unica soluzione. ## Cosa includere {#what-to-include} | Elemento | Come ottenerlo | |---|---| | Versione di NexCMP | `sudo nexcmp status` o System › Admin › License & updates | | Dominio principale e ultimi 4 caratteri della chiave di licenza | License & updates (non inviare mai la chiave completa) | | Cosa hai fatto e cosa ti aspettavi | Passaggi esatti | | Il testo dell'errore o uno screenshot | Nascondi i dati sensibili prima dell'invio | | Stato del servizio | `sudo nexcmp status` | | Righe di log recenti | `sudo journalctl -u nexcmp -u nexcmp-vmd -n 100 --no-pager` | | Infrastruttura | Versione di CloudStack o Proxmox VE, una zona o più zone | ::: warning Non inviare mai dati sensibili Non inviare chiavi di licenza, chiavi API, password, il codice di configurazione, credenziali di pagamento o archivi di backup. Oscurali nei log e negli screenshot. ::: ## Segnalazioni di sicurezza {#security-reports} Se ritieni di aver trovato una vulnerabilità, invia un'e-mail allo stesso indirizzo con oggetto "Security" ed evita di pubblicare i dettagli pubblicamente prima che venga risolta.