安装指南

本文档提供详细的安装步骤和系统要求说明。

📋 目录

系统要求
安装方式一：使用安装脚本（推荐，支持自动更新）
安装方式二：下载打包版本
安装方式三：从源码运行
安装方式四：Docker部署
安装方式五：macOS 原生运行（Apple Silicon）
故障排除

系统要求

最低配置

操作系统：Windows 10/11 (64位)、Linux 或 macOS 12+ (Apple Silicon)
内存：8 GB RAM
存储空间：5 GB 可用空间（用于程序和模型文件）
Python 版本（开发版）：Python 3.12

安装方式一：使用安装脚本（⭐ 推荐，自动安装 Miniconda）

脚本会自动完成所有配置，并支持一键更新。

⚠️ 网络提示：下载过程需要从 GitHub 拉取代码，网络不好建议开代理。 💡 新特性：无需预装 Python，脚本会自动安装 Miniconda（轻量级Python环境管理）

前提条件

无需预装 Python：脚本会自动下载安装 Miniconda
Git（可选）：脚本可以自动下载便携版 Git

详细步骤

1. 获取安装脚本

访问仓库：https://github.com/hgmzhn/manga-translator-ui
下载 步骤1-首次安装.bat
保存到你想安装程序的目录（如 D:\manga-translator-ui\）

2. 运行安装脚本

双击 步骤1-首次安装.bat，脚本会：

2.1 检测并安装 Miniconda

✓ 如果系统已有 Python/Conda，直接使用
✗ 如果未安装：
- 提供下载源选择：清华大学镜像（国内推荐）或 Anaconda 官方
- 自动下载 Miniconda3 安装程序（约 50MB）
- 静默安装到：<项目目录>\Miniconda3（不占用C盘）
- 自动配置环境变量
- 注意：安装完成后需要重新运行脚本（重新加载环境变量）

2.2 检测/安装 Git

✓ 如果系统已有 Git，使用系统 Git
✗ 如果没有 Git，提供两个选项：
- 选项 1（推荐）：自动下载便携版 Git（约 50MB）
- 选项 2：手动安装 Git 后重新运行

2.3 选择下载源

选项 1：GitHub 官方源（国外网络）
选项 2（推荐）：gh-proxy.com 镜像（国内更快）

2.4 克隆/更新代码

如果是首次安装：从 GitHub 克隆代码
如果已有代码：自动更新到最新版本

2.5 创建 Conda 环境

在项目目录创建 conda_env 环境（Python 3.12）
位置：<项目目录>\conda_env\
不占用C盘系统空间，环境在项目目录内
隔离项目依赖，不影响系统

2.6 安装依赖

自动检测 GPU：
- ✓ NVIDIA 显卡：
  - 检测 CUDA 版本
  - CUDA >= 12: 安装 GPU 版本依赖（requirements_gpu.txt）
  - CUDA < 12: 提示更新驱动或使用 CPU 版本
- ✓ AMD 显卡：
  - 自动识别显卡型号和 gfx 版本
  - 询问用户确认后安装 AMD ROCm PyTorch（requirements_amd.txt）
  - 仅支持 RX 7000/9000 系列（RDNA 3/4）
  - RX 5000/6000 系列会自动使用 CPU 版本
- ✗ 其他显卡/集显：安装 CPU 版本依赖（requirements_cpu.txt）
使用 launch.py 智能安装所有必需的包

2.7 完成安装

显示安装位置
询问是否立即运行程序

Miniconda 特点

优势：

✅ 体积小（约 50MB）
✅ 可管理多个 Python 版本
✅ 环境隔离，互不干扰
✅ 自带 pip 包管理
✅ 完全安装在项目目录，不占用 C 盘系统空间

目录结构：

D:\manga-translator-ui\          # 你选择的安装目录
├── 步骤1-首次安装.bat            # 安装脚本
├── 步骤2-启动Qt界面.bat          # 启动脚本
├── 步骤3-检查更新并启动.bat      # 更新并启动
├── 步骤4-更新维护.bat            # 维护工具
├── Miniconda3\                   # Miniconda主程序（约600MB）
│   ├── python.exe
│   ├── Scripts\
│   ├── pkgs\
│   └── ...
├── conda_env\                    # 项目虚拟环境（约2-5GB）
│   ├── python.exe
│   ├── Scripts\
│   ├── Lib\
│   └── ...
├── PortableGit\                  # 便携版Git（如果下载）
├── desktop_qt_ui\                # Qt界面源码
├── manga_translator\             # 核心翻译模块
└── ...                           # 其他项目文件

3. 启动程序

安装完成后，以后每次使用只需：

双击 步骤2-启动Qt界面.bat

提示：也可以双击 步骤3-检查更新并启动.bat 在启动前自动检查更新

4. 更新程序（可选）

需要更新到最新版本时：

双击 步骤4-更新维护.bat，选择"完整更新"

安装方式二：下载打包版本

适合不想安装 Python 的用户，但文件较大（约 3-5 GB）。

1. 访问发布页面

前往 GitHub Releases 页面。

2. 选择版本

下载最新版本的安装包：

CPU 版本：

文件名：manga-translator-cpu-vX.X.X.zip 或分卷文件
适用范围：所有电脑
优点：无需 GPU，兼容性好
缺点：翻译速度较慢

GPU 版本：

文件名：manga-translator-gpu-vX.X.X.zip 或分卷文件
适用范围：拥有 NVIDIA 显卡的电脑
要求：CUDA 12.x 支持
优点：翻译速度快
缺点：需要兼容的 NVIDIA 显卡

3. 分卷下载说明

如果文件被分成多个压缩包（如 part1.rar, part2.rar, part3.rar...），请按照以下步骤操作：

下载所有分卷：
- 必须下载所有分卷文件到同一文件夹
- 例如：part1.rar, part2.rar, part3.rar
解压第一个分卷：
- 只需右键点击 part1.rar
- 选择"解压到..."或"Extract to..."
- 其他分卷会自动参与解压
注意事项：
- 所有分卷必须在同一目录
- 不要重命名分卷文件
- 缺少任何一个分卷都会导致解压失败

4. 安装步骤

解压文件：

将下载的压缩包解压到任意目录
例如：D:\manga-translator\

检查文件结构：

manga-translator/
├── app.exe          # 主程序
├── _internal/       # 依赖文件
├── fonts/           # 字体文件
├── models/          # AI 模型文件
└── examples/        # 配置示例

运行程序：
- 双击 app.exe 启动程序
- 首次运行会自动加载模型文件

安装方式三：从源码运行

适合开发者或想自定义的用户。

1. 克隆仓库

git clone https://github.com/hgmzhn/manga-translator-ui.git
cd manga-translator-ui

2. 安装依赖

# CPU 版本
pip install -r requirements_cpu.txt

# GPU 版本（需要 CUDA 12.x）
pip install -r requirements_gpu.txt

3. 运行程序

# 运行 PyQt6 界面
python -m desktop_qt_ui.main

# 或运行旧版 CustomTkinter 界面
python -m desktop-ui.main

安装方式四：Docker 镜像部署（实验性）

适合使用宝塔面板、Portainer 等 Docker 管理工具的用户。

快速启动

Windows CMD / PowerShell：

docker run -d --name manga-translator -p 8000:8000 hgmzhn/manga-translator:latest-cpu

Linux / macOS：

docker run -d --name manga-translator -p 8000:8000 hgmzhn/manga-translator:latest-cpu

启动后访问：

🌐 用户界面：http://localhost:8000
🔧 管理界面：http://localhost:8000/admin.html

镜像仓库

本项目的 Docker 镜像同时发布在两个镜像仓库，选择下载速度更快的即可：

Docker Hub（推荐）：

CPU 版本：hgmzhn/manga-translator:latest-cpu
GPU 版本：hgmzhn/manga-translator:latest-gpu

GitHub Container Registry（备用，国内可能更快）：

CPU 版本：ghcr.io/hgmzhn/manga-translator:latest-cpu
GPU 版本：ghcr.io/hgmzhn/manga-translator:latest-gpu

💡 提示：两个仓库的镜像完全相同，选择下载速度更快的即可。

端口映射

容器端口：8000
主机端口：8000（可自定义）

环境变量配置

💡 提示：所有环境变量都是可选的，程序会使用合理的默认值。

基础配置（可选）

变量名	示例值	默认值	说明
`MT_WEB_HOST`	`0.0.0.0`	`0.0.0.0`	监听地址（0.0.0.0 允许外部访问，127.0.0.1 仅本地访问）
`MT_WEB_PORT`	`8000`	`8000`	服务端口
`MT_USE_GPU`	`true`	`false`	是否使用 GPU（仅 GPU 版本镜像需要设置）
`MT_MODELS_TTL`	`300`	`0`	模型在内存中的存活时间（秒），0 表示永久保留
`MT_RETRY_ATTEMPTS`	`-1`	`None`	翻译失败重试次数，-1 表示无限重试
`MT_VERBOSE`	`true`	`false`	是否显示详细日志
`MANGA_TRANSLATOR_ADMIN_PASSWORD`	`your_password`	无	管理员密码（至少 6 位，不设置则无法访问管理界面）

API Keys 配置（根据使用的翻译器选择）

OpenAI 系列：

变量名	说明
`OPENAI_API_KEY`	OpenAI API Key（用于 openai、openai_hq 翻译器）
`OPENAI_MODEL`	OpenAI 模型名称（可选，默认 gpt-4o）
`OPENAI_API_BASE`	OpenAI API 基础 URL（可选，默认官方地址，可用于自定义端点）
`OPENAI_HTTP_PROXY`	OpenAI HTTP 代理（可选）
`OPENAI_GLOSSARY_PATH`	OpenAI 术语表路径（可选，默认 ./dict/mit_glossary.txt）

Google Gemini 系列：

变量名	说明
`GEMINI_API_KEY`	Google Gemini API Key（用于 gemini、gemini_hq 翻译器）
`GEMINI_MODEL`	Gemini 模型名称（可选，默认 gemini-1.5-flash-002）
`GEMINI_API_BASE`	Gemini API 基础 URL（可选，默认官方地址）

其他商业翻译服务：

变量名	说明
`DEEPL_AUTH_KEY`	DeepL API Key
`GROQ_API_KEY`	Groq API Key
`GROQ_MODEL`	Groq 模型名称（可选，默认 mixtral-8x7b-32768）
`DEEPSEEK_API_KEY`	DeepSeek API Key
`DEEPSEEK_API_BASE`	DeepSeek API 基础 URL（可选，默认官方地址）
`DEEPSEEK_MODEL`	DeepSeek 模型名称（可选，默认 deepseek-chat）
`TOGETHER_API_KEY`	Together AI API Key
`TOGETHER_VL_MODEL`	Together AI 视觉模型（可选，默认 Qwen/Qwen2.5-VL-72B-Instruct）

国内翻译服务：

变量名	说明
`BAIDU_APP_ID`	百度翻译 APP ID
`BAIDU_SECRET_KEY`	百度翻译密钥
`YOUDAO_APP_KEY`	有道翻译应用 ID
`YOUDAO_SECRET_KEY`	有道翻译应用密钥
`CAIYUN_TOKEN`	彩云小译 API 访问令牌
`PAPAGO_CLIENT_ID`	Papago 客户端 ID
`PAPAGO_CLIENT_SECRET`	Papago 客户端密钥

本地/自定义模型：

变量名	说明
`SAKURA_API_BASE`	Sakura API 地址（默认 http://127.0.0.1:8080/v1）
`SAKURA_DICT_PATH`	Sakura 术语表路径（可选，默认 ./dict/sakura_dict.txt）
`CUSTOM_OPENAI_API_KEY`	自定义 OpenAI 兼容 API Key（如 Ollama，默认 ollama）
`CUSTOM_OPENAI_API_BASE`	自定义 OpenAI 兼容 API 地址（默认 http://localhost:11434/v1）
`CUSTOM_OPENAI_MODEL`	自定义模型名称（如 qwen2.5:7b）
`CUSTOM_OPENAI_MODEL_CONF`	自定义模型配置（如 qwen2）

💡 提示：

只需配置你要使用的翻译器对应的 API Key

如果不设置管理员密码，用户可以直接使用翻译功能，但无法访问管理界面

API Keys 也可以在启动后通过管理界面配置（需要先设置管理员密码）

访问地址

部署成功后访问：

用户界面：http://服务器IP:8000
管理界面：http://服务器IP:8000/admin.html（需要管理员密码）

宝塔面板部署步骤

开放端口：
- 进入宝塔面板 → 安全 → 放行端口 8000
- 如有云服务器安全组，也需要开放 8000 端口
安装 Docker：
- 软件商店 → 搜索 Docker 管理器 → 安装
拉取镜像：
- Docker 管理器 → 镜像 → 从仓库拉取
- 填写镜像名：
  - CPU 版本：hgmzhn/manga-translator:latest-cpu
  - GPU 版本：hgmzhn/manga-translator:latest-gpu
创建容器：
- 容器 → 创建容器
- 镜像：选择刚才拉取的镜像
- 端口映射：8000:8000
- 环境变量：根据需要添加（可选）
  
  最小配置（无需设置环境变量，直接启动即可）
  
  推荐配置示例（设置管理员密码和 GPU）：
```
MT_USE_GPU=true
MANGA_TRANSLATOR_ADMIN_PASSWORD=your_secure_password
```
  完整配置示例（包含 API Keys）：
```
MT_USE_GPU=true
MANGA_TRANSLATOR_ADMIN_PASSWORD=your_secure_password
OPENAI_API_KEY=sk-xxxxxxxxxxxxx
GEMINI_API_KEY=xxxxxxxxxxxxx
```
启动容器，访问 http://服务器IP:8000 即可使用

⚠️ 注意：Docker 镜像功能目前处于实验阶段，可能存在未知问题。

部署完成后：

🌐 用户界面：http://服务器IP:8000 - 上传图片进行翻译
🔧 管理界面：http://服务器IP:8000/admin.html - 配置翻译器和参数（需要管理员密码）
📖 使用教程：命令行使用指南 - 了解更多功能和命令行模式

安装方式五：macOS 原生运行（Apple Silicon）

专为搭载 Apple Silicon (M1/M2/M3/M4) 芯片的 Mac 设备设计，利用 MPS (Metal Performance Shaders) 提供原生 GPU 加速。

系统要求

硬件：Mac 电脑 (M1/M2/M3/M4 芯片，Intel Mac 也可运行但使用 CPU 模式)
系统：macOS 12.0 或更高版本
软件：Xcode Command Line Tools（脚本会自动检查并提示安装）

脚本说明

项目提供了 4 个 macOS 专用脚本，对应 Windows 的批处理脚本：

脚本文件	说明	对应 Windows
`macOS_1_首次安装.sh`	首次环境配置、代码克隆、Miniforge 安装、依赖安装	步骤1-首次安装.bat
`macOS_2_启动Qt界面.sh`	启动图形界面	步骤2-启动Qt界面.bat
`macOS_3_检查更新并启动.sh`	检查版本更新后启动	步骤3-检查更新并启动.bat
`macOS_4_更新维护.sh`	运行维护菜单（更新代码、更新依赖、清理缓存等）	步骤4-更新维护.bat

安装步骤

方式一：快速安装（推荐）

只需下载安装脚本，其他全自动：

# 1. 下载安装脚本
curl -O https://raw.githubusercontent.com/hgmzhn/manga-translator-ui/main/macOS_1_首次安装.sh

# 2. 赋予执行权限
chmod +x macOS_1_首次安装.sh

# 3. 运行安装
./macOS_1_首次安装.sh

脚本会自动完成：

检查并提示安装 Xcode Command Line Tools（包含 Git）
克隆项目代码
检测并安装 Miniforge（如未安装）
创建独立的 manga-env 虚拟环境（Python 3.12）
安装所有依赖（使用 requirements_metal.txt）
配置 MPS GPU 加速

方式二：手动克隆

如果你想先查看代码或已有 Git：

# 1. 克隆仓库
git clone https://github.com/hgmzhn/manga-translator-ui.git
cd manga-translator-ui

# 2. 赋予执行权限
chmod +x macOS_*.sh

# 3. 运行安装
./macOS_1_首次安装.sh

验证与启动

安装完成后：

正常启动：
```
./macOS_2_启动Qt界面.sh
```
检查更新并启动：
```
./macOS_3_检查更新并启动.sh
```
更新维护：
```
./macOS_4_更新维护.sh
```
维护菜单提供：
- 更新代码（强制同步到远程）
- 更新/安装依赖
- 完整更新（代码+依赖）
- 修复模式（重装所有依赖）

常见问题

Q: 首次安装需要多长时间？ A: 约 10-20 分钟，取决于网络速度。需要下载约 2GB 的依赖包。

Q: Intel Mac 可以使用吗？ A: 可以，脚本会自动检测并使用 Intel 版本的 Miniforge，但只能使用 CPU 模式（无 MPS 加速）。

Q: 如何更新到最新版本？ A: 运行 ./macOS_4_更新维护.sh，选择"完整更新"即可。

首次运行

1. 启动程序

双击 app.exe，程序会自动：

加载 AI 模型（首次运行需要几分钟）
初始化翻译引擎
打开主界面

2. 基础设置（CPU 版本用户必看）

如果使用 CPU 版本，请务必：

点击"基础设置"标签页
取消勾选"使用 GPU"
点击"保存配置"

⚠️ 重要：CPU 版本如果启用 GPU 会导致程序崩溃！

3. 设置输出目录

在主界面点击"选择输出文件夹"按钮
选择翻译结果的保存位置
程序会记住此设置

4. 选择翻译器

在"基础设置"中找到"翻译器"下拉菜单
首次使用推荐选择：
- 高质量翻译 OpenAI 或 高质量翻译 Gemini（多模态，看图翻译，效果最好）⭐ 强烈推荐
- 需要配置 API Key → 查看 API 配置教程

5. 添加图片

支持以下方式添加图片：

方式 1：点击"添加文件"按钮选择图片
方式 2：点击"添加文件夹"按钮选择文件夹
方式 3：直接拖拽图片到窗口

支持的图片格式：.jpg, .jpeg, .png, .webp, .bmp

6. 开始翻译

确认设置无误
点击"开始翻译"按钮
等待翻译完成
结果会自动保存到输出文件夹

故障排除

程序无法启动

问题：双击 app.exe 没有反应或闪退

解决方法：

检查是否解压了所有文件（不要直接在压缩包中运行）
检查杀毒软件是否拦截了程序
以管理员身份运行 app.exe
查看 logs/error.log 文件

缺少 DLL 文件

问题：提示缺少 VCRUNTIME140.dll 或其他 DLL 文件

解决方法：

下载并安装 Microsoft Visual C++ Redistributable
重启电脑
重新运行程序

GPU 版本崩溃

问题：GPU 版本运行时崩溃或报错

解决方法：

确认显卡支持 CUDA 12.x
安装或更新 NVIDIA 显卡驱动
下载并安装 CUDA Toolkit 12.x
如果仍然失败，使用 CPU 版本

翻译失败

问题：添加图片后翻译失败

解决方法：

检查图片格式是否支持
确认 models/ 目录中的模型文件完整
在"基础设置"中勾选"详细日志"查看错误信息
查看 logs/app.log 文件

模型加载缓慢

问题：首次运行时模型加载时间过长

原因：程序需要加载多个 AI 模型文件（总计约 2-3 GB）

建议：

首次运行耐心等待 5-10 分钟
后续运行会快很多（模型已缓存）
建议安装在 SSD 上以提高加载速度

下一步

安装完成后，建议阅读以下文档：

功能特性 - 了解程序的所有功能
工作流程 - 学习不同的翻译工作流程
设置说明 - 配置翻译器和参数

返回主页

FilesExpand file tree

INSTALLATION.md

Latest commit

History

INSTALLATION.md

File metadata and controls

安装指南

📋 目录

系统要求

最低配置

推荐配置

安装方式一：使用安装脚本（⭐ 推荐，自动安装 Miniconda）

前提条件

详细步骤

1. 获取安装脚本

2. 运行安装脚本

Miniconda 特点

3. 启动程序

4. 更新程序（可选）

安装方式二：下载打包版本

1. 访问发布页面

2. 选择版本

3. 分卷下载说明

4. 安装步骤

安装方式三：从源码运行

1. 克隆仓库

2. 安装依赖

3. 运行程序

安装方式四：Docker 镜像部署（实验性）

快速启动

镜像仓库

端口映射

环境变量配置

基础配置（可选）

API Keys 配置（根据使用的翻译器选择）

访问地址

宝塔面板部署步骤

安装方式五：macOS 原生运行（Apple Silicon）

系统要求

脚本说明

安装步骤

验证与启动

常见问题

首次运行

1. 启动程序

2. 基础设置（CPU 版本用户必看）

3. 设置输出目录

4. 选择翻译器

5. 添加图片

6. 开始翻译

故障排除

程序无法启动

缺少 DLL 文件

GPU 版本崩溃

翻译失败

模型加载缓慢

下一步