Linee guida generali
Esegui sempre un backup del database prima di iniziare la procedura di aggiornamento eseguendo:- Arresta Twenty:
docker compose down - Modifica il valore di
TAGnel file.envnella stessa directory didocker-compose.yml - Avvia Twenty:
docker compose up -d
Prefisso della cache Redis
REDIS_CACHE_PREFIX è facoltativo e per impostazione predefinita è una stringa vuota. Lasciarlo vuoto preserva esattamente i nomi delle chiavi della cache esistenti, senza due punti aggiuntivi né migrazione delle chiavi.
Per le distribuzioni Redis Enterprise o Azure Managed Redis che segnalano errori CROSSSLOT durante le operazioni di cache, imposta REDIS_CACHE_PREFIX={twenty-cache} su ogni comando del server, del worker e di aggiornamento. Le parentesi graffe fanno sì che tutte le chiavi di archiviazione della cache condividano uno slot hash Redis. Questo non distribuisce i dati della cache tra gli shard. REDIS_QUEUE_PREFIX si applica solo alle code e rimane separato.
Ad esempio, engine:workspace:flatObjectMetadataMaps:123:hash diventa {twenty-cache}:engine:workspace:flatObjectMetadataMaps:123:hash solo quando quel prefisso è configurato. cache:flush utilizza automaticamente il prefisso configurato.
La modifica del prefisso passa a uno spazio dei nomi della cache separato. Arresta tutti i server e i worker di Twenty prima di modificarlo, quindi riavviali con lo stesso valore. Le voci esistenti con il prefisso precedente rimangono inalterate. Se riutilizzi un prefisso usato in precedenza, esegui yarn command:prod cache:flush con tale valore prima del riavvio per rimuovere le voci obsolete. Le distribuzioni rolling con valori di prefisso diversi non sono supportate.
Aggiornamento alla v2.34+ — PostgreSQL 15 minimo
Twenty v2.34 richiede PostgreSQL 15 o una versione successiva. La configurazione ufficiale di Docker Compose utilizza PostgreSQL 16. Se la tua istanza si connette a un database gestito esternamente, aggiornalo prima di avviare il server v2.34.Aggiornamenti tra versioni (v1.23+)
A partire da v1.23, Twenty supporta gli aggiornamenti tra versioni. Puoi passare direttamente da qualsiasi versione supportata all’ultima versione senza dover attraversare ogni versione intermedia. Ad esempio, l’aggiornamento da v1.23 direttamente a v2.0 è pienamente supportato.Aggiornamento alla v2.5+ — envelope di crittografia dei dati a riposo
A partire dalla v2.5, Twenty memorizza i segreti a riposo (token OAuth, variabili dell’applicazione, chiavi private di firma, valori di configurazione sensibili, segreti TOTP) all’interno di un envelope versionatoenc:v2: crittografato con ENCRYPTION_KEY (o APP_SECRET se ENCRYPTION_KEY non è impostata).
Il primo avvio su v2.5 esegue comandi di aggiornamento lenti che popolano retroattivamente le righe esistenti nel nuovo envelope. Sono idempotenti — se si interrompe e si riavvia il server, riprende da dove si era interrotto — ma possono richiedere tempo su database di grandi dimensioni. Puoi monitorare l’avanzamento con upgrade:status.
Dovresti impostare un ENCRYPTION_KEY dedicato prima dell’aggiornamento a v2.5, in modo che il popolamento retroattivo scriva fin dall’inizio le righe sotto tale chiave. Cambiare chiave dopo il popolamento retroattivo richiede una rotazione.
Rotazione di segreti e chiavi di firma
Per le attività operative quotidiane come ruotareENCRYPTION_KEY, ruotare la chiave di firma JWT o revocare una chiave di firma compromessa, vedi la Guida alla rotazione delle chiavi dedicata.
Verifica dello stato dell’aggiornamento
Il comandoupgrade:status consente di ispezionare lo stato corrente della tua istanza e delle migrazioni degli spazi di lavoro. È utile per eseguire il debug di problemi di aggiornamento o quando si apre una richiesta di assistenza.
Eseguilo dal container del server:
Opzioni
Risoluzione dei problemi
Se l’aggiornamento non riesce su alcuni spazi di lavoro, il server non proseguirà oltre il passaggio in cui si è verificato l’errore. Riavviando il server (docker compose up -d), l’aggiornamento verrà riprovato dal punto in cui era stato interrotto.
Per identificare rapidamente i problemi, esegui: