mirror of
https://github.com/sky22333/hubproxy.git
synced 2026-08-05 03:24:57 +08:00
update docs
This commit is contained in:
sky22333
@@ -11,7 +11,7 @@ description: HubProxy 配置文件完整参考。
|
||||
|----|------|--------|------|
|
||||
| `host` | string | `0.0.0.0` | 监听地址 |
|
||||
| `port` | int | `5000` | 监听端口 |
|
||||
| `fileSize` | int | `2147483648` | 单文件大小上限（字节），影响 GitHub 代理与离线镜像 |
|
||||
| `fileSize` | int | `2147483648` | 单文件大小上限（字节），仅影响 GitHub / Hugging Face URL 代理 |
|
||||
| `enableH2C` | bool | `false` | 启用 HTTP/2 Cleartext |
|
||||
| `enableFrontend` | bool | `true` | 启用 Web 界面（Vue SPA） |
|
||||
|
||||
@@ -22,7 +22,7 @@ description: HubProxy 配置文件完整参考。
|
||||
| `requestLimit` | int | `500` | 每 IP 每周期允许请求数 |
|
||||
| `periodHours` | float | `3.0` | 限流周期（小时） |
|
||||
|
||||
IPv4 按完整 IP 计数，IPv6 按 `/64` 网段计数。前端静态路由（`/`、`/images`、`/search`、`/assets/*`）不计入限流。
|
||||
IPv4 按完整 IP 计数，IPv6 按 `/64` 网段计数。仅前端静态路由（`/`、`/images`、`/search`、`/favicon.ico`、`/assets/*`）不计入限流；`/ready`、API 与代理请求均会计入。
|
||||
|
||||
:::note
|
||||
Docker 拉取一个镜像会请求多个 layer，每个 HTTP 请求均消耗限流配额。
|
||||
@@ -69,7 +69,7 @@ Docker 拉取一个镜像会请求多个 layer，每个 HTTP 请求均消耗限
|
||||
默认预置 `ghcr.io`、`gcr.io`、`quay.io`、`registry.k8s.io`。Docker Hub 固定走 `registry-1.docker.io`，不在此段配置。
|
||||
|
||||
:::note
|
||||
当前版本对所有 Registry 均使用匿名拉取（`authn.Anonymous`），`authType` 仅用于标识认证端点类型，**尚未**实现 GitHub Token 或 Google 服务账号等私有仓库凭据。私有镜像仍需客户端自行携带认证。
|
||||
当前版本对所有 Registry 均使用匿名拉取（`authn.Anonymous`），`authType` 仅用于标识认证端点类型，**尚未**实现 GitHub Token 或 Google 服务账号等私有仓库凭据，且不转发客户端 `Authorization` 头。**无法**通过 HubProxy 拉取需要认证的私有镜像。
|
||||
:::
|
||||
|
||||
## [tokenCache]
|
||||
@@ -93,7 +93,7 @@ Manifest 缓存 TTL 规则：
|
||||
|
||||
| 路径 | 说明 |
|
||||
|------|------|
|
||||
| `GET /ready` | 健康检查，返回 `ready`、`version`、`uptime_sec` 等 |
|
||||
| `GET /ready` | 健康检查，返回 `ready`、`version`、`uptime_sec` 等（**计入** IP 限流） |
|
||||
| `GET /api/search?q=...` | Docker Hub 镜像搜索 |
|
||||
| `GET /api/tags/:namespace/:name` | 镜像标签列表 |
|
||||
| `GET /api/image/info?image=...` | 镜像元信息 |
|
||||
|
||||
@@ -11,7 +11,7 @@ Default config path is `./config.toml` in the working directory. Override with `
|
||||
|-----|------|---------|-------------|
|
||||
| `host` | string | `0.0.0.0` | Listen address |
|
||||
| `port` | int | `5000` | Listen port |
|
||||
| `fileSize` | int | `2147483648` | Max single-file size (bytes), affects GitHub proxy and offline images |
|
||||
| `fileSize` | int | `2147483648` | Max single-file size (bytes), GitHub / Hugging Face URL proxy only |
|
||||
| `enableH2C` | bool | `false` | Enable HTTP/2 Cleartext |
|
||||
| `enableFrontend` | bool | `true` | Enable web UI (Vue SPA) |
|
||||
|
||||
@@ -22,7 +22,7 @@ Default config path is `./config.toml` in the working directory. Override with `
|
||||
| `requestLimit` | int | `500` | Requests per IP per period |
|
||||
| `periodHours` | float | `3.0` | Rate limit period (hours) |
|
||||
|
||||
IPv4 uses full addresses; IPv6 uses `/64` prefixes. Frontend static routes (`/`, `/images`, `/search`, `/assets/*`) are not rate-limited.
|
||||
IPv4 uses full addresses; IPv6 uses `/64` prefixes. Only frontend static routes (`/`, `/images`, `/search`, `/favicon.ico`, `/assets/*`) are exempt; `/ready`, API, and proxy requests all count.
|
||||
|
||||
:::note
|
||||
Pulling one Docker image triggers multiple layer requests — each HTTP request counts against the limit.
|
||||
@@ -69,7 +69,7 @@ Per-registry keys:
|
||||
Defaults include `ghcr.io`, `gcr.io`, `quay.io`, `registry.k8s.io`. Docker Hub always proxies to `registry-1.docker.io` and is not configured here.
|
||||
|
||||
:::note
|
||||
All registries currently use anonymous pulls (`authn.Anonymous`). `authType` labels the auth endpoint only — **GitHub tokens and Google service accounts are not yet implemented**. Private images require client-side authentication.
|
||||
All registries currently use anonymous pulls (`authn.Anonymous`). `authType` labels the auth endpoint only — **GitHub tokens and Google service accounts are not yet implemented**, and client `Authorization` headers are not forwarded. **Private authenticated images cannot be pulled through HubProxy.**
|
||||
:::
|
||||
|
||||
## [tokenCache]
|
||||
@@ -93,7 +93,7 @@ Upstream token `expires_in` is used for token cache (5-minute safety margin, min
|
||||
|
||||
| Path | Description |
|
||||
|------|-------------|
|
||||
| `GET /ready` | Health check — returns `ready`, `version`, `uptime_sec`, etc. |
|
||||
| `GET /ready` | Health check — returns `ready`, `version`, `uptime_sec`, etc. (**counts toward** rate limit) |
|
||||
| `GET /api/search?q=...` | Docker Hub image search |
|
||||
| `GET /api/tags/:namespace/:name` | Image tag list |
|
||||
| `GET /api/image/info?image=...` | Image metadata |
|
||||
|
||||
@@ -20,7 +20,7 @@ Strongly recommended. It provides TLS, correct client IP passing, and avoids exp
|
||||
<details>
|
||||
<summary>What's the difference between rate-limit and registry whitelists?</summary>
|
||||
|
||||
`[security].whiteList` exempts IPs from rate limiting. `[access].whiteList` controls which Docker images and GitHub repos can be proxied. They are independent.
|
||||
`[security].whiteList` exempts IPs from rate limiting. `[access].whiteList` controls which Docker images, GitHub repos, and Hugging Face resources can be proxied. They are independent.
|
||||
|
||||
</details>
|
||||
|
||||
@@ -55,7 +55,7 @@ If HubProxy connects directly to Cloudflare edges, rate limits apply per Cloudfl
|
||||
<details>
|
||||
<summary>How do I verify the service is running?</summary>
|
||||
|
||||
Visit `https://example.com/ready` — a healthy response includes `ready`, `service`, `version`, and `uptime_sec`.
|
||||
Visit `https://example.com/ready` — a healthy response includes `ready`, `service`, `version`, and `uptime_sec`. This path **counts toward** the IP rate limit; avoid high-frequency polling.
|
||||
|
||||
</details>
|
||||
|
||||
@@ -87,6 +87,6 @@ Add a regex to `githubExps` in `src/handlers/github.go`. See [Development & Buil
|
||||
<details>
|
||||
<summary>Why can't I pull private images with authType github?</summary>
|
||||
|
||||
`authType` labels auth endpoints only — credential injection is not yet implemented. All registry pulls use anonymous auth. Use client-side `docker login` for private images.
|
||||
`authType` labels auth endpoints only — credential injection is not yet implemented. All registry pulls use anonymous auth and client `Authorization` headers are not forwarded. **Private authenticated images cannot be pulled through HubProxy.**
|
||||
|
||||
</details>
|
||||
|
||||
@@ -45,7 +45,7 @@ enabled = true
|
||||
| `quay` | Quay.io auth endpoint |
|
||||
|
||||
:::note
|
||||
`authType` matches upstream token auth endpoints only. The current version does **not** inject GitHub tokens or Google service accounts — all pulls use anonymous auth. Private images require client-side `docker login`.
|
||||
`authType` matches upstream token auth endpoints only. The current version does **not** inject GitHub tokens or Google service accounts — all pulls use anonymous auth and client credentials are not forwarded. **Private authenticated images cannot be pulled.**
|
||||
:::
|
||||
|
||||
## Pull Path Format
|
||||
|
||||
@@ -62,7 +62,7 @@ curl "https://example.com/api/tags/library/nginx"
|
||||
- Each layer counts against rate limits
|
||||
- Configure `[access].whiteList` for public deployments
|
||||
- Ensure correct client IP behind reverse proxy — see [Reverse Proxy](/en/deployment/reverse-proxy/)
|
||||
- Anonymous upstream pulls; private images need client-side `docker login`
|
||||
- Anonymous upstream pulls — **private authenticated images cannot be pulled through HubProxy**
|
||||
|
||||
## Other environments
|
||||
|
||||
|
||||
@@ -22,6 +22,29 @@ git clone https://example.com/https://github.com/owner/repo.git
|
||||
curl "https://example.com/https://api.github.com/repos/owner/repo/releases/latest"
|
||||
```
|
||||
|
||||
### Global Git acceleration
|
||||
|
||||
Use `url.<base>.insteadOf` so every `https://github.com/` clone/fetch goes through HubProxy automatically:
|
||||
|
||||
```bash
|
||||
git config --global url."https://example.com//https://github.com/".insteadOf "https://github.com/"
|
||||
```
|
||||
|
||||
Then clone as usual:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/owner/repo.git
|
||||
# actually requests https://example.com//https://github.com/owner/repo.git
|
||||
```
|
||||
|
||||
HubProxy normalizes extra leading slashes in the path — this is equivalent to a single-slash prefix form.
|
||||
|
||||
To remove:
|
||||
|
||||
```bash
|
||||
git config --global --unset url.https://example.com//https://github.com/.insteadOf
|
||||
```
|
||||
|
||||
### Omit `https://`
|
||||
|
||||
HubProxy auto-prepends the scheme:
|
||||
@@ -57,7 +80,7 @@ HubProxy can rewrite GitHub URLs inside `.sh` / `.ps1` install scripts (max 10MB
|
||||
|-------|-------------|
|
||||
| Web content | `text/html`, `application/xml`, etc. are blocked (403) — not for browsing GitHub pages |
|
||||
| File size | `[server].fileSize` caps single-file downloads (default 2GB) |
|
||||
| Repo access | `[access].whiteList` / `blackList` restrict proxied GitHub repos |
|
||||
| Repo access | `[access].whiteList` / `blackList` restrict proxied GitHub repos and Hugging Face resources |
|
||||
|
||||
Large Release files support `wget -c` resume — see [Transfer Capabilities](/en/guides/capabilities/).
|
||||
|
||||
|
||||
@@ -25,16 +25,6 @@ curl -L -O "https://example.com/huggingface.co/bert-base-uncased/resolve/main/py
|
||||
curl -L -O "https://example.com/https://cdn-lfs.hf.co/user/model-repo/abc123..."
|
||||
```
|
||||
|
||||
## Python / huggingface_hub
|
||||
|
||||
Replace original HF URLs with:
|
||||
|
||||
```
|
||||
https://example.com/https://huggingface.co/...
|
||||
```
|
||||
|
||||
Ensure paths match Hugging Face regexes in `githubExps`.
|
||||
|
||||
## Limits
|
||||
|
||||
Same as [GitHub Acceleration](/en/guides/github-proxy/):
|
||||
|
||||
@@ -79,5 +79,5 @@ sudo systemctl restart containerd
|
||||
## Notes
|
||||
|
||||
- Configure every node; use HTTPS in production
|
||||
- Private images need `imagePullSecrets`; HubProxy pulls upstream anonymously
|
||||
- HubProxy pulls upstream anonymously — **private authenticated images cannot be proxied**
|
||||
- See [Transfer Capabilities](/en/guides/capabilities/)
|
||||
|
||||
@@ -9,7 +9,31 @@ Downloads use a **two-step flow**: `prepare` for a one-time token, then download
|
||||
|
||||
## Web UI
|
||||
|
||||
Visit the HubProxy homepage and use the offline image feature. When selecting an architecture, if the image does not provide the selected architecture or the input is invalid, it automatically falls back to `linux/amd64`.
|
||||
Visit the HubProxy homepage and use the offline image feature. Leave architecture empty to prefer `linux/amd64`; if a specified architecture is unmatched, the first available platform in the multi-arch index is used.
|
||||
|
||||
## Image Reference Format
|
||||
|
||||
Besides Docker Hub official images, enter a full registry-prefixed reference to pull from other platforms:
|
||||
|
||||
| Source | Example input |
|
||||
|--------|---------------|
|
||||
| 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` |
|
||||
|
||||
Missing tags default to `:latest`. Single-segment names (no `/`) get the `library/` namespace. The registry must be enabled in `[registries]` and the image must be anonymously pullable.
|
||||
|
||||
## Compressed Layers
|
||||
|
||||
The web UI and API expose a compressed-layers toggle (`compressed` / `useCompressedLayers`, **on by default**). **Keep it enabled** in most cases.
|
||||
|
||||
| Setting | Contents of each `layer.tar` in the archive | Size | Use case |
|
||||
|---------|-----------------------------------------------|------|----------|
|
||||
| On (default) | **Compressed blob** from the registry (usually gzip) | Smaller, faster download | Modern Docker Engine, `docker load` |
|
||||
| Off | **Uncompressed** filesystem layer tar (classic `docker save` format) | Larger, slower to build | Older Docker Engine versions or environments that only accept uncompressed layers |
|
||||
|
||||
HubProxy outputs a `docker load`-compatible tar. With compression enabled, each layer keeps the upstream compressed blob instead of decompressing and re-packing on the server, which saves bandwidth and CPU. The off switch remains for **legacy Docker** (image format v1 era and early `docker load` implementations): those expect uncompressed filesystem tars in `layer.tar`, matching `docker save` output — disabling compression produces the same layer format.
|
||||
|
||||
## Single Image API
|
||||
|
||||
@@ -37,9 +61,9 @@ Optional parameters:
|
||||
|
||||
| Param | Description |
|
||||
|-------|-------------|
|
||||
| `platform` | Target platform, e.g. `linux/arm64`; falls back to `linux/amd64` if unmatched or invalid |
|
||||
| `platform` | Target platform, e.g. `linux/arm64`; empty prefers `linux/amd64`; if specified but unmatched, uses the first available platform in the index |
|
||||
| `tag` | Used when image has no tag, default `latest` |
|
||||
| `compressed` | Compress layers, default `true` |
|
||||
| `compressed` | Keep registry-compressed layers in tar, default `true` (recommended — see **Compressed Layers** above) |
|
||||
|
||||
## Batch API
|
||||
|
||||
@@ -48,7 +72,7 @@ Optional parameters:
|
||||
```bash
|
||||
curl -X POST "https://example.com/api/image/batch?mode=prepare" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"images":["nginx:latest","redis:alpine"]}'
|
||||
-d '{"images":["nginx:latest","ghcr.io/sky22333/hubproxy:latest"],"useCompressedLayers":true}'
|
||||
```
|
||||
|
||||
**Step 2: Download combined tar**
|
||||
@@ -81,4 +105,4 @@ maxImages = 10
|
||||
|
||||
- Large images take longer; streamed downloads must restart if interrupted
|
||||
- Subject to `[access]` lists and IP rate limiting
|
||||
- `/ready` and frontend static pages are not rate-limited; API and proxy requests are
|
||||
- Frontend static routes (`/`, `/images`, `/search`, `/assets/*`) are not rate-limited; `/ready`, API, and proxy requests all count
|
||||
|
||||
@@ -11,7 +11,7 @@ HubProxy is an open proxy service — improper deployment creates abuse risk. Fo
|
||||
|-----------|-------------|
|
||||
| IP rate limiting | Per real client IP (IPv6 uses `/64`) |
|
||||
| IP allow/deny | `[security]` controls rate-limit exemption and blocking |
|
||||
| Repo access control | `[access]` restricts proxied images and GitHub repos |
|
||||
| Repo access control | `[access]` restricts proxied images, GitHub repos, and Hugging Face resources |
|
||||
| Trusted proxies | Forward headers trusted only from private/local networks |
|
||||
| File size limit | `[server].fileSize` prevents oversized file abuse |
|
||||
| Offline download tokens | One-time tokens bound to IP and User-Agent, 2-minute TTL |
|
||||
|
||||
@@ -20,7 +20,7 @@ HubProxy 是完全自托管的代理服务，数据与带宽由你自己控制
|
||||
<details>
|
||||
<summary>限流白名单和仓库白名单有什么区别？</summary>
|
||||
|
||||
`[security].whiteList` 是限流豁免 IP，不影响可代理的仓库。`[access].whiteList` 控制允许代理哪些 Docker 镜像和 GitHub 仓库。两者独立配置。
|
||||
`[security].whiteList` 是限流豁免 IP，不影响可代理的仓库。`[access].whiteList` 控制允许代理哪些 Docker 镜像、GitHub 仓库与 Hugging Face 资源。两者独立配置。
|
||||
|
||||
</details>
|
||||
|
||||
@@ -55,7 +55,7 @@ HubProxy 是完全自托管的代理服务，数据与带宽由你自己控制
|
||||
<details>
|
||||
<summary>如何验证服务是否正常？</summary>
|
||||
|
||||
访问 `https://example.com/ready`，正常时返回 `{"ready":true,"service":"hubproxy",...}`，包含 `version` 与 `uptime_sec` 字段。
|
||||
访问 `https://example.com/ready`，正常时返回 `{"ready":true,"service":"hubproxy",...}`，包含 `version` 与 `uptime_sec` 字段。该路径**会计入** IP 限流，避免高频轮询。
|
||||
|
||||
</details>
|
||||
|
||||
@@ -87,6 +87,6 @@ HubProxy 是完全自托管的代理服务，数据与带宽由你自己控制
|
||||
<details>
|
||||
<summary>authType 配置了 GitHub Token 为什么私有镜像仍拉不下来？</summary>
|
||||
|
||||
当前版本 `authType` 仅标识认证端点类型，尚未实现凭据注入，所有 Registry 均使用匿名拉取。私有镜像需客户端自行 `docker login` 后在请求中携带认证信息。
|
||||
当前版本 `authType` 仅标识认证端点类型，尚未实现凭据注入，所有 Registry 均使用匿名拉取，且不转发客户端 `Authorization` 头。**无法**通过 HubProxy 拉取需要认证的私有镜像。
|
||||
|
||||
</details>
|
||||
|
||||
@@ -45,7 +45,7 @@ enabled = true
|
||||
| `quay` | Quay.io 认证端点 |
|
||||
|
||||
:::note
|
||||
`authType` 用于匹配上游 token 认证地址，当前版本**不会**据此注入 GitHub Token 或 Google 服务账号。所有 Registry 拉取均使用匿名认证；拉取私有镜像需客户端自行提供 `docker login` 凭据。
|
||||
`authType` 用于匹配上游 token 认证地址，当前版本**不会**据此注入 GitHub Token 或 Google 服务账号。所有 Registry 拉取均使用匿名认证，且不转发客户端凭据，**无法**拉取需要认证的私有镜像。
|
||||
:::
|
||||
|
||||
## 拉取路径格式
|
||||
|
||||
@@ -62,7 +62,7 @@ curl "https://example.com/api/tags/library/nginx"
|
||||
- 拉取一个镜像会请求多个 layer，每个 HTTP 请求均计入 IP 限流配额
|
||||
- 公网服务建议配置 `[access].whiteList` 限制可代理的镜像
|
||||
- 配合反向代理时确保正确传递客户端 IP，详见 [反向代理配置](/deployment/reverse-proxy/)
|
||||
- 当前版本对 Registry 使用匿名拉取，私有镜像需客户端自行 `docker login`
|
||||
- 当前版本对 Registry 使用匿名拉取，**无法**通过 HubProxy 拉取需要认证的私有镜像
|
||||
|
||||
## 其他环境
|
||||
|
||||
|
||||
@@ -22,6 +22,29 @@ git clone https://example.com/https://github.com/owner/repo.git
|
||||
curl "https://example.com/https://api.github.com/repos/owner/repo/releases/latest"
|
||||
```
|
||||
|
||||
### Git 全局加速
|
||||
|
||||
配置 `url.<base>.insteadOf` 后，所有 `https://github.com/` 开头的 clone/fetch 会自动走 HubProxy，无需每次手动改 URL：
|
||||
|
||||
```bash
|
||||
git config --global url."https://example.com//https://github.com/".insteadOf "https://github.com/"
|
||||
```
|
||||
|
||||
之后可直接：
|
||||
|
||||
```bash
|
||||
git clone https://github.com/owner/repo.git
|
||||
# 实际请求 https://example.com//https://github.com/owner/repo.git
|
||||
```
|
||||
|
||||
HubProxy 会自动规范化路径首部多余斜杠，上述写法与单斜杠前缀等价。
|
||||
|
||||
取消配置：
|
||||
|
||||
```bash
|
||||
git config --global --unset url.https://example.com//https://github.com/.insteadOf
|
||||
```
|
||||
|
||||
### 省略 `https://`
|
||||
|
||||
HubProxy 会自动补全协议头：
|
||||
@@ -57,7 +80,7 @@ HubProxy 可自动改写 `.sh` / `.ps1` 安装脚本中的 GitHub URL（脚本
|
||||
|------|------|
|
||||
| 网页内容 | `text/html`、`application/xml` 等网页类型会被拒绝（403），不能用来加速 GitHub 网页浏览 |
|
||||
| 文件大小 | `[server].fileSize` 控制单文件上限，默认 2GB |
|
||||
| 仓库访问 | `[access].whiteList` / `blackList` 限制可代理的 GitHub 仓库 |
|
||||
| 仓库访问 | `[access].whiteList` / `blackList` 限制可代理的 GitHub 仓库与 Hugging Face 资源 |
|
||||
|
||||
Release 等大文件支持 `wget -c` 断点续传，见 [传输特性](/guides/capabilities/)。
|
||||
|
||||
|
||||
@@ -28,16 +28,6 @@ curl -L -O "https://example.com/huggingface.co/bert-base-uncased/resolve/main/py
|
||||
curl -L -O "https://example.com/https://cdn-lfs.hf.co/user/model-repo/abc123..."
|
||||
```
|
||||
|
||||
## Python / huggingface_hub
|
||||
|
||||
将原始 HF URL 替换为 HubProxy 前缀形式：
|
||||
|
||||
```
|
||||
https://example.com/https://huggingface.co/...
|
||||
```
|
||||
|
||||
确保最终请求路径能被 `githubExps` 中的 Hugging Face 正则匹配。
|
||||
|
||||
## 限制
|
||||
|
||||
与 [GitHub 加速](/guides/github-proxy/) 相同：
|
||||
|
||||
@@ -86,5 +86,5 @@ sudo systemctl restart containerd
|
||||
## 注意事项
|
||||
|
||||
- 每节点独立配置；生产环境 HubProxy 建议 HTTPS 反代
|
||||
- 私有镜像需 `imagePullSecrets`；HubProxy 对上游匿名拉取
|
||||
- HubProxy 对上游匿名拉取，**无法**代理需要认证的私有镜像
|
||||
- 见 [传输特性](/guides/capabilities/)
|
||||
|
||||
@@ -9,7 +9,31 @@ HubProxy Web 界面（`enableFrontend = true`）与 API 支持将镜像在线打
|
||||
|
||||
## Web 界面
|
||||
|
||||
访问 HubProxy 首页，在「离线镜像」功能中输入镜像名与标签即可下载。架构选择时，若镜像不存在所选架构或输入有误，会自动回落到 `linux/amd64`。
|
||||
访问 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
|
||||
|
||||
@@ -37,9 +61,9 @@ curl -L -o nginx.tar "https://example.com/api/image/download?image=library/nginx
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| `platform` | 指定平台，如 `linux/arm64`；匹配不到或格式错误时自动回落到 `linux/amd64` |
|
||||
| `platform` | 指定平台，如 `linux/arm64`；留空时优先 `linux/amd64`；指定但匹配不到时使用索引中第一个可用平台 |
|
||||
| `tag` | 镜像未含 tag 时使用，默认 `latest` |
|
||||
| `compressed` | 是否压缩层，默认 `true` |
|
||||
| `compressed` | 是否保留 Registry 压缩层写入 tar，默认 `true`（建议开启，见上文「压缩层」） |
|
||||
|
||||
## 批量 API
|
||||
|
||||
@@ -48,7 +72,7 @@ curl -L -o nginx.tar "https://example.com/api/image/download?image=library/nginx
|
||||
```bash
|
||||
curl -X POST "https://example.com/api/image/batch?mode=prepare" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"images":["nginx:latest","redis:alpine"]}'
|
||||
-d '{"images":["nginx:latest","ghcr.io/sky22333/hubproxy:latest"],"useCompressedLayers":true}'
|
||||
```
|
||||
|
||||
**第二步：下载合并 tar**
|
||||
@@ -81,4 +105,4 @@ maxImages = 10
|
||||
|
||||
- 大镜像打包耗时较长，流式传输中断后需重新请求
|
||||
- 受 `[access]` 黑白名单与 IP 限流约束
|
||||
- `/ready` 与前端静态页面不计入限流，API 与代理请求会计入
|
||||
- 前端静态页面（`/`、`/images`、`/search`、`/assets/*`）不计入限流；`/ready`、API 与代理请求均会计入
|
||||
|
||||
@@ -11,7 +11,7 @@ HubProxy 作为开放代理服务，部署不当可能带来滥用风险。遵
|
||||
|------|------|
|
||||
| IP 限流 | 按真实客户端 IP 限制请求频率（IPv6 按 `/64`） |
|
||||
| IP 黑白名单 | `[security]` 控制限流豁免与封禁 |
|
||||
| 仓库访问控制 | `[access]` 限制可代理的镜像与 GitHub 仓库 |
|
||||
| 仓库访问控制 | `[access]` 限制可代理的镜像、GitHub 仓库与 Hugging Face 资源 |
|
||||
| 可信代理 | 仅信任来自私网/本机的转发头，防止 IP 伪造 |
|
||||
| 文件大小限制 | `[server].fileSize` 防止超大文件滥用 |
|
||||
| 离线下载 Token | 一次性 token，绑定 IP 与 User-Agent，2 分钟过期 |
|
||||
|
||||
Reference in New Issue
Block a user