镜像仓库与加速：让拉取又快又稳

为什么生产集群要有自己的镜像仓库#

刚开始学习时，image: nginx:1.27 就够了：kubelet 会自己去 Docker Hub 拉。到了生产环境，这条路径会变成一连串问题。

• 外网依赖：节点出不了公网、或者上游 registry 抖动，整个发布流程就停摆。集群越大，这个依赖越致命。
• 速率限制：公共仓库对匿名拉取有频率限制，一次扩容几十个节点、或者一批 Pod 同时启动，很容易被限流，表现为 toomanyrequests 或 ImagePullBackOff。
• 安全审计：你不知道镜像里到底有什么、有没有被替换过。自建仓库才有扫描、签名、来源控制的抓手。
• 离线与内网环境：很多生产集群（尤其是金融、制造、科研）根本不允许访问公网。

一句话：生产集群的镜像来源应该只有一个，就是你自己控制的仓库。

自建仓库不是「多一台服务器」那么简单，它同时承担了分发入口、安全闸门和跨机房同步三个角色：

开发机构建 ──push──▶ Harbor（内网唯一入口）
                        │
                        ├── 漏洞扫描（Trivy）→ 扫描报告
                        ├── 签名（cosign）→ 供准入策略校验
                        └── 仓库复制 ──▶ 灾备机房 / 另一套集群
                        ▲
                        │ pull
                   节点 containerd
                        ▲
                        └── Dragonfly / Spegel：节点之间 P2P 互相分发

Harbor 能给你什么#

自己用 registry 镜像起一个仓库也能用，但它只有一个账号池，没有项目隔离、没有扫描。Harbor 是在 registry 之上加了管理能力的发行版，生产上更常用。

代价是组件多：core、jobservice、portal、registry 加 PostgreSQL 与 Redis。所以生产环境建议外接数据库与对象存储，而不是全靠内置组件加 PVC。

动手：用 Helm 装 Harbor 并推拉一个镜像#

helm repo add harbor https://helm.goharbor.io
helm repo update
helm search repo harbor/harbor --versions | head -5

expose:
  type: ingress
  tls:
    enabled: true
  ingress:
    className: nginx
    hosts:
      core: harbor.example.com
externalURL: https://harbor.example.com

persistence:
  enabled: true
  persistentVolumeClaim:
    registry:
      storageClass: <你的 StorageClass>
      size: 200Gi
    database:
      storageClass: <你的 StorageClass>
      size: 20Gi
    redis:
      storageClass: <你的 StorageClass>
      size: 10Gi

harborAdminPassword: "<改成强密码>"
trivy:
  enabled: true

helm install harbor harbor/harbor \
  --namespace harbor --create-namespace \
  -f harbor-values.yaml
kubectl -n harbor get pods
kubectl -n harbor get svc

echo '<adminPassword>' | docker login harbor.example.com -u admin --password-stdin

docker pull nginx:1.27
docker tag nginx:1.27 harbor.example.com/library/nginx:1.27
docker push harbor.example.com/library/nginx:1.27

docker rmi harbor.example.com/library/nginx:1.27
docker pull harbor.example.com/library/nginx:1.27

imagePullSecret：让 Pod 有权拉私有镜像#

仓库通了，但 Pod 还不知道怎么登录。私有仓库需要一个 docker-registry 类型的 Secret，创建时必须把仓库地址写对：

kubectl -n demo create secret docker-registry harbor-cred \
  --docker-server=harbor.example.com \
  --docker-username='robot$kube101' \
  --docker-password='<机器人账号的 token>' \
  --docker-email=dev@example.com

在 Harbor 里给应用建一个机器人账号，而不是用 admin。然后在 Pod 里引用它：

apiVersion: v1
kind: Pod
metadata:
  name: app
  namespace: demo
spec:
  imagePullSecrets:
    - name: harbor-cred
  containers:
    - name: app
      image: harbor.example.com/library/nginx:1.27

如果每个 Pod 都写一遍太啰嗦，就把它挂到命名空间的 ServiceAccount 上，所有使用该 SA 的 Pod 自动继承：

kubectl -n demo patch serviceaccount default \
  -p '{"imagePullSecrets":[{"name":"harbor-cred"}]}'
kubectl -n demo get serviceaccount default -o yaml | grep -A3 imagePullSecrets

验证方式是拉取失败时的报错能不能自证：kubectl -n demo describe pod app 的 Events 里出现 401 Unauthorized 或 pull access denied，说明鉴权没通；出现 Pulling 之后 Successfully pulled，说明通了。

Harbor 的生产配置：复制、扫描与配额#

装起来只是第一步，「谁能推、推上去要不要拦、拦下来谁来清」这条链才是生产价值所在。三个旋钮最容易被忽略。

镜像复制解决跨机房、跨集群分发：在「仓库管理 → 新建目标」登记对端仓库，再用复制规则让 Harbor 自己同步，别靠人往两边各推一次。两个讲究：规则按项目建而不是全库复制，避免把开发镜像同步到灾备机房；事件驱动加定时兜底，事件让新 tag 尽快到位、定时修补中断的同步。公网镜像不必手工同步，直接把项目做成 proxy cache 项目：

harbor login https://harbor.example.com -u admin -p '<adminPassword>'
for r in docker.io registry.k8s.io quay.io nvcr.io; do
  url="https://$r"; [ "$r" = "docker.io" ] && url="https://mirror.gcr.io"
  harbor registry create --name "$r" --type docker-registry --url "$url"
done
harbor registry list -o json | jq -r '.Payload[] | "\(.id) \(.name)"' | while read id name; do
  harbor project create "$name" --proxy-cache --public --registry-id "$id"
done

漏洞扫描的价值不在 trivy.enabled: true，而在什么时候扫、扫出来怎么办：项目里打开「推送时自动扫描」，并勾选阻止有高危漏洞的镜像被拉取，再让 CI 在推完镜像后查一次扫描结果——高危未修复就不进入部署流程。内网还要单独规划 Trivy 漏洞库的更新源，否则扫描结论越来越旧，看着「全绿」却没有意义。

配额与保留策略必须一起配：配额（项目级存储上限）防止一个团队写满整个仓库，保留策略按 tag 数量或天数清理历史镜像。只配配额，写满时整个项目都推不上去；只配保留策略，则可能在清理前就被写满。为什么生产上非做不可：仓库是全集群唯一的镜像入口，它一满或一慢，表现就是所有人 ImagePullBackOff——这两个配置不是省磁盘，而是把故障半径限制在单个项目内。

参考：reference/k8s-in-action/repo/harbor/README.md

Dragonfly：P2P 分发加速#

镜像仓库解决了「从哪拉」，但没解决「拉多快」。一次扩容 50 个 Pod，50 个节点同时去仓库拉同一个 2GB 镜像，仓库出口带宽立刻被打满，镜像拉取变成扩容的瓶颈。

Dragonfly 的思路是 P2P：把镜像切成块，节点之间互相交换已经下载的块，只让少数节点（seed peer）回源仓库。

                    ┌──────────────┐
                    │  Harbor 仓库 │
                    └──────┬───────┘
                           │ 只有 seed peer 回源
                           ▼
   ┌────────────┐   ┌────────────┐   ┌────────────┐
   │  节点 A    │◀─▶│  节点 B    │◀─▶│  节点 C    │
   │ (seed peer)│   │            │   │            │
   └────────────┘   └────────────┘   └────────────┘
        P2P 网络：块在节点之间直接交换

组件构成是 manager、scheduler、seed peer 加每个节点上的客户端，另带 MySQL 与 Redis。用 Helm 安装，chart 名 dragonfly/dragonfly：

helm repo add dragonfly https://dragonflyoss.github.io/helm-charts/
helm repo update
helm install dragonfly dragonfly/dragonfly \
  --namespace dragonfly-system --create-namespace
kubectl -n dragonfly-system get pods

和 containerd 集成靠 client.dfinit：

client:
  dfinit:
    enable: true
    config:
      containerRuntime:
        containerd:
          configPath: /etc/containerd/config.toml
          registries:
            - {hostNamespace: docker.io, serverAddr: https://mirror.gcr.io, capabilities: [pull, resolve]}

和 containerd 集成靠 client.dfinit：它改写节点上的 containerd 配置，把镜像拉取指向本机的 dfdaemon 代理，再由 P2P 网络决定从哪里取块。早期版本里节点侧组件叫 dfget-proxy 与 dfdaemon，v2 之后统一为 dragonfly-client，集成方式也从手改配置变成由 dfinit 自动完成。

验证方式是在节点上直接拉一个镜像，再看客户端日志：

crictl pull harbor.example.com/library/nginx:1.27
kubectl -n dragonfly-system logs -l app=dragonfly-client --tail=50
kubectl -n dragonfly-system port-forward svc/dragonfly-manager 8080:8080

日志里出现 download task started 就说明流量走了 P2P；manager 的控制台能看任务与流量统计。

Dragonfly 与 Spegel 怎么选#

两者都做 P2P，取向不同：Spegel 是单个 DaemonSet，让节点互为镜像源、直接复用各节点 containerd 里已经拉取过的镜像层，没有中心节点，但只支持 containerd；Dragonfly 是一套独立的 P2P 网络，由 seed client 统一回源，能力更多、组件也更多。

Spegel 有个节点侧前提最容易漏：containerd 不能丢弃已解包的层，否则节点之间没有可复用的内容，P2P 直接失效。滚动改完再重启，然后看它的自检页面：

# 在 /etc/containerd/config.toml 的 overlayfs 段设 discard_unpacked_layers = false 后滚动重启：
systemctl restart containerd
kubectl -n spegel port-forward svc/spegel 9090   # 打开 http://localhost:9090/debug/web

判断标准很直接：UI 里 Last Mirror Success 显示时间而不是 Pending，说明镜像源发现正常。选型记一句话：只是「同一个镜像在多个节点重复拉」，选 Spegel；要预热新镜像、要分发模型权重这类非镜像文件、或节点运行时不是 containerd，才上 Dragonfly。

参考：reference/k8s-in-action/base/spegel/README.md、reference/k8s-in-action/repo/dragonfly/README.md

节点级镜像缓存：预拉取与 kube-fledged#

P2P 解决的是「多个节点同时拉」。还有一类场景是「镜像已经确定，但不想等它拉」：比如大版本发布前，先把镜像预热到所有节点上。

最简单的办法是用一个 DaemonSet 在每台节点上把镜像拉一遍：

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: preload-nginx
  namespace: kube-system
spec:
  selector: {matchLabels: {app: preload-nginx}}
  template:
    metadata: {labels: {app: preload-nginx}}
    spec:
      initContainers:
        - name: preload
          image: harbor.example.com/library/nginx:1.27
          command: ["/bin/true"]
      containers:
        - name: pause
          image: registry.k8s.io/pause:3.10
          resources: {requests: {cpu: 1m, memory: 8Mi}}

initContainer 的作用只是「让 kubelet 在每台节点上拉一次这个镜像」，拉完立刻退出。如果镜像很多、或者想按标签批量管理缓存，可以用 kube-fledged：它用一个 ImageCache 资源声明要缓存的镜像列表，再由控制器负责在节点上预拉并保持。

tag、digest 与多架构镜像#

• tag 是可变的，app:1.2.3 可以被重新推送，所以生产上更推荐 image@sha256:... 固定 digest，这一点在 安全加固 里讲过。
• 多架构镜像用 manifest list 承载：同一个 tag 下面挂着 amd64、arm64 等多个架构的镜像，节点拉取时自动选择匹配的那一份。

docker buildx build --platform linux/amd64,linux/arm64 \
  -t harbor.example.com/library/app:1.2.3 --push .
docker buildx imagetools inspect harbor.example.com/library/app:1.2.3

imagetools inspect 会列出所有平台与各自的 digest。只在 arm64 笔记本上构建、直接推给 amd64 节点用，会遇到 exec format error 或 no matching manifest——这就是多架构没做对的表现。

离线依赖源：PyPI 与 Conda 镜像#

镜像只是一半。构建训练镜像时要 pip install、运行时要用 conda 环境，这些依赖同样出网，集群内网化之后它们是最先断掉的一环。做法是在内网跑按需缓存的镜像源：第一次请求回源并落盘，之后命中缓存。

Python 用 devpi 建一个 mirror index（服务端执行 devpi index -c root/pypi type=mirror mirror_url=https://pypi.org/simple/，上游建议指向 pypi.org，部分公共镜像源在 devpi 下有兼容问题；索引设成 volatile=False，已缓存的版本才不会被顶掉），客户端改一行就切过去：

pip config set global.index-url https://pypi.example.com/root/pypi/+simple/

Conda 用 quetz 建 proxy 模式的 channel，客户端写 ~/.condarc：

curl --request POST --url https://conda.example.com/api/channels \
  --header 'Content-Type: application/json' --header 'X-API-Key: <API Key>' \
  --data '{"name":"main","private":false,"mirror_mode":"proxy","mirror_channel_url":"https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main"}'

# ~/.condarc
channels:
  - defaults
default_channels:
  - https://conda.example.com/get/main
  - https://conda.example.com/get/r

改完执行 conda clean -i 清掉索引缓存，否则客户端还在用旧 channel。存储只随「实际拉取过的包」增长（PyPI 全量在 20Ti 量级，按需缓存远小于此）。适用场景：PyPI 镜像给 Python 应用与训练镜像构建用，收益是断网可用加构建可复现；Conda 镜像给数据科学与 GPU 环境用，包体积大、缓存收益更明显。它们替代不了制品库——内部私有包仍要发到同一套 devpi / quetz 的私有索引里。容器内注意 pip config 只对当前用户生效，Dockerfile 里要用 pip install --index-url https://pypi.example.com/root/pypi/+simple/，或者往镜像里写全局 /etc/pip.conf。

参考：reference/k8s-in-action/repo/pypi/README.md、reference/k8s-in-action/repo/conda/README.md

常见坑与速查表#

自测题#

小结#

• 生产集群自建镜像仓库的理由是外网依赖、速率限制、安全审计与离线环境，镜像来源应当收敛到唯一入口。
• Harbor 在 registry 之上提供项目 RBAC、复制、扫描、签名、代理缓存与保留策略；生产上要配好按项目的复制规则、推送时自动扫描与项目配额，代价是组件多、建议外接数据库与对象存储。
• 私有镜像要在 Pod 或 ServiceAccount 上引用 imagePullSecret，Secret 必须和目标 Pod 在同一个命名空间；固定 digest 比固定 tag 更可靠，多架构镜像用 buildx 构建 manifest list。
• P2P 解决「多节点同时拉」：Spegel 用一个 DaemonSet 复用节点已有层，Dragonfly 支持预热与非镜像文件但组件多；节点预拉取适合发布前预热，注意磁盘容量。
• 镜像只是一半，内网还要有 PyPI / Conda 的按需缓存镜像源（devpi / quetz），否则内网化之后依赖是最先断掉的一环。

练习#

1. 给 Harbor 配一个上游 docker.io 的 proxy cache 项目，从它拉一个公网镜像，观察缓存命中前后的耗时差异。
2. 在 demo 命名空间删掉 harbor-cred Secret，再重建一个 Pod，用 kubectl describe pod 记录完整的鉴权失败报错。
3. 给一个常用镜像构建多架构版本并推到 Harbor，然后在 amd64 节点上确认它跑得起来。

到这里，「进阶：生产实践」模块就讲完了：集群怎么装、网络怎么通、数据怎么落、状态怎么看、安全怎么加固、交付怎么自动化、数据怎么恢复、镜像怎么分发——这八件事撑起了在生产环境里管集群的底气。