企业官网建设流程全解析

LibreTranslate自托管翻译API实战：一条Docker命令跑通，附限流与上线清单

【免费下载链接】LibreTranslateFree and Open Source Machine Translation API. Self-hosted, offline capable and easy to setup.项目地址: https://gitcode.com/GitHub_Trending/li/LibreTranslate

LibreTranslate 是开源、可完全离线跑的翻译API（AGPL-3.0，当前 v1.9.6）：一条 Docker 命令就有/translate接口和网页界面，文本全程不出本机。适合想在网站或脚本里免费加机器翻译、又不想数据经过第三方的个人开发者。

快速上手：10分钟Docker跑通翻译API 🐳

最快路径就是官方镜像，一条命令起服务，成功标志是日志出现Running on http://127.0.0.1:5000且健康检查返回 ok。

# 一条命令启动 LibreTranslate：映射 5000 端口，模型缓存挂命名卷防止重启重下 docker run -d -ti -p 5000:5000 \ -v lt-local:/home/libretranslate/.local \ --name libretranslate \ libretranslate/libretranslate:latest

首启会自动下载语言模型，大一点的语言需要几分钟，属于正常现象。跑起来后用两条命令验证：

# 验证服务健康 + 真实翻译一次，两条都有预期输出即部署成功 curl -s http://localhost:5000/health # 应返回 {"status":"ok"} curl -s -X POST http://localhost:5000/translate \ -d "q=hello world" -d "source=en" -d "target=fr" # 应返回 {"translatedText":"bonjour le monde"}

浏览器直接打开http://localhost:5000有内置翻译页面，/docs是 Swagger 在线接口文档，/languages能拿到当前实例实际可用的语言列表。不想用 Docker 的话，看这张表就够了：

能力全景：接口与治理能力地图

一句话概括：翻译、文件、检测三个核心接口加一个内置网页，治理能力（限流、密钥、指标、缓存）全部用命令行参数打开。

和直接调商业翻译服务相比，取舍是这样的：

接入你的业务：3个即贴即用的调用示例

接口参数很少：/translate只需q、source、target，可选format（text/html）和alternatives（候选译文条数）。下面三个场景直接抄。

场景一：给网站加语言切换开关（JavaScript）

// 页面语言下拉框：选中语言后，批量翻译所有带># 批量翻译多语言日志，source 用 auto 自动检测，并打印每条的置信度 import requests BASE = "http://127.0.0.1:5000" lines = ["It is raining.", "Il pleut aujourd'hui", "今天下雨。"] r = requests.post( f"{BASE}/translate", json={"q": lines, "source": "auto", "target": "en", "format": "text"} ) data = r.json() for line, out, det in zip(lines, data["translatedText"], data["detectedLanguage"]): print(f"{line} -> {out} (detected: {det['language']}, {det['confidence']}%)")

场景三：整份文档翻译（Python）

# 把本地 txt 文档整体翻成日文：上传 /translate_file，拿回下载地址再取回 import requests BASE = "http://127.0.0.1:5000" with open("release_notes.txt", "rb") as f: r = requests.post( f"{BASE}/translate_file", data={"source": "en", "target": "ja"}, files={"file": f} ) url = r.json()["translatedFileUrl"] open("release_notes_ja.txt", "wb").write(requests.get(url).content)

文件格式以服务端支持列表为准（/frontend/settings的supportedFilesFormat字段可查）；不放心文档外泄的话，服务端可以用--disable-files-translation整个关掉这个能力。

生产化清单：上线前逐项打勾 ✅

全部默认值来自 libretranslate/main.py 的参数定义，按顺序勾完再对外：

• 分钟级限流：默认LT_REQ_LIMIT=-1不限流，公网必开。做法：--req-limit 100（每 IP 每分钟 100 次）
• 小时/日双保险：防脚本跨天慢速刷。做法：--hourly-req-limit 3000 --daily-req-limit 30000
• 单次字符上限：防一次塞 10 万字把 CPU 打满。做法：--char-limit 5000
• API 密钥隔离：不同业务方要独立配额。做法：--api-keys启用密钥库，再ltmanage keys add 60 --char-limit 2000发 key（60 = 每分钟 60 次）
• 只加载必要模型：内存和启动时间正比于模型数。做法：--load-only en,zh,fr
• Prometheus 监控：要能看请求耗时和在途数（libretranslate_http_request_duration_seconds、libretranslate_http_requests_in_flight）。做法：--metrics，并配--metrics-auth-token加 Bearer 认证
• 重复请求走缓存：相同参数命中缓存不重算，省 CPU。做法：--translation-cache all
• 违规封禁：限流被突破多次的 IP 直接拉黑。做法：--req-flood-threshold 5
• 反代后按真实 IP 限流：Nginx 后面限流会全算到本机。做法：--trust-forwarded-for
• 传输加密：--ssl自带证书可行，更推荐反代终结 TLS；纯内网场景至少保持默认只绑 127.0.0.1

避坑手册：5个高频问题与解法

1. 首次启动卡很久，甚至容器还没就绪现象：容器日志长时间停在模型下载，或 healthcheck 一直不过。 原因：首启要拉全部语言模型，体积不小。 解法：务必挂卷-v lt-local:/home/libretranslate/.local让缓存跨重启保留；用--load-only只留需要的语言，下载量和内存一起降。

2./translate返回 400 "xx is not supported"现象：明明语言代码是对的，却报不支持。 原因：Argos 是按"方向"发模型的，不是所有语言两两都能互译，冷门语言对确实缺模型。 解法：先curl http://localhost:5000/languages看每个语言的targets数组里有没有你的目标语言，没有就换语言对或等模型更新。

3. 间歇性 429 "Slowdown" 或 403 封禁现象：同一客户端偶尔被拒，重启容器后又好了。 原因：命中限流；限流计数默认存memory://，重启即清零。 解法：客户端加退避重试；确属正常高频业务就调高--req-limit，或把计数存到 Redis（--req-limit-storage）。

4. 容器重建后 API key 全部丢失现象：重新docker run后，之前发的 key 全部 403 "Invalid API key"。 原因：密钥库默认在容器内db/api_keys.db，没挂卷就随容器删掉。 解法：--api-keys-db-path指向命名卷，docker-compose.yml 里已留好-v libretranslate_api_keys:/app/db的注释模板，解开即用。

5. 数组批量请求报 "exceeds text limit"现象：单条能过，传数组就 400。 原因：--batch-limit限制单次条数、--char-limit限制每条长度，都会单独校验。 解法：按业务量拆小批次；注意数组请求的限流成本按条数计算（10 条 = 扣 10 次分钟配额），别把它当成"一次请求"。

下一步：先跑这条验证命令

先本地跑通/health，再按生产化清单逐条打勾，最后挂上反代、发 API key 再对外。第一步就是：

# 跑完等 /health 返回 ok，部署就算落地 docker run -d -p 5000:5000 -v lt-local:/home/libretranslate/.local libretranslate/libretranslate

【免费下载链接】LibreTranslateFree and Open Source Machine Translation API. Self-hosted, offline capable and easy to setup.项目地址: https://gitcode.com/GitHub_Trending/li/LibreTranslate