Tolgee 命令与运维：启动参数、PAT API、备份与升级

Tolgee v3.241.1 运维实战：systemd 日常管理、命令行启动参数、PAT 令牌与项目/翻译 CRUD、pg_dump 与文件存储备份、替换 jar 升级闭环与故障速查。

TolgeeTolgeeJava平台JVM2026/10/28

Tolgee 命令与运维：启动参数、PAT API、备份与升级

本篇为运维篇，前置阅读：Tolgee 单机安装实战：Ubuntu 22.04 + OpenJDK 25 + jar + systemd 与 Tolgee 配置详解：application.properties 与环境变量逐项生效验证。

一、日常服务管理与启动参数

1.1 systemd 日常命令

承接安装篇的 tolgee.service，日常运维命令与实测回显（2026-10-28，v3.241.1）：

systemctl start|stop|restart|status tolgee
systemctl is-active tolgee && systemctl is-enabled tolgee
journalctl -u tolgee -n 200 --no-pager
journalctl -u tolgee -f

实测 systemctl status tolgee --no-pager 关键回显：

● 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:18:14 UTC; 10s ago
   Main PID: 7704 (java)
      Tasks: 30 (limit: 2932)
     Memory: 599.0M

启动到可服务约需 30–40 秒（含 Liquibase 库结构校验），脚本化重启后请轮询端口而非盲等：

for i in $(seq 1 30); do curl -s -o /dev/null -w '%{http_code}' http://localhost:8080/ | grep -q 200 && break; sleep 2; done

运行时 JVM 参数核查（运维红线：堆改动必须验证）：

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

实测回显：

-Xms256m
-Xmx512m

1.2 命令行启动参数实测

除了配置文件与环境变量，Tolgee 支持标准 Spring Boot 命令行参数（--键=值，优先级最高）。实测临时用 8090 端口启动：

java -Xms256m -Xmx512m -jar tolgee-3.241.1.jar \
  --server.port=8090 \
  --spring.datasource.url=jdbc:postgresql://localhost:5432/tolgee \
  --spring.datasource.username=postgres \
  --spring.datasource.password=q1w2e3r4 \
  --tolgee.postgres-autostart.enabled=false \
  --tolgee.authentication.jwt-secret=tolgee-lab-jwt-secret-2026-0123456789abcdef

实测日志回显：

2026-10-28T02:28:58.512Z  INFO 8714 --- [main] o.s.boot.tomcat.TomcatWebServer : Tomcat started on port 8090 (http) with context path '/'

命令行参数真实压过了配置里的端口。典型用途：临时端口拉起第二个实例做数据核对、临时关闭遥测、一次性调整认证参数等。注意同一机器跑两个实例要共用 PostgreSQL 时，确认连接池与负载可承受。

二、PAT 令牌与 REST API 实操

2.1 创建个人访问令牌（PAT）

PAT（Personal Access Token）是绑定到个人账号的 API 令牌，适合脚本与 CI。先用管理员账号换 JWT，再建 PAT（实测）：

TOKEN=$(curl -s -X POST http://localhost:8080/api/public/generatetoken \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}' | python3 -c 'import json,sys; print(json.load(sys.stdin)["accessToken"])')

curl -s -X POST http://localhost:8080/v2/pats \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"description":"ops-lab-pat","expiresAt":1824681600000}'

实测回显：

{"token":"tgpat_1l4okgb65ge8sebh3fc52cnfpbdgb4vdfdme60tcsmjgtmi56ula","createdAt":1793154277997,"description":"ops-lab-pat","expiresAt":1824681600000,"id":1000011001,"lastUsedAt":null,"updatedAt":1793154277997}

两个实测踩坑：

  1. expiresAt 是 epoch 毫秒时间戳，传 "2027-10-28" 这类日期字符串会报 Cannot deserialize value of type 'java.lang.Long'（400）；
  2. PAT 的管理端点在 /v2/pats（列表 GET、删除 DELETE /v2/pats/{id}、重签 PUT /v2/pats/{id}/regenerate），自查用 GET /v2/pats/current。

2.2 PAT 的认证方式：X-API-Key 头（实测）

PAT 必须放 X-API-Key 请求头，不能放 Authorization，实测对比：

PAT='tgpat_1l4okgb65ge8sebh3fc52cnfpbdgb4vdfdme60tcsmjgtmi56ula'
curl -s -o /dev/null -w 'X-API-Key: %{http_code}\n' http://localhost:8080/v2/projects -H "X-API-Key: $PAT"
curl -s -o /dev/null -w 'Bearer:    %{http_code}\n' http://localhost:8080/v2/projects -H "Authorization: Bearer $PAT"

实测回显：

X-API-Key: 200
Bearer:    401

GET /v2/pats/current 用 PAT 自查身份与有效期，实测回显含 "lastUsedAt":1793154331847（平台会记录最近使用时间，可用于审计僵尸令牌）。另外注意 PAT 权限有边界：实测用 PAT 调组织头像接口返回 {"code":"api_access_forbidden"}，文件类/管理类操作仍需 JWT 或在界面完成。

2.3 项目与翻译 CRUD 实测链路

建项目（实测：必须带 organizationId；语言对象的 name 与 originalName 都不能为空，缺一个都是 400 校验错误）：

curl -s -X POST http://localhost:8080/v2/projects \
  -H "X-API-Key: $PAT" -H 'Content-Type: application/json' \
  -d '{"name":"demo-web","organizationId":1,"languages":[{"tag":"en","name":"English","originalName":"English"},{"tag":"zh","name":"简体中文","originalName":"简体中文"}]}'

实测回显（节选）：{"id": 2, "name": "demo-web", ...}（200）。组织 id 自查：GET /v2/user/single-owned-organizations。

建翻译键（一次带上 en/zh 两个语言译文）：

curl -s -X POST http://localhost:8080/v2/projects/2/keys \
  -H "X-API-Key: $PAT" -H 'Content-Type: application/json' \
  -d '{"name":"login.title","translations":{"en":"Welcome back","zh":"欢迎回来"}}'

实测回显（节选）：

{"id":1000017001,"name":"login.title",...,"translations":{"en":{"id":1000018001,"text":"Welcome back","state":"TRANSLATED",...},"zh":{"id":1000018002,"text":"欢迎回来","state":"TRANSLATED",...}}}

读回与改键名：

curl -s 'http://localhost:8080/v2/projects/2/translations/en' -H "X-API-Key: $PAT"
# 实测回显：{"en":{"login":{"title":"Welcome back"}}}
curl -s -X PUT 'http://localhost:8080/v2/projects/2/keys/1000017001' \
  -H "X-API-Key: $PAT" -H 'Content-Type: application/json' \
  -d '{"name":"login.title.renamed"}' -o /dev/null -w '%{http_code}\n'
# 实测回显：200

导出译文（CI 拉取译文用；注意导出是 POST 且返回 zip，GET /v2/projects/2/export/json?zip=false 这类直观路径会被前端路由接管返回 HTML 页面）：

curl -s -X POST 'http://localhost:8080/v2/projects/2/export' \
  -H "X-API-Key: $PAT" -H 'Content-Type: application/json' \
  -d '{"format":"JSON","filterState":["TRANSLATED"]}' -o /tmp/export.bin
python3 -c "import zipfile; print(zipfile.ZipFile('/tmp/export.bin').namelist())"

实测回显：

zip entries: ['en.json', 'zh.json']

三、备份与恢复

3.1 备份什么

Tolgee 的全部状态 = PostgreSQL 数据库（项目、键值、翻译、用户、活动记录）+ 文件存储目录（TOLGEE_FILE_STORAGE_FS_DATA_PATH 指向的目录，含头像与截图）+ 配置文件（/etc/default/tolgee 与 tolgee.service）。三者齐备才能完整重建。

3.2 备份实测

mkdir -p /opt/backup
su postgres -c 'pg_dump -d tolgee -Fc' > /opt/backup/tolgee-db-20261028.dump
tar czf /opt/backup/tolgee-filestorage-20261028.tar.gz -C /opt/tolgee file-storage
ls -lh /opt/backup/
su postgres -c 'pg_restore --list /opt/backup/tolgee-db-20261028.dump' | grep -cE 'TABLE DATA|SEQUENCE'

实测回显：

total 348K
-rw-r--r-- 1 root root 343K Oct 28 02:28 tolgee-db-20261028.dump
-rw-r--r-- 1 root root  532 Oct 28 02:28 tolgee-filestorage-20261028.tar.gz
150

pg_dump 自定义格式（-Fc）支持并发恢复与选择性恢复；pg_restore --list 校验转储可读（实测 150 个对象条目）。生产环境把上述两行加进 cron（建议每日一次，保留 ≥14 天）并将产物异机存放。

3.3 恢复流程（命令 + 预期结果）

以下为标准恢复流程：pg_restore --list 已实测可用，整库恢复动作遵循 pg_restore 标准语义，生产执行前务必先在测试库演练。

systemctl stop tolgee
su postgres -c "dropdb tolgee && createdb tolgee"
su postgres -c "pg_restore -d tolgee /opt/backup/tolgee-db-20261028.dump"
tar xzf /opt/backup/tolgee-filestorage-20261028.tar.gz -C /opt/tolgee
systemctl start tolgee
# 预期：日志出现 Tomcat started on port 8080，登录接口返回 200，译文与头像完整

四、升级：替换 jar 实测闭环

4.1 升级原理

Tolgee 升级 = 替换 jar 文件 + 重启。数据库结构由新版内置 Liquibase 在启动时自动增量迁移（实测启动日志多次出现 Database is up to date, no changesets to execute），配置（环境变量/properties）与数据均不动。升级前必须完成 3.2 节备份。

4.2 实测：替换 jar 全流程

在实测环境用 v3.241.1（当前版）与 v3.240.3（上一维护版，2026-10-26 发布，SHA-256 b5c5b3cec1f3cb5a7344ad247cb871e8b572620351923246364fd0e03c975983）做了双向替换验证：

# 1) 停服务、备份旧 jar
systemctl stop tolgee
cp /opt/tolgee/tolgee-3.241.1.jar /opt/backup/tolgee-3.241.1.jar.bak

# 2) 放入新 jar，把 tolgee.service 的 ExecStart 指向新文件
mv tolgee-3.240.3.jar /opt/tolgee/
sed -i 's|tolgee-3.241.1.jar|tolgee-3.240.3.jar|' /etc/systemd/system/tolgee.service
systemctl daemon-reload && systemctl start tolgee && sleep 40

# 3) 验证版本号与数据完整性
curl -s http://localhost:8080/api/public/configuration | python3 -c 'import json,sys; print("version:", json.load(sys.stdin)["version"])'

替换后实测回显：

version: v3.240.3

随后改回 tolgee-3.241.1.jar 重启，实测回显 version: v3.241.1，且登录接口 200、替换前建的翻译键数据原样保留（GET /v2/projects/2/translations/en 仍返回改名后的键与译文）。版本回显字段 version 来自 /api/public/configuration，是升级验收的标准探针。

4.3 升级注意

  • 不建议降级：相邻维护版（v3.240.3 ↔ v3.241.1）实测可双向切换且库结构兼容，但跨多个小版本的"升级后回退"存在 Liquibase 已前滚变更无法安全回滚的风险，唯一安全回退手段是 3.3 节的整库恢复；
  • 发版节奏快：半月 20 版（2026-10 实况），建议锁定季度节奏升级，升级前读 Release Notes 关注 breaking 标记；
  • JDK 要求随版本走：当前版本线要求 Java 25（class file 69.0），升级到未来版本时先查 Release Notes 的 Java 最低要求，避免启动报 UnsupportedClassVersionError。

五、故障排查速查

5.1 状态一页表

症状首查命令实测经验
服务反复重启journalctl -u tolgee -n 200 --no-pager大多是数据库连不上或配置校验失败（如 jwt-secret 过短）
启动慢看 Liquibase 行首次建库或大版本迁移需数分钟，等 Database is up to date
接口 403确认令牌类型PAT 走 X-API-Key，JWT 走 Authorization: Bearer；登录只能 POST /api/public/generatetoken
界面 502/超时systemctl is-active tolgee + ss -ltn | grep 8080进程活着但端口没起 = 还在启动中；等就绪再查前置代理
内存增长jps -v 核对堆参 + jstat -gc <pid>堆上限 512 MB 起步，按活跃翻译量与并发调整

5.2 一键体检脚本（命令 + 预期结果）

已在实测环境验证各单项命令；脚本为串联封装，标注意为预期结果。

#!/bin/bash
echo -n "service: "; systemctl is-active tolgee
echo -n "port:    "; curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8080/
echo -n "login:   "; 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'
echo -n "version: "; curl -s http://localhost:8080/api/public/configuration | grep -o '"version": "[^"]*"'
echo -n "jvm:     "; /usr/lib/jvm/java-25-openjdk-amd64/bin/jps -v | grep -c tolgee

预期五项输出依次为 active、200、200、当前版本号、1。任一项异常再按 5.1 定位。

回顾全系列：选型认知见 Tolgee 是什么：自托管国际化翻译管理平台的认知与选型，安装见 Tolgee 单机安装实战：Ubuntu 22.04 + OpenJDK 25 + jar + systemd，配置见 Tolgee 配置详解：application.properties 与环境变量逐项生效验证。