升级指南 - Twenty Documentation

通用指南

在开始升级流程之前务必备份数据库，运行：

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，请按照以下步骤操作：

停止 Twenty：docker compose down
在与 docker-compose.yml 同目录的 .env 文件中更改 TAG 值
启动 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。届时，您可以直接跳到最新版本。

​通用指南

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

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

​轮换机密和签名密钥

​检查升级状态

​选项

​故障排除

​v1.22 之前