Saltar para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.twenty.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Diretrizes gerais

Sempre faça backup do seu banco de dados antes de iniciar o processo de atualização executando: 
docker exec -it {db_container_name_or_id} pg_dumpall -U {postgres_user} > databases_backup.sql
Para restaurar a partir de um backup: 
cat databases_backup.sql | docker exec -i {db_container_name_or_id} psql -U {postgres_user}
Se você usa o Docker Compose, siga estas etapas:
  1. Pare o Twenty: docker compose down
  2. Altere o valor de TAG no arquivo .env que está no mesmo diretório do seu docker-compose.yml
  3. Inicie o Twenty: docker compose up -d
O servidor executa automaticamente todas as migrações de atualização necessárias na inicialização. Nenhum comando manual é necessário.

​
Atualizações entre versões (v1.22+)

A partir da v1.22, o Twenty oferece suporte a atualizações entre versões. Você pode pular diretamente de qualquer versão compatível para a versão mais recente sem passar por cada versão intermediária. Por exemplo, a atualização da v1.22 diretamente para a v2.0 é totalmente suportada.

​
Atualizando para a v2.5+ — envelope de criptografia em repouso

A partir da v2.5, Twenty armazena segredos em repouso (tokens OAuth, variáveis de aplicação, chaves privadas de chaves de assinatura, valores de configuração sigilosos, segredos TOTP) dentro de um envelope versionado enc:v2: criptografado com ENCRYPTION_KEY (ou APP_SECRET se ENCRYPTION_KEY não estiver definido). A primeira inicialização na v2.5 executa comandos de atualização lentos que preenchem retroativamente as linhas existentes no novo envelope. Eles são idempotentes — interromper e reiniciar o servidor retoma do ponto em que parou —, mas podem demorar em bancos de dados grandes. Você pode monitorar o progresso com upgrade:status. Você deve definir uma ENCRYPTION_KEY dedicada antes da atualização para a v2.5, para que o preenchimento retroativo grave as linhas sob ela desde o início. Trocar as chaves após o preenchimento retroativo exige uma rotação.

​
Rotação de segredos e chaves de assinatura

Para tarefas operacionais do dia a dia, como rotacionar a ENCRYPTION_KEY, rotacionar a chave de assinatura JWT ou revogar uma chave de assinatura vazada, consulte o guia de rotação de chaves dedicado.

​
Verificando o status da atualização

O comando upgrade:status permite inspecionar o estado atual da sua instância e das migrações dos espaços de trabalho. É útil para depurar problemas de atualização ou ao abrir uma solicitação de suporte. Execute-o a partir do contêiner do servidor: 
docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status
Exemplo de saída: 
APP_VERSION: v1.23.0

Instance
    Inferred version: 1.23.0
    Latest command:   1.23.0_DropWorkspaceVersionColumnFastInstanceCommand_1785000000000
    Status:           Up to date
    Executed by:      v1.23.0
    At:               2026-04-16T11:43:58.823Z

Workspace
  Apple (20202020-1c25-4d02-bf25-6aeccf7ea419)
      Inferred version: 1.23.0
      Latest command:   1.23.0_UpdateGlobalObjectContextCommandMenuItemsCommand_1780000005000
      Status:           Up to date
      Executed by:      v1.23.0
      At:               2026-04-16T11:44:09.361Z

Summary
    Instance: Up to date
    Workspaces: 1 up to date, 0 behind, 0 failed (1 total)

​
Opções

OpçãoDescrição
-w, --workspace-id <id>Restringe a um espaço de trabalho específico. Pode ser passada várias vezes.
-f, --failed-onlyOculta os espaços de trabalho atualizados; mostra apenas os que estão desatualizados e os com falha.

​
Resolução de Problemas

Se a atualização falhar em alguns espaços de trabalho, o servidor não avançará além da etapa com falha. Reiniciar o servidor (docker compose up -d) tentará novamente a atualização a partir de onde parou. Para identificar rapidamente os problemas, execute: 
docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status --failed-only
Isso mostra apenas os espaços de trabalho que estão desatualizados ou com falha, juntamente com a mensagem de erro de cada falha.

​
Antes da v1.22

Se a sua instância for anterior à v1.22, você deve atualizar incrementalmente por cada versão principal marcada (da v1.6 para a v1.7, depois da v1.7 para a v1.8 e assim por diante) até chegar à v1.22. A partir daí, você pode pular diretamente para a versão mais recente.