Salta al contenuto
IT
Ottieni NexCMP gratis

Guida

Come aggiungere un chatbot di supporto AI e un agente SSH a un cloud CloudStack

NexCMP è un portale clienti e sistema di billing self-hosted per Apache CloudStack e Proxmox VE. La versione 1.2.0 include due moduli di intelligenza artificiale: AI Chat, un assistente integrato nel portale clienti, e AI Agent, che esegue attività sulla VM del cliente via SSH. Questa guida spiega come configurare entrambi con una chiave API compatibile con OpenAI, tramite screenshot del portale clienti e della console di amministrazione.

Ottieni NexCMP gratisGuarda la demo

Tempo necessario: circa 15 minuti su un'installazione NexCMP esistente.

Lo stack

Quattro componenti, tre dei quali probabilmente già in uso.

  • NexCMP 1.2.0

    Il pannello che i tuoi clienti usano già, installato su Ubuntu 22.04 o 24.04. AI Chat e AI Agent sono inclusi nella licenza — nessun costo aggiuntivo.

  • Un endpoint compatibile con OpenAI

    Qualsiasi API di chat completion che supporti il tool (function) calling: un provider gestito o un proxy configurato a monte di diversi provider.

  • Una chiave con limite di spesa

    Assegna al pannello una chiave dedicata e imposta un budget mensile presso il provider o nel proxy, per evitare consumi incontrollati.

  • Le tue VM CloudStack

    AI Agent accede alla VM del cliente tramite SSH dal server del pannello, utilizzando le credenziali salvate dal cliente per quella VM.

Passo dopo passo

  1. Aggiorna il pannello alla versione 1.2.0

    Nella console di amministrazione apri License e premi Update, oppure esegui sudo nexcmp update sul server. L'aggiornamento è firmato e verificato prima dell'installazione.

  2. Crea una chiave API con limite di spesa

    Presso il tuo provider AI (o nel proxy) crea una chiave dedicata esclusivamente a questo pannello e assegna un budget mensile. Un modello rapido ed economico è sufficiente per la chat di supporto.

  3. Inseriscila in Admin › Settings › AI provider

    Incolla l'URL dell'endpoint, la chiave e il nome del modello, quindi premi Test connection. La chiave viene memorizzata in modo crittografato nel database del pannello e non verrà mai più mostrata.

  4. Attiva il modulo AI

    In License › Modules attiva AI. AI Chat e AI Agent appariranno nel menu del portale clienti dopo aver ricaricato la pagina; disattivando il modulo verranno nascosti di nuovo.

  5. I clienti chiedono a AI Chat

    AI Chat risponde a domande su piani e prezzi e sui servizi del cliente. Quando una richiesta richiede l'intervento di una persona, il cliente può trasferire la conversazione al tuo team di supporto.

    Portale clienti, AI Chat risponde a una domanda sui server del cliente

  6. I clienti eseguono AI Agent su una VM

    Il cliente seleziona una delle proprie VM e descrive l'attività in linguaggio naturale. L'agente esegue i comandi via SSH e mostra ciascun comando con il relativo output.

    Portale clienti, AI Agent che esegue comandi su una VM e ne mostra l'output

  7. Monitora i consumi

    I consumi vengono fatturati dal tuo provider AI, non da NexCMP. Controlla la spesa sulla dashboard del provider o del proxy e adatta il budget della chiave man mano che i clienti adottano la funzionalità.

Cosa serve prima di iniziare

  • NexCMP 1.2.0 o successivo, con il modulo AI in License › Modules.
  • Un provider AI con un endpoint chat/completions compatibile con OpenAI e un modello che supporti il tool calling (chiamata di funzioni): vanno bene OpenAI, OpenRouter, un gateway LiteLLM o il proprio server vLLM.
  • Per AI Agent, openssh-client sul server del pannello (l'installer lo aggiunge automaticamente) e una route di rete dal server del pannello alla porta SSH di ciascuna VM, di default la 22.
  • Per AI Agent, una VM Linux appartenente al cliente, avviata e non bloccata, con credenziali memorizzate (salvate alla creazione della VM o al reset della password) o la chiave operativa del pannello. Le VM Windows vengono rifiutate.
  • Opzionale per il passaggio a un operatore in AI Chat: un bot Telegram e il chat ID in Settings › Admin alerts.
ssh -V
nc -vz 198.51.100.10 22

Testa prima l'endpoint dal server del pannello

NexCMP aggiunge /chat/completions a un URL che termina con /v1, e /v1/chat/completions a qualsiasi altro URL; un URL che termina già con /chat/completions viene utilizzato così com'è. Prima di inserire l'endpoint, invia una richiesta dal server NexCMP. Una risposta JSON con choices[0].message.content indica che endpoint e modello funzionano.

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"}]}'

Come AI Agent esegue i comandi e cosa non eseguirà autonomamente

  • I comandi vengono eseguiti dal server del pannello con il proprio client ssh, un comando non interattivo alla volta. La destinazione è sempre l'indirizzo IP della VM presente nel database, mai quello ricavato dalla richiesta.
  • La password salvata viene passata tramite un helper SSH_ASKPASS monouso nell'ambiente del processo: non viene scritta su disco né inserita nella riga di comando.
  • L'output di ciascun comando è limitato a 200 KB, un turno termina dopo un massimo di 10 passaggi e un cliente può avere al massimo 2 esecuzioni dell'agente attive contemporaneamente.
  • In modalità Confirm ogni comando attende che il cliente prema Run. In modalità Auto solo i comandi inclusi in un rigido elenco di sola lettura, come df -h, ps o journalctl, vengono eseguiti automaticamente.
  • I comandi che sovrascrivono o eliminano file, modificano account o chiavi SSH, inviano dati a un server esterno, scaricano ed eseguono uno script, oppure arrestano o riavviano la macchina mostrano sempre Needs confirmation, anche in modalità Auto.
  • L'output dei comandi viene presentato al modello come dato non attendibile e le istruzioni trovate al suo interno non vengono eseguite.

Risoluzione dei problemi

I messaggi più frequenti e cosa verificare.

  • Test connection fallisce con 401

    Causa probabile
    La chiave non è corretta per quell'endpoint.
    Cosa fare
    Verifica la chiave e l'endpoint, e reinserisci la chiave se hai modificato l'URL di base.

  • Test connection fallisce con 404 o model not found

    Causa probabile
    Percorso o ID del modello errati.
    Cosa fare
    Verifica che l'URL di base termini con /v1 e usa l'ID esatto del modello del provider.

  • Il portale non mostra alcun menu AI

    Causa probabile
    Il modulo è disattivato oppure il provider non è abilitato come attivo.
    Cosa fare
    Attiva il modulo AI in License › Modules e abilita il provider.

  • L'Agent non è riuscito ad accedere

    Causa probabile
    Nessuna password salvata e nessuna chiave operativa per quella VM.
    Cosa fare
    Reimposta la password della VM nel portale per salvarla nuovamente.

  • Il server non ha risposto in tempo

    Causa probabile
    Un firewall, SSH non in ascolto o una VM occupata.
    Cosa fare
    Esegui nc -vz <vm-ip> 22 dal server del pannello e avvia sshd nella VM.

  • L'IA risponde troppo lentamente

    Causa probabile
    Il provider o il modello è lento.
    Cosa fare
    Usa un modello più veloce o un Reasoning effort inferiore in Settings › AI provider.

  • Accedi per utilizzare AI Chat

    Causa probabile
    Il visitatore non ha effettuato l'accesso.
    Cosa fare
    Previsto: AI Chat è riservato esclusivamente ai clienti che hanno effettuato l'accesso.

Privacy e costi

Le domande dei clienti e i dati che l'IA legge per quel cliente (in sola lettura) vengono inviati al tuo provider AI. È necessario specificarlo nella tua informativa sulla privacy.

NexCMP non conteggia i costi dell'IA. Utilizza le funzionalità di budget del tuo provider e riduci l'impostazione dei turni AI al giorno per cliente (40 come valore predefinito, in Customers › Support › Ticket › AI settings) per limitare la spesa.

Passaggi successivi

AI Chat e AI Agent rimangono disattivati finché non salvi una chiave del provider, quindi non ti verrà addebitato nulla né inviato alcun dato prima che tu lo decida. Leggi la panoramica o scopri gli altri moduli.

Domande sui moduli AI

Quali modelli AI sono supportati?
Qualsiasi modello accessibile tramite un endpoint chat-completions compatibile con OpenAI che supporti il tool (function) calling. Puoi configurare endpoint, chiave e modello in Admin › Settings › AI provider.
L'agente può accedere ai server di altri clienti?
No. AI Agent funziona solo sulle VM appartenenti all'account del cliente che ha effettuato l'accesso, utilizzando le credenziali salvate per quella VM.
NexCMP applica costi per l'AI?
No. I moduli AI sono inclusi nella licenza. Paghi direttamente al tuo provider AI l'utilizzo della chiave configurata.
Come posso testare la connessione al provider AI?
In Admin › Settings › AI provider fai clic su Save, poi su Test connection. Verrà inviata una breve richiesta e verrà mostrato Connected con il nome del modello e il tempo impiegato, oppure l'errore restituito dal provider.
AI Agent ha bisogno di un gateway SSH separato?
No. Nell'installazione predefinita il pannello utilizza il proprio client ssh. Il terminale web opzionale ssh-proxy viene impiegato solo quando la funzionalità web SSH è abilitata.
I visitatori non autenticati possono utilizzare AI Chat?
No. AI Chat è riservato esclusivamente ai clienti che hanno effettuato l'accesso; a un visitatore non autenticato viene richiesto di accedere prima.
AI Agent funziona sulle VM Windows?
No. Funziona sulle VM Linux attive; le VM Windows vengono rifiutate.
Posso disattivarlo?
Sì. Disattiva il modulo AI in License › Modules; AI Chat e AI Agent scompariranno dal portale e la loro API risponderà indicando che il modulo è disabilitato.

Riferimenti

Specifiche citate in questa guida.

Aggiungi l'IA al tuo cloud

AI Chat e AI Agent sono inclusi in ogni licenza NexCMP — gratis per il primo anno, oppure $499 una tantum con il codice sorgente.

Ottieni NexCMP gratisContatta il reparto venditeGuarda la demo

Ultimo aggiornamento: