# Aggiornamento

> Aggiorna un'installazione a una nuova release e cosa cambiare quando passi dalla 2.1.0 alla 2.2.0.

Un aggiornamento sostituisce le immagini di PentAGI e, quando la release le ha modificate, i file compose. I tuoi `.env` e i volumi dei dati rimangono, e le migrazioni del database vengono eseguite all’avvio di PentAGI.

## [Prima di iniziare](https://pentagi.com/it/docs/deployment/upgrade/#before-you-start)

* Leggi le [note di rilascio](https://pentagi.com/changelog/) di ogni versione successiva a quella che esegui; dalla 2.1.0 includono note di aggiornamento.
* Esegui il backup del database. Né l’installer né PentAGI lo fanno, e le migrazioni non possono essere annullate senza perdere dati. Con le impostazioni predefinite `PENTAGI_POSTGRES_USER` e `PENTAGI_POSTGRES_DB`:

  ```bash
  docker exec pgvector pg_dump -U postgres -Fc pentagidb > pentagi-backup.dump
  ```

  Conserva anche copie di `.env` e dei file compose: l’installer sostituisce i file compose senza crearne un backup.
* Completa i [flow](https://pentagi.com/it/docs/glossary/#flow) che non ti servono più. Un [sandbox](https://pentagi.com/it/docs/glossary/#sandbox) ancora in esecuzione viene riutilizzato così com’è stato creato, con le impostazioni della release che lo ha creato.
* Se provieni dalla 2.1.0, apporta le modifiche indicate in [Da 2.1.0 a 2.2.0](#from-210-to-220) a `.env` e ai file adiacenti prima dell’avvio della nuova release. Con l’accesso tramite Google o GitHub attivo, svuota ora `OAUTH_GOOGLE_CLIENT_ID` e `OAUTH_GITHUB_CLIENT_ID`; la sezione spiega il motivo.

## [Docker Compose](https://pentagi.com/it/docs/deployment/upgrade/#docker-compose)

1. Scarica i file compose della nuova release accanto al tuo `.env`: `docker-compose.yml` e il file di ogni stack opzionale che esegui. Il container PentAGI riceve solo le variabili elencate nel suo file compose, quindi le nuove impostazioni in `.env` non hanno effetto se usi un file più vecchio.

   ```bash
   cd ~/pentagi
   curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/main/docker-compose.yml
   # and the file of each optional stack you run, for example:
   curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/main/docker-compose-langfuse.yml
   ```

2. Effettua il pull delle immagini e riavvia, usando gli stessi file `-f` con cui avvii lo stack. Senza `pull`, `up -d` mantiene le immagini già presenti sull’host.

   ```bash
   docker compose pull && docker compose up -d
   ```

3. Aggiorna l’immagine del sandbox sull’host Docker che esegue i flow, operazione che `docker compose pull` non esegue. I flow creati successivamente la utilizzeranno.

   ```bash
   docker pull vxcontrol/kali-linux
   ```

Il tag dell’immagine `latest` segue il branch principale. Per rimanere su una singola release, imposta `PENTAGI_IMAGE=vxcontrol/pentagi:<version>` in `.env`.

## [Installer](https://pentagi.com/it/docs/deployment/upgrade/#installer)

1. Scarica l’installer della nuova release da [Quick start](https://pentagi.com/it/docs/getting-started/quickstart/) ed eseguilo con il tuo `.env`. L’installer 2.1.0 non può aggiornare se stesso.
2. Per sostituire i file compose, modifica un’impostazione in modo che **Apply Changes** appaia nel menu, selezionalo e rispondi `y` quando l’installer elenca i file non aggiornati.
3. Nel menu di manutenzione, esegui **Update PentAGI** per effettuare il pull delle nuove immagini e **Update Worker Image** quando viene offerto. **Update PentAGI** da solo mantiene i vecchi file compose.

## [Da 2.1.0 a 2.2.0](https://pentagi.com/it/docs/deployment/upgrade/#from-210-to-220)

### [File](https://pentagi.com/it/docs/deployment/upgrade/#files)

* Il file compose monta `example.bedrock.provider.yml` accanto a sé. L’installer lo crea; in un’installazione manuale crealo tu stesso, un file vuoto è sufficiente: `touch example.bedrock.provider.yml`.
* Sostituisci `docker-compose-langfuse.yml` se esegui Langfuse: il file 2.1.0 fa riferimento all’immagine `minio/minio`, che non viene più pubblicata, quindi `docker compose pull` fallisce con essa. Se il tuo `.env` imposta `MINIO_IMAGE=minio/minio:…`, rimuovi quella riga.
* Per il [knowledge graph](https://pentagi.com/it/docs/glossary/#knowledge-graph), inserisci `examples/neo4j` dal repository in `./neo4j` — Graphiti necessita del suo plugin APOC — e consulta [Memory and knowledge](https://pentagi.com/it/docs/concepts/memory/#knowledge-graph-optional) per i preset dei modelli. `GRAPHITI_MODEL_NAME` non viene più letto.
* Otto migrazioni del database vengono eseguite al primo avvio. `docker compose logs pentagi` mostra "Database schema updated successfully" quando sono completate.

### [Accesso e autenticazione](https://pentagi.com/it/docs/deployment/upgrade/#sign-in-and-access)

* Tutti devono accedere nuovamente: le sessioni della versione 2.1.0 vengono rifiutate. I token API continuano a funzionare e gli script effettuano il logout con `POST /api/v1/auth/logout`.
* Un token API riceve un errore 403 sulle route REST `/users`, `/roles` e `/tokens`: gestisci account, ruoli e token da una sessione browser autenticata.
* L’accesso con Google e GitHub ora associa un’e-mail verificata dal [provider](https://pentagi.com/it/docs/glossary/#provider) all’account esistente con quell’indirizzo, inclusi gli account locali, mantenendo il ruolo di quell’account. La versione 2.1.0 non può modificare l’e-mail di un account, quindi se l’accesso è attivo, esegui l’aggiornamento con `OAUTH_GOOGLE_CLIENT_ID` e `OAUTH_GITHUB_CLIENT_ID` vuoti, sposta `admin@pentagi.com` su un indirizzo sotto il tuo controllo in **Settings → Account**, quindi riattiva l’accesso. La funzione **Reset Admin Password** dell’installer trova l’amministratore solo tramite `admin@pentagi.com`.
* Dietro un reverse proxy, imposta `TRUSTED_PROXIES`, altrimenti ogni utente condivide l’indirizzo del proxy e un picco di tentativi di accesso falliti blocca tutti per 15 minuti — vedi [Network exposure](https://pentagi.com/it/docs/configuration/security/#network-exposure).

### [Sandbox](https://pentagi.com/it/docs/deployment/upgrade/#sandboxes)

* Con `DOCKER_INSIDE=true` — il template `.env` predefinito della versione 2.1.0 e dell’installer — la versione 2.1.0 montava il socket Docker dell’host in ogni sandbox. La versione 2.2.0 fornisce agli [agent](https://pentagi.com/it/docs/glossary/#agent) Docker solo da un daemon separato impostato in `DOCKER_INSIDE_HOST`; senza di esso non ne ricevono alcuno e il log riporta `sandbox DISABLED`. Con `DOCKER_INSIDE_HOST`, imposta `DOCKER_SOCKET=` vuoto, altrimenti il `/var/run/docker.sock` del template viene ancora montato. Vedi [Worker node](https://pentagi.com/it/docs/deployment/worker-node/).
* Completa i flow avviati sulla versione 2.1.0: i loro sandbox mantengono il vecchio mount del socket e le capacità fino al termine del flow.
* Lascia `TENANT_ID` vuoto: su un’installazione esistente punta PentAGI verso uno schema nuovo e vuoto.

### [Modelli e prompt](https://pentagi.com/it/docs/deployment/upgrade/#models-and-prompts)

* Il provider personalizzato richiede `LLM_SERVER_KEY`: con una chiave vuota è disabilitato, quindi per un server senza autenticazione imposta qualsiasi valore non vuoto.
* `LLM_SERVER_LEGACY_REASONING` è stato rimosso. Il provider personalizzato invia `reasoning_effort` e converte un budget `reasoning.max_tokens` in un livello di sforzo; sui modelli Kimi K2, GLM precedenti alla 5.2 e MiniMax M un budget ora fa fallire la chiamata, quindi rimuovilo da quegli agent.
* Nei file di configurazione del provider, una voce agent che lascia vuoti `max_tokens`, `temperature`, `top_p` o `n` ora ottiene i valori predefiniti del tipo di provider invece di non inviare nulla.
* I modelli predefiniti integrati sono cambiati per ogni provider tranne Bedrock; i provider salvati in **Settings → Providers** mantengono i loro modelli. Cinque configurazioni incluse nell’immagine hanno cambiato modelli — `openrouter`, `deepinfra`, `ollama-cloud`, `moonshot` e `deepseek`. Se `LLM_SERVER_CONFIG_PATH` o `OLLAMA_SERVER_CONFIG_PATH` punta a uno di essi sotto `/opt/pentagi/conf/`, mantieni il file 2.1.0 sull’host e montalo come configurazione personalizzata o Ollama.
* Con `EMBEDDING_URL` su un server diverso da quello di OpenAI, imposta `EMBEDDING_KEY`: `OPEN_AI_KEY` non viene più inviato lì.
* Gli agent cercano attraverso un unico [tool](https://pentagi.com/it/docs/glossary/#tool) `web_search`. I prompt personalizzati con `{{.GoogleToolName}}` e le altre variabili per motore vengono ignorati, con un avviso nel log, finché non utilizzano `{{.WebSearchToolName}}`; aggiorna i prompt personalizzati per searcher e pentester basandoti sui nuovi valori predefiniti.

### [Altre modifiche](https://pentagi.com/it/docs/deployment/upgrade/#other-changes)

* Entro due minuti dall'avvio e poi ogni tre ore, PentAGI segnala la sua versione e un riepilogo dell’installazione a `update.pentagi.com`; [Update check](https://pentagi.com/it/docs/configuration/security/#update-check) elenca ciò che viene inviato e `UPDATE_CHECK_INTERVAL=0` lo disattiva.
* Il profiler non ascolta più sulla porta 7777 a meno che `PPROF_ADDR` non sia impostato.
* Le nuove impostazioni opzionali includono [provider failover](https://pentagi.com/it/docs/configuration/llm-providers/#failover) con `LLM_FALLBACK_PROVIDER`, `DOCKER_PORTS_BASE` per [several instances](https://pentagi.com/it/docs/deployment/production/#several-instances-tenant_id), `DOCKER_IMAGE_SELECTION_MODE` e `DOCKER_ALLOWED_IMAGES`, il motore di ricerca interno `WEB_SEARCH_INTERNAL_ENABLED` e le chiavi Mistral, xAI, MiniMax e Firecrawl.

## [Backup e rollback](https://pentagi.com/it/docs/deployment/upgrade/#back-up-and-roll-back)

PentAGI non esegue mai le migrazioni all’indietro ed eseguirle manualmente elimina i dati, quindi il modo per tornare alla versione 2.1.0 è il backup. Arresta i servizi che usano il database, ricrealo e ripristina il dump:

```bash
docker compose stop pentagi pgexporter
docker exec pgvector dropdb -U postgres pentagidb
docker exec pgvector createdb -U postgres pentagidb
docker exec -i pgvector pg_restore -U postgres -d pentagidb < pentagi-backup.dump
```

Poi ripristina i file `.env` e compose salvati, imposta `PENTAGI_IMAGE=vxcontrol/pentagi:2.1.0` e avvia lo stack. Mantieni il nuovo `docker-compose-langfuse.yml`: l’immagine MinIO del file 2.1.0 non può più essere scaricata.