企业官网建设流程全解析

如何完整部署 Ghost-Downloader-3 多协议下载器的 Docker 镜像

【免费下载链接】Ghost-Downloader-3The only downloader you need. 下载器的集大成者。项目地址: https://gitcode.com/GitHub_Trending/gh/Ghost-Downloader-3

Ghost-Downloader-3 是一款整合 HTTP、m3u8、BT、eD2K 等协议的多协议下载器，还能接收浏览器扩展推送的资源。本文把它部署到 Docker（把应用连同依赖打包成镜像的容器平台）上：构建一个镜像、运行一个容器，就能在服务器上得到一个无界面也能跑通完整下载流程的实例，复制 3 条命令即可上线。

环境与目录前置准备

本节先花几分钟核对 4 项内容，全部通过后再进入构建环节。

• 确认 Docker 可用。在宿主机执行docker version，Client 与 Server 版本号都应正常返回。
• 核对依赖清单。项目依赖声明在 pyproject.toml：Python ≥ 3.13、PySide6 界面、libtorrent 等，版本被仓库根的 uv.lock 锁定，因此基础镜像选python:3.13-slim正好对齐。
• 镜像里要带上两个目录。app/是应用源码；features/ 是功能包目录，每个 pack 对应一种下载协议（m3u8_pack、bittorrent_pack 等），缺了它对应协议就不可用。
• 了解两个运行时路径。路径规则集中在 app/config/paths.py：挂载了/app/GhostDownloader目录时它被用作配置目录（存放 UserConfig.json 与运行日志）；默认下载目标为/root/Downloads。

编写 Dockerfile 并构建镜像

先克隆源码，把下面的 Dockerfile 放在仓库根目录：

git clone https://gitcode.com/GitHub_Trending/gh/Ghost-Downloader-3 cd Ghost-Downloader-3

FROM python:3.13-slim # offscreen 平台所需的 Qt(PySide6) 运行库 + 中文字体 RUN apt-get update && apt-get install -y --no-install-recommends \ libegl1 libgl1 libxkbcommon0 libdbus-1-3 libfontconfig1 \ fonts-noto-cjk \ && rm -rf /var/lib/apt/lists/* WORKDIR /app COPY pyproject.toml uv.lock ./ COPY app/ ./app/ COPY features/ ./features/ COPY Ghost-Downloader-3.py ./ # 仓库自带 uv.lock，用 uv 一次装齐依赖 RUN pip install --no-cache-dir uv && uv sync --frozen --no-dev # 无头服务器：没有 X 显示，Qt 界面走内存渲染 ENV QT_QPA_PLATFORM=offscreen CMD ["uv", "run", "Ghost-Downloader-3.py", "--silence"]

入口是一个 Qt GUI 程序，无头服务器没有显示器，不设置QT_QPA_PLATFORM=offscreen进程会在启动时直接退出；--silence参数则跳过首次运行的引导页——引导页需要交互，容器里你无法操作，跳过后才能直接落到主窗口。另外fonts-noto-cjk也是必须项，界面默认中文，缺 CJK 字体时标题和按钮全是方框。

运行容器并验证启动

挂载两个数据卷启动

docker build -t ghost-downloader:local . docker run -d --name ghost-downloader \ -v $(pwd)/gd-data:/app/GhostDownloader \ -v $(pwd)/downloads:/root/Downloads \ ghost-downloader:local

两个-v的作用：宿主机gd-data挂进容器当配置目录，设置与日志在镜像重建后不丢失，日志文件会落在宿主机的gd-data/GhostDownloader.log；宿主机downloads挂成下载目标，下载完成的文件在宿主机直接可见。容器名ghost-downloader可以自行修改。

查看日志确认启动

docker logs -f ghost-downloader

预期输出中至少能看到这样一行：

... | INFO | ... - Ghost Downloader v4.3.7 launched

判断标准：出现Ghost Downloader v4.3.7 launched说明下载引擎已就绪。若出现could not load the Qt platform plugin，是系统库缺失；若出现Traceback，是 Python 依赖没装全——两者都用docker build --no-cache -t ghost-downloader:local .重新构建解决。

高频问题速查

Qt 平台插件加载失败。现象：日志打印could not load the Qt platform plugin "offscreen"，容器随即退出。原因：镜像缺少 libegl1、libfontconfig1 等 Qt 运行库。解法：检查 Dockerfile 的 apt 安装行是否被删减，用docker build --no-cache -t ghost-downloader:local .重建。

容器重建后数据消失。现象：docker rm并重新构建后，之前下载的文件与设置都不见了。原因：/root/Downloads和/app/GhostDownloader两个目录没有做数据卷映射，数据只存在容器层里。解法：docker run 时始终带上前面「运行」一节的两个-v参数。

浏览器扩展无法配对。现象：扩展里连接状态长期停留在未连接。原因：扩展默认配对端口 14370 没有暴露到宿主机，浏览器所在网络访问不到容器。解法：docker run 追加-p 14370:14370，然后docker restart ghost-downloader。

部署之后

跑通后可以改用 docker compose 管理容器，并在deploy.resources下设置内存上限（如 512M），避免大文件下载占满宿主机内存。若还要用 aria2 客户端从外部提交任务，在应用设置里开启 Aria2 RPC，再为容器发布默认端口 16800（-p 16800:16800）。

【免费下载链接】Ghost-Downloader-3The only downloader you need. 下载器的集大成者。项目地址: https://gitcode.com/GitHub_Trending/gh/Ghost-Downloader-3