企业官网建设流程全解析

如何升级 Twenty 自托管实例？备份数据库、修改 Docker 镜像 TAG 并检查 upgrade:status

【免费下载链接】twentyThe open alternative to Salesforce, designed for AI.项目地址: https://gitcode.com/GitHub_Trending/tw/twenty

如果你用 Docker Compose 自托管了一套 Twenty CRM 实例，现在想升到新版本，整个过程的核心动作只有三个：先备份数据库，再把.env里的镜像TAG改成目标版本，最后用upgrade:status命令确认迁移是否全部完成。Twenty 的服务器会在启动时自动执行所有升级迁移，不需要手动跑迁移命令。本文基于仓库内的 Upgrade guide 和 Docker Compose 指南，适用于通过 Docker Compose 部署、工作目录里有docker-compose.yml和.env文件的实例。

升级前确认版本适用条件

在动手之前，先根据当前版本确认三条适用条件，它们决定了你升级前还要做什么：

• v1.23 起支持跨版本升级。从 v1.23 开始可以直接从任一受支持版本跳到最新 release，无需逐个经过中间版本，例如从 v1.23 直接升到 v2.0 是官方支持的。
• 如果你的实例早于 v1.23，必须按每个大版本逐步升级（v1.6 到 v1.7，再到 v1.8，依此类推）直到 v1.23，之后才能直接跳到最新版。
• v2.34 起要求 PostgreSQL 15 或更高。官方 Docker Compose 配置使用的是 PostgreSQL 16（见 docker-compose.yml 中db服务的image: postgres:16）。如果你的实例连接的是外部托管的数据库，要在启动 v2.34 服务器之前先把数据库升到 PostgreSQL 15+。
• 升到 v2.5 或更高版本前建议先设置专用的ENCRYPTION_KEY。从 v2.5 开始，Twenty 把静态存储的密钥（OAuth token、应用变量、签名私钥、敏感配置值、TOTP 密钥等）存入带版本号的enc:v2:信封，用ENCRYPTION_KEY（未设置时回退到APP_SECRET）加密。v2.5 首次启动会运行较慢的升级命令，把已有行回填进新信封；这些命令是幂等的，中断后重启会从断点续跑，但大数据库上可能耗时较长。在升级前设置好ENCRYPTION_KEY，回填的行从一开始就会写在这把密钥下；回填完成后再换密钥则需要走 密钥轮换流程。

第一步：备份数据库

官方升级指南的第一条总则是：开始升级流程前一定要备份数据库。运行：

docker exec -it {db_container_name_or_id} pg_dumpall -U {postgres_user} > databases_backup.sql

其中{db_container_name_or_id}换成你的 PostgreSQL 容器名或容器 ID，{postgres_user}换成实际的 Postgres 用户。官方 Docker Compose 里db服务的POSTGRES_USER默认取PG_DATABASE_USER，未设置时为postgres。Docker Compose 指南 里的备份示例写法是：

docker exec twenty-postgres pg_dump -U postgres twenty > backup_$(date +%Y%m%d).sql

注意两处差异：它针对具体库twenty用pg_dump（升级指南用pg_dumpall导出全部），容器名写作twenty-postgres（取决于实际容器命名，以你机器上docker ps看到的为准）。

如果升级出问题需要回滚，从备份恢复：

cat databases_backup.sql | docker exec -i {db_container_name_or_id} psql -U {postgres_user}

第二步：修改 .env 中的镜像 TAG

Twenty 的 Docker Compose 配置里，server 和 worker 两个服务的镜像都是twentycrm/twenty:${TAG:-latest}，版本由.env文件里的TAG变量控制（参见 .env.example 的第一行TAG=latest）。升级步骤就是：

1. 停止 Twenty：

   docker compose down

2. 修改与docker-compose.yml同目录的.env文件，把TAG值改为目标版本，例如：

   TAG=v2.34.0

   具体版本号以 Docker Hub 上twentycrm/twenty仓库的 tag 为准；install.sh脚本拉取最新稳定版时就是从这个仓库的 tag 列表里取的。

3. 启动 Twenty：

   docker compose up -d

服务器启动后会自动运行所有必需的升级迁移，无需手动执行任何迁移命令。

第三步：用 upgrade:status 检查升级状态

upgrade:status命令用于检查实例和各 workspace 的迁移状态，适合在升级后做最终确认，也适合排查升级问题或提交支持请求时使用。从服务器容器内运行：

docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status

{server_container_name_or_id}替换为你的 Twenty server 容器名或容器 ID。文档给出的示例输出如下（文档示例，实际版本号、workspace 名和时间以你的实例为准）：

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)

输出分三部分：Instance是实例级迁移状态，每个 workspace 一段，最后Summary汇总。升级完成的判断依据就是Summary中的统计——实例Up to date，且没有 behind 或 failed 的 workspace。

该命令支持两个参数：

升级失败时的处理

如果升级在某些 workspace 上失败，服务器不会越过失败步骤继续。官方给出的处理方式是重启服务器重试，升级会从断点续跑：

docker compose up -d

要快速定位问题，只列出落后或失败的 workspace 及其错误信息：

docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status --failed-only

边界与参考

• 升级期间如果数据库是外部托管而非官方 compose 内的postgres:16镜像，PostgreSQL 15+ 这条硬要求需要你在启动新版服务器前自行满足。
• 升级 v2.5+ 后如果发现密钥是在回填之后才换的，需要按 Key rotation guide 的secret-encryption:rotate流程（v2.6+ 提供）处理，不要在事后直接改ENCRYPTION_KEY。
• 日常备份建议（定期备份、异地存储等）见 Docker Compose 指南的 Backup and Restore 一节；更复杂的排障问题见 Troubleshooting。

【免费下载链接】twentyThe open alternative to Salesforce, designed for AI.项目地址: https://gitcode.com/GitHub_Trending/tw/twenty