Tolgee 单机安装实战：Ubuntu 22.04 + OpenJDK 25 + jar + systemd

组件定位与选型背景见 Tolgee 是什么：自托管国际化翻译管理平台的认知与选型。本篇为安装篇，配套的参数验证见配置篇、日常操作见运维篇。

一、安装前准备

1.1 目标与环境约定

本篇在 Ubuntu 22.04.5 LTS 服务器上完成 Tolgee v3.241.1 的完整安装：OpenJDK 25 + 官方 Release jar + PostgreSQL 14 + systemd 托管，最终通过浏览器访问 http://<服务器IP>:8150 并用初始管理员账号登录。全部命令均在实测环境执行并记录真实回显，实测时间 2026-10-28。

安装形态约定：

组件	版本/路径	说明
操作系统	Ubuntu 22.04.5 LTS	`cat /etc/os-release` 确认
JDK	OpenJDK 25.0.4.1（apt 仓库）	见 1.3 版本陷阱，17/21 不可用
Tolgee	tolgee-3.241.1.jar → /opt/tolgee/	GitHub Releases 下载
数据库	PostgreSQL 14.24（apt 仓库）	本机 5432，库名 tolgee
进程托管	systemd 单元 tolgee.service	开机自启、崩溃自动拉起
服务端口	8080（Tolgee 默认）	官方默认端口，如需 8150 对外可由前端反向代理或改 `SERVER_PORT`

官方系统要求（docs.tolgee.io，2026-10-28 查询）：最低 2 核 / 4 GB 内存，推荐 4 核 / 16 GB 内存 / 20 GB 磁盘。

1.2 前置检查

cat /etc/os-release | head -2
ss -ltn | grep 8080 || echo "8080 FREE"
free -m | head -2

实测回显：

PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu" VERSION_ID="22.04" VERSION="22.04 (Jammy)"
8080 FREE
               total        used        free      shared  buff/cache   available
Mem:            3936         412        2950          1        574       3339

若 8080 被占用，先排掉冲突进程，或直接决定改用其他端口（改法见配置篇）。

1.3 关键版本陷阱：必须 OpenJDK 25（排障实录）

Ubuntu 22.04 的 apt 仓库里可用的 JDK 有 8/11/17/18/21/25。不要按惯性装 17 或 21——Tolgee v3.241.1 的字节码版本是 class file version 69.0（对应 Java 25），实测用 OpenJDK 21 启动直接报错：

Exception in thread "main" java.lang.UnsupportedClassVersionError:
io/tolgee/Application has been compiled by a more recent version of the
Java Runtime (class file version 69.0), this version of the Java Runtime
only recognizes class file versions up to 65.0

class file version 对照：61 = Java 17，65 = Java 21，69 = Java 25。结论：当前版本线要求 Java 25，后续大版本升级 Tolgee 时先看 Release Notes 中的 Java 要求。

二、安装 JDK 与 PostgreSQL

2.1 安装 OpenJDK 25

apt-get update
apt-get install -y openjdk-25-jdk-headless
update-alternatives --set java /usr/lib/jvm/java-25-openjdk-amd64/bin/java
java -version

实测回显：

openjdk version "25.0.4.1" 2026-08-18
OpenJDK Runtime Environment (build 25.0.4.1+1-1-22.04.4-Ubuntu)
OpenJDK 64-Bit Server VM (build 25.0.4.1+1-1-22.04.4-Ubuntu, mixed mode, sharing)

同时安装 jar/jps 等工具链（openjdk-25-jdk-headless 已含 jar 与 jps，后续运维篇验证 JVM 参数会用到）。若系统里并存多个 JDK，务必用 update-alternatives --set 切到 25，并用 java -version 复核。

2.2 安装并初始化 PostgreSQL

apt-get install -y postgresql postgresql-contrib
service postgresql start
su postgres -c "psql -c \"ALTER USER postgres PASSWORD 'q1w2e3r4';\""
su postgres -c "createdb tolgee"
su postgres -c "psql -c \"select version();\"" | head -3

实测回显（节选）：

ALTER ROLE
                                                 version
------------------------------------------------------------------------------------------------------------------------------------
 PostgreSQL 14.24 (Ubuntu 14.24-0ubuntu0.22.04.1) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 11.4.0-1ubuntu1~22.04.3) 11.4.0, 64-bit

说明：生产环境建议为 Tolgee 单独建数据库账号（如 CREATE USER tolgee WITH PASSWORD '...' 后 GRANT ALL PRIVILEGES ON DATABASE tolgee TO tolgee），本文为简化实验使用 postgres 超级用户加强口令。库结构无需手工创建——Tolgee 首次启动时由内置 Liquibase 自动迁移建表。

三、安装 Tolgee 本体

3.1 下载 jar 并做 SHA-256 校验

从 GitHub Releases 获取当前最新稳定版（查询日期 2026-10-28：v3.241.1，2026-10-27 发布）：

mkdir -p /opt/tolgee && cd /opt/tolgee
curl -L -o tolgee-3.241.1.jar \
  https://github.com/tolgee/tolgee-platform/releases/download/v3.241.1/tolgee-3.241.1.jar
sha256sum tolgee-3.241.1.jar
ls -lh tolgee-3.241.1.jar

实测回显：

10557d34c2187cb0dc01cc66b8cadad37f301cca128031371a76bd2ad6b74238  tolgee-3.241.1.jar
-rw-r--r-- 1 root root 261M Oct 28 02:07 tolgee-3.241.1.jar

文件约 261 MB。GitHub Release 页未提供官方校验和文件，因此按"同一版本多来源/多次下载比对 SHA-256"的方式核验一致性；升级替换时也应记录新旧 jar 的哈希值。

3.2 编写最小配置文件

Tolgee 支持 jar 同目录 application.properties 自动加载（官方推荐的最省事方式）：

cat > /opt/tolgee/application.properties <<'EOF'
# 关闭内嵌数据库自拉起，使用自备 PostgreSQL（纯服务器形态必配）
tolgee.postgres-autostart.enabled=false
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
# JWT 签名密钥：必须不少于 32 字符
tolgee.authentication.jwt-secret=tolgee-lab-jwt-secret-2026-0123456789abcdef
tolgee.telemetry.enabled=false
EOF

两个实测踩过的坑，务必注意：

tolgee.postgres-autostart.enabled=false 必须显式配置。 官方文档（Running with Java）说明 v2 起默认尝试自动拉起内嵌 PostgreSQL，服务器上通常没有相关运行时，会导致启动失败或行为异常。
tolgee.authentication.jwt-secret 不得少于 32 字节。 实测配置 26 字符的密钥直接启动失败，关键报错：

Caused by: io.jsonwebtoken.security.WeakKeyException:
The specified key byte array is 208 bits which is not secure enough
for any JWT HMAC-SHA algorithm. ... keys used with HMAC-SHA algorithms
MUST have a size >= 256 bits

3.3 首次启动与初始管理员验证

先手动前台方式验证一次（确认配置无误后再交给 systemd）：

cd /opt/tolgee
java -Xms256m -Xmx512m -jar tolgee-3.241.1.jar

日志出现 Tomcat started on port 8080 (http) 后，另开终端验证初始管理员（账号密码即 3.2 中的 initial-username / initial-password）：

curl -s -X POST http://localhost:8080/api/public/generatetoken \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}'

实测回显（JWT 为实测截取）：

{"accessToken":"eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE3OTMxNTM4NDMsImF1ZCI6WyJ0Zy50b2siXSwic3ViIjoiMSJ9.…（中间段与签名段略，实测完整 token 共 260 字符）","tokenType":"Bearer"}

返回 200 与 accessToken 即代表初始管理员创建成功、认证链路正常。注意登录端点是 POST /api/public/generatetoken（Spring Security 过滤器之外的显式登录接口，实测直接 POST /api/login 会得到 403）。浏览器访问 http://<服务器IP>:8080/ 可进入 Web 界面并用同一账号登录。

确认无误后停止手动进程（Ctrl+C 或 pkill -f tolgee-3.241.1.jar），进入 systemd 托管阶段。

四、systemd 托管与开机自启

4.1 专用运行账号

useradd -r -m -d /opt/tolgee -s /usr/sbin/nologin tolgee
chown -R tolgee:tolgee /opt/tolgee

4.2 编写单元文件

cat > /etc/systemd/system/tolgee.service <<'EOF'
[Unit]
Description=Tolgee Translation Platform
Documentation=https://tolgee.io
After=network.target postgresql.service
Wants=postgresql.service

[Service]
Type=simple
User=tolgee
Group=tolgee
WorkingDirectory=/opt/tolgee
ExecStart=/usr/bin/java -Xms256m -Xmx512m -Djava.awt.headless=true -jar /opt/tolgee/tolgee-3.241.1.jar
SuccessExitStatus=143
Restart=on-failure
RestartSec=10
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload
systemctl enable tolgee
systemctl start tolgee
systemctl status tolgee --no-pager -l | head -8

实测回显（节选）：

Created symlink /etc/systemd/system/multi-user.target.wants/tolgee.service → /etc/systemd/system/tolgee.service.
● tolgee.service - Tolgee Translation Platform
     Loaded: loaded (/etc/systemd/system/tolgee.service; enabled; vendor preset: enabled)
     Active: active (running) since Wed 2026-10-28 02:17:47 UTC; 8s ago
   Main PID: 7585 (java)
      Tasks: 30 (limit: 2932)

一个实测踩坑必须提醒：不要写成 Environment=JAVA_OPTS=-Xms256m -Xmx512m 再在 ExecStart 里引用 $JAVA_OPTS——systemd 中变量值含空格需要引号包裹，且单元文件经脚本生成时 $VAR 极易被外层展开吞掉，实测出现过"进程起来了但堆参数没生效"的情况。最稳的写法就是把 JVM 参数直接内联在 ExecStart 里（如上）。

4.3 用 jps -v 验证 JVM 堆参数真实生效

/usr/lib/jvm/java-25-openjdk-amd64/bin/jps -v | grep tolgee | tr ' ' '\n' | grep -E '^-Xms|^-Xmx|headless'

实测回显：

-Xms256m
-Xmx512m
-Djava.awt.headless=true

jps -v 输出与配置一致，堆上限 512 MB 生效。后续调整堆大小时：修改 tolgee.service 的 ExecStart → systemctl daemon-reload → systemctl restart tolgee → 重跑本节命令复核。

4.4 验证开机自启与崩溃拉起

systemctl is-enabled tolgee
systemctl is-active tolgee

实测回显：

enabled
active

Restart=on-failure 保证进程异常退出后 10 秒自动拉起；SuccessExitStatus=143 允许 systemd stop（SIGTERM）的正常退出码不计为失败。

五、安装验收清单与 K8s 编排说明

5.1 验收清单

逐项执行，全部通过即安装完成：

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'
su postgres -c "psql -d tolgee -c '\dt'" | head -5

实测回显：

active
200
200
                 List of relations
 Schema |         Name          | Type  |  Owner
--------+-----------------------+-------+----------
 public | access_token          | table | postgres
 public | advanced_storing_type | table | postgres

四项分别对应：服务运行中、Web 可达、初始管理员可登录、数据库表已由 Liquibase 迁移生成。

5.2 K8s 编排形态说明

官方自托管文档当前提供 Java 运行与托管云（Azure）两条路线，未提供官方 K8s 编排或 Helm 图表（2026-10-28 实查，tolgee-helm-charts 等仓库地址 404，官方文档无 K8s 入口）。若必须在 K8s 编排环境运行，社区通行做法是自行编写 Deployment：单副本（Tolgee 部分后台任务依赖单实例语义）、外置 PostgreSQL（集群内或云数据库）、将文件存储目录挂载为 PVC（或直接改配 S3 对象存储）、探针用 GET /api/public/configuration 的 200 响应。自研编排前请先在单机形态完成本文的验收清单，排除环境变量后再叠加 K8s 复杂度。

下一篇《Tolgee 配置详解：application.properties 与环境变量逐项生效验证》将逐项验证数据源、端口、认证、文件存储与遥测开关等关键配置。