Docker Image Puller

项目简介

Docker Image Puller 是一个方便的工具，用于从 Docker 仓库拉取镜像，支持断点续传、多架构选择。该工具采用 MIT 许可证，开放源代码，方便用户根据需要进行定制和扩展。

特点

• 无需安装 Docker 或 Python 环境：直接使用单文件 EXE 或 Python 脚本，开箱即用。
• 无依赖 EXE 执行：编译为独立 EXE 文件，无需安装 Python 环境，无需安装 Docker 环境，直接在 Releases 下载就能直接使用。
• 断点续传：支持下载中断后继续下载，无需重新开始。
• 失败重试：自动重试失败的下载，最大重试10次，确保下载成功。
• SHA256 校验：下载完成后自动校验文件完整性，确保镜像正确。
• 多架构支持：支持多种架构（如 amd64、arm64），自动识别镜像可用架构并提示选择。
• 兼容最新 Docker Registry API：确保与 Docker Hub、Quay.io 等镜像仓库的最新接口兼容。
• 单文件 Python 脚本：便于携带和使用，无需复杂安装。
• 用户友好：提供交互式输入，简化操作流程。
• 下载统计：显示平均下载速度和总耗时。
• 自定义输出目录：支持指定下载目录，默认输出到当前目录。

🌟 全新 Web 可视化版本 (Gradio UI)

除了命令行工具，本次更新特别推出了基于 Gradio 的一站式 Web 图形界面版本（app.py），让搜索、下载、配置和管理流程彻底可视化，操作体验跨越式升级！无需记忆任何命令行参数，只需点点鼠标即可完成离线打包。

Web 版核心亮点：

• 🖥️ 一站式 Web 控制台：告别黑框框，启动后直接在浏览器中进行全流程交互。
• 🔍 全网可视搜索与表格展示：输入关键词，实时呈现包含镜像名称、Star 数、拉取量、更新日期等详细信息的直观表格。
• 🖱️ 智能联动选择：在左侧表格中点击任意镜像，右侧会自动拉取所有可用 Tag 列表。Tag 与架构（amd64/arm64等）均可通过下拉框轻松点选。
• 🌐 多源切换 & 图形化代理配置：
  • 内置支持防墙数据源（如 1ms 专属加速源、国内南大镜像源、Docker官方源）一键切换。
  • 提供单选按钮轻松切换网络模式（无代理、系统代理、自定义账号密码代理），并支持一键开关 SSL 验证。
• 📊 精美实时进度面板：消除传统命令行的刷屏闪烁，提供定制化的 HTML 动态多排条形进度UI，实时展示：当前分块状态、总进度百分比、各分层下载量，以及预估实时下载速度。
• 📁 内置本地镜像大管家：提供独立的本地 .tar 文件管理面板。在前端不仅可以看到所有已下载的包，还支持直接在浏览器里点击下载到当前设备，以及提供下拉框一键删除不需要的包以释放空间。

Web 版使用方法：

运行环境准备（如果非 EXE 版本）：

# 确保安装了相关依赖包
pip install -r requirements.txt

启动服务：

python app.py

终端提示 服务启动中... 后，在任意浏览器中打开 http://127.0.0.1:7860 即可开始使用。

Web 版操作三步走：

1. 第一步（查）：输入 nginx 等关键词，点击搜索，表格出结果后点击你想要的那一行。
2. 第二步（选）：右侧确认 Tag（版本）和 Arch（架构），点击“开始下载”。
3. 第三步（管）：下方进度条跑满后，自动在本地镜像列表中刷出 .tar 文件，可以直接下载到本机转移或一键删除。

Web服务截图

命令截图：

1ms 专版

1ms 专版是针对 1ms.run 镜像仓库优化的版本，提供关键词搜索和一键下载功能。

特点

• 关键词搜索：无需知道完整镜像名，输入关键词即可搜索相关镜像
• 智能推荐：显示搜索结果中每个镜像的下载量stars，帮助选择最流行的镜像
• tag 选择：自动获取并展示可用 tag 列表
• 多架构支持：自动识别可用架构并支持选择
• 多线程下载：支持并发下载，加速大镜像拉取
• 无需 Docker 环境：生成 .tar 包，方便内网传输和使用

使用方法

python docker_image_puller_1ms.py

操作流程

1. 搜索镜像：输入关键词搜索 Docker 镜像

   

2. 选择标签：从可用 tag 列表中选择需要的版本

   

3. 选择架构：根据目标设备选择合适的 CPU 架构

   

4. 多线程下载：支持并发下载，显示实时进度

   

参数说明

参数	说明
-k, --keyword	搜索关键词
-i, --image	镜像名称（与 --keyword 二选一）
-t, --tag	镜像 tag（不传则从列表中选择）
-a, --arch	架构，默认：amd64
-o, --output	输出目录
-w, --workers	并发下载线程数，默认4
--api	1ms API 地址，默认：https://1ms.run/api/v1/registry
--registry	1ms registry 地址，默认：docker.1ms.run

示例

# 交互式搜索下载
python docker_image_puller_1ms.py

# 指定关键词搜索
python docker_image_puller_1ms.py -k nginx

# 指定镜像和tag
python docker_image_puller_1ms.py -i nginx -t latest -a arm64

---

安装

下载 EXE 文件

前往 Releases 页面，下载 DockerPull.exe，无需安装任何依赖，直接运行。

通过 Git 克隆

git clone https://github.com/topcss/docker-pull-tar.git

使用方法

基本用法

DockerPull.exe [选项]

参数说明

参数	说明
-i, --image	Docker 镜像名称（例如：nginx:latest 或 harbor.abc.com/abc/nginx:1.26.0）
-a, --arch	架构，默认：amd64，常见：amd64, arm64 等
-r, --custom-registry	自定义仓库地址（例如：harbor.abc.com）
-u, --username	Docker 仓库用户名
-p, --password	Docker 仓库密码
-o, --output	输出目录，默认为当前目录下的镜像名_tag_arch 目录
-q, --quiet	静默模式，减少交互
--debug	启用调试模式，打印详细日志
--workers	并发下载线程数，默认4
-v, --version	显示版本信息
-h, --help	显示帮助信息

示例

交互式模式

D:\> DockerPull.exe

🚀 Docker 镜像拉取工具 v1.4.0
请输入 Docker 镜像名称（例如：nginx:latest 或 harbor.abc.com/abc/nginx:1.26.0）：alpine
请输入自定义仓库地址（默认 dockerhub）：
请输入镜像仓库用户名：
请输入镜像仓库密码：
📋 当前可用架构：amd64, arm64, armv7, ppc64le, s390x
请输入架构（可选: amd64, arm64, armv7, ppc64le, s390x，默认: amd64）：arm64
📦 仓库地址：registry-1.docker.io
📦 镜像：library/alpine
📦 标签：latest
📦 架构：arm64
📁 输出目录：D:\library_alpine_latest_arm64
📥 开始下载...
✅ 镜像已保存为: library_alpine_latest_arm64.tar
💡 导入命令: docker load -i library_alpine_latest_arm64.tar

命令行模式

# 下载 Docker Hub 镜像
DockerPull.exe -i nginx:latest

# 下载指定架构镜像
DockerPull.exe -i alpine:latest -a arm64

# 下载私有仓库镜像
DockerPull.exe -i harbor.example.com/library/nginx:1.26.0 -u admin -p password

# 指定输出目录
DockerPull.exe -i nginx:latest -o ./downloads

# 静默模式下载
DockerPull.exe -i nginx:latest -q

# 下载 Quay.io 多架构镜像
DockerPull.exe -i quay.io/ascend/vllm-ascend:v0.11.0-a3-openeuler -a arm64

输出目录说明

工具默认将镜像下载到当前目录下的 镜像名_tag_arch 目录中，例如：

• library_alpine_latest_amd64/
• ascend_vllm-ascend_v0.11.0-a3-openeuler_arm64/

可以使用 -o 参数指定输出目录：

DockerPull.exe -i nginx:latest -o ./downloads
# 输出到 ./downloads/library_nginx_latest_amd64/

内网 Docker 导入方法

1. 拉取镜像并打包
   使用本工具拉取镜像并生成 .tar 文件，例如 library_alpine_latest_amd64.tar。

2. 将 .tar 文件传输到内网机器
   通过 U 盘、内网文件服务器或其他方式将 .tar 文件传输到目标机器。

3. 导入镜像到 Docker
   在内网机器上运行以下命令导入镜像：

   docker load -i library_alpine_latest_amd64.tar
   

4. 验证镜像
   导入完成后，运行以下命令查看镜像：

   docker images
   

   然后启动容器：

   docker run -it alpine
   

高可用性特性

断点续传

• 下载中断后，再次运行相同命令会自动从断点继续下载
• 支持网络中断、程序崩溃等场景的恢复
• 进度文件保存在输出目录中

失败重试

• 认证失败：最多重试3次
• 清单获取失败：最多重试3次
• 文件下载失败：最多重试10次
• 采用指数退避策略，避免服务器压力过大

SHA256 校验

• 每个下载的层都会进行 SHA256 校验
• 校验失败自动删除损坏文件并重新下载

信号处理

• 支持 Ctrl+C 优雅退出
• 退出时自动保存下载进度

许可证

本项目采用 MIT 许可证，详情见 LICENSE 文件。

联系方式

如有任何问题或建议，请通过 GitHub Issues 提出。

为什么选择这个工具？

• 无需安装 Docker 或 Python：直接运行 EXE 文件，适合内网环境。
• 断点续传：网络中断不怕，继续下载即可。
• 高可靠性：自动重试、校验完整性，确保下载成功。
• 架构灵活：支持 amd64 和 arm64 等架构，适应多种环境。
• 易于使用：单文件脚本，无需复杂配置。
• 开放源代码：自由定制和扩展。

常见问题

Q: 如何配置国内镜像源？
A: 使用 -r 参数指定仓库地址，或设置环境变量 HTTP_PROXY / HTTPS_PROXY。

Q: 支持哪些架构？
A: 支持 Docker Hub 上所有 Linux 架构，常见：amd64、arm64、armv7 等。工具会自动列出可用架构供选择。

Q: 是否需要安装 Docker 或 Python？
A: 不需要！直接下载 DockerPull.exe 即可运行。

Q: 如何在内网中使用？
A: 使用本工具拉取镜像并生成 .tar 文件，然后通过 docker load 命令导入内网机器。

Q: 下载中断了怎么办？
A: 直接再次运行相同命令，工具会自动从断点继续下载。

Q: 如何指定下载目录？
A: 使用 -o 参数指定，例如 DockerPull.exe -i nginx:latest -o ./downloads。

---

鸣谢：topcss Jack、Potterluo Keriko、wang-lg 等网友贡献的代码。

希望通过这个工具能为您的 Docker 镜像管理带来便利！ 🚀