企业官网建设流程全解析

1. 这不是普通镜像仓库：为什么必须用 MinIO + 容器化 + 高可用来重构 docker-registry

你有没有遇到过这样的场景：团队在 CI/CD 流水线里 push 镜像时突然卡住，报错unauthorized: authentication required或者net/http: request canceled；半夜运维收到告警，registry 容器 OOM 被 kill，整个构建链路中断；某天发现历史镜像莫名丢失，回溯才发现是本地磁盘挂载点被误删，而备份脚本半年没跑过一次；又或者——最扎心的——测试环境能 pull 的镜像，在生产环境死活拉不下来，排查半天发现是 registry 后端存储用了单点 NFS，而 NFS 服务端刚好在那个时间窗口做了内核热补丁重启。

这些不是偶发故障，而是传统 docker-registry 部署模式的结构性缺陷。标题里这句“基于 MinIO 存储，容器化部署高可用 docker-registry”，表面看是三个技术词堆砌，实则是一套经过生产验证的、闭环的架构决策链：用 MinIO 替代本地文件系统或 NFS，解决存储层单点与一致性问题；用容器化（而非裸机二进制）封装 registry 服务，实现环境隔离、版本可追溯、启停原子化；再通过多实例+反向代理+健康检查组合，达成真正意义上的高可用——不是“看起来不挂”，而是“挂了也不影响业务”。

核心关键词就三个：MinIO、容器化、高可用。它们不是并列关系，而是层层递进的因果链。MinIO 是底座，它让 registry 不再依赖脆弱的本地路径，而是对接一个具备对象存储语义、支持多副本、自带 HTTP API、可横向扩展的存储后端；容器化是载体，它把 registry 的配置、依赖、启动逻辑全部打包固化，避免“在我机器上能跑”的环境幻觉；高可用是结果，但这个结果必须建立在前两者稳固的基础上——没有 MinIO 的 registry 多实例，只是多个单点；没有容器化的高可用，等于在沙上建塔。

适合谁参考？如果你正面临以下任一情况，这篇就是为你写的：

• 正在从 Jenkins + Shell 脚本式 CI 迁移到 GitLab CI / GitHub Actions，需要稳定可靠的私有镜像仓库支撑；
• 团队规模超过 15 人，每天镜像 push/pull 请求超 2000 次，现有 registry 经常出现 503 或 slow response；
• 运维要求所有中间件必须容器化纳管，且需接入 Prometheus + Grafana 监控体系；
• 安全审计提出“镜像存储必须加密落盘、访问必须留痕、数据必须跨 AZ 冗余”，而你还在用--storage-file参数硬编码路径；
• 或者，你只是个想搞懂“为什么大厂不用 docker run -d -p 5000:5000 registry:2”这种玩具方案的开发者。

这不是一篇教你怎么敲几行命令的速成指南。接下来我会带你一层层剥开：为什么 MinIO 是当前最务实的选择（而不是 Ceph、S3 兼容网关或自研对象存储）；容器化部署时 registry 配置文件里每个字段的真实含义和取舍逻辑；高可用背后那些文档里不会写的细节——比如反向代理如何做健康检查才不会把流量打到假死的实例上，比如 registry 实例间如何避免缓存雪崩，比如证书链怎么配才能让docker login不报x509: certificate signed by unknown authority。所有内容，都来自我在三个不同行业客户现场落地该方案时踩过的坑、记下的日志、改过的配置。

2. 为什么是 MinIO？不是 S3、不是 NFS、更不是本地磁盘

2.1 本地磁盘方案的致命伤：它根本不是为 registry 设计的

很多人第一次搭私有 registry，直接执行这条命令：

docker run -d -p 5000:5000 --restart=always --name registry \ -v /mnt/registry:/var/lib/registry \ -e REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/var/lib/registry \ registry:2

看起来很干净，对吧？但只要业务量上来，问题立刻暴露。registry 的存储模型是典型的“小文件海”：一个镜像由 manifest.json、layers（每层一个 tar.gz）、config.json 等组成，push 一个 500MB 的镜像，实际会在磁盘生成 20+ 个 1MB~50MB 不等的文件。Linux ext4 文件系统对海量小文件的元数据操作（inode 分配、目录项查找）效率极低。我们曾在一个 4C8G 的虚拟机上实测：当/mnt/registry下文件数超过 12 万，docker push的平均耗时从 8 秒飙升到 47 秒，ls -lR | wc -l命令甚至会卡住超过 2 分钟。

更致命的是单点风险。一旦/mnt/registry所在磁盘损坏，或者宿主机宕机导致文件系统损坏（ext4 journal crash 后 fsck 失败概率不为零），整个镜像仓库就不可逆地丢失。你可能会说：“我有备份！”——但 registry 的备份不是简单rsync，因为它的存储结构是松散的哈希目录树（如docker/registry/v2/repositories/nginx/_manifests/revisions/sha256/ab.../link），直接拷贝可能遇到正在写入的文件，导致备份不一致。而官方推荐的registry garbage-collect命令，又要求 registry 必须停止服务，这在生产环境根本不可接受。

提示：registry 的garbage-collect不是“删除无用层”，而是“清理未被 manifest 引用的 blob”。它依赖 registry 内部的数据库（实际上是个内存映射的 boltdb 文件）与文件系统状态严格一致。如果在运行中强行rsync，很可能备份出来的 boltdb 和文件不匹配，restore 后 registry 启动失败或返回 404。

2.2 NFS 方案的隐性成本：网络延迟放大器

为了解决单机磁盘问题，不少人转向 NFS。配置起来似乎更“企业级”：

# docker-compose.yml 片段 services: registry: image: registry:2 volumes: - nfs-registry:/var/lib/registry volumes: nfs-registry: driver: local driver_opts: type: nfs o: addr=192.168.10.100,rw,nfsvers=4.1 device: ":/exports/registry"

但 NFS 在 registry 场景下，本质是把本地 I/O 延迟，转化成了网络 RTT 延迟，并且是指数级放大的。原因在于 registry 的读写模式：每次 pull 一个 layer，registry 需要先读取该 layer 的link文件（获取 blob digest），再根据 digest 拼出完整路径去读取 tar.gz 文件。这个过程涉及至少 2 次 NFS lookup + 1 次 read。而 NFSv4.1 虽然支持 delegations，但 registry 进程本身并不做客户端缓存（它假设底层是 POSIX-compliant 且低延迟的块设备），所以每次操作都是同步阻塞的。

我们在某金融客户现场做过压测：后端 NFS 服务器是 3 节点集群（NFS-Ganesha + CephFS），单节点吞吐 1.2GB/s，但 registry 实例的 P95 延迟仍高达 1.8 秒。抓包发现，90% 的时间花在了 TCP 握手、NFS COMPOUND 请求拆分、以及服务器端的锁竞争上。更麻烦的是，NFS 的soft mount会导致 registry 在网络抖动时静默失败（返回 EIO 而非 ETIMEDOUT），docker pull就卡住不动；hard mount则会让整个 registry 进程 hang 住，触发 Kubernetes 的 liveness probe 失败，反复重启。

2.3 为什么 MinIO 成为最优解：它精准匹配 registry 的对象存储语义

MinIO 的设计哲学，与 docker-registry 的存储需求存在天然契合点。registry 从诞生起，就不是为“文件系统”设计的，而是为“对象存储”设计的——它的所有数据，最终都以sha256:<digest>为 key 存储，value 是任意二进制 blob（layer tar.gz）或 JSON 文本（manifest）。这正是对象存储的核心抽象：Key-Value。

MinIO 作为 S3 兼容的对象存储，提供了 registry 官方原生支持的s3storage driver。这意味着 registry 不需要任何适配层，直接通过 HTTP PUT/GET 操作 MinIO，完全绕过了 POSIX 文件系统语义。我们来看关键优势：

• 强一致性保障：MinIO 默认开启erasure coding（纠删码）。以 4 节点集群为例，数据被切分为 4 份，同时生成 2 份校验块，允许任意 2 节点故障而不丢数据。这比 NFS 的“主从复制”或本地磁盘的“RAID5”可靠性更高，且无需额外维护同步进程。
• 无单点元数据瓶颈：MinIO 的元数据（bucket、object list）也分布存储在各节点，不像传统 NFS 有中心化的 MDS（Metadata Server）。registry 的高频HEAD请求（检查 blob 是否存在）不会打爆单一节点。
• 无缝 TLS 加密：MinIO 原生支持 Let's Encrypt 自动续签，registry 的s3driver 可直接配置secure: true和skipverify: false，所有流量走 HTTPS，满足等保三级对传输加密的要求。
• 成熟监控集成：MinIO 内置 Prometheus metrics endpoint（/minio/prometheus/metrics），可直接采集minio_bucket_objects_total、minio_s3_requests_duration_seconds等指标，与 registry 的http_request_duration_seconds指标联动，快速定位是存储慢还是 registry 逻辑慢。

当然，MinIO 不是银弹。它对内存要求较高（每 1TB 存储建议 8GB RAM），且集群扩容必须按节点整数倍进行（不能只加 1 台）。但相比 Ceph 的复杂运维（需要管理 MON、OSD、MDS 多种角色），MinIO 的mc alias set一条命令就能完成集群接入，对中小团队更友好。我们选型时做过对比：Ceph 集群上线平均耗时 3.2 人日，MinIO 集群（4 节点）仅需 4 小时，且后续扩容只需mc admin service restart即可生效。

2.4 为什么不直接用 AWS S3？成本与合规的现实约束

有人会问：“既然 registry 支持 S3，为啥不直接上云？”答案很现实：成本不可控 + 合规风险。

以某电商客户为例，其 registry 日均写入 12TB 新镜像（含 CI 构建的临时 tag），读取 8TB。若使用 AWS us-east-1 的 S3 Standard，仅存储费用每月就超 $18,000（$0.023/GB），加上 2000 万次 GET 请求（$0.0004/1000 次）和 500 万次 PUT（$0.005/1000 次），请求费用另加 $2500。更关键的是，其安全策略禁止生产镜像流出内网，而 S3 的 VPC Endpoint 无法完全规避 DNS 劫持风险（S3 的 DNS 解析仍依赖公网根域名服务器）。

MinIO 则完美规避这两点：所有流量在内网完成，存储成本仅为硬件折旧（4 台 32G RAM/8C/10TB NVMe 服务器，3 年总成本约 $15,000）；且 MinIO 支持policy-based access control，可精确限制某个 registry 实例只能读写特定 bucket，权限粒度远超 S3 的 IAM Role。

3. 容器化部署：不只是 docker run，而是配置即代码的工程实践

3.1 registry 配置文件的每一行，都在回答一个生产问题

很多人以为 registry 的配置就是config.yml里几行 YAML。但当你把它放到生产环境，每一行配置背后，都是对一个具体运维场景的应答。我们来看一份经过千锤百炼的config.yml：

version: 0.1 log: level: info fields: service: registry storage: cache: blobdescriptor: inmemory s3: region: us-east-1 bucket: docker-registry-prod encrypt: true secure: true v4auth: true chunksize: 5242880 rootdirectory: /docker/registry/v2 http: addr: minio.prod.svc.cluster.local:9000 path: / accesskey: minioadmin secretkey: minioadmin sessiontoken: "" maintenance: uploadpurging: enabled: true age: 168h interval: 24h dryrun: false readonly: enabled: false auth: htpasswd: realm: basic-realm path: /etc/registry/auth/htpasswd http: addr: :5000 net: tcp prefix: / secret: a-super-secret-key-changed-every-30-days relativeurls: false tls: certificate: /etc/registry/certs/domain.crt key: /etc/registry/certs/domain.key headers: X-Content-Type-Options: [nosniff] health: storagedriver: enabled: true interval: 10s threshold: 3

别急着复制。我们逐段拆解它解决的实际问题：

• log.fields.service: registry：这是为了日志采集。Kubernetes 的 Fluentd DaemonSet 会自动给日志打上kubernetes.container_name=registry标签，配合这个service字段，可在 Grafana 中用service="registry"快速过滤所有 registry 日志，避免和 nginx ingress 的日志混在一起。

• storage.cache.blobdescriptor: inmemory：registry 默认会对每个 blob 的 descriptor（元数据）做磁盘缓存（boltdb），但在高并发下，这个 DB 会成为瓶颈。inmemory模式将其移入内存，P95 延迟下降 60%，代价是内存占用增加约 1.2GB（按 10 万 blobs 估算）。我们选择它，是因为 MinIO 本身已提供强一致性，registry 无需再靠 boltdb 做二次校验。

• storage.s3.chunksize: 5242880（5MB）：这是关键调优参数。registry 上传 layer 时，会将大文件分块 PUT 到 S3。MinIO 对单块大小有默认限制（5MB），若设得过大（如 10MB），遇到网络抖动会导致整块重传，反而更慢；设得太小（如 1MB），则 HTTP 请求次数暴增，消耗连接池。5MB 是我们在 10Gbps 内网环境下实测的最优值。

• maintenance.uploadpurging：CI 流水线经常生成dev-*、pr-123这类临时 tag，它们占满存储却无人清理。此配置启用自动清理：每 24 小时扫描一次，删除 7 天前未被任何 manifest 引用的 upload（即断点续传残留的临时文件）。dryrun: false表示真删，不是预演。

• http.tls：必须配置！否则docker login https://registry.example.com会因证书不信任失败。这里强调：证书必须是完整的证书链（.crt文件里包含 root CA + intermediate CA + domain cert），不能只放 domain cert。我们曾因此浪费 3 小时排查x509: certificate signed by unknown authority。

3.2 容器镜像选择：为什么不用官方 registry:2，而用 distribution/distribution:latest

官方 Docker Hub 上的registry:2镜像是基于distribution/distribution:v2.7.1构建的，而后者已于 2022 年 10 月停止维护。新版本distribution/distribution:latest（当前为 v2.8.3）修复了多个关键漏洞：

• CVE-2022-29181：恶意构造的 manifest 可导致 registry 进程 panic（DoS）；
• CVE-2023-25167：/v2/_catalog接口未做鉴权，可被未授权用户枚举所有仓库名；
• 更重要的是，v2.8+ 原生支持oci-mediatypes，能正确处理 Helm Chart OCI 包（application/vnd.cncf.helm.chart.content.v1.tar+gzip），这对正在向 OCI 迁移的团队至关重要。

构建自己的 registry 镜像也很简单，只需一个Dockerfile：

FROM golang:1.21-alpine AS builder RUN apk add --no-cache git make WORKDIR /src RUN git clone https://github.com/distribution/distribution.git . && \ git checkout v2.8.3 && \ make binaries FROM alpine:3.18 RUN apk add --no-cache ca-certificates && update-ca-certificates COPY --from=builder /src/cmd/registry/registry /bin/registry COPY config.yml /etc/registry/config.yml EXPOSE 5000 CMD ["/bin/registry", "/etc/registry/config.yml"]

这样做的好处是：镜像体积从官方registry:2的 28MB 降到 12MB，启动时间缩短 40%，且所有依赖（如ca-certificates）版本可控，避免 Alpine 基础镜像升级导致的 TLS 握手失败。

3.3 Kubernetes 部署清单：StatefulSet 还是 Deployment？答案是 Deployment + headless Service

registry 是无状态服务（stateless），它的“状态”全部在 MinIO 里。因此，用Deployment而非StatefulSet是更合理的选择。StatefulSet的序号、稳定网络标识（pod-0.registry.default.svc.cluster.local）对 registry 毫无意义，反而增加运维复杂度。

但有一个关键细节：必须用headless Service（clusterIP: None）。为什么？

因为 registry 的健康检查依赖http://<pod-ip>:5000/health，而 Kubernetes 的普通 Service 会做 kube-proxy 的 DNAT，导致 registry 日志里看到的 client IP 全是10.244.x.x（Node 的 CNI 网段），无法区分真实请求来源。headless Service则直接返回 Pod 的真实 IP，配合 registry 的log.http.request.remoteaddr字段，可精准定位是哪个 CI Agent 的 IP 在高频刷请求。

以下是精简版deployment.yaml：

apiVersion: apps/v1 kind: Deployment metadata: name: registry spec: replicas: 3 selector: matchLabels: app: registry template: metadata: labels: app: registry annotations: prometheus.io/scrape: "true" prometheus.io/port: "5000" spec: containers: - name: registry image: my-registry-internal.com/distribution:2.8.3 ports: - containerPort: 5000 name: http env: - name: REGISTRY_CONFIGURATION value: "/etc/registry/config.yml" volumeMounts: - name: config mountPath: /etc/registry/config.yml subPath: config.yml - name: certs mountPath: /etc/registry/certs - name: auth mountPath: /etc/registry/auth volumes: - name: config configMap: name: registry-config - name: certs secret: secretName: registry-tls - name: auth secret: secretName: registry-auth --- apiVersion: v1 kind: Service metadata: name: registry-headless annotations: service.alpha.kubernetes.io/tolerate-unready-endpoints: "true" spec: clusterIP: None selector: app: registry ports: - port: 5000 targetPort: 5000

注意annotations: service.alpha.kubernetes.io/tolerate-unready-endpoints: "true"。这是为了兼容 registry 的启动慢特性——registry 启动时要初始化 MinIO 连接、加载配置、预热缓存，通常需 8~12 秒。此注解允许 Service 在 PodReady状态为 False 时，仍将其 IP 加入 endpoints，避免滚动更新时出现短暂 503。

4. 高可用实现：三节点不是终点，而是起点

4.1 反向代理层：Nginx Ingress Controller 的健康检查陷阱

高可用的第一道防线是反向代理。很多人直接用nginx或haproxy做四层 TCP 代理，但这会丢失 HTTP 层的语义。正确的做法是：用七层 HTTP 代理，并开启 registry-aware 的健康检查。

Kubernetes 生态中，ingress-nginx是最主流的选择。但它的默认healthCheck配置对 registry 是无效的。默认的nginx.ingress.kubernetes.io/health-check-path: /healthz会向 registry 的/healthz发送 GET，而 registry 根本没有这个 endpoint！它只有/health（返回 JSON{ "storagedriver": { "healthy": true } }）。

必须显式配置：

apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: registry-ingress annotations: nginx.ingress.kubernetes.io/health-check-path: "/health" nginx.ingress.kubernetes.io/health-check-interval: "10" nginx.ingress.kubernetes.io/health-check-fail: "3" nginx.ingress.kubernetes.io/health-check-pass: "2" nginx.ingress.kubernetes.io/ssl-redirect: "true" spec: tls: - hosts: - registry.example.com secretName: registry-tls rules: - host: registry.example.com http: paths: - path: / pathType: Prefix backend: service: name: registry-headless port: number: 5000

这里的关键参数：

• health-check-fail: "3"：连续 3 次/health返回非 200，才将该 Pod 从 upstream 中剔除；
• health-check-pass: "2"：连续 2 次成功，才重新加入；
• health-check-interval: "10"：每 10 秒检查一次。

为什么不是fail: 1？因为 registry 的/health接口会触发一次 MinIO 的 HEAD 请求（检查 bucket 是否可读），在网络抖动时可能偶发超时。设为 3 次，可过滤掉瞬时抖动，避免“惊群效应”（所有代理同时踢掉同一 Pod，导致流量瞬间打向剩余两个，引发连锁雪崩）。

4.2 registry 实例间的协同：避免缓存雪崩的 secret 配置

registry 的http.secret参数，不仅用于签名 token，更关键的是：它决定了多个 registry 实例是否共享同一个 token 签发密钥。如果三台 registry 的secret不同，那么 A 实例签发的 token，B 实例就无法验证，导致docker login后，docker push时 B 实例返回invalid token。

但更大的风险在于缓存。registry 内部有个inmemorycache（前面提到的blobdescriptor），它缓存的是 blob 的元数据（size、digest、mediaType）。如果三台实例的secret不同，它们的 cache key 计算方式就不同，导致同一 blob 在三台机器上被缓存三次，内存浪费 3 倍。更糟的是，当某台实例重启，它的 cache 清空，大量请求会穿透到 MinIO，造成 MinIO 的GETQPS 瞬间翻 3 倍，触发 MinIO 的限流（max_concurrent_gets默认 100），进而拖慢所有 registry。

解决方案：所有 registry 实例必须使用相同的、强随机的 secret。我们用openssl rand -hex 32生成，并通过 Kubernetes Secret 注入：

kubectl create secret generic registry-secret \ --from-literal=secret=$(openssl rand -hex 32)

然后在config.yml中引用：

http: secret: ${REGISTRY_HTTP_SECRET}

并在 Deployment 的 env 中注入：

env: - name: REGISTRY_HTTP_SECRET valueFrom: secretKeyRef: name: registry-secret key: secret

4.3 MinIO 集群的高可用：纠删码 vs 分布式模式的选择

MinIO 有两种高可用模式：Erasure Coding（EC）和Distributed。很多文档没讲清区别，导致选错。

• Erasure Coding：数据被切分为 N 份，生成 M 份校验块，总节点数 = N + M。例如minio server http://node{1...4}/data{1...2}表示 4 节点，每节点 2 块盘，共 8 块盘，采用 EC 4+2（4 数据块 + 2 校验块），允许任意 2 节点故障。优点：存储利用率高（8 块盘有效容量 = 4 块盘），适合大容量归档；缺点：小文件读写性能略低（需计算校验）。

• Distributed Mode：数据在所有节点间做哈希分片（类似一致性哈希），每个 object 只存一份，但通过--minio-disk-limit设置磁盘使用率阈值（如 85%），当某节点磁盘快满时，自动触发 rebalance。优点：小文件性能好，延迟低；缺点：无冗余，必须配合外部备份。

我们选择 EC 模式，因为 registry 的 layer 文件普遍较大（平均 150MB），且对“绝对不丢数据”要求极高。实测 EC 4+2 模式下，100MB layer 的 PUT 延迟为 120ms，而 Distributed 模式为 95ms——差距在可接受范围，但 EC 换来了 2 节点故障不丢数据的确定性。

部署命令示例（4 节点，每节点 2 块 NVMe 盘）：

# 所有节点执行 minio server \ http://minio-node1/data{1...2} \ http://minio-node2/data{1...2} \ http://minio-node3/data{1...2} \ http://minio-node4/data{1...2} \ --console-address ":9001" \ --address ":9000"

注意：--console-address必须显式指定，否则 MinIO Console（Web UI）会绑定到localhost:9001，外部无法访问。生产环境应通过 Ingress 暴露 Console，并设置 Basic Auth。

4.4 全链路监控：从 registry 到 MinIO 的黄金信号

高可用不是“不挂”，而是“挂了也能快速发现、定位、恢复”。我们定义 registry 全链路的 4 个黄金信号（Golden Signals）：

其中，最关键的交叉分析是：当registry的 P95 延迟升高时，同步查看minio_s3_requests_duration_seconds{operation="GetObject"}[5m]。如果后者也升高，则问题在 MinIO；如果后者正常，而registry的http_request_duration_seconds{handler="blobGetHandler"}升高，则是 registry 的 blob 获取逻辑有问题（如 cache miss 率过高）。

我们用一个 Grafana Panel 实现一键下钻：点击 registry 延迟曲线上的峰值点，自动跳转到 MinIO 的对应时间段面板，并高亮GetObject指标。这个功能，让故障定位时间从平均 42 分钟缩短到 6 分钟。

5. 实操避坑指南：那些文档里绝不会写的血泪教训

5.1 “docker login 失败：x509: certificate signed by unknown authority”的 5 种真实原因

这个问题太常见，但网上答案大多治标不治本。根据我们 17 次现场排障记录，真实原因如下：

1. 证书链不完整（占比 41%）：你的.crt文件只包含 domain cert，缺少 intermediate CA。用openssl crl2pkcs7 -nocrl -certfile domain.crt | openssl pkcs7 -print_certs -noout查看，应输出 2~3 个证书。缺了就去证书颁发机构下载 full chain。

2. registry 的 TLS 配置指向了错误路径（23%）：config.yml中http.tls.certificate是相对路径，而 registry 启动时工作目录是/，所以它实际找的是/etc/registry/certs/domain.crt。但如果你用 ConfigMap 挂载，subPath写错了（如写成cert.crt而不是domain.crt），就会静默失败。

3. Docker daemon 的根证书库未更新（18%）：docker login时，Docker daemon 进程（不是 registry 容器）会验证证书。在 CentOS 7 上，/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem可能很老。执行update-ca-trust并重启dockerd。

4. Ingress Controller 的 SSL Passthrough 未开启（12%）：如果你用nginx-ingress，且ingress.spec.tls配置了secretName，但没在 Ingress annotation 中加nginx.ingress.kubernetes.io/ssl-passthrough: "true"，那么 Ingress 会用自己的证书终止 TLS，再以 HTTP 连接 registry，导致 registry 的 TLS 配置完全失效。

5. 客户端 DNS 缓存了旧 IP（6%）：registry.example.com的 DNS TTL 是 300 秒，但某些 Android 手机的 DNS 缓存长达 24 小时。用dig registry.example.com确认解析 IP 是否正确。

实操心得：遇到此问题，第一步永远是curl -v https://registry.example.com/health。如果 curl 报同样的 x509 错误，说明是证书问题；如果 curl 成功而docker login失败，则一定是 Docker daemon 或 Ingress 配置问题。

5.2 MinIO 启动后mc alias set总是 timeout？检查这 3 个防火墙端口

MinIO 默认监听 3 个端口：

• 9000：S3 API（registry 使用）
• 9001：Console Web UI（管理用）
• 9002：Prometheus metrics（监控用）

mc alias set命令默认尝试连接9000和9001。如果9001被防火墙拦截，mc会等待 10 秒超时，然后报Unable to initialize new alias from the provided credentials。这不是认证失败，而是连接失败！

检查方法：

# 从 registry Pod 内执行 nc -zv minio.prod.svc.cluster.local 9000 # 应返回 succeeded nc -zv minio.prod.svc.cluster.local 9001 # 应返回 succeeded nc -zv minio.prod.svc.cluster.local 9002 # 应返回 succeeded

如果9001失败，要么开放防火墙，要么在mc alias set时显式指定--api S3v4并关闭 Console 访问：

mc alias set myminio \ https://minio.prod.svc.cluster.local:9000 \ minioadmin minioadmin \ --api S3v4

5.3 registry 启动日志里出现 “error authorizing context: authorization token required”？不是权限问题，是配置缺失

这个错误看似是鉴权失败，实则是 registry 的auth配置未生效。常见原因有两个：

• htpasswd 文件权限不对：Kubernetes Secret 挂载的文件，默认权限是644，但 registry 要求htpasswd文件必须是600（仅 owner 可读）。解决方案：在 Deployment 的securityContext中添加fsGroup: 1001，让 kubelet 自动chown所有挂载文件到 group 1001，registry 进程以 UID 1001 运行即可读取。

• **