103 lines
4.9 KiB
Plaintext
103 lines
4.9 KiB
Plaintext
---
|
|
title: Guia de atualização
|
|
icon: arrow-up-right-dots
|
|
---
|
|
|
|
## Diretrizes gerais
|
|
|
|
**Sempre faça backup do seu banco de dados antes de iniciar o processo de atualização** executando:
|
|
|
|
```bash
|
|
docker exec -it {db_container_name_or_id} pg_dumpall -U {postgres_user} > databases_backup.sql
|
|
```
|
|
|
|
Para restaurar a partir de um backup:
|
|
|
|
```bash
|
|
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](/l/pt/developers/self-host/capabilities/key-rotation).
|
|
|
|
## 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](/l/pt/developers/self-host/capabilities/key-rotation) 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:
|
|
|
|
```bash
|
|
docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status
|
|
```
|
|
|
|
Exemplo de saída:
|
|
|
|
```sh
|
|
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ção | Descrição |
|
|
| ------------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
| `-w, --workspace-id <id>` | Restringe a um espaço de trabalho específico. Pode ser passada várias vezes. |
|
|
| `-f, --failed-only` | Oculta 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:
|
|
|
|
```bash
|
|
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.
|