From f410a9de80ce52277c0c5503a85daa7c2642570c Mon Sep 17 00:00:00 2001
From: guoqingshan <704299375@qq.com>
Date: Sat, 1 Aug 2026 18:07:07 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0LibreTranslate?=
 =?UTF-8?q?=E9=83=A8=E7=BD=B2=E6=96=B9=E6=A1=88?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 LibreTranslate部署方案.md | 248 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 248 insertions(+)
 create mode 100644 LibreTranslate部署方案.md

diff --git a/LibreTranslate部署方案.md b/LibreTranslate部署方案.md
new file mode 100644
index 0000000..bd43277
--- /dev/null
+++ b/LibreTranslate部署方案.md
@@ -0,0 +1,248 @@
+# LibreTranslate 部署方案
+
+## 1. LibreTranslate 是什么
+
+LibreTranslate 是一个开源、可自托管的机器翻译服务，基于 Argos Translate 神经翻译引擎。
+
+特点：
+
+- 无按字符计费，部署后翻译次数基本不受商业 API 限制
+- 翻译在本地模型上运行，文本不会发送给 Google、DeepL 等第三方
+- 提供 REST API，格式和本项目自定义接口兼容
+- 可离线运行，语言模型下载后不再依赖外网
+
+## 2. 翻译效果评价
+
+### 优点
+
+- 中文、英语、西班牙语等常见语言对可达到日常使用水平
+- 适合短句、日记、学习辅助、工具类应用
+- 隐私好，无第三方泄漏风险
+- 成本低，只承担服务器费用
+
+### 局限
+
+- 翻译质量整体低于 DeepL 和 Google Cloud Translation
+- 长句、文学化表达、俚语、文化语境容易不自然
+- 部分冷门语言或语言对需要自己查找/安装模型
+- 首次下载模型较慢，服务器内存不足时响应会变慢
+
+### 适用场景
+
+- 个人学习工具
+- 不需要把文本发送给第三方的内部系统
+- 对翻译成本敏感的项目
+- 对质量要求不是“出版级”的应用
+
+## 3. 推荐部署方式
+
+推荐使用 Docker Compose，最简单且便于升级。
+
+### 3.1 环境要求
+
+```text
+CPU：2 核以上
+内存：4GB 以上（至少 2GB）
+磁盘：10GB 以上，其中模型约 1-4GB
+系统：Linux 推荐；Windows 使用 Docker Desktop
+软件：Docker 20.10+，Docker Compose v2
+```
+
+### 3.2 Docker Compose 部署
+
+创建目录：
+
+```powershell
+mkdir libretranslate
+cd libretranslate
+```
+
+创建 `docker-compose.yml`：
+
+```yaml
+services:
+  libretranslate:
+    image: libretranslate/libretranslate:latest
+    container_name: libretranslate
+    restart: unless-stopped
+    ports:
+      - "5001:5000"
+    environment:
+      - LT_LOAD_ONLY=zh,es,en
+      - LT_API_KEYS=false
+      - LT_REQ_LIMIT=100
+      - LT_UPDATE_MODELS=true
+    volumes:
+      - lt-models:/app/.local
+
+volumes:
+  lt-models:
+```
+
+启动：
+
+```powershell
+docker compose up -d
+```
+
+查看日志：
+
+```powershell
+docker compose logs -f
+```
+
+### 3.3 验证翻译服务
+
+```powershell
+curl -X POST http://localhost:5001/translate ^
+  -H "Content-Type: application/json" ^
+  -d "{\"q\":\"我喜欢篮球\",\"source\":\"zh\",\"target\":\"es\"}"
+```
+
+正常返回类似：
+
+```json
+{
+  "translatedText": "Me gusta el baloncesto"
+}
+```
+
+## 4. 与本项目集成
+
+在本项目“翻译设置”中：
+
+```text
+翻译方式：自定义接口
+接口地址：http://localhost:5001/translate
+接口密钥：留空
+扩展配置：
+{
+  "result_key": "translatedText"
+}
+```
+
+如果 LibreTranslate 和 Web 项目部署在不同机器，接口地址需要写服务器公网或内网地址。
+
+## 5. 安全与生产部署建议
+
+### 5.1 仅本机使用
+
+如果只在本机运行，把 Docker 端口绑定到本机：
+
+```yaml
+ports:
+  - "127.0.0.1:5001:5000"
+```
+
+### 5.2 使用 API Key
+
+设置环境变量：
+
+```yaml
+environment:
+  - LT_API_KEYS=true
+  - LT_API_KEYS_DB_PATH=/app/db/api_keys.db
+  - LT_ADMIN_PASSWORD=你的管理密码
+```
+
+启动后访问管理页面生成 API Key，再在项目设置中填入。
+
+### 5.3 使用 Nginx 反向代理
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name translate.example.com;
+
+    location / {
+        proxy_pass http://127.0.0.1:5001;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+```
+
+建议配合 HTTPS 证书使用。
+
+### 5.4 只加载需要的语言
+
+```yaml
+environment:
+  - LT_LOAD_ONLY=zh,es,en
+```
+
+只加载中文、西班牙语、英语模型，可以减少内存占用并加快启动。
+
+## 6. 常见问题
+
+### 6.1 模型下载失败
+
+确认环境变量：
+
+```yaml
+LT_UPDATE_MODELS=true
+```
+
+并检查服务器是否能访问互联网。
+
+### 6.2 提示语言未加载
+
+检查 `LT_LOAD_ONLY` 是否包含要使用的语言，例如：
+
+```text
+zh,es,en
+```
+
+### 6.3 内存不足
+
+减少加载语言，或把服务器内存提升到 4GB 以上。
+
+### 6.4 公共实例返回 403
+
+不要依赖公共实例，建议部署自己的实例。
+
+### 6.5 翻译质量不够
+
+可考虑混合策略：
+
+- 普通短句：LibreTranslate
+- 重要长句：MyMemory 或 DeepL Free
+
+## 7. 其他部署方式
+
+### 7.1 Railway 一键部署
+
+访问 Railway 的 LibreTranslate 模板，选择部署即可。
+
+适合快速测试，模型需要持久化存储。
+
+### 7.2 Python 源码部署
+
+```bash
+pip install libretranslate
+libretranslate --host 0.0.0.0 --port 5001 --load-only zh,es,en
+```
+
+Windows 本地部署建议使用 Docker Desktop，Python 源码方式更容易遇到依赖问题。
+
+## 8. 与其他服务对比
+
+| 方案 | 免费额度 | 质量 | 部署难度 | 成本 |
+|------|---------|------|---------|------|
+| MyMemory | 约 5000 字符/天 | 中 | 无 | 免费 |
+| LibreTranslate 自部署 | 无字符限制 | 中 | 中 | 服务器费用 |
+| DeepL API Free | 50万字符/月 | 高 | 低 | 免费额度 |
+| Google Translation Basic | 50万字符/月 | 高 | 低 | 免费额度 |
+| Azure Translator F0 | 200万字符/月 | 高 | 低 | 免费额度 |
+
+## 9. 总结
+
+LibreTranslate 是“零按量费用 + 私有部署”的最佳选择，适合本项目作为长期稳定的翻译后端。
+
+推荐方案：
+
+```text
+个人使用：Docker 本机部署 + 127.0.0.1
+公网使用：Docker 部署 + API Key + Nginx + HTTPS
+质量优先：保留 MyMemory / DeepL 作为可选配置
+```