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
 ```