103 lines
4.0 KiB
Plaintext
103 lines
4.0 KiB
Plaintext
---
|
||
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。 届时，您可以直接跳到最新版本。
|