# dockerpull4j

**Repository Path**: lanseba/dockerpull4j

## Basic Information

- **Project Name**: dockerpull4j
- **Description**: docker pull java实现，用于没有docker环境时，原生docker pull 遇到证书问题时等情况下下载docker 镜像
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-05
- **Last Updated**: 2025-12-04

## Categories & Tags

**Categories**: containers

**Tags**: None

## README

# Java Docker 镜像下载器 (docker pull for java)

这是一个使用 Java 编写的命令行工具，用于从 Docker Registry 下载指定的镜像，包括其 manifest、config blob 和所有层文件。它支持多线程下载层文件、断点续传（通过哈希验证本地缓存）、处理多架构镜像、模拟浏览器头部以应对某些安全防护（如 Cloudflare），并将下载的组件打包成一个 `.tar` 文件。最终，它可以选择性地尝试将这个 `.tar` 文件导入到本地 Docker 环境中。


## 编译好可执行jar  dp.jar 可以直接下载使用

* 用法: java -jar DockerImageDownloader.jar <完整镜像名> [--arch <架构>] [--token <Bearer Token>] [--threads <数量>] [--output-tar <输出tar包名.tar>] [--no-cleanup]
* 示例 (私有仓库): java -jar dp.jar myregistry.com/namespace/image:tag --token YOUR_TOKEN_HERE --threads 8 --output-tar myimage.tar
* 示例 (Docker Hub 公共): java -jar dp.jar ubuntu:latest --arch amd64 --threads 2
* 示例 (最简): java -jar dp.jar ubuntu:latest
## _功能特性_

*   **镜像解析**: 支持解析标准 Docker 镜像名称格式，包括可选的 registry host、namespace、镜像名和标签。
*   **默认 Docker Hub**: 如果未指定 registry host，且镜像名格式符合 Docker Hub 官方或用户镜像，则自动使用 Docker Hub (`docker.1panel.live`)。
*   **多架构支持**:
    *   如果镜像是多架构 manifest list，用户可以通过 `--arch` 参数指定目标架构。
    *   如果未指定 `--arch`，程序会尝试自动检测当前运行环境的 CPU 架构作为默认值。
    *   如果仍无法确定或找不到匹配架构，会尝试选择一个默认的 Linux 架构（如 amd64 或 arm64）。
*   **认证**: 支持通过 `--token` 参数传入 Bearer Token 以访问需要认证的私有 Docker Registry。对于 Docker Hub 上的公共镜像，程序会尝试自动获取匿名的只读访问 token。
*   **多线程下载**: 使用可配置的线程池并发下载镜像的层文件，以提高下载效率。
*   **断点续传与哈希验证**:
    *   在下载每个层或 config blob 之前，会检查本地缓存中是否存在该文件。
    *   如果文件存在，会计算其 SHA256 哈希值并与 manifest 中记录的摘要进行比较。
    *   如果哈希匹配，则跳过下载（缓存命中）。
    *   如果哈希不匹配或文件不存在，则重新下载。
    *   下载完成后会再次验证哈希，确保文件完整性。
*   **进度报告**:
    *   为每个并发下载的层文件在控制台独立打印下载进度，包括已下载百分比、大小和即时下载速度 (MB/s)。
    *   打印总体下载进度（已下载 MB / 总 MB）。
*   **模拟浏览器头部**: 在发起 HTTP 请求时，模拟常见的浏览器 `User-Agent` 和其他 HTTP 头部，以尝试绕过一些基于请求头部的安全防护（如某些 Cloudflare 设置）。
*   **本地缓存**: 所有下载的组件（manifest, config, layer blobs）会存储在程序运行目录下自动创建的一个缓存子目录中 (例如 `./myimage_latest_cache/`)。
*   **最终归档**:
    *   将下载的 manifest、config 和所有层 blob 打包成一个 `.tar` 文件。
    *   生成的 tar 包结构尝试接近 `docker save` 的输出，以便能被 `docker load` 命令加载：
        *   顶层 `manifest.json` (描述镜像的 JSON 数组)
        *   `<config_digest_content>.json` (配置文件)
        *   `blobs/sha256/<layer_digest_content>.tar.gz` (每个原始层 blob)
*   **可选 Docker 导入**: 下载并打包完成后，程序会询问用户是否尝试将生成的 `.tar` 文件导入到本地 Docker 环境中（通过执行 `docker load -i <tarfile>`）。
*   **缓存清理**: 默认情况下，在所有操作成功完成后，缓存目录会被删除。可以通过 `--no-cleanup` 参数保留缓存。如果程序中途出错，缓存通常不会被删除，以便下次运行时可以利用已下载的部分。
*   **中文日志**: 程序的主要输出信息和日志为中文。

## 环境要求

*   Java Development Kit (JDK) 1.8 或更高版本。
*   Apache Maven (如果从源码编译)。
*   已安装并配置好的 Docker 环境 (如果需要使用 `导入docker` 功能)。
*   网络连接，以便访问 Docker Registry。

## 依赖库 (Maven)

程序依赖以下第三方库，如果使用 Maven 构建，它们会自动处理：

*   `org.json:json`: 用于解析和处理 JSON 数据 (manifest, config)。
*   `org.apache.commons:commons-compress`: 用于处理 `.tar.gz` 文件的解压和创建最终的 `.tar` 归档。
*   `commons-io:commons-io`: (可选, 但 `IOUtils.copy` 很方便) 用于流操作。

请确保在 `pom.xml` 文件中包含这些依赖。

## 如何编译 (使用 Maven)

1.  将源码保存到你的项目中 (例如 `src/main/java/com/tcshuo/DockerImageDownloader.java`)。
2.  在项目根目录下，运行 Maven 命令进行编译和打包：
    ```bash
    mvn clean package
    ```
3.  这会在 `target/` 目录下生成一个包含所有依赖的可执行 JAR 文件 (例如 `YourProjectName-1.0-SNAPSHOT-jar-with-dependencies.jar`)。

## 如何运行

使用 `java -jar` 命令运行编译好的 JAR 文件。

**基本用法:**

```bash
java -jar YourJarName.jar <完整镜像名> [选项...]