---
title: 升级指南
icon: arrow-up-right-dots
---

## 通用指南

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

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

从备份恢复：

```bash
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`，这样回填从一开始就会在该密钥下写入行。 在回填完成后再更换密钥，则需要进行一次[轮换](/l/zh/developers/self-host/capabilities/key-rotation)。

## 轮换机密和签名密钥

对于日常运维任务，例如轮换 `ENCRYPTION_KEY`、轮换 JWT 签名密钥或吊销泄露的签名密钥，请参阅专门的[密钥轮换指南](/l/zh/developers/self-host/capabilities/key-rotation)。

## 检查升级状态

`upgrade:status` 命令可用于查看您的实例和工作区迁移的当前状态。 这在调试升级问题或提交支持请求时非常有用。

在服务器容器中运行：

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

示例输出:

```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)
```

### 选项

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

## 故障排除

如果某些工作区的升级失败，服务器将不会越过失败的步骤继续进行。 重启服务器（`docker compose up -d`）将从中断处重试升级。

要快速定位问题，运行：

```bash
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。 届时，您可以直接跳到最新版本。