Docker Hub

Docker Hub — 镜像仓库管理

Guidance for publishing, pulling, and managing Docker images.

When to Use

ALWAYS use this skill when the user mentions:

• "docker hub", "docker registry", "镜像仓库"
• "docker push", "docker pull", "docker tag"
• "私有仓库", "private registry", "Harbor"
• "镜像加速", "registry mirror"
• "docker login", "authentication"

Core Workflow

# Login
docker login
docker login registry.example.com   # Private registry

# Tag
docker tag myapp:latest myuser/myapp:v1.0.0
docker tag myapp:latest myuser/myapp:latest

# Push
docker push myuser/myapp:v1.0.0
docker push myuser/myapp:latest

# Pull
docker pull myuser/myapp:v1.0.0
docker pull myuser/myapp:latest

Tag Strategy

Production: NEVER use :latest. Always pin exact version or digest.
Development: :latest is OK for convenience.

Private Registry

Docker Registry (Official)

docker run -d -p 5000:5000 --name registry \
  -v registry:/var/lib/registry \
  registry:2
docker tag myapp localhost:5000/myapp:v1
docker push localhost:5000/myapp:v1

Harbor (Enterprise)

# Download and run
wget https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-offline-installer-v2.10.0.tgz
tar xzf harbor-offline-installer-v2.10.0.tgz
cd harbor
cp harbor.yml.tmpl harbor.yml
# Edit harbor.yml (hostname, passwords)
./install.sh

Image Digest (Immutable Reference)

# Get digest
docker inspect --format='{{.RepoDigests}}' myimage:tag

# Pull by digest (immutable)
docker pull alpine@sha256:abc123...

Workflow — 推荐操作流程

Step 1: 登录仓库: docker login 或 docker login ghcr.io Step 2: 打标签: docker tag myapp:v1 ghcr.io/org/myapp:v1 Step 3: 推送镜像: docker push ghcr.io/org/myapp:v1 Step 4: 验证: docker pull ghcr.io/org/myapp:v1 拉取确认 Step 5: 固定版本: 生产使用 docker pull myapp@sha256:abc...

Gotchas — Common Pitfalls

• `:latest` in production: Tags are mutable — latest can point to different images over time. → Recovery: Always pin version or digest: docker pull myapp:v1.2.3@sha256:abc....
• Mixed public/private registries: docker login is per-registry. → Recovery: docker login registry.example.com separately; use credential helpers: docker-credential-ecr-login for AWS ECR.
• Large image push timeout: Set max-concurrent-uploads in daemon config for large images. → Recovery: Edit /etc/docker/daemon.json: {"max-concurrent-uploads": 1} for slow connections.
• Registry auth in CI: Use docker/login-action (GitHub Actions) or secrets manager. → Recovery: Never commit credentials; use OIDC for cloud registries instead of long-lived tokens.

Boundary — 能力边界（适用与不适用场景）

When NOT to Use

Security & Stability

• Never commit registry credentials. Use CI secrets manager.
• Use content trust: export DOCKER_CONTENT_TRUST=1 for signed images.
• Harbor provides vulnerability scanning, replication, and RBAC.
• No executable scripts bundled. Guidance only.

📚 官方文档参考

🧭 Docker Skills Journey

📍 You are here: `docker-hub` — 镜像仓库管理

← Prev: docker-scout — Vulnerability scanning → Next: docker-cicd — CI/CD integration

FAQ

Q1: 如何快速上手此技能？ A: 参考上方的快速开始章节，按步骤操作即可。

Q2: 遇到版本不兼容问题怎么办？ A: 检查依赖版本，使用 lock 文件锁定，参考常见陷阱章节。

Q3: 如何在生产环境使用？ A: 参考最佳实践章节，确保配置正确，做好监控和日志。

Q4: 性能如何优化？ A: 参考性能优化相关文档，使用缓存、索引等手段。

Q5: 如何贡献或反馈问题？ A: 在 GitHub 仓库提交 Issue 或 Pull Request。

Q6: 是否支持中文？ A: 支持中文文档和中文注释，详见国内适配章节。

镜像发布与标签策略

登录

docker login
docker login ghcr.io -u USERNAME -p $GITHUB_TOKEN
docker login registry.gitlab.com

标签策略

# 构建时打好所有标签
docker build -t myapp:v1.2.3 \
             -t myapp:v1.2 \
             -t myapp:v1 \
             -t myapp:latest \
             -t ghcr.io/myorg/myapp:v1.2.3 .

# 推送
docker push myapp:v1.2.3
docker push myapp:v1.2
docker push myapp:v1
docker push myapp:latest
docker push ghcr.io/myorg/myapp:v1.2.3

多标签推送

# 使用 --all-tags
docker push myapp --all-tags

# 或使用 docker buildx（含多平台）
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag myapp:v1.2.3 \
  --tag myapp:latest \
  --push .

SHA256 Digest 固定

# 获取 digest
docker inspect --format='{{index .RepoDigests 0}}' myapp:latest
# myapp@sha256:abc123def456...

# 拉取固定版本（不随 tag 变化）
docker pull myapp@sha256:abc123def456...

CI/CD 自动标签

# GitHub Actions
- name: Docker metadata
  id: meta
  uses: docker/metadata-action@v5
  with:
    images: ghcr.io/${{ github.repository }}
    tags: |
      type=semver,pattern={{version}}
      type=semver,pattern={{major}}.{{minor}}
      type=sha,format=short
      type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}

输出示例：v1.2.3, v1.2, abc1234, latest（仅 main 分支）

私有仓库搭建

Docker Registry（最简单）

# compose.yml
services:
  registry:
    image: registry:2.8
    ports:
      - "5000:5000"
    volumes:
      - registry_data:/var/lib/registry
    environment:
      REGISTRY_STORAGE_DELETE_ENABLED: "true"
    restart: unless-stopped

volumes:
  registry_data:

docker compose up -d
docker tag myapp localhost:5000/myapp:v1
docker push localhost:5000/myapp:v1

Registry + 认证

# 创建 htpasswd
docker run --rm httpd:alpine htpasswd -Bbn admin password > htpasswd

services:
  registry:
    image: registry:2.8
    ports:
      - "5000:5000"
    volumes:
      - registry_data:/var/lib/registry
      - ./htpasswd:/auth/htpasswd:ro
      - ./certs:/certs:ro
    environment:
      REGISTRY_AUTH: htpasswd
      REGISTRY_AUTH_HTPASSWD_REALM: Registry Realm
      REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd
      REGISTRY_HTTP_TLS_CERTIFICATE: /certs/registry.crt
      REGISTRY_HTTP_TLS_KEY: /certs/registry.key

Harbor（企业方案）

# 下载 Harbor
wget https://github.com/goharbor/harbor/releases/download/v2.12.0/harbor-online-installer-v2.12.0.tgz
tar xzf harbor-online-installer-v2.12.0.tgz
cd harbor

# 配置
cp harbor.yml.tmpl harbor.yml
# 编辑 harbor.yml：设置 hostname、密码、证书路径

# 安装
./install.sh --with-trivy    # 含漏洞扫描

Harbor 提供：

• Web UI 管理
• 漏洞扫描（Trivy 集成）
• 镜像复制（跨数据中心同步）
• RBAC 权限
• 垃圾回收与配额管理

镜像清理策略

# Docker Registry 垃圾回收
docker exec registry bin/registry garbage-collect /etc/docker/registry/config.yml

# Harbor 清理策略（Web UI 配置）
# Administration → Cleanup → 设置保留策略（保留最近 N 个 tag、保留时间）

Registry Mirror 加速

// /etc/docker/daemon.json
{
  "registry-mirrors": [
    "https://mirror.gcr.io",
    "https://hub-mirror.c.163.com"
  ]
}

镜像标签策略

常见标签策略对比

推荐标签方案

# 每个 build 打 3 类标签
docker build \
  -t myapp:v1.2.3 \                          # SemVer
  -t myapp:v1.2 \                             # Minor 浮动
  -t myapp:v1 \                               # Major 浮动
  -t myapp:sha-$(git rev-parse --short HEAD) \ # Git SHA
  -t ghcr.io/org/myapp:v1.2.3 .

不可变标签最佳实践

# ❌ 不要：latest 随意覆盖
docker build -t myapp:latest .
docker push myapp:latest    # 不知道具体是哪个版本

# ✅ 正确：latest 始终指向最新稳定版
docker build -t myapp:v1.2.3 -t myapp:latest .
docker push myapp:v1.2.3
# latest 仅在稳定版 release 时更新

# ✅ 生产环境使用 digest
docker pull myapp@sha256:abc123def456...

Docker metadata-action 标签模板

tags: |
  type=semver,pattern={{version}}
  type=semver,pattern={{major}}.{{minor}}
  type=sha,format=short
  type=ref,event=branch
  type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}

标签清理

# Docker Hub API 删除 tag
curl -X DELETE -u "$DOCKER_USER:$DOCKER_TOKEN" \
  "https://hub.docker.com/v2/repositories/$DOCKER_USER/myapp/tags/v0.1.0/"

Harbor 企业级镜像仓库搭建

架构

┌───────────────────────────────────────────────┐
│                    Harbor                      │
│                                                │
│  ┌──────────┐  ┌───────────┐  ┌────────────┐ │
│  │  Portal  │  │  Core     │  │ Job Service│ │
│  │  (UI)    │  │  (API)   │  │            │ │
│  └──────────┘  └───────────┘  └────────────┘ │
│                                                │
│  ┌───────────┐  ┌───────────┐                 │
│  │ Registry  │  │ Trivy     │                 │
│  │ (OCI)     │  │ (扫描)    │                 │
│  └───────────┘  └───────────┘                 │
│                                                │
│  ┌──────────┐  ┌───────────────┐              │
│  │ Redis    │  │ PostgreSQL    │              │
│  │ (缓存)   │  │ (元数据)      │              │
│  └──────────┘  └───────────────┘              │
└───────────────────────────────────────────────┘

最小配置

# harbor.yml
hostname: registry.example.com

http:
  port: 80

# 使用 HTTP（测试环境）或 HTTPS
# https:
#   port: 443
#   certificate: /data/certs/registry.crt
#   private_key: /data/certs/registry.key

harbor_admin_password: Harbor12345

database:
  password: root123
  max_idle_conns: 100
  max_open_conns: 900

data_volume: /data

trivy:
  ignore_unfixed: false
  skip_update: false
  offline_scan: false
  insecure: false

安装

# 在线安装（含 Trivy 扫描器）
./install.sh --with-trivy

# 仅核心功能
./install.sh

项目配置

1. 创建项目：Projects → New Project 2. 设为私有（Private）或公开（Public） 3. 配置成员权限：项目管理员/开发者/访客 4. 配置镜像代理缓存：Proxy Cache → 代理 Docker Hub

镜像复制（跨数据中心）

杭州 Harbor → 北京 Harbor
  ┌─────────────────┐      ┌─────────────────┐
  │ myapp:v1.2.3    │ ───→ │ myapp:v1.2.3    │
  └─────────────────┘      └─────────────────┘

配置：Administration → Replications → New Replication Rule

垃圾回收

# 手动触发
docker exec -it harbor-core /bin/bash
# Web UI: Administration → Garbage Collection

与 Docker Desktop 集成

Docker Desktop → Settings → Docker Engine：

{
  "insecure-registries": ["registry.example.com"]
}