LibreTranslate 1.9.6 配置参数详解

LibreTranslate 1.9.6 全部 40 项启动参数与 LT_* 环境变量逐项实测：默认值总览、生效验证回显、API Key/限流/指标端点实测与两档生产配置模板。

LibreTranslateLibreTranslateRESTAPI机器翻译2026/10/28

LibreTranslate 1.9.6 配置参数详解

目标：逐项讲清 LibreTranslate 1.9.6 的启动参数与环境变量（LT_*）——默认值、作用、生效验证方法与生产配置模板。全部参数在 Ubuntu 22.04 + LibreTranslate 1.9.6 实测环境逐项验证，标注✅者为带实测回显的参数，◐者为源码/设置端点验证，△者为帮助口径（未做长窗口或场景级实测）。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64，6 核 / 18GB 内存）
  • 软件版本：LibreTranslate 1.9.6（venv 安装于 /opt/libretranslate/venv，argos-translate-lt 1.12.1，ctranslate2 4.8.4，waitress 2.1.2）
  • 托管方式：systemd（单元文件 /etc/systemd/system/libretranslate.service）
  • 服务端口：5000（本文验证用的临时端口 5002–5008 仅出现在实验命令中）
  • 语言范围：--load-only en,zh,ja,ko,de,fr,es,ru（8 语言 14 语言对，模型 1.9GB）
  • 安装过程见安装部署篇；本文所有验证命令在该环境实测，回显逐行照抄。

二、前置条件

  1. 已完成 LibreTranslate 安装并能 systemctl start libretranslate（见安装部署篇）；
  2. 修改参数后 systemctl daemon-reload && systemctl restart libretranslate 生效；
  3. 验证工具：curl、jq（JSON 解析）、sqlite3（查密钥库）、ss -ltn（看监听）。
systemctl is-active libretranslate

active

三、参数查看与修改方式

3.1 查看全部参数：--help

/opt/libretranslate/venv/bin/libretranslate --help

usage: libretranslate [-h] [--host HOST] [--port PORT]
                      [--char-limit <number of characters>]
                      [--req-limit <number>]
                      [--req-limit-storage <Storage URI>]
                      [--hourly-req-limit <number>]
                      [--hourly-req-limit-decay <number>]
                      [--daily-req-limit <number>]
                      [--req-flood-threshold <number>]
                      [--req-time-cost <number>]
                      [--batch-limit <number of texts>] [--debug] [--ssl]
                      [--frontend-language-source <language code>]
                      [--frontend-language-target <language code>]
                      [--frontend-language <language code>]
                      [--frontend-title <title>]
                      [--frontend-timeout <milliseconds>] [--api-keys]
                      [--api-keys-db-path API_KEYS_DB_PATH]
                      [--api-keys-remote API_KEYS_REMOTE]
                      [--get-api-key-link GET_API_KEY_LINK]
                      [--require-api-key-origin REQUIRE_API_KEY_ORIGIN]
                      [--require-api-key-secret]
                      [--require-api-key-fingerprint] [--hide-api]
                      [--under-attack] [--shared-storage <Storage URI>]
                      [--secondary]
                      [--load-only <comma-separated language codes>]
                      [--alternatives-limit <maximum number of alternatives translations>]
                      [--threads <number of threads>] [--suggestions]
                      [--disable-files-translation] [--disable-web-ui]
                      [--update-models] [--force-update-models] [--metrics]
                      [--metrics-auth-token METRICS_AUTH_TOKEN]
                      [--translation-cache <comma separated API keys or 'all'>]
                      [--url-prefix URL_PREFIX]

（usage 节选：options 段每项的完整说明与默认值见第四章总览表，总览表默认值与 --help 输出逐项核对过。）

⚠️ 注意：--help 中 --load-only 的说明文字写着「Set available languages (ar,de,en,es,fr,ga,hi,it,ja,ko,pt,ru,zh)」，括号里这串语言是帮助文案里硬编码的示例，不是默认值——源码中 LT_LOAD_ONLY 的默认值为 None（不限制），不传 --load-only 时服务会尝试加载索引里全部语言。

3.2 修改方式一：CLI 参数（systemd ExecStart）

最直接的方式，改 /etc/systemd/system/libretranslate.service 的 ExecStart= 行后重启：

systemctl daemon-reload
systemctl restart libretranslate

3.3 修改方式二：环境变量（LT_ 前缀）

每个 CLI 参数都有对应的 LT_<大写下划线名> 环境变量（源码 libretranslate/default_values.py 中定义了 40 项，前缀 LT_）。布尔型接受 TRUE/True/true/1 与 FALSE/False/false/0，整型解析失败时静默回退默认值。

实测：LT_PORT 生效（命令行不传 --port 时，LT_PORT=5002 决定监听端口；--host 0.0.0.0 照常传）：

cd /opt/libretranslate
(LT_PORT=5002 /opt/libretranslate/venv/bin/libretranslate --host 0.0.0.0 --load-only en,zh &)
sleep 12
curl -s http://127.0.0.1:5002/health

{"status":"ok"}

（同时 curl http://127.0.0.1:5000/health 连接失败，确认 5000 未监听、5002 生效。）

实测优先级：CLI 参数 > 环境变量（同时给 LT_PORT=5002 与 --port 5003，最终监听 5003）：

(LT_PORT=5002 /opt/libretranslate/venv/bin/libretranslate --host 0.0.0.0 --port 5003 --load-only en,zh &)
sleep 12
curl -s http://127.0.0.1:5003/health

{"status":"ok"}

💡 技术拓展：配置注入的同类方案对比——CLI 参数（本文主用，systemd ExecStart 中可见、可审计）、环境变量 LT_*（适合多实例差异化注入与 secrets 类配置）、配置文件（LibreTranslate 1.9.6 无原生 config file 参数，可由 systemd EnvironmentFile= 间接实现集中管理）。实际采用：常规参数写 ExecStart，环境差异（代理等）用 systemd Environment=，与安装部署篇单元文件一致。

systemd 中注入环境变量的写法（每行一个 Environment=）：

[Service]
Environment="LT_PORT=5000"
Environment="LT_LOAD_ONLY=en,zh,ja"
Environment="LT_THREADS=4"

四、参数总览

40 项参数按功能域分组，默认值取自 --help 与源码 default_values.py（两者已逐项核对一致）。生效标记：✅=本文带实测回显；◐=源码或设置端点验证；△=帮助口径（未做长窗口/场景级实测）。

4.1 网络与服务

参数默认值生效说明
--host127.0.0.1✅监听地址；对外服务必须显式 0.0.0.0
--port5000✅监听端口
--url-prefix空✅在所有端点前加路径前缀（反代共用域名场景）
--threads4✅HTTP 工作线程数，作用于 waitress（WSGI 服务器），非模型推理线程
--sslFalse◐仅把 waitress 的 url_scheme 标为 https，自身不做 TLS 终结；TLS 由前置反代负责
--debugFalse◐切换为 werkzeug 开发服务器（源码 run_simple）；--debug 且 --host * 时监听 ::（IPv4+6）

4.2 翻译行为与 Web 界面

参数默认值生效说明
--char-limit-1（不限）✅单次请求文本字符上限
--batch-limit-1（不限）✅批量请求 q 数组长度上限
--alternatives-limit-1（不限）✅备选译文数量上限
--load-onlyNone（全部可用语言）✅限定加载的语言码（逗号分隔），直接决定内存与磁盘占用
--suggestionsFalse✅开放 /suggest 用户建议提交
--disable-files-translationFalse✅关闭文件翻译（/translate_file 与 Web 文件页签）
--disable-web-uiFalse✅关闭 Web 翻译界面，仅留 API
--hide-apiFalse✅隐藏 Web 界面中的 API 文档链接与 API 设置区
--frontend-language-sourceauto◐Web 界面默认源语言
--frontend-language-targetlocale（跟随浏览器语言）✅Web 界面默认目标语言
--frontend-language空△强制 Web 界面语言（界面文案语言）
--frontend-title空✅Web 界面标题
--frontend-timeout500△前端翻译请求超时（毫秒）
--translation-cache空△按 API Key（或 all）缓存翻译结果，1.8.4 引入
--update-modelsFalse✅启动时更新语言包索引并升级已装包（触发联网与语言码校验）
--force-update-modelsFalse◐强制重装全部已装语言包（源码 force=True，磁盘与耗时等同重下）

4.3 请求限流与防护

参数默认值生效说明
--req-limit-1（不限）✅每客户端每分钟请求上限（基于 IP；API Key 用户用密钥自身限额）
--req-limit-storagememory://△限流计数存储 URI（flask-limiter）；多进程需换共享存储
--hourly-req-limit-1（不限）△每小时请求上限（叠加在 req-limit 之上）
--hourly-req-limit-decay0△与 hourly 组合的对数衰减式逐小时递减限制
--daily-req-limit-1（不限）△每天请求上限
--req-flood-threshold-1（不限）△客户端超限次数达到阈值后封禁
--req-time-cost-1（不限）△把翻译耗时折算成限流代价（如耗时 10s、设 5，则计 2 次请求）

4.4 API Key 与访问控制

参数默认值生效说明
--api-keysFalse✅启用本地 API Key 库（SQLite），按 Key 限额
--api-keys-db-pathdb/api_keys.db✅密钥库路径（相对 WorkingDirectory）
--api-keys-remote空△远程密钥校验端点（替代本地库）
--get-api-key-link空△Web 界面展示「获取 API Key」跳转链接
--require-api-key-origin空△除指定来源域外，编程访问一律要求 API Key
--require-api-key-secretFalse△要求请求附带与密钥匹配的 secret 才免 Key
--require-api-key-fingerprintFalse△要求客户端指纹匹配才免 Key
--under-attackFalse△「防攻击模式」：所有请求必须带 API Key

4.5 指标与多实例

参数默认值生效说明
--metricsFalse✅开放 Prometheus /metrics 端点
--metrics-auth-token空✅用 Bearer Token 保护 /metrics
--shared-storagememory://△多进程（gunicorn）间共享数据（限流计数等）的存储 URI
--secondaryFalse△标记为副实例（多节点部署避免与主节点冲突）

💡 技术拓展：限流存储 URI 的常见取值——memory://（进程内存，重启清零、单进程适用，本文默认）、redis://host:6379/0（多进程/多实例共享计数）、sqlite:///path.db（轻量持久化）。单机 systemd 部署 memory:// 足够；将来用 gunicorn 多 worker 或多节点时必须换 Redis，否则各 worker 各自计数、限额翻倍。本文采用默认 memory://。

五、核心参数分类详解（逐项生效验证）

5.1 --host / --port：监听地址与端口

默认只监听 127.0.0.1，本机外不可访问；对外服务必须 --host 0.0.0.0。--port 默认 5000。生效验证最直接：改端口后轮询 /health（安装部署篇 7.3 实测改配置重启后 READY at +2s、{"status":"ok"}）。注意 --debug 且 host 传 * 时会转成 :: 同时监听 IPv4/IPv6（源码行为）。

5.2 --load-only：语言范围（内存与磁盘的总开关）

默认不限制——首次启动会下载索引内全部 100 个语言对（15GB+ 量级）。生产必须显式限定。语言码用 /languages 返回的代码（zh-Hans 简体、zh-Hant 繁体、pt-BR 巴西葡语等变体码）。

生效验证一：8 语言配置下 /languages 恰好返回 8 项：

curl -s http://127.0.0.1:5000/languages | jq -r ".[].code" | tr "\n" " "; echo

en zh-Hans fr de ja ko ru es

生效验证二：无效语言码在模型安装路径被校验拒绝（带 --update-models 启动，实测）：

Updating language models
Found 100 models
Cannot update models (normal if you're offline): Unavailable language codes: xx.
Running on http://0.0.0.0:5008

注意：已装包 ≥2 个且不带 --update-models 时，无效码会被静默忽略（实测 --load-only en,xx 服务正常启动）——写错语言码不会报错，务必用 5.2 验证一核对实际加载清单。

5.3 --threads：HTTP 工作线程数

该参数作用于 waitress（WSGI HTTP 服务器）的线程池，控制并发 HTTP 请求处理能力，不是模型推理线程（源码 main.py 末尾 serve(app, ..., threads=args.threads)）。默认 4。

生效验证（翻译一次后统计进程线程数，--threads 1 对比 --threads 4）：

PID=$(systemctl show libretranslate -p MainPID --value); ps -T -p $PID | wc -l

--threads 1 → 20
--threads 4 → 24

差值 4 即 waitress 线程池规模，参数真实生效。经验值：CPU 推理是瓶颈时盲目加大 --threads 只会排队，4–8 足够；配套推理吞吐与模型占用见安装部署篇 8.7。

5.4 --req-limit：每分钟请求上限

默认 -1 不限流。实测设 5（无 Key 客户端按 IP 限流）：

第 6 次请求（前 5 次均成功返回 {"translatedText":"Hallo"}）：

curl -s -X POST http://127.0.0.1:5000/translate -H "Content-Type: application/json" \
  -d '{"q":"Hello","source":"en","target":"de","format":"text"}'

{"error":"Slowdown: 5 per 1 minute"}

生效确认：第 6 次起返回 Slowdown: 5 per 1 minute（HTTP 429）。分钟窗口滚过后自动恢复。--hourly-req-limit/--daily-req-limit 同理叠加小时/天维度（△：长窗口行为未逐项实测）。封禁与代价折算见 4.3 表。

5.5 --api-keys 与 --api-keys-db-path：API Key 体系

--api-keys 启用本地密钥库（默认 db/api_keys.db，相对 WorkingDirectory 即 /opt/libretranslate/db/api_keys.db）。启用后 /frontend/settings 的 apiKeys 变 true：

curl -s http://127.0.0.1:5000/frontend/settings | jq "{apiKeys,charLimit,keyRequired}"

{
  "apiKeys": true,
  "charLimit": 100,
  "keyRequired": false
}

建 Key（ltmanage keys add <每分钟限额> --key <密钥值> --char-limit <字符限额>，在 WorkingDirectory 下执行；密钥值不传则自动生成随机串）：

cd /opt/libretranslate
/opt/libretranslate/venv/bin/ltmanage keys add 60 --key q1w2e3r4

q1w2e3r4

落库验证（sqlite3）：

sqlite3 /opt/libretranslate/db/api_keys.db "select * from api_keys;"

q1w2e3r4|60|

三列分别为密钥、每分钟限额、字符限额（空=继承服务端 --char-limit）。

开关前后对比实测：同一服务（--req-limit 5）下，匿名客户端第 6 次请求被 429 拒绝；带合法 Key 的请求连续 7 次全部成功（Key 走自身 60/min 限额）：

curl -s -X POST http://127.0.0.1:5000/translate -H "Content-Type: application/json" \
  -d '{"q":"Hello","source":"en","target":"de","format":"text","api_key":"q1w2e3r4"}'

{"translatedText":"Hallo"}

错误 Key 实测：

curl -s -X POST http://127.0.0.1:5000/translate -H "Content-Type: application/json" \
  -d '{"q":"Hello","source":"en","target":"de","format":"text","api_key":"badkey123"}'

{"error":"Invalid API key"}

⚠️ 注意：--api-keys 启用后匿名请求仍按默认限流放行（keyRequired 仍为 false）；要「无 Key 一律拒绝」需组合 --require-api-key-origin/--under-attack（△ 未逐项实测，语义见 4.4 表）。q1w2e3r4 为本文演示密钥，生产请用随机长串并按涉密信息管理。

5.6 --char-limit / --batch-limit / --alternatives-limit：请求体防护

三项默认 -1 不限。实测组合（--char-limit 100 --batch-limit 3 --alternatives-limit 2）：

字符超限（150 字符 > 100）：

{"error":"Invalid request: request (150) exceeds text limit (100)"}

批量超限（4 条 > 3 条）：

{"error":"Invalid request: request (4) exceeds text limit (3)"}

备选译文超限（要 3 个 > 上限 2）：

{"error":"Invalid request: alternatives parameter must be <= 2"}

合规请求正常返回（备选译文最多给出上限内的 alternatives 数组）：

curl -s -X POST http://127.0.0.1:5000/translate -H "Content-Type: application/json" \
  -d '{"q":"Hello","source":"en","target":"zh-Hans","format":"text","alternatives":2}'

{"alternatives":["哈啰"],"translatedText":"哈罗"}

三项在 /frontend/settings 中同步可见（charLimit:100），Web 界面据此限制输入。

5.7 --metrics 与 --metrics-auth-token：Prometheus 指标

实测：不带 Token 访问 /metrics 返回 401，带 Authorization: Bearer q1w2e3r4（与 --metrics-auth-token 一致）返回 200：

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:5000/metrics
curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer q1w2e3r4" http://127.0.0.1:5000/metrics

401
200

指标样例（节选，按 API Key/端点/来源 IP 维度统计）：

# HELP libretranslate_http_requests_in_flight Multiprocess metric
# TYPE libretranslate_http_requests_in_flight gauge
libretranslate_http_requests_in_flight{api_key="",endpoint="/translate",request_ip="127.0.0.1"} 0.0
libretranslate_http_requests_in_flight{api_key="q1w2e3r4",endpoint="/translate",request_ip="127.0.0.1"} 0.0
# HELP libretranslate_http_request_duration_seconds Multiprocess metric
# TYPE libretranslate_http_request_duration_seconds summary
libretranslate_http_request_duration_seconds_count{api_key="",endpoint="/translate",request_ip="127.0.0.1",status="200"} 5.0

5.8 --disable-web-ui / --hide-api / --disable-files-translation：界面与功能裁剪

--disable-web-ui（仅留 API，Web 入口重定向）：

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:5000/

301

--hide-api（隐藏界面中的 API 区块；验证方式为抓首页统计「API Docs」导航链接出现次数）：

默认：grep -c "API Docs" → 2
--hide-api：grep -c "API Docs" → 0

（两次均为 curl -s http://127.0.0.1:5000/ | grep -c "API Docs" 实测。）

--disable-files-translation（关闭文件翻译）：

curl -s http://127.0.0.1:5000/frontend/settings | jq "{filesTranslation,supportedFilesFormat}"

{
  "filesTranslation": false,
  "supportedFilesFormat": []
}

默认开启时 filesTranslation:true 且支持 .txt/.odt/.odp/.docx/.pptx/.epub/.html/.srt/.pdf 九种格式（见 settings 端点返回）。

5.9 --url-prefix：路径前缀

反代共用域名时把服务挂在子路径。实测 --url-prefix /lt：根路径 GET / 301 重定向，业务端点全部迁移到 /lt/ 下：

curl -s http://127.0.0.1:5000/lt/frontend/settings | head -c 120
curl -s -X POST http://127.0.0.1:5000/lt/translate -H "Content-Type: application/json" \
  -d '{"q":"Hello","source":"en","target":"de","format":"text"}'

{"apiKeys":false,"charLimit":-1,"filesTranslation":true,"frontendTimeout":500,...
{"translatedText":"Hallo"}

5.10 --frontend-title / --frontend-language-target：界面默认值

实测 --frontend-title 翻译服务（首页 <title> 变更）：

curl -s http://127.0.0.1:5000/ | grep -o "<title>[^<]*</title>"

<title>翻译服务</title>

实测 --frontend-language-target en（settings 端点的默认目标语言从跟随浏览器（locale）变为固定 en）：

curl -s http://127.0.0.1:5000/frontend/settings | jq ".language"

{
  "source": {
    "code": "auto",
    "name": "Auto Detect"
  },
  "target": {
    "code": "en",
    "name": "English"
  }
}

--frontend-language-source 同理控制默认源语言（默认 auto 自动检测）；--frontend-language 强制界面文案语言（△ 未单独实测）。

5.11 --suggestions：翻译建议入库

默认关闭时 /suggest 返回 {"error":"Suggestions are disabled on this server."}；开启后实测：

curl -s -X POST http://127.0.0.1:5000/suggest -H "Content-Type: application/json" \
  -d '{"q":"Hello","s":"Hallo","source":"en","target":"de"}'

{"success":true}

建议写入 db/suggestions.db（相对 WorkingDirectory），可离线导出用于改进模型。

5.12 --update-models / --force-update-models：模型更新策略

  • --update-models：每次启动都联网更新索引并升级已装语言包（实测输出 Updating language models → Found 100 models）；适合定期维护窗口拉新模型，代价是启动变慢且依赖外网；
  • --force-update-models：强制重装已装语言包（◐ 源码语义 force=True；等价全部重新下载，磁盘与耗时同首次安装）；
  • 默认两者皆关：已装包 ≥2 个时启动不发起任何联网请求（安装部署篇 5.4 离线迁移即依赖该行为）。

--ssl 与 --debug 的源码级行为见 4.1 表；--req-limit-storage/--shared-storage/--secondary 等多实例参数见 4.5 拓展与表中说明。

六、生产配置模板

6.1 小内存机型模板（2GB 内存 / NVMe / 内网 API 场景，4–8 个语言对）

[Unit]
Description=LibreTranslate Translation API
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/libretranslate
ExecStart=/opt/libretranslate/venv/bin/libretranslate --host 0.0.0.0 --port 5000 --load-only en,zh,ja --threads 4 --char-limit 5000 --batch-limit 20 --req-limit 60 --api-keys --metrics --metrics-auth-token q1w2e3r4
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

要点：3 个语言（en/zh/ja，实测对应 2+2 个语言对模型数百 MB 磁盘）；--char-limit 5000 --batch-limit 20 挡超大请求；--req-limit 60 兜底限流；--api-keys 为批量调用方发独立 Key；--metrics 接监控。

6.2 通用中大型模板（8GB+ 内存 / 反代后多语言 / Web UI 开放）

ExecStart=/opt/libretranslate/venv/bin/libretranslate --host 0.0.0.0 --port 5000 --load-only en,zh,zh-Hant,ja,ko,de,fr,es,ru,pt --threads 8 --char-limit 10000 --batch-limit 50 --req-limit 120 --hourly-req-limit 5000 --api-keys --suggestions --metrics --metrics-auth-token q1w2e3r4
Environment="LT_HOURLY_REQ_LIMIT_MULTIPLIER=60"

要点：--threads 8 匹配更多并发；小时限流防脚本滥用；TLS 由 Nginx 等反代终结（--ssl 不做 TLS，见 4.1）；对外域名反代不需要 --url-prefix（仅共用域名子路径时用）。

七、常见问题（FAQ）

Q1：改了参数没生效？ 确认走了 systemctl daemon-reload && systemctl restart libretranslate；确认改的是 ExecStart 实际引用的 venv 路径；环境变量与 CLI 同时存在时 CLI 优先（3.3 实测）。启动期 journalctl -u libretranslate -n 50 可看完整启动日志。

Q2：--load-only 写了无效码为什么没报错？ 已装包 ≥2 时启动不走模型校验路径，无效码静默忽略；用 /languages 核对实际加载清单（5.2）。带 --update-models 时才报 Unavailable language codes。

Q3：限流的「客户端」怎么界定的？ 按请求 IP（API Key 用户按 Key）。反代场景注意 memory:// 存储与 X-Forwarded-For 的取值——多 worker/多实例务必换共享存储，否则限额按 worker 翻倍。

Q4：/metrics 报 401？ --metrics-auth-token 设置后必须带 Authorization: Bearer <token>（5.7 实测）。

Q5：参数里哪些没在本文实测？ △ 标记项（长窗口限流、远程密钥、多实例共享存储、界面语言强制、前端超时、翻译缓存等）以 --help 帮助口径与源码语义为准，未做长窗口或场景级实测；✅/◐ 项均有一手验证。

八、参考链接