LibreTranslate Conda部署方案 Ubuntu

guoqingshan edited this page 2026-08-02 09:03:23 +08:00

Table of Contents

• LibreTranslate Conda 部署方案（Ubuntu）
• 1. 方案说明
• 2. 安装 Miniconda
• 2.1 下载并安装
• 2.2 初始化 conda
• 3. 创建 LibreTranslate 环境
• 4. 安装 LibreTranslate
• 5. 准备数据和日志目录
• 6. 首次下载语言模型
• 7. 创建服务运行用户
• 8. 创建 systemd 服务
• 9. 启动并设置开机自启
• 10. API Key 管理
• 10.1 创建 API Key
• 10.2 查看 Key
• 10.3 删除 Key
• 10.4 使用 Key 调用翻译
• 11. 一键管理脚本
• 12. 配置 Nginx 反向代理
• 12.1 安装 Nginx
• 12.2 创建站点配置
• 13. 接入西班牙语日记项目
• 14. 国内网络模型下载说明
• 14.1 使用代理
• 14.2 手动下载模型
• 15. 常见问题
• 15.1 服务启动失败
• 15.2 提示语言未加载
• 15.3 API Key 文件无权限
• 15.4 模型下载慢
• 16. 总结

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

LibreTranslate Conda 部署方案（Ubuntu）

中文语言标识：简体中文使用 zh-Hans（部分版本也接受 zh），繁体中文使用 zh-Hant。本项目是简体中文，因此自定义接口应使用 zh-Hans，不是 zh-Hant。

1. 方案说明

国内服务器通常无法直接拉取 Docker Hub 镜像，因此本方案使用：

Ubuntu + Miniconda + Python 虚拟环境 + LibreTranslate + systemd

部署完成后：

• LibreTranslate 通过 systemd 自动启动
• 开机自启
• 支持 API Key 管理
• 可作为项目“自定义翻译接口”

2. 安装 Miniconda

2.1 下载并安装

x86_64 服务器：

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 服务器：

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

sudo /opt/miniconda3/bin/conda init bash
source ~/.bashrc

检查版本：

conda --version

3. 创建 LibreTranslate 环境

conda create -n libretranslate python=3.10 -y
conda activate libretranslate

建议使用 Python 3.10；LibreTranslate 在部分 Ubuntu 的 Python 3.12 上存在兼容问题。

4. 安装 LibreTranslate

pip install --upgrade pip
pip install libretranslate

验证安装：

which libretranslate
ltmanage --help

conda 环境内的命令路径通常是：

/opt/miniconda3/envs/libretranslate/bin/libretranslate
/opt/miniconda3/envs/libretranslate/bin/ltmanage

5. 准备数据和日志目录

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. 首次下载语言模型

先手动启动一次，让服务下载中文、西班牙语、英语模型：

conda activate libretranslate
cd /opt/libretranslate
libretranslate \
  --host 127.0.0.1 \
  --port 5001 \
  --load-only zh,es,en \
  --update-models

首次启动会下载模型，需要等待几分钟。看到类似输出后说明成功：

Running on http://127.0.0.1:5001

测试：

curl -X POST http://127.0.0.1:5001/translate \
  -H "Content-Type: application/json" \
  -d '{"q":"我喜欢篮球","source":"zh-Hans","target":"es"}'

正常返回：

{"translatedText":"Me gusta el baloncesto"}

测试完成后按 Ctrl+C 停止。

如果 /languages 只返回 zh-Hans、zh-Hant，可以把 --load-only zh,es,en 改为 --load-only zh-Hans,es,en 后再启动。

7. 创建服务运行用户

sudo useradd -r -s /usr/sbin/nologin -d /opt/libretranslate libretranslate
sudo chown -R libretranslate:libretranslate /opt/libretranslate

8. 创建 systemd 服务

创建服务文件：

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

说明：

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. 启动并设置开机自启

sudo systemctl daemon-reload
sudo systemctl enable --now libretranslate
sudo systemctl status libretranslate

常用命令：

sudo systemctl start libretranslate
sudo systemctl stop libretranslate
sudo systemctl restart libretranslate
sudo journalctl -u libretranslate -f

10. API Key 管理

10.1 创建 API Key

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 次请求。

还可以添加单次字符限制：

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

命令会输出类似：

API key created: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

10.2 查看 Key

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 确认当前版本参数：

/opt/miniconda3/envs/libretranslate/bin/ltmanage keys --help

常见删除命令：

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 调用翻译

curl -X POST http://127.0.0.1:5001/translate \
  -H "Authorization: Bearer 你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{"q":"我喜欢篮球","source":"zh-Hans","target":"es"}'

11. 一键管理脚本

创建脚本 /opt/libretranslate/manage_keys.sh：

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

使用：

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

sudo apt update
sudo apt install nginx -y

12.2 创建站点配置

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. 接入西班牙语日记项目

在本项目“翻译设置”中填写：

翻译方式：自定义接口
接口地址：http://127.0.0.1:5001/translate
接口密钥：你的APIKey
扩展配置：
{
  "result_key": "translatedText",
  "headers": {
    "Authorization": "Bearer 你的APIKey"
  }
}

项目现在默认向自定义接口发送 zh-hans。如果接口要求其他写法，可在扩展配置中增加：

{
  "zh_code": "zh"
}

14. 国内网络模型下载说明

如果首次启动时模型下载失败：

14.1 使用代理

Environment=HTTPS_PROXY=http://你的代理地址:端口
Environment=HTTP_PROXY=http://你的代理地址:端口

14.2 手动下载模型

查询 Argos Translate 可用模型：

/opt/miniconda3/envs/libretranslate/bin/argospm search zh

手动安装：

/opt/miniconda3/envs/libretranslate/bin/argospm install translate-zh_es

模型名称以实际 argospm search 结果为准。

15. 常见问题

15.1 服务启动失败

sudo journalctl -u libretranslate -e

检查目录权限：

sudo chown -R libretranslate:libretranslate /opt/libretranslate

15.2 提示语言未加载

确认环境变量：

LT_LOAD_ONLY=zh,es,en

如果 /languages 显示的是 zh-Hans / zh-Hant，可改为：

LT_LOAD_ONLY=zh-Hans,es,en

15.3 API Key 文件无权限

sudo chown -R libretranslate:libretranslate /opt/libretranslate/db
sudo systemctl restart libretranslate

15.4 模型下载慢

• 配置 HTTPS 代理
• 只加载简体中文 zh-Hans、西语 es、英语 en 三个模型（部分版本也可写 zh,es,en）
• 保证磁盘剩余 5GB 以上

16. 总结

1. 安装 Miniconda
2. 创建 python=3.10 环境
3. pip install libretranslate
4. 手动下载简体中文 zh-Hans、西语 es、英语 en 模型
5. 创建 /opt/libretranslate 目录
6. 创建 systemd 服务并开机自启
7. 使用 ltmanage 创建/查看/删除 API Key
8. 可选配置 Nginx + HTTPS
9. 项目翻译设置选择“自定义接口”并填入 API Key