Ghost-Downloader-3 Docker 部署：三步跑通全协议下载器的容器化指南
【免费下载链接】Ghost-Downloader-3The only downloader you need. 下载器的集大成者。项目地址: https://gitcode.com/GitHub_Trending/gh/Ghost-Downloader-3
Ghost-Downloader-3 是一款覆盖 HTTP、BT、M3U8、MPEG-DASH、eD2k 等协议的开源多平台下载器。本文将其容器化部署拆解为镜像构建、无头运行、数据持久化三步，让你在同一台宿主机上复用同一份运行环境，无需逐平台安装依赖。
🧭 部署前检查清单
宿主机环境要求
- 已安装 Docker Engine 与 docker compose 插件（
docker compose version可正常输出）。 - CPU 需支持 AVX 指令集。项目基于 Qt 6.6+ 的 PySide6 构建，pyproject.toml 中声明了
pyside6~=6.10.3，不支持 AVX 的旧处理器（常见于低配 VPS）会启动失败。 - Python 无需在宿主机安装。项目要求 Python 3.13+（见 pyproject.toml 的
requires-python），由镜像内置，宿主机只需 Docker。
目录规划
建议在工作目录下规划两个持久化目录：
ghost-dl/ ├── Dockerfile ├── docker-compose.yml ├── data/GhostDownloader/ # 应用数据：日志、UserConfig.json 等 └── downloads/ # 下载产物端口与资源预估
- 容器默认不监听对外端口即可运行。若启用 aria2 兼容 RPC（默认 16800，绑定 127.0.0.1，实现见 app/services/aria2_rpc.py）或浏览器扩展服务（默认 14370），才需要映射对应端口，且仅在内网或本机访问时暴露。
- 内存：PySide6 界面 + 下载引擎，空闲约 300~500 MB，下载任务多时预留 1 GB 以上。
- 磁盘：镜像约 1 GB 量级；下载目录按实际文件量规划。
构建镜像：Dockerfile 的四个核心决策
完整文件不必手抄，抓住以下四条核心行即可：
FROM python:3.13-slim RUN apt-get update && apt-get install -y --no-install-recommends \ libgl1 libegl1 libxkbcommon0 libxcb-cursor0 libfontconfig1 \ && rm -rf /var/lib/apt/lists/* COPY pyproject.toml uv.lock ./ RUN pip install uv && uv sync --frozen COPY . . ENV QT_QPA_PLATFORM=offscreen CMD ["python", "Ghost-Downloader-3.py", "--silence"]- 基础镜像：选
python:3.13-slim，与项目requires-python = ">=3.13"严格对齐；slim 变体已足够小，且含编译 C 扩展所需的 glibc。 - 系统依赖：PySide6 依赖一组 Qt 共享库（libgl、libxkbcommon 等），slim 镜像默认不含，必须 apt 安装，否则进程会在加载 QtGui 时直接报错退出。
- 依赖安装：项目使用 uv 管理依赖且锁定了 uv.lock，
uv sync --frozen按锁文件复现，比逐包 pip install 更快、更稳定。 - 无头运行：
QT_QPA_PLATFORM=offscreen让 Qt 在无显示器的容器内渲染到虚拟表面；入口参数--silence见 Ghost-Downloader-3.py，跳过交互窗口直接启动引擎服务。
运行与验证：从启动命令到可用性确认
三条命令构成完整的验证流程：
docker compose up -d # 1. 后台启动 docker compose logs -f # 2. 跟踪日志，出现 "launched" 即引擎已拉起 docker compose ps # 3. 确认状态为 running 且未 restart 循环日志中出现Ghost Downloader v... launched表示主流程初始化完成；若启用了 aria2 RPC，日志会进一步打印 RPC 端口启动信息。需要浏览器扩展配对时，参考下图指引完成安装，扩展通过对应端口与容器通信：
数据持久化：两个必须映射的卷
Ghost-Downloader-3 的数据目录逻辑在 app/config/paths.py：若可执行文件旁存在GhostDownloader/目录，日志、UserConfig.json（语言、端口、下载目录等全部用户配置）都会写入该目录；下载产物默认写入用户Downloads目录。容器内二者都不在镜像层，重启即丢，因此 compose 中必须映射两个卷：
volumes: - ./data/GhostDownloader:/app/GhostDownloader - ./downloads:/root/Downloads这样宿主机上直接可见下载文件与配置，换镜像版本升级时数据原样保留。
生产加固：资源限制、重启策略与健康检查
三项配置合并写入 compose 即可：
services: ghost-downloader: restart: unless-stopped environment: - QT_QPA_PLATFORM=offscreen deploy: resources: limits: cpus: "2" memory: 1g- 资源限制：下载类进程在突发大文件任务时内存波动明显，
1g上限可防止它挤占同机其他服务；CPU 限制到 2 核已够单实例吞吐。 - 重启策略：
unless-stopped保证宿主机重启或进程异常后自动拉起，管理员显式docker stop时不再重启。 - 健康检查：应用为 GUI 进程且服务仅监听容器内回环地址，无法用 HTTP 探活；以进程存活为准——
test: ["CMD", "pgrep", "-f", "Ghost-Downloader-3.py"]，配interval: 30s、retries: 3。
故障速查
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
容器启动后立即退出，日志含libEGL/libxcb相关缺失 | Qt 共享库未装全 | 在 Dockerfile 补齐libgl1 libegl1 libxkbcommon0 libxcb-cursor0后重新构建 |
启动报illegal instruction | 宿主机 CPU 不支持 AVX | 更换支持 AVX 的宿主机，无法在镜像层规避 |
| 升级镜像后配置"消失" | 数据卷未映射 | 按上文映射./data/GhostDownloader，重启容器 |
| 下载文件找不到 | 只映射了数据目录，漏了下载目录 | 补充./downloads:/root/Downloads卷映射 |
| 浏览器扩展连不上 | 扩展端口未映射或端口冲突 | 映射 14370 端口，或在 UserConfig.json 中改用未占用端口 |
| 大文件任务后容器被 OOM kill | 内存限制过低 | 将memory上限调至 2g 或移除该限制观察峰值 |
容器化让 Ghost-Downloader-3 的依赖、配置与运行环境固化为单一镜像，配合卷映射与重启策略，即可作为长期下载服务运行在任意支持 AVX 的主机上。
【免费下载链接】Ghost-Downloader-3The only downloader you need. 下载器的集大成者。项目地址: https://gitcode.com/GitHub_Trending/gh/Ghost-Downloader-3
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
