Twenty项目自托管升级指南：从备份到版本迁移全流程

前言

对于使用Twenty项目进行自托管的用户来说，系统升级是保证功能完整性和安全性的重要环节。本文将全面介绍Twenty项目的升级流程，包括通用指南和版本特定的升级步骤，帮助管理员顺利完成系统升级。

通用升级指南

数据库备份

在进行任何升级操作前，必须完整备份数据库。这是升级过程中最重要的安全措施。

使用以下命令备份PostgreSQL数据库：

docker exec -it <数据库容器名称或ID> pg_dumpall -U <PostgreSQL用户名> > databases_backup.sql

如需恢复备份，执行：

cat databases_backup.sql | docker exec -i <数据库容器名称或ID> psql -U <PostgreSQL用户名>

Docker Compose升级流程

1. 停止运行中的Twenty服务：

docker compose down

2. 修改.env文件中的TAG值为目标版本（推荐使用主次版本号如v0.53）

3. 重新启动服务：

docker compose up -d

重要提示：如需跨多个版本升级（如从v0.33.0到v0.35.0），必须按顺序逐个版本升级（先到v0.34.0，再到v0.35.0）。

版本特定升级说明

v1.0版本

Twenty项目迎来v1.0里程碑版本！这是一个重要的稳定版本。

v0.60版本

性能优化

• 元数据API交互全面优化
• 重构缓存策略，优先使用缓存而非数据库查询
• 如遇运行时问题，可执行缓存刷新：

yarn command:prod cache:flush

v0.55版本

升级至v0.55镜像后，系统将自动处理所有必要的迁移操作，无需手动执行命令。

权限错误处理

如升级后出现"User does not have permission"错误，需刷新权限缓存：

yarn command:prod cache:flush

v0.54版本

从v0.53开始，升级过程已自动化：

• 元数据模式已合并至核心模式
• 迁移命令已整合至升级流程，不建议手动执行

v0.53+版本

重要变更：

• 升级流程已集成至Dockerfile
• 必须按顺序升级，不可跳过中间版本
• 检查工作区版本：查看core.workspace表中的版本号
• 移除了auditLog标准对象，可显著减小备份体积

历史版本升级命令汇总

版本范围	升级命令
v0.51→v0.52	yarn database:migrate:prod yarn command:prod upgrade
v0.50→v0.51	同上
v0.44→v0.50	同上
v0.43→v0.44	同上
v0.42→v0.43	同上

PostgreSQL 16迁移指南

v0.42→v0.43版本涉及数据库镜像变更：

1. 从旧容器导出数据：

docker exec -it twenty-db-1 sh 
pg_dump -U {用户名} -d {数据库名} > databases_backup.sql
exit
docker cp twenty-db-1:/home/postgres/databases_backup.sql .

2. 更新docker-compose.yml使用postgres:16镜像

3. 导入数据至新容器：

docker cp databases_backup.sql twenty-db-1:/databases_backup.sql
docker exec -it twenty-db-1 sh
psql -U {用户名} -d {数据库名} -f databases_backup.sql
exit

环境变量变更历史

• v0.42.0：移除FRONT_PORT等，新增FRONTEND_URL等
• v0.41.0：移除AUTH_MICROSOFT_TENANT_ID
• v0.40.0：新增IS_EMAIL_VERIFICATION_REQUIRED等
• v0.35.0：ENABLE_DB_MIGRATIONS改为DISABLE_DB_MIGRATIONS
• v0.34.0：前端URL处理方式变更
• v0.32.0：Redis连接方式简化，JWT令牌处理简化

升级问题排查

1. 工作区版本不同步：按顺序重新执行升级流程
2. 权限问题：执行缓存刷新命令
3. 数据库迁移失败：检查备份完整性后重试
4. 环境变量冲突：对照版本说明更新配置

最佳实践建议

1. 建立定期备份机制
2. 在测试环境验证升级流程
3. 关注版本发布说明中的重大变更
4. 保持升级的及时性，避免累积多个版本
5. 升级后全面测试核心功能

通过遵循本指南，您可以确保Twenty项目的升级过程平稳顺利，充分利用新版本带来的性能改进和功能增强。