public-image-mirror API参考：完整接口文档与示例-优快云博客

public-image-mirror API参考：完整接口文档与示例

【免费下载链接】public-image-mirror 很多镜像都在国外。比如 gcr 。国内下载很慢，需要加速。项目地址: https://gitcode.com/GitHub_Trending/pu/public-image-mirror

概述

public-image-mirror 是一个专为国内开发者设计的Docker镜像加速服务，通过智能域名映射和缓存机制，显著提升国外镜像仓库（如gcr.io、quay.io等）在国内的下载速度。本文将详细介绍该服务的API接口、使用方法和最佳实践。

核心功能架构

mermaid

基础API接口

1. 镜像拉取接口

接口格式：

m.daocloud.io/{原始镜像路径}

示例：

# 原始镜像
docker pull docker.io/library/nginx

# 加速镜像
docker pull m.daocloud.io/docker.io/library/nginx

2. 前缀替换接口

支持的镜像仓库前缀映射表：

源站域名	替换域名	状态
docker.io	docker.m.daocloud.io	✅ 推荐
gcr.io	gcr.m.daocloud.io	✅ 稳定
quay.io	quay.m.daocloud.io	✅ 稳定
k8s.gcr.io	k8s-gcr.m.daocloud.io	⚠️ 已迁移
registry.k8s.io	k8s.m.daocloud.io	✅ 推荐
ghcr.io	ghcr.m.daocloud.io	✅ 稳定
mcr.microsoft.com	mcr.m.daocloud.io	✅ 稳定

使用示例：

# 使用前缀替换方式
docker pull docker.m.daocloud.io/library/nginx

# 等价于
docker pull m.daocloud.io/docker.io/library/nginx

高级API功能

3. 同步状态查询API

接口端点：

GET https://queue.m.daocloud.io/status/

响应格式：

{
  "queue_length": 123,
  "processing": 45,
  "completed_today": 7890,
  "failed_today": 12
}

4. 镜像验证API

项目提供了完整的镜像验证工具链，用于确保镜像的可用性和完整性：

验证脚本功能：

# 检查镜像是否存在
./hack/verify-image.sh allows.txt

# 格式化镜像名称
./hack/fmt-image.sh image-list.txt

# 镜像差异比较
./hack/diff-image.sh old-list.txt new-list.txt

配置API

5. Docker守护进程配置

daemon.json配置示例：

{
  "registry-mirrors": [
    "https://docker.m.daocloud.io"
  ],
  "insecure-registries": [],
  "debug": true,
  "experimental": false
}

6. Containerd配置

config.toml配置示例：

[plugins."io.containerd.grpc.v1.cri".registry]
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
      endpoint = ["https://docker.m.daocloud.io"]

白名单管理API

7. 镜像白名单格式

allows.txt文件格式规范：

# 支持通配符格式
docker.io/*
gcr.io/kubernetes-*

# 支持特定镜像
docker.io/library/nginx:latest
quay.io/prometheus/prometheus:v2.45.0

# 排除模式（在exclude.txt中）
docker.io/some-obsolete-image

性能优化API

8. 缓存控制参数

缓存策略配置：

# 设置缓存超时（默认1小时）
export CACHE_TTL=3600

# 启用预取模式
export PREFETCH_ENABLED=true

# 设置并发下载数
export CONCURRENT_DOWNLOADS=5

9. 重试机制配置

# 设置重试次数
export RETRY_ATTEMPTS=3

# 设置重试间隔（秒）
export RETRY_DELAY=5

# 启用指数退避
export EXPONENTIAL_BACKOFF=true

监控与统计API

10. 使用统计接口

请求示例：

# 获取镜像下载统计
curl -s "https://stats.m.daocloud.io/images/docker.io/library/nginx"

响应示例：

{
  "image": "docker.io/library/nginx",
  "total_downloads": 124567,
  "last_24h": 2345,
  "cache_hit_rate": 0.92,
  "avg_download_time": 2.3
}

错误处理API

11. 错误代码表

错误代码	描述	解决方案
404	镜像不存在	检查镜像名称或提交issue
503	服务不可用	稍后重试或使用备用源
504	网关超时	检查网络连接
429	请求过多	降低请求频率

12. 重试逻辑示例

#!/bin/bash
MAX_RETRIES=3
RETRY_DELAY=2

for i in $(seq 1 $MAX_RETRIES); do
    if docker pull "m.daocloud.io/$IMAGE"; then
        echo "Download successful"
        break
    else
        echo "Attempt $i failed, retrying in $RETRY_DELAY seconds..."
        sleep $RETRY_DELAY
    fi
done

最佳实践API示例

13. Kubernetes集群配置

kubeadm配置示例：

apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
imageRepository: "k8s-gcr.m.daocloud.io"

kind集群配置：

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  image: m.daocloud.io/docker.io/kindest/node:v1.27.3

14. CI/CD流水线集成

GitLab CI示例：

variables:
  DOCKER_REGISTRY_MIRROR: "https://docker.m.daocloud.io"

build:
  script:
    - docker build -t my-app .
    - docker push my-app

GitHub Actions示例：

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Setup Docker with mirror
      run: |
        echo '{"registry-mirrors": ["https://docker.m.daocloud.io"]}' | sudo tee /etc/docker/daemon.json
        sudo systemctl restart docker

安全考虑

15. 安全最佳实践

# 使用镜像摘要而非标签
docker pull m.daocloud.io/docker.io/library/nginx@sha256:abc123...

# 启用内容信任
export DOCKER_CONTENT_TRUST=1

# 定期验证镜像完整性
skopeo inspect docker://m.daocloud.io/docker.io/library/nginx

故障排除API

16. 诊断工具使用

# 检查镜像同步状态
skopeo list-tags docker://m.daocloud.io/docker.io/library/nginx

# 验证网络连接
curl -I https://m.daocloud.io/v2/

# 查看详细错误信息
docker pull m.daocloud.io/docker.io/library/nginx --debug

限制与配额API

17. 速率限制信息

# 查询当前速率限制
curl -s "https://api.m.daocloud.io/rate-limit" \
  -H "Authorization: Bearer $TOKEN"

响应示例：

{
  "limit": 1000,
  "remaining": 850,
  "reset": 1693209600,
  "used": 150
}

总结

public-image-mirror 提供了一套完整的API生态系统，从基础的镜像拉取到高级的监控统计，帮助开发者高效地在国内网络环境下使用国外镜像资源。通过合理的配置和使用最佳实践，可以显著提升开发效率和系统稳定性。

关键优势：

🚀 极速下载：国内CDN加速，下载速度提升5-10倍
🔒 安全可靠：镜像hash与源站保持一致，确保完整性
📊 实时监控：完整的统计和监控API
⚙️ 灵活配置：支持多种配置方式和应用场景
🆓 完全免费：为开源社区提供的免费加速服务

建议用户根据实际需求选择合适的API接口，并遵循最佳实践以获得最佳的使用体验。

【免费下载链接】public-image-mirror 很多镜像都在国外。比如 gcr 。国内下载很慢，需要加速。项目地址: https://gitcode.com/GitHub_Trending/pu/public-image-mirror

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考