mirror of
https://github.com/sky22333/hubproxy.git
synced 2026-08-09 21:52:11 +08:00
109 lines
4.2 KiB
Plaintext
109 lines
4.2 KiB
Plaintext
---
|
||
title: 离线镜像包
|
||
description: 在线打包 Docker 镜像为 tar 文件，支持单镜像与批量下载。
|
||
---
|
||
|
||
HubProxy Web 界面（`enableFrontend = true`）与 API 支持将镜像在线打包为 tar 离线包，无需本地 Docker 环境。
|
||
|
||
下载采用**两步流程**：先 `prepare` 获取一次性 token，再携带 token 下载。Token 有效期 **2 分钟**，绑定客户端 IP 与 User-Agent。
|
||
|
||
## Web 界面
|
||
|
||
访问 HubProxy 首页，在「离线镜像」功能中输入镜像名与标签即可下载。架构选择留空时优先使用 `linux/amd64`；指定架构但匹配不到时，使用多架构索引中的第一个可用平台。
|
||
|
||
## 镜像名称格式
|
||
|
||
除 Docker Hub 官方镜像外，可直接输入带 Registry 域名的完整引用，从对应平台拉取并打包：
|
||
|
||
| 来源 | 输入示例 |
|
||
|------|---------|
|
||
| Docker Hub | `nginx`、`redis:7` |
|
||
| GHCR | `ghcr.io/sky22333/hubproxy`、`ghcr.io/owner/app:v1.0` |
|
||
| Quay | `quay.io/coreos/etcd:latest` |
|
||
| GCR / K8s | `gcr.io/distroless/base`、`registry.k8s.io/pause:3.9` |
|
||
|
||
未写 tag 时自动补 `:latest`；官方镜像（不含 `/` 的单段名称）会自动补齐 `library/` 命名空间。Registry 需在 `[registries]` 中启用，且镜像可匿名拉取。
|
||
|
||
## 压缩层
|
||
|
||
Web 界面与 API 均提供「压缩层」开关（`compressed` / `useCompressedLayers`，**默认开启**）。**建议保持开启**。
|
||
|
||
| 开关 | tar 内 `layer.tar` 内容 | 体积 | 适用场景 |
|
||
|------|--------------------------|------|---------|
|
||
| 开启（默认） | Registry 中的**压缩 blob**（通常为 gzip） | 更小，下载更快 | 现代 Docker Engine，`docker load` 导入 |
|
||
| 关闭 | **解压后**的文件系统层 tar（与 `docker save` 经典格式一致） | 更大，打包更慢 | 较旧版本 Docker Engine 或仅支持未压缩 layer 的环境 |
|
||
|
||
HubProxy 输出的 tar 为 `docker load` 兼容格式。开启压缩层时，每层保留上游 Registry 原样压缩数据，避免 HubProxy 在服务端解压再重打包，显著减少传输体积与 CPU 开销。保留关闭选项，是为了兼容**旧版 Docker**（镜像 v1 时代及更早的 `docker load` 实现）：彼时 `layer.tar` 通常为未压缩的文件系统 tar，与 `docker save` 导出结果一致；关闭后输出的 layer 格式与之相同。
|
||
|
||
## 单镜像 API
|
||
|
||
**第一步：申请下载**
|
||
|
||
```bash
|
||
curl "https://example.com/api/image/download?image=library/nginx:latest&mode=prepare"
|
||
```
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"download_url": "/api/image/download?image=library/nginx%3Alatest&token=..."
|
||
}
|
||
```
|
||
|
||
**第二步：下载 tar**
|
||
|
||
```bash
|
||
curl -L -o nginx.tar "https://example.com/api/image/download?image=library/nginx:latest&token=YOUR_TOKEN"
|
||
```
|
||
|
||
可选参数：
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| `platform` | 指定平台，如 `linux/arm64`；留空时优先 `linux/amd64`；指定但匹配不到时使用索引中第一个可用平台 |
|
||
| `tag` | 镜像未含 tag 时使用，默认 `latest` |
|
||
| `compressed` | 是否保留 Registry 压缩层写入 tar，默认 `true`（建议开启，见上文「压缩层」） |
|
||
|
||
## 批量 API
|
||
|
||
**第一步：申请批量下载**
|
||
|
||
```bash
|
||
curl -X POST "https://example.com/api/image/batch?mode=prepare" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"images":["nginx:latest","ghcr.io/sky22333/hubproxy:latest"],"useCompressedLayers":true}'
|
||
```
|
||
|
||
**第二步：下载合并 tar**
|
||
|
||
```bash
|
||
curl -L -o batch.tar "https://example.com/api/image/batch?token=YOUR_TOKEN"
|
||
```
|
||
|
||
## 镜像信息
|
||
|
||
```bash
|
||
curl "https://example.com/api/image/info?image=library/nginx:latest"
|
||
```
|
||
|
||
## 限制
|
||
|
||
| 配置 / 规则 | 默认值 | 说明 |
|
||
|------------|--------|------|
|
||
| `[download].maxImages` | `10` | 单次批量镜像数量上限 |
|
||
| prepare 防抖（单镜像） | 5 秒 | 同一用户重复 prepare 会返回 429 |
|
||
| prepare 防抖（批量） | 60 秒 | 同上 |
|
||
| Token TTL | 2 分钟 | 过期或 IP/UA 不匹配则无效 |
|
||
|
||
```toml
|
||
[download]
|
||
maxImages = 10
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
- 大镜像打包耗时较长，流式传输中断后需重新请求
|
||
- 受 `[access]` 黑白名单与 IP 限流约束
|
||
- 前端静态页面（`/`、`/images`、`/search`、`/assets/*`）不计入限流；`/ready`、API 与代理请求均会计入
|