LibreTranslate本地部署指南：为Dify与Ollama链路构建私有翻译服务

在折腾本地部署 AI 工具链的这两年，我发现一个特别容易被忽视的环节：翻译服务。Dify 里接了大模型，文档管理工具也跑起来了，但一遇到跨语言流程，第一反应还是去申请某个在线翻译平台的 API Key。倒不是说不行，而是当你把 Dify、Ollama 这类本地部署链路搭起来之后，再让翻译请求绕到外部服务，整个体系的“本地化”就漏了个口子。数据要出网、免费额度有上限、接口限流说不准什么时候就触发。后来我把开源翻译工具 LibreTranslate 部署到自己的机器上，做了 API 鉴权，又通过 Nginx 把服务开放到公网，这套链路才算完整闭环。

这篇文章不是翻译史上最全教程，而是我实际部署、接入、踩坑后的一次完整记录。适合正在搭本地 AI 工具链、想给 Dify 或自动化流程加一个私有翻译服务的开发者，也适合单纯不想把翻译数据交给第三方的个人用户。我会先把选型逻辑讲清楚，再给部署配置，最后说外网访问和安全兜底的做法。

1. 为什么翻译要自部署：数据安全、成本与可控性

在决定自部署之前，我其实是先用了一轮在线翻译 API 的。不能说不好用，但在真实项目里被卡过几次之后，才意识到问题不在翻译质量，而在“不可控”。

最典型的一次是跑一个文档批量翻译任务，大概有几千句话需要中英互译。在线 API 按字符计费，免费额度只够试水，量一上来就必须充值；而且并发一高，接口开始限流，任务中断。更麻烦的是文档内容里有内部术语和未公开的数据，虽然对方平台有隐私政策，但“数据离开你自己的服务器”这件事本身，对很多团队来说就是不可接受的。

LibreTranslate 的出现正好补了这个空档。它是开源项目，底层基于 Argos Translate 离线模型，支持 RESTful API 调用，也自带一个简单的网页界面。部署好之后，所有翻译请求都在本机或内网完成，不依赖外部接口，不需要按字付费，也没有 QPS 配额卡你。说白了，它就是把翻译能力做成了你可以完全掌控的一个私有服务。

当然，离线翻译模型和商业级云翻译引擎之间是有质量差距的。成语、俚语、长难句的语义连贯性，LibreTranslate 偶尔会有明显的“机翻味”。所以我的建议是：先明确你的场景。如果你需要的是流程里自动化的、能正确传达信息且隐私可控的翻译能力，LibreTranslate 很合适；如果你要的是出版级译文，那还是老老实实找商业引擎或人工校对。

1.1 与主流翻译 API 的横向对比

选型的时候我列过一个对比，直接放出来：

这个表格的结论并不复杂：在“翻译效果”这一栏，本地离线方案确实不如商业引擎；但在“可控性”和“成本”上，它几乎是碾压级的。个人开发者、中小团队、内部系统集成，优先级应该是隐私和稳定大于那一点点译文润色。

1.2 最适合它的几个场景

在实际使用中，我把 LibreTranslate 定位成了翻译基础设施，而不是一个打开网页手动翻译的工具。它能融入的场景大致有这几类：

• Dify、n8n 等自动化平台里的翻译节点，替代外部云服务；
• 爬虫或知识库系统的多语言内容处理；
• 文档批量翻译、邮件草稿预翻译；
• 私密资料库的跨语言检索和辅助阅读；
• 给本地大模型（比如通过 Ollama 部署的 Qwen、DeepSeek）做译文前置或后置润色。

特别是最近本地部署大语言模型、本地部署 agent 的风气很盛，大家把模型、知识库、工作流全部装进了自己的机器，那翻译作为链路里的一环，也应该用同样的逻辑收编进来。整条链路上只剩翻译依赖外部 API，其实是件挺奇怪的事。

2. 部署前准备：Docker Compose 和源码方式怎么选

LibreTranslate 的部署方式不复杂，大致两条路：Docker Compose 一键起，或者源码/pip 方式直接跑。我推荐 Docker，原因很简单：环境隔离，依赖不污染宿主机，升级回滚都方便。但如果你想排查底层问题，源码方式对理解运行机制更有帮助。

2.1 Docker Compose 一键部署

服务器装好 Docker 和 Docker Compose 之后，先建一个工作目录：

bash复制mkdir libretranslate && cd libretranslate

然后创建一个 docker-compose.yml：

yml复制version: "3.8"

services:
  libretranslate:
    image: libretranslate/libretranslate:latest
    container_name: libretranslate
    restart: unless-stopped
    ports:
      - "5000:5000"
    environment:
      - LT_LOAD_ONLY=zh,en,ja,ko
      - LT_REQ_LIMIT=200
      - LT_API_KEYS=true
      - LT_API_KEYS_DB_PATH=/app/db/api_keys.db
      - LT_MAX_TEXT_LENGTH=5000
    volumes:
      - ./lt_data:/app/db
      - ./lt_models:/root/.local/share/argos-translate

注意：LT_LOAD_ONLY 这个参数很重要，它决定只加载哪些语言包。如果不设置，首次启动时程序会尝试加载所有语言包，内存直接爆掉，启动时间也会拖得很长。

执行启动命令：

bash复制docker compose up -d

第一次启动会下载语言模型，网络正常的话几分钟内就能完成。中间可以看日志了解进度：

bash复制docker logs -f libretranslate

看到日志停止滚动、容器状态稳定之后，浏览器访问 http://服务器IP:5000，就能看到 LibreTranslate 的网页界面。

2.2 不用 Docker，直接在 Python 环境跑

如果机器上没有 Docker，或者你更习惯虚拟环境管理，也可以直接用 pip 装：

bash复制python3 -m venv lt_env
source lt_env/bin/activate
pip install libretranslate
libretranslate --load-only zh,en,ja,ko --host 0.0.0.0 --port 5000

这种方式的好处是启动参数一目了然，定位问题更直接。缺点是依赖管理在你手上，Python 版本冲突时需要自己解决。我实测在 Python 3.10 和 3.12 下都能正常运行，没有遇到兼容性问题。

2.3 起来之后先验证

不管用哪种方式，部署完不要急着接外网，先在本地验证一遍。打开浏览器确认 Web 界面能显示，然后在命令行调一次 API：

bash复制curl -X POST "http://127.0.0.1:5000/translate" \
  -H "Content-Type: application/json" \
  -d '{"q": "Hello, world", "source": "en", "target": "zh"}'

能返回 JSON 翻译结果，说明核心服务正常：

json复制{
  "translatedText": "你好，世界"
}

如果这一步就报错，多半是语言包没下完、端口被占用、或者工作目录没有写权限。直接看容器日志比瞎猜快得多：

bash复制docker logs libretranslate --tail 100

3. 让它按你的规矩运行：密钥、语言包和并发设置

默认配置只适合快速体验，真要跑链路，有几个参数必须调明白。这里我把它们拆开讲。

3.1 核心环境变量速查表

Docker Compose 方式通过 environment 传参，源码方式用命令行参数，内容一一对应。

3.2 一定要开 API 密钥

只要服务有暴露到外网的可能，API 密钥就是必选项。不开密钥，任何拿到你服务地址的人都能自由调用，白白消耗你的服务器资源。

开启密钥后，通过一次不带鉴权的请求拿到管理员密钥：

bash复制curl -X POST "http://127.0.0.1:5000/keys" \
  -H "Content-Type: application/json" \
  -d '{}'

返回结果里的 api_key 就是管理员密钥，后续所有调用都要带上：

bash复制curl -X POST "http://127.0.0.1:5000/translate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 你的密钥" \
  -d '{"q": "Hello", "source": "en", "target": "zh"}'

这里有个容易被忽略的细节：LT_API_KEYS_DB_PATH 必须指向持久化目录，比如 compose 文件里的 /app/db 映射到宿主机 ./lt_data。否则容器一旦重建，密钥数据库会丢失，所有 Key 都要重新生成，挺折腾的。

3.3 控制内存：别把所有语言包都装上

语言包体积不小，加载进内存之后会长期占用资源。LT_LOAD_ONLY 的作用就是只加载你需要的那几种语言，从而控制内存。

我测试过一组数据：一台 2GB 内存的服务器，加载中、英、日、韩四组语言包，服务稳定运行时的内存占用大约在 1GB 到 1.5GB。如果你的机器只有 1GB 内存，保守一点，只保留 zh,en 两组就够。剩余空间留给系统和其他进程，跑起来会更从容。

语言代码之间用英文逗号分隔，不要带空格。常用代码：

翻译模型的效果会受语言对影响，中英、英中这种高频语言对质量相对稳定，小语种的效果就要放低预期。

3.4 并发和限流设置

LibreTranslate 没有内置复杂的任务队列，并发请求一多，响应时间会明显上升。LT_REQ_LIMIT 控制的是单 IP 每分钟的最大请求数，主要作用是防止某个调用方把服务占满。

如果内部链路确实会有高并发需求，我的建议是：先用限流保护，再考虑扩容。比如在 Nginx 层针对接口路径做更细粒度的限流，或者用多个容器实例共享一个负载均衡入口。LibreTranslate 本身是无状态的，加上共享密钥库之后，横向扩展起来并不难。

4. 让它变成基础设施：API 调用和 Dify 接入

部署起来只是第一步，真正体现价值的是接入自己的系统。LibreTranslate 接口非常简洁，支持 GET 和 POST。我基本只用 POST，因为 GET 对 URL 长度有天然限制，不适合长文本。

4.1 批量翻译脚本实战

我写过一个简单的 Python 脚本，用来处理文档里需要批量翻译的文本。核心逻辑是这样的：

python复制import json
import requests

API_URL = "http://127.0.0.1:5000/translate"
API_KEY = "你的密钥"

def translate(text, source="en", target="zh"):
    resp = requests.post(
        API_URL,
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"q": text, "source": source, "target": target},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json().get("translatedText")

if __name__ == "__main__":
    texts = [
        "Hello world",
        "LibreTranslate is useful",
        "Deploy it locally and control your data",
    ]
    for t in texts:
        print(f"{t} -> {translate(t)}")

这里有一个实战经验：source 参数不建议留空。虽然接口支持自动检测语言，但自动检测本身要消耗模型资源，而且在多语言混排的文本上偶尔会判断错。能明确来源语言的时候就明确传值，更稳。真的需要自动检测时，传 "auto" 就行。

4.2 把翻译接进 Dify 工作流

最近“Dify 本地部署教程”特别火，我自己也在用 Dify 搭 agent。Dify 的“自定义工具”功能可以很自然地把 LibreTranslate 接进来，配置步骤大致如下：

1. 在 Dify 工作台进入“工具”页面，选择“自定义工具”；
2. 用 OpenAPI schema 描述 /translate 接口的入参和出参；
3. 把服务地址填成 http://libretranslate容器IP:5000/translate；
4. 鉴权方式选 API Key，填上刚才生成的密钥；
5. 在工作流里添加这个工具节点，把上游文本节点传入，输出取 translatedText 字段。

接好之后，Dify 工作流里的翻译请求全部走本地，不依赖外部服务，也不会因为免费额度用尽导致自动话术失败。配合 Ollama 本地部署的模型，整个链路可以做到完全离线，这在某些特定环境下是刚需。

4.3 网页端和 API 的边界

LibreTranslate 自带一个简单的网页界面，主要用来调试和手工翻译。但它本质是一个 API 服务，网页端只暴露了一部分能力。比如语言自动检测接口 /detect、获取支持语言列表的 /languages 接口，网页端并没有专门的交互入口，只能通过 API 调用。

所以我的建议是：不要把网页当主力，把它当作接口测试工具就好。真正干活的时候，用脚本、用 Dify、用你的业务系统直接调 API。

5. 从本机到外网：访问路径、防火墙和 HTTPS 落地

“外网访问”这个需求要分几种情况讨论。是同一局域网内访问？还是有公网 IP 的服务器？还是没有公网 IP 的家庭网络？不同的前提，方案完全不同。下面按我从易到难的顺序来写。

5.1 先解决局域网访问

服务要能被其他机器访问，监听地址必须是 0.0.0.0，而不是 127.0.0.1。Docker Compose 的 ports: "5000:5000" 默认就是这样，但源码方式启动时如果不写 --host 0.0.0.0，就只能在容器或本机访问。

接下来是防火墙。这一步最容易坑人：

• Linux 服务器用 sudo ufw status 查看，放行 5000 端口；
• Windows 机器需要在“高级安全 Windows Defender 防火墙”里添加入站规则；
• 云主机还要去云控制台检查安全组规则，确认入方向放行了对应端口。

做完这些，同一内网的另一台机器访问 http://本机IP:5000，应该就能打开页面。

5.2 有公网 IP 的端口映射

如果网络环境允许做端口映射，比如宽带分配了公网 IP，可以在路由器管理页面设置端口映射，把外网端口转发到内网机器的 5000 端口。

但是，我强烈不建议裸奔 HTTP。至少要做两件事：

1. 不要用默认的 5000 端口直接暴露，换一个高位端口，减少被批量扫描的概率；
2. 确保 API 密钥已经开启，并且不要在网页端做任何管理操作。

即使这样，纯 HTTP 传输仍然有被截获的风险，所以更推荐下面这种带 HTTPS 的做法。

5.3 用 Nginx 做前端转发并启用 HTTPS

一个成熟的对外服务，前面应该有一层 Nginx 负责 TLS 终结和请求转发，内部服务不直接暴露到公网。我的 Nginx 配置大致是这样：

nginx复制server {
    listen 443 ssl;
    server_name translate.example.com;

    ssl_certificate     /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;

    client_max_body_size 20m;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

server {
    listen 80;
    server_name translate.example.com;
    return 301 https://$host$request_uri;
}

注意：proxy_set_header 里的 X-Forwarded-For 和 X-Forwarded-Proto 必须带上。LibreTranslate 的限流逻辑依赖真实客户端 IP，如果 Nginx 不把这些头传过去，它看到的所有请求都来自同一个 IP，限流规则等于失效。

证书可以用正规渠道申请，也可以直接用自动化方式申请免费证书。配好 HTTPS 之后，外部访问入口统一走 443 端口，安全和合规性都更可控。

5.4 没有固定公网 IP 怎么办

这是很多人卡住的地方。如果你的家庭宽带没有公网 IP，最省心的做法不是折腾各种网络工具，而是直接买一台低配云服务器，把服务部署到云主机上。云主机的安全组里只放行 443 端口，配合 Nginx 和 HTTPS，一条龙解决。

一核两G的最低配跑轻量翻译服务完全够用，成本也不高。这种方式绕开了家庭网络的各种限制，稳定性和可用性都有保障，后续想扩容也更容易。

无论走哪条路，原则都一样：能用 HTTPS 就不用 HTTP，能加鉴权就不要裸奔。翻译服务要是被滥用，不仅白白消耗资源，还可能触发云服务商的安全告警，到时候就不是配置问题这么简单了。

6. 踩坑记录与资源占用观察

最后分享几个我实际踩过的坑，每一个都在文档之外。

6.1 首次启动模型下载慢

第一次启动 LibreTranslate 时，程序会下载对应的语言模型，文件大小从几十 MB 到两百多 MB 不等。网络链路不好时，启动可能要等很久。我第一次部署时一度以为服务卡死了，直到看了日志才发现是在下载模型。

解决办法有三条：一是部署前尽量选网络链路正常的服务器；二是提前在本地把模型下载好，把模型目录直接打包进镜像；三是把 LT_UPDATE_MODELS 设为 false，避免每次重启都去联网检查更新。如果你下载模型时始终不稳定，试试手动方式下载模型文件再放到 argos-translate 的模型目录下。

6.2 URL 和专有名词会被拆坏

实测中，LibreTranslate 对中英混排文本的效果比预期好，但遇到大写缩写、URL、邮箱地址时，偶尔会丢失格式。比如：

• “Hello, we use OpenAI API” 翻译成“你好，我们使用 OpenAI API”，专有名词能保留；
• “RTX 4090 is powerful” 翻译成“RTX 4090 是强大的”，语义通顺；
• 但长 URL 夹在句子中间时，偶尔会被切断。

解决思路是在送入翻译之前，先用正则把 URL、变量名、代号抽离成占位符，翻译完成后再替换回来。批量处理文档时这个技巧非常实用，能明显减少译文里乱糟糟的格式问题。

6.3 自动语言检测并不可靠

/detect 接口返回的结果长这样：

json复制{
  "confidence": 0.9,
  "language": "en"
}

置信度高不代表一定对。在多语言混排文本中，detect 返回的语言很可能和你的预期不一致。所以我的批量脚本都要求显式传 source，保持原文语言信息，不依赖自动检测。如果你只是临时翻译几段话，自动检测没问题；但一旦进入生产链路，显式传参是最稳的。

6.4 资源占用实测

我用 docker stats 观察过运行中的容器，数据大致如下：

这个开销在今天的服务器配置面前不算高，属于可以长期挂着跑的服务。如果内存确实紧张，可以只在需要翻译时临时启动容器，翻译完再关闭，配合自动化脚本也能用。

6.5 离线模型的翻译质量边界

这里必须说一句公道话：LibreTranslate 的离线翻译模型，质量定位是“能正确传达信息”，不是“文笔优美”。日常沟通、技术文档、常规商务内容都能应付；诗歌、俏皮话、行业黑话，效果就很拉胯。

我现在的做法是把它和本地大模型组合起来用。流程是：原文先由 LibreTranslate 做初翻，快速拿到一个可读的译本，然后用 Ollama 部署的本地模型对译文做润色，修正不通顺的地方。两步都在内网完成，翻译效果比单用任何一个都明显更好。

最后再分享一个升级建议：LibreTranslate 版本更新时，翻译模型可能会变化，译文风格也会有细微差异。如果你的生产批任务正在跑，最好先在测试环境观察新版输出，再决定是否升级。升级前备份 db 目录里的密钥库和模型目录，这个习惯能帮你省掉很多麻烦。整体跑下来，LibreTranslate 属于投入产出比很高的自部署项目，尤其是你在搭 Dify、Ollama 这类本地 AI 链路时，把翻译环节也收编进来，整套系统的可控性会提升一个明显档次。