MTranServer：1G 内存离线翻译服务怎么部署

MTranServer 是一个可以私有部署的离线翻译服务，仓库在 xxnuo/MTranServer，协议 Apache-2.0。它不吃显卡，官方给的速度是单个请求大约 50 毫秒；早期对外一直说 1G 内存能跑，v4 又把内存和稳定性压过一轮。模型用的是 Mozilla Firefox Translations（Bergamot）那一套。作者自己把上限写在 README 里：翻译质量一般，赶不上大模型，合同和论文这类稿子还是走在线 LLM。

下面按官方 README 和 API.md 写怎么在本机或小机器上挂起来，给浏览器插件和自己的脚本用。

适合什么场景

浏览器里开「沉浸式翻译」或「简约翻译」，想把接口指到自己机器，网页正文不出网。本机或小 VPS 上要一个 HTTP 翻译 API，给脚本、注释翻译插件调用。机器没有 GPU，也不打算为翻译单独上 LibreTranslate 那种吃内存的方案。

官方对比表（CPU、英译中、非严格测试）里，相对 NLLB、LibreTranslate、OPUS-MT 和大模型，这个项目内存占用低、请求也快，效果一栏写的是「一般」。预期对齐了，用起来不容易失望。

硬件和内存

不用 GPU。1G 内存是项目早期一直在用的数字，v4 专门优化过占用。实际吃多少跟加载了几个语言对有关：英中双向先下一对就能用，把很多语言同时塞进内存就另说了。小机器只下载自己常用的语言对。Worker 空闲默认 300 秒会回收，别一上来把所有模型都预热一遍。

CPU 指令集要注意。默认 Docker 镜像按 AVX2 编，老 CPU 启动时报 Illegal instruction，换成 xxnuo/mtranserver:legacy，Releases 里也有带 -legacy 的包。官方构建同时推 linux/amd64 和 linux/arm64。

Docker 部署

官方推荐桌面端或 Docker，手动丢二进制留给熟手。服务默认听 8989。找一个空目录，写 compose.yml：

yml

services:
  mtranserver:
    image: xxnuo/mtranserver:latest
    container_name: mtranserver
    restart: unless-stopped
    ports:
      - "8989:8989"
    environment:
      - MT_HOST=0.0.0.0
      - MT_PORT=8989
      - MT_OFFLINE=false
      - MT_API_TOKEN=change-me
    volumes:
      - ./models:/app/models

然后：

bash

docker pull xxnuo/mtranserver:latest
docker compose up -d

./models 挂到容器里的 /app/models，模型下次重启还在。MT_OFFLINE=false 时，第一次翻译某个语言对会自动下载模型，网不好会卡住一段时间。建议先手动打一条翻译，等模型下完再给插件用。

只给本机用，把端口写成 127.0.0.1:8989:8989。完全不想自动下模型，设 MT_OFFLINE=true；离线模式下 --download 和 --languages 不能用，模型得事先下好。

健康检查：

bash

curl -s http://127.0.0.1:8989/health
curl -s http://127.0.0.1:8989/version

Web UI 默认开着，浏览器打开 http://127.0.0.1:8989 能看到简单页面和 Swagger。公网暴露务必带上 MT_API_TOKEN，不要把 8989 裸挂出去。

本机快速试一下

不走 Docker 也可以。程序员本机用 Node 包管理器执行 mtranserver 这个包就能拉起服务，也可以先全局安装再运行。Windows、Mac、Linux 另有桌面安装包，从 Releases 下载，装完托盘里管服务。

想先把英中模型下好，用 download 参数指定语言对 en_zh 和 zh_en；languages 参数会列出可下载的语言对。常用参数还有 host、port、offline、ui、model-dir（默认在用户目录的 .config/mtran/models）。桌面端自带 UI 和调试文档，本机随手开比 SSH 上服务器省事。

调翻译 API

自带接口写在仓库的 API.md。配了访问令牌之后，翻译接口要认证：请求头用 Authorization Bearer，或在 URL 上加 token 查询参数。健康检查和版本接口不用认证。

单条翻译 POST 到 /translate，请求体如下。批量则 POST 到 /translate/batch，把 text 换成 texts 数组。语言列表用 GET /languages。html 为 true 时按 HTML 片段处理，插件翻网页会用到。

json

{
  "from": "en",
  "to": "zh-Hans",
  "text": "Hello, world!",
  "html": false
}

网页翻译插件不用自己拼 JSON，服务已经做了兼容入口：

插件	地址
沉浸式翻译	`http://localhost:8989/imme`（有令牌就加 `?token=`）
简约翻译	`http://localhost:8989/kiss`
DeepL / DeepLX	`/deepl`、`/deeplx`
Google Translate v2	`/google/language/translate/v2`
划词翻译	`/hcfy`

沉浸式翻译要在设置里打开开发者 Beta，才能看到自定义 API。作者自己的示例把每秒最大请求数拉到 512、每次段落数设 1，按机器再调。简约翻译把并发和间隔调高，才能把 CPU 跑满。VS Code / Cursor 里有配套插件 MTranCode，默认打本机 8989 做注释翻译。

环境变量

够用的几项（完整表看 API.md；启动后的 docs 路径是 Swagger）：

变量	默认	作用
MT_HOST	0.0.0.0	监听地址
MT_PORT	8989	端口
MT_OFFLINE	false	true 时不自动下新模型
MT_API_TOKEN	空	访问令牌
MT_MODEL_DIR	用户目录下 .config/mtran/models	模型目录
MT_ENABLE_UI	true	Web UI
MT_WORKER_IDLE_TIMEOUT	300	worker 空闲回收秒数
MT_LOG_LEVEL	warn	日志
MT_CACHE_SIZE	0	缓存最近几次翻译

Docker 里把模型目录挂到容器的 /app/models。只给本机用时，端口映射写成 127.0.0.1:8989:8989。

常见翻车

现象	先查
第一次翻译很慢或一直转圈	正在下模型。看日志，确认 models 目录可写。国内网络下模型可能慢，先只下一个英中对。
离线模式报没有模型	离线开关打开后不会自动下。先联网下载，再开离线。
容器起不来，日志里 Illegal instruction	CPU 没 AVX2，换 legacy 镜像或 Releases 里的 legacy 包。
插件连上了但不翻译	设了令牌但插件 URL 或 KEY 没带；或健康检查通了但模型还没加载完。打一次 translate 接口看返回。
1G 机器卡死	语言对下多了。只留常用的，确认镜像是 v4 以后。
译文发虚、术语飘	这是模型上限。官方对比表效果栏是「一般」。

小结

服务端用 Docker 挂 8989，模型目录做持久化，令牌打开，先翻一条把英中模型下载完，再把沉浸式翻译或自己的脚本指过去。桌面端和 Node 包适合本机随手开。参数和接口以仓库 README 和 API.md 为准。