Tolgee平台从v1升级到v3.72.0的配置迁移指南

背景介绍

Tolgee是一款开源的本地化平台，随着版本迭代，其配置方式从v1到v3发生了显著变化。许多用户在升级过程中遇到了配置迁移的问题，特别是从传统的.env文件配置转向更现代的YAML配置方式时。

核心问题分析

在从Tolgee v1升级到v3.72.0的过程中，主要存在以下配置问题：

1. 数据库连接配置冲突：同时配置了嵌入式PostgreSQL和外部PostgreSQL数据库
2. 认证机制失效：升级后系统认证功能无法正常工作
3. 配置加载顺序问题：系统未能正确识别新的YAML配置文件

配置迁移解决方案

1. 数据库配置优化

在v3版本中，Tolgee提供了更灵活的数据库配置选项。正确的做法是：

spring:
  datasource:
    url: jdbc:postgresql://db:5432/postgres
    username: your_username
    password: your_password
tolgee:
  postgres-autostart:
    enabled: false  # 必须明确禁用嵌入式数据库

关键点：

• 确保只使用一种数据库连接方式
• 如果使用外部数据库，必须显式禁用嵌入式数据库
• 数据库连接参数必须与实际的PostgreSQL服务配置匹配

2. 认证配置

认证配置需要单独设置：

tolgee:
  authentication:
    enabled: true  # 确保认证功能开启
  front-end-url: https://your_domain.com

3. Docker Compose配置

正确的Docker Compose配置应包含：

version: '3'

services:
  app:
    image: tolgee/tolgee:latest
    volumes:
      - ./data:/data
      - ./config.yaml:/config.yaml
    ports:
      - "8258:8080"
    environment:
      spring.config.additional-location: file:///config.yaml
    depends_on:
      - db
  db:
    image: postgres:13
    environment:
      POSTGRES_DB: postgres
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    volumes:
      - ./data/postgres:/var/lib/postgresql/data

常见错误排查

1. 角色不存在错误：确保数据库用户有正确的权限
2. 连接失败：检查数据库服务是否正常运行
3. 配置未生效：确认YAML文件路径和格式正确

最佳实践建议

1. 升级前备份所有数据
2. 分阶段测试配置变更
3. 监控日志以识别潜在问题
4. 逐步淘汰旧的.env配置方式

通过遵循这些指南，用户可以顺利完成从Tolgee v1到v3的配置迁移，确保系统稳定运行。