Tolgee 配置详解：application.properties 与环境变量逐项生效验证

本篇为配置篇，承接 Tolgee 单机安装实战：Ubuntu 22.04 + OpenJDK 25 + jar + systemd 的安装结果；组件定位与选型背景见 Tolgee 是什么：自托管国际化翻译管理平台的认知与选型。

一、配置体系总览

1.1 三种配置方式与优先级

Tolgee 服务端基于 Spring Boot，完全遵循其配置标准（来源：docs.tolgee.io "Server configuration"，2026-10-28 查询）。可用的三种方式按优先级从高到低：

命令行参数：java -jar tolgee-3.241.1.jar --server.port=8081（启动参数实测见运维篇）；
环境变量：Spring 风格 relaxed binding，server.port 写成 SERVER_PORT，spring.datasource.url 写成 SPRING_DATASOURCE_URL；
配置文件：jar 同目录 application.properties（官方推荐，自动加载，无需额外参数），也可用 --spring.config 指定其他路径。

同键冲突时高优先级覆盖低优先级。本篇在 v3.241.1 / Ubuntu 22.04.5 LTS 实测环境（承接安装篇的 systemd 形态）逐项验证：每种方式都真实改过、真实重启、真实验证过结果，实测时间 2026-10-28。

1.2 配置项的四大前缀

前缀	归属	典型项
`server.`	Web 服务器	`server.port`（默认 8080）
`spring.`	Spring 框架	`spring.datasource.url/username/password`
`tolgee.`	Tolgee 业务	`tolgee.authentication.`、`tolgee.file-storage.`、`tolgee.telemetry.*`
`tolgee.machine-translation.*`	机器翻译	`tolgee.machine-translation.google.api-key` 等

二、环境变量方式：/etc/default/tolgee 实测

2.1 用 systemd EnvironmentFile 托管配置

生产环境推荐把配置从 application.properties 迁到 systemd 的 EnvironmentFile，改配置不再碰 jar 目录，且权限收敛在 root：

cat > /etc/default/tolgee <<'EOF'
# Tolgee server configuration via environment variables (Spring relaxed binding)
SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/tolgee
SPRING_DATASOURCE_USERNAME=postgres
SPRING_DATASOURCE_PASSWORD=q1w2e3r4
TOLGEE_AUTHENTICATION_ENABLED=true
TOLGEE_AUTHENTICATION_INITIAL_USERNAME=admin
TOLGEE_AUTHENTICATION_INITIAL_PASSWORD=q1w2e3r4
TOLGEE_AUTHENTICATION_JWT_SECRET=tolgee-lab-jwt-secret-2026-0123456789abcdef
TOLGEE_POSTGRES_AUTOSTART_ENABLED=false
TOLGEE_FRONT_END_URL=http://192.168.1.62:8150
TOLGEE_FILE_STORAGE_FS_DATA_PATH=/opt/tolgee/file-storage
TOLGEE_TELEMETRY_ENABLED=false
SERVER_PORT=8080
EOF
mv /opt/tolgee/application.properties /opt/tolgee/application.properties.bak

单元文件中把 Environment= 行替换为：

EnvironmentFile=/etc/default/tolgee

然后 systemctl daemon-reload && systemctl restart tolgee。

2.2 生效验证：整链路回归

移走 properties 文件、仅靠环境变量启动后的实测结果：

systemctl is-active tolgee
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8080/
curl -s -X POST http://localhost:8080/api/public/generatetoken \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}' -o /dev/null -w '%{http_code}\n'

实测回显：

active
200
200

三项分别证明：数据源四项（URL/用户/口令）真实生效（登录要查库）、TOLGEE_AUTHENTICATION_* 生效（服务接受了正确口令并签发 JWT）、TOLGEE_POSTGRES_AUTOSTART_ENABLED=false 生效（纯环境变量下没有内嵌数据库自拉起干扰）。

三、关键配置项逐项验证

3.1 server.port：改端口实测

把 /etc/default/tolgee 中 SERVER_PORT=8080 改为 SERVER_PORT=8081，重启后：

curl -s -o /dev/null -w '8081:%{http_code}\n' http://localhost:8081/
curl -s -o /dev/null -w '8080:%{http_code}\n' http://localhost:8080/
journalctl -u tolgee -n 100 --no-pager | grep -o 'Tomcat started on port.*' | tail -1

实测回显：

8081:200
8080:000
Tomcat started on port 8081 (http) with context path '/'

端口迁移真实生效：新端口 200、旧端口连接拒绝、日志明示监听口。验证完改回 SERVER_PORT=8080 并重启恢复。

3.2 spring.datasource.*：数据库连接

四项配置（url / username / password / 驱动自动识别）实测已随登录链路验证。补充两个实测事实：

无需手动建表：首次连接空库时内置 Liquibase 自动迁移建表，实测日志：Database is up to date, no changesets to execute；
连接失败即启动失败：把 URL 指向不存在的库重启，Tolgee 会因无法建立连接池而退出，systemd 的 Restart=on-failure 会反复拉起——排障时先看 journalctl -u tolgee 的首屏异常。

3.3 tolgee.authentication.*：认证与初始管理员

配置项	作用	实测结论
`tolgee.authentication.enabled`	是否启用本地账号认证	`true` 时 `GET /api/public/configuration` 回显 `"authentication": true`
`tolgee.authentication.initial-username` / `initial-password`	初始管理员	仅首次初始化数据库时创建，之后改这两项不影响已有账号
`tolgee.authentication.jwt-secret`	JWT 签名密钥	实测必须 ≥32 字符，26 字符启动报 `WeakKeyException`（208 bits < 256 bits）
`tolgee.authentication.native-enabled`	是否允许账号密码登录	关闭后仅第三方 OAuth/SSO 登录

GET /api/public/configuration 的回显（实测节选）是验证认证配置最直接的窗口：

"version": "v3.241.1",
"authentication": true,
"authMethods": { "github": { "clientId": null, "enabled": false }, ... }

运维提示：jwt-secret 一旦投入使用就不可随意更换（换后所有已签发 JWT 失效、用户被登出）；生产环境用 openssl rand -base64 48 生成并妥善保管。

3.4 tolgee.file-storage.*：文件存储落盘实测

tolgee.file-storage.fs-data-path 控制 avatar、界面截图等文件的落盘目录（来源：v3.241.1 源码 FileStorageProperties.kt，默认值为 ~/.tolgee，即服务运行用户的主目录；亦可改配 S3 或 Azure Blob 对象存储，前缀 tolgee.file-storage.s3.* / tolgee.file-storage.azure.*）。

实测把路径显式设为 /opt/tolgee/file-storage 后，用管理员 JWT 给组织上传头像（1×1 PNG）：

curl -s -X PUT 'http://localhost:8080/v2/organizations/1/avatar' \
  -H "Authorization: Bearer $TOKEN" \
  -F 'avatar=@/tmp/logo.png;type=image/png'
find /opt/tolgee/file-storage -type f

实测回显（哈希目录与文件名来自真实运行）：

/opt/tolgee/file-storage/avatars/FF36688EA32267C9E8C8D7632ADA86192792F689D36C83C334D1F0AB3CCB951D.png
/opt/tolgee/file-storage/avatars/FF36688EA32267C9E8C8D7632ADA86192792F689D36C83C334D1F0AB3CCB951D-thumb.png

结论：目录配置真实生效，文件按内容哈希存放在 avatars/ 子目录，同时生成缩略图。这个目录必须纳入备份（见运维篇），升级或迁移时与数据库同等重要。

3.5 tolgee.telemetry.*：遥测开关

官方文档（源码 TelemetryProperties.kt）说明：默认开启，每天向官方上报一次匿名统计——项目数、语言数、翻译数、用户数四项计数，此外无其他数据。

实测关闭方式：TOLGEE_TELEMETRY_ENABLED=false。关闭后对服务无任何功能影响；验证手段是启动日志中检索遥测组件：

journalctl -u tolgee --no-pager -n 200 | grep -ciE 'telemetry|posthog'

实测回显：

0 行输出表明遥测组件未活动。对外网严格隔离的内网环境，此开关建议关闭（省去每天一次的出站请求失败重试噪音）。

3.6 tolgee.front-end-url / back-end-url：公共地址

tolgee.front-end-url 用于生成对外链接（邮件确认、邀请链接等）。官方文档（Server configuration）明确警告：不配置该属性会有安全问题，公网可达的实例强烈建议配置。单机部署（前后端同 jar 同端口）时设为对外访问地址即可，实测值 http://192.168.1.62:8150（经前置代理映射到服务 8080）。tolgee.back-end-url 仅在前后端分离部署时需要单独设置。

3.7 机器翻译与上传限制等实用项

机器翻译：tolgee.machine-translation.<service>.api-key 按服务配置（google/aws/deepl/azure/baidu）。未配任何 key 时，实测 GET /api/public/configuration 回显六种服务全部 "enabled": false，平台其余功能不受影响；
上传限制：tolgee.max-upload-file-size（单位 KB，默认 51200≈50MB）、tolgee.max-screenshots-per-key（默认 20）、tolgee.max-translation-text-length（默认 10000 字符）；
并发线程池：tolgee.async.background.* 与 tolgee.async.streaming.* 默认按数据库连接池大小推导，小规模实例不必显式配置。

四、配置排障速查

4.1 常见启动失败对照表

报错关键字	原因	处置
`WeakKeyException ... 208 bits`	jwt-secret 不足 32 字符	换 ≥32 字符密钥
`UnsupportedClassVersionError ... 69.0`	JDK 版本低于 25	换 OpenJDK 25
`Connection refused ... 5432`	PostgreSQL 未启动或地址错	先 `service postgresql start`，再核对 SPRING_DATASOURCE_URL
端口被占 `Port 8080 ... already in use`	端口冲突	换 SERVER_PORT 或停冲突进程

4.2 配置变更的通用流程

vim /etc/default/tolgee          # 或 /opt/tolgee/application.properties
systemctl restart tolgee
journalctl -u tolgee -n 100 --no-pager | grep -E 'Tomcat started|ERROR'

配置类变更一律"改 → 重启 → 看日志确认监听口与无 ERROR → 业务接口冒烟"。涉及数据库与文件存储目录的配置变更前，先做备份（流程见运维篇）。