docs: 添加LibreTranslate Conda部署方案（Ubuntu）

2026-08-01 20:44:25 +08:00
parent f410a9de80
commit 0120d799a5
1 changed files with 423 additions and 0 deletions
@@ -0,0 +1,423 @@
+# LibreTranslate Conda 部署方案（Ubuntu）
+
+## 1. 方案说明
+
+国内服务器通常无法直接拉取 Docker Hub 镜像，因此本方案使用：
+
+```text
+Ubuntu + Miniconda + Python 虚拟环境 + LibreTranslate + systemd
+```
+
+部署完成后：
+
+- LibreTranslate 通过 systemd 自动启动
+- 开机自启
+- 支持 API Key 管理
+- 可作为项目“自定义翻译接口”
+
+## 2. 安装 Miniconda
+
+### 2.1 下载并安装
+
+x86_64 服务器：
+
+```bash
+cd /tmp
+wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
+sudo bash Miniconda3-latest-Linux-x86_64.sh -b -p /opt/miniconda3
+```
+
+ARM64 服务器：
+
+```bash
+wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-aarch64.sh
+sudo bash Miniconda3-latest-Linux-aarch64.sh -b -p /opt/miniconda3
+```
+
+### 2.2 初始化 conda
+
+```bash
+sudo /opt/miniconda3/bin/conda init bash
+source ~/.bashrc
+```
+
+检查版本：
+
+```bash
+conda --version
+```
+
+## 3. 创建 LibreTranslate 环境
+
+```bash
+conda create -n libretranslate python=3.10 -y
+conda activate libretranslate
+```
+
+> 建议使用 Python 3.10；LibreTranslate 在部分 Ubuntu 的 Python 3.12 上存在兼容问题。
+
+## 4. 安装 LibreTranslate
+
+```bash
+pip install --upgrade pip
+pip install libretranslate
+```
+
+验证安装：
+
+```bash
+which libretranslate
+ltmanage --help
+```
+
+conda 环境内的命令路径通常是：
+
+```text
+/opt/miniconda3/envs/libretranslate/bin/libretranslate
+/opt/miniconda3/envs/libretranslate/bin/ltmanage
+```
+
+## 5. 准备数据和日志目录
+
+```bash
+sudo mkdir -p /opt/libretranslate/db
+sudo mkdir -p /opt/libretranslate/logs
+sudo chmod 755 /opt/libretranslate
+sudo chown -R $USER:$USER /opt/libretranslate
+```
+
+## 6. 首次下载语言模型
+
+先手动启动一次，让服务下载中文、西班牙语、英语模型：
+
+```bash
+conda activate libretranslate
+cd /opt/libretranslate
+libretranslate \
+  --host 127.0.0.1 \
+  --port 5001 \
+  --load-only zh,es,en \
+  --update-models
+```
+
+首次启动会下载模型，需要等待几分钟。看到类似输出后说明成功：
+
+```text
+Running on http://127.0.0.1:5001
+```
+
+测试：
+
+```bash
+curl -X POST http://127.0.0.1:5001/translate \
+  -H "Content-Type: application/json" \
+  -d '{"q":"我喜欢篮球","source":"zh","target":"es"}'
+```
+
+正常返回：
+
+```json
+{"translatedText":"Me gusta el baloncesto"}
+```
+
+测试完成后按 `Ctrl+C` 停止。
+
+## 7. 创建服务运行用户
+
+```bash
+sudo useradd -r -s /usr/sbin/nologin -d /opt/libretranslate libretranslate
+sudo chown -R libretranslate:libretranslate /opt/libretranslate
+```
+
+## 8. 创建 systemd 服务
+
+创建服务文件：
+
+```bash
+sudo tee /etc/systemd/system/libretranslate.service > /dev/null <<'EOF'
+[Unit]
+Description=LibreTranslate Machine Translation API
+After=network.target
+
+[Service]
+Type=simple
+User=libretranslate
+Group=libretranslate
+WorkingDirectory=/opt/libretranslate
+Environment=HOME=/opt/libretranslate
+Environment=LT_LOAD_ONLY=zh,es,en
+Environment=LT_UPDATE_MODELS=true
+Environment=LT_API_KEYS=true
+Environment=LT_API_KEYS_DB_PATH=/opt/libretranslate/db/api_keys.db
+Environment=LT_REQ_LIMIT=60
+Environment=LT_CHAR_LIMIT=2000
+ExecStart=/opt/miniconda3/envs/libretranslate/bin/libretranslate --host 127.0.0.1 --port 5001
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+EOF
+```
+
+说明：
+
+```text
+LT_LOAD_ONLY=zh,es,en    只加载中文、西班牙语、英语模型
+LT_UPDATE_MODELS=true    启动时允许更新/下载模型
+LT_API_KEYS=true         启用 API Key
+LT_REQ_LIMIT=60          每分钟请求限制
+LT_CHAR_LIMIT=2000       单次最大字符数
+```
+
+## 9. 启动并设置开机自启
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now libretranslate
+sudo systemctl status libretranslate
+```
+
+常用命令：
+
+```bash
+sudo systemctl start libretranslate
+sudo systemctl stop libretranslate
+sudo systemctl restart libretranslate
+sudo journalctl -u libretranslate -f
+```
+
+## 10. API Key 管理
+
+### 10.1 创建 API Key
+
+```bash
+sudo -u libretranslate /opt/miniconda3/envs/libretranslate/bin/ltmanage keys \
+  --api-keys-db-path /opt/libretranslate/db/api_keys.db \
+  add 120
+```
+
+参数 `120` 表示该 Key 每分钟最多 120 次请求。
+
+还可以添加单次字符限制：
+
+```bash
+sudo -u libretranslate /opt/miniconda3/envs/libretranslate/bin/ltmanage keys \
+  --api-keys-db-path /opt/libretranslate/db/api_keys.db \
+  add 120 --char-limit 5000
+```
+
+命令会输出类似：
+
+```text
+API key created: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+```
+
+### 10.2 查看 Key
+
+```bash
+sudo -u libretranslate /opt/miniconda3/envs/libretranslate/bin/ltmanage keys \
+  --api-keys-db-path /opt/libretranslate/db/api_keys.db \
+  list
+```
+
+### 10.3 删除 Key
+
+先查看 `ltmanage keys --help` 确认当前版本参数：
+
+```bash
+/opt/miniconda3/envs/libretranslate/bin/ltmanage keys --help
+```
+
+常见删除命令：
+
+```bash
+sudo -u libretranslate /opt/miniconda3/envs/libretranslate/bin/ltmanage keys \
+  --api-keys-db-path /opt/libretranslate/db/api_keys.db \
+  remove 你的APIKey
+```
+
+### 10.4 使用 Key 调用翻译
+
+```bash
+curl -X POST http://127.0.0.1:5001/translate \
+  -H "Authorization: Bearer 你的APIKey" \
+  -H "Content-Type: application/json" \
+  -d '{"q":"我喜欢篮球","source":"zh","target":"es"}'
+```
+
+## 11. 一键管理脚本
+
+创建脚本 `/opt/libretranslate/manage_keys.sh`：
+
+```bash
+sudo tee /opt/libretranslate/manage_keys.sh > /dev/null <<'EOF'
+#!/usr/bin/env bash
+set -e
+
+LT=/opt/miniconda3/envs/libretranslate/bin/ltmanage
+DB=/opt/libretranslate/db/api_keys.db
+
+usage() {
+  echo "用法: $0 {add [限额] [字符限制] | list | remove <key>}"
+  exit 1
+}
+
+case "$1" in
+  add)
+    limit="${2:-120}"
+    char_limit="${3:-2000}"
+    sudo -u libretranslate "$LT" keys --api-keys-db-path "$DB" add "$limit" --char-limit "$char_limit"
+    ;;
+  list)
+    sudo -u libretranslate "$LT" keys --api-keys-db-path "$DB" list
+    ;;
+  remove)
+    [ -n "$2" ] || usage
+    sudo -u libretranslate "$LT" keys --api-keys-db-path "$DB" remove "$2"
+    ;;
+  *)
+    usage
+    ;;
+esac
+EOF
+
+sudo chmod +x /opt/libretranslate/manage_keys.sh
+```
+
+使用：
+
+```bash
+sudo /opt/libretranslate/manage_keys.sh add 120 5000
+sudo /opt/libretranslate/manage_keys.sh list
+sudo /opt/libretranslate/manage_keys.sh remove 你的APIKey
+```
+
+## 12. 配置 Nginx 反向代理
+
+### 12.1 安装 Nginx
+
+```bash
+sudo apt update
+sudo apt install nginx -y
+```
+
+### 12.2 创建站点配置
+
+```bash
+sudo tee /etc/nginx/sites-available/libretranslate > /dev/null <<'EOF'
+server {
+    listen 80;
+    server_name translate.example.com;
+
+    client_max_body_size 2m;
+
+    location / {
+        proxy_pass http://127.0.0.1:5001;
+        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;
+    }
+}
+EOF
+
+sudo ln -s /etc/nginx/sites-available/libretranslate /etc/nginx/sites-enabled/
+sudo nginx -t
+sudo systemctl reload nginx
+```
+
+公网部署建议配置 HTTPS（Certbot）。
+
+## 13. 接入西班牙语日记项目
+
+在本项目“翻译设置”中填写：
+
+```text
+翻译方式：自定义接口
+接口地址：http://127.0.0.1:5001/translate
+接口密钥：你的APIKey
+扩展配置：
+{
+  "result_key": "translatedText",
+  "headers": {
+    "Authorization": "Bearer 你的APIKey"
+  }
+}
+```
+
+## 14. 国内网络模型下载说明
+
+如果首次启动时模型下载失败：
+
+### 14.1 使用代理
+
+```ini
+Environment=HTTPS_PROXY=http://你的代理地址:端口
+Environment=HTTP_PROXY=http://你的代理地址:端口
+```
+
+### 14.2 手动下载模型
+
+查询 Argos Translate 可用模型：
+
+```bash
+/opt/miniconda3/envs/libretranslate/bin/argospm search zh
+```
+
+手动安装：
+
+```bash
+/opt/miniconda3/envs/libretranslate/bin/argospm install translate-zh_es
+```
+
+> 模型名称以实际 `argospm search` 结果为准。
+
+## 15. 常见问题
+
+### 15.1 服务启动失败
+
+```bash
+sudo journalctl -u libretranslate -e
+```
+
+检查目录权限：
+
+```bash
+sudo chown -R libretranslate:libretranslate /opt/libretranslate
+```
+
+### 15.2 提示语言未加载
+
+确认环境变量：
+
+```ini
+LT_LOAD_ONLY=zh,es,en
+```
+
+### 15.3 API Key 文件无权限
+
+```bash
+sudo chown -R libretranslate:libretranslate /opt/libretranslate/db
+sudo systemctl restart libretranslate
+```
+
+### 15.4 模型下载慢
+
+- 配置 HTTPS 代理
+- 只加载 `zh,es,en` 三个模型
+- 保证磁盘剩余 5GB 以上
+
+## 16. 总结
+
+```text
+1. 安装 Miniconda
+2. 创建 python=3.10 环境
+3. pip install libretranslate
+4. 手动下载 zh,es,en 模型
+5. 创建 /opt/libretranslate 目录
+6. 创建 systemd 服务并开机自启
+7. 使用 ltmanage 创建/查看/删除 API Key
+8. 可选配置 Nginx + HTTPS
+9. 项目翻译设置选择“自定义接口”并填入 API Key
+```