本文来自我的个人博客：告别网页翻译限制！手把手教你搭建私有翻译服务器，附客户端接入指南 - 叹惋博客
MTranServer 是一款基于 Mozilla Firefox 翻译模型的开源离线翻译服务器。完全通过 CPU 计算，不需要独立显卡。单个翻译请求的平均响应时间仅 50 毫秒。英译中模型最低只需要 300MiB 内存即可运行。目前最新版本是 v4，优化了内存占用，速度进一步提升。
支持包括简体中文、英文、法文在内的 30 多种语言。部署完成后所有翻译都在本地完成，不需要联网，也没有调用次数限制。
一、准备工作
在开始安装之前，要有服务器，我用的是雨云服务器
然后确认一下系统环境。
操作系统：Ubuntu 22.04 LTS（其他 Linux 发行版也兼容，但本文以 Ubuntu 22.04 为例）。
硬件要求：仅需 CPU + 1G 内存即可运行，无需显卡。如果有 2G 或更高内存，运行会更流畅。
网络：服务器需要能访问互联网，因为首次翻译时需要自动下载对应的翻译模型。模型文件根据语言对不同大概在 100-500MB 左右。
端口：MTranServer 默认使用 8989 端口。部署前确认一下这个端口没有被占用，如果服务器有防火墙，记得提前放行。
先确认一下系统版本：
cat /etc/os-release
如果显示 PRETTY_NAME="Ubuntu 22.04.xx LTS" 就对了。
二、安装 Docker 和 Docker Compose
MTranServer 官方推荐使用 Docker 部署。下面是在 Ubuntu 22.04 上安装 Docker 的完整步骤。
2.1 更新软件包索引
耗时不短，请耐心等待
sudo apt update
2.2 安装依赖包
Docker 安装需要一些前置依赖：
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
这些包的作用分别是：apt-transport-https 允许 apt 通过 HTTPS 访问仓库，ca-certificates 提供根证书，curl 用于下载文件，software-properties-common 提供 add-apt-repository 命令。
请耐心等待安装完成
2.3 添加 Docker 官方 GPG 密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
2.4 添加 Docker 官方软件源
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
2.5 再次更新软件包索引
sudo apt update
2.6 安装 Docker Engine
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
这里安装的 docker-compose-plugin 就是 Docker Compose 的插件版本。Ubuntu 22.04 推荐使用这种方式安装 Compose。
2.7 验证 Docker 安装
sudo docker run hello-world
如果能看到欢迎信息，说明 Docker 安装成功了。
2.8 验证 Docker Compose 安装
docker compose version
如果显示版本号，说明 Compose 插件也安装好了。
2.9 （可选）将当前用户加入 docker 组
如果不想每次都用 sudo 运行 docker 命令，可以把当前用户加入 docker 组：
sudo usermod -aG docker $USER
执行后需要退出重新登录才能生效。
三、部署 MTranServer
3.1 创建项目目录
找一个合适的位置创建目录，比如在用户目录下：
mkdir -p ~/mtranserver
cd ~/mtranserver
3.2 创建模型目录
mkdir -p models
这个目录用来存放翻译模型文件。
3.3 编写 docker-compose.yml 文件
在 ~/mtranserver 目录下创建 compose.yml 文件：
nano compose.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=your_secret_token_here
volumes:
- ./models:/app/models
几个配置项说明一下：
image: xxnuo/mtranserver:latest：使用最新版的 Docker 镜像container_name: mtranserver：给容器起个名字，方便管理restart: unless-stopped：容器意外停止后会自动重启ports: - "8989:8989"：把服务器的 8989 端口映射到容器的 8989 端口MT_HOST=0.0.0.0：监听所有网络接口，这样外部才能访问MT_PORT=8989：服务端口MT_OFFLINE=false：设为 false 表示允许自动下载模型；如果想完全离线使用可以改为 trueMT_API_TOKEN：访问密钥，强烈建议取消注释并设置自己的密钥，防止服务被他人滥用（若要开启，请去掉#）volumes: - ./models:/app/models：把容器内的模型目录映射到宿主机，容器重建不需要重新下载模型
如果想改端口，比如改成 9000，就把 "8989:8989" 改成 "9000:8989"。
3.4 启动服务
在 ~/mtranserver 目录下执行：
docker compose up -d
-d 参数让容器在后台运行。如果想先测试一下看日志，可以不加 -d：
docker compose up
看到启动日志后按 Ctrl+C 停止，然后用 -d 重新启动后台运行。
3.5 查看容器运行状态
docker ps
应该能看到名为 mtranserver 的容器在运行。
3.6 查看容器日志
如果启动过程中遇到问题，可以查看日志：
docker logs mtranserver
四、配置防火墙
如果你的 Ubuntu 服务器开启了 UFW 防火墙，需要放行 8989 端口：
sudo ufw allow 8989/tcp
有些厂商还需要在云控制台的安全组或防火墙中放行 8989 端口。
查看防火墙状态：
sudo ufw status
五、验证服务是否正常运行
5.1 浏览器访问
容器启动后，在浏览器里访问：
http://你的服务器IP:8989/docs
如果能看到 Swagger API 文档页面，就说明服务已经正常运行了。所有可用的 API 接口都会在这个页面里列出。
5.2 curl 测试
也可以用 curl 命令测试一下：
curl http://你的IP:8989/languages
这个接口会返回所有支持的语言列表。如果返回了 JSON 数据，说明服务完全正常。
六、第一次翻译——下载模型
重要提示：首次翻译某个语言对时，服务器会自动下载对应的翻译模型。这个过程可能需要等待一段时间，取决于网络速度和模型大小。下载完成后，后续翻译就是毫秒级响应。
建议部署完成后先主动触发一次翻译请求，让服务器把模型下载好：
curl -X POST http://你的IP:8989/translate \
-H "Content-Type: application/json" \
-d '{"from": "en", "to": "zh-CN", "text": "Hello world"}'
如果设置了 MT_API_TOKEN，需要在请求头中加上 Authorization：
curl -X POST http://你的IP:8989/translate \
-H "Authorization: 3qCkhJi05M8Zepo5" \
-H "Content-Type: application/json" \
-d '{"from": "en", "to": "zh-CN", "text": "Hello world"}'
如果第一次返回比较慢（可能几秒到几十秒），别着急，等模型下载完就好了。
如果模型下载卡住了，可以用 docker logs mtranserver 查看进度。
注意：每个翻译方向需要独立的模型文件。比如日语→英语和英语→日语是两个不同的模型。如果提示 “Language pair is not supported”，说明当前语言对没有对应的模型文件。
七、接入翻译客户端
服务搭好了，怎么用呢？MTranServer 提供了多种 API 接口，可以接入各种翻译工具。
7.1 沉浸式翻译插件
沉浸式翻译（Immersive Translate）是浏览器上非常好用的双语翻译插件。
配置步骤：
1.在 Edge 或 Chrome 应用商店安装沉浸式翻译插件
这里以edge为例，访问Microsoft Edge 加载项 - Immersive Translate
2.打开插件设置 → 开发者模式 → 启用 Beta 特性
3.选择“添加自定义翻译服务” → “自定义 API”
4.API 地址填：http://你的IP:8989/imme?token=your_token （如没设置设了 MT_API_TOKEN，则填入http://你的IP:8989/imme）
5.支持的语言先填：en,zh-CN
7.剩下部分根据你服务器情况填写
6.点击“测试服务”，出现绿色提示就配置成功了
配置好后，浏览外文网页就能享受自己服务器提供的翻译服务了。
7.2 简约翻译插件
简约翻译也支持接入 MTranServer：
1.前往Microsoft Edge 加载项 - KISS Translator按照上面同样步骤获取并安装
2.进行设置
URL填入：http://你的IP:8989/kiss
若设置了 MT_API_TOKEN，往Key中填入你的token
下拉到下面测试并保存。
7.3 插件配置对照
| 名称 | URL | 插件设置 |
|---|---|---|
| 沉浸式翻译无密码 | http://localhost:8989/imme |
自定义API 设置 - API URL |
| 沉浸式翻译有密码 | http://localhost:8989/imme?token=your_token |
同上，需要更改 URL 尾部的 your_token 为你的 MT_API_TOKEN 值 |
| 简约翻译无密码 | http://localhost:8989/kiss |
接口设置 - Custom - URL |
| 简约翻译有密码 | http://localhost:8989/kiss |
同上，需要 KEY 填 your_token |
| DeepL 兼容 | http://localhost:8989/deepl |
使用 DeepL-Auth-Key 或 Bearer 认证 |
| DeepLX 兼容 | http://localhost:8989/deeplx |
支持 token 参数或 Bearer 认证 |
| Google 兼容 | http://localhost:8989/google/language/translate/v2 |
使用 key 参数或 Bearer 认证 |
| 划词翻译 | http://localhost:8989/hcfy |
支持 token 参数或 Bearer 认证 |
7.4 PotPlayer 视频播放器（字幕翻译）
有开发者专门为 PotPlayer 制作了调用 MTranServer API 实现字幕翻译的功能。看生肉视频时，字幕可以实时翻译成中文。
项目地址：albertyann/potplayer-translation-mtranserver
7.5 自定义开发
MTranServer 提供了标准的 RESTful API，主要接口包括：
/languages：获取支持的语言列表/translate：执行翻译请求/translate/batch：批量翻译/imme：沉浸式翻译专用接口/kiss：简约翻译专用接口/ui：简单 UI 界面
访问 http://你的IP:8989/docs 可以看到完整的 API 文档。
八、进阶配置
8.1 离线模式部署
如果服务器网络环境不太好，或者想完全离线使用，可以设置 MT_OFFLINE=true：
environment:
- MT_OFFLINE=true
但注意首次使用前需要手动把模型文件放到 ./models 目录。模型文件可以从项目的 Releases 页面下载。
8.2 老 CPU 兼容
极老的 CPU 可能不支持 AVX2 指令集。项目有专门为仅支持 SSE 指令集的 CPU 准备的兼容镜像：
services:
mtranserver:
image: xxnuo/mtranserver-amd64v1:latest
8.3 内存优化
如果同时加载了多个语言模型，内存占用会相应增加。只保留自己需要的语言模型即可。
8.4 更新容器
程序经常更新，更新到最新版的方法：
docker compose down
docker pull xxnuo/mtranserver:latest
docker compose up -d
九、常见问题
Q：访问 /docs 显示 404 或 405？
这说明服务可能没正常启动，或者端口没放行。检查容器状态：docker ps -a，确认容器在运行。如果是云服务器，检查防火墙和安全组是否放行了 8989 端口。
Q：翻译请求返回很慢或者没反应？
首次翻译某个语言对时会自动下载模型，耐心等待即可。可以用 docker logs mtranserver 查看下载进度。
Q：提示 “Language pair is not supported”？
说明当前语言对没有对应的模型文件。不同语言之间的翻译需要独立的模型文件。可以到项目的 Releases 页面下载对应的模型包，解压到 models 目录。
Q：老 CPU 启动失败？
极老的 CPU 可能不支持 AVX2 指令集。使用兼容镜像：xxnuo/mtranserver-amd64v1:latest。
Q：内存占用太高？
如果同时加载了多个语言模型，内存占用会相应增加。只保留自己需要的语言模型即可。另外 v4 版本优化了内存占用，建议使用最新版。
十、总结
到这里，一个属于自己的私有翻译服务器就搭建好了。整个过程用 Docker 部署，只需几条命令就能搞定。
MTranServer 最大的优势在于低资源消耗——1G 内存就能跑；速度快——50ms 的平均响应时间；以及完全离线、私有部署——数据不外传，没有调用次数限制。
日常看网页、读文献、看视频字幕，它完全能够胜任。项目是开源的，如果觉得有用可以去 GitHub 仓库 给作者点个 Star。
本文基于 MTranServer 官方 GitHub 仓库及 Docker 镜像文档整理，部署时建议参考最新版官方文档。