跳转到主要内容

​
通用指南

在开始升级流程之前务必备份数据库，运行： 
docker exec -it {db_container_name_or_id} pg_dumpall -U {postgres_user} > databases_backup.sql
从备份恢复： 
cat databases_backup.sql | docker exec -i {db_container_name_or_id} psql -U {postgres_user}
如果您使用 Docker Compose，请按照以下步骤操作：
  1. 停止 Twenty：docker compose down
  2. 在与 docker-compose.yml 同目录的 .env 文件中更改 TAG 值
  3. 启动 Twenty：docker compose up -d
服务器在启动时会自动运行所有所需的升级迁移。 无需手动执行任何命令。

​
跨版本升级（v1.22+）

自 v1.22 起，Twenty 支持跨版本升级。 您可以从任意受支持的版本直接跳到最新版本，而无需逐一经过每个中间版本。 例如，从 v1.22 直接升级到 v2.0 完全受支持。

​
升级到 v2.5+ — 静态数据加密信封

从 v2.5 开始，Twenty 会将静态存储的机密（OAuth 令牌、应用程序变量、签名密钥的私钥、敏感配置值、TOTP 机密）存储在带版本的 enc:v2: 加密信封中，并使用 ENCRYPTION_KEY（如果未设置 ENCRYPTION_KEY，则使用 APP_SECRET）进行加密。 在 v2.5 的首次启动时会运行较慢的升级命令，将现有行回填到新的加密信封中。 这些命令是幂等的——中断并重新启动服务器后会从上次停止的位置恢复——但在大型数据库上可能需要一段时间才能完成。 你可以使用 upgrade:status 来监控进度。 你应该在 v2.5 升级之前设置专用的 ENCRYPTION_KEY，这样回填从一开始就会在该密钥下写入行。 在回填完成后再更换密钥，则需要进行一次轮换。

​
轮换机密和签名密钥

对于日常运维任务，例如轮换 ENCRYPTION_KEY、轮换 JWT 签名密钥或吊销泄露的签名密钥，请参阅专门的密钥轮换指南。

​
检查升级状态

upgrade:status 命令可用于查看您的实例和工作区迁移的当前状态。 这在调试升级问题或提交支持请求时非常有用。 在服务器容器中运行： 
docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status
示例输出: 
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)

​
选项

标志描述
-w, --workspace-id <id>筛选特定工作区。 可多次传递。
-f, --failed-only隐藏已是最新的工作区，仅显示落后和失败的条目。

​
故障排除

如果某些工作区的升级失败，服务器将不会越过失败的步骤继续进行。 重启服务器（docker compose up -d）将从中断处重试升级。 要快速定位问题，运行： 
docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status --failed-only
这将仅显示落后或失败的工作区，并附上每个失败的错误信息。

​
v1.22 之前

如果您的实例早于 v1.22，您必须按顺序逐步升级经过每个主要标记版本（从 v1.6 到 v1.7，再从 v1.7 到 v1.8，依此类推），直到达到 v1.22。 届时，您可以直接跳到最新版本。