# Harbor 镜像缓存解决方案

## 问题背景

Kubernetes Dashboard 部署时遇到 `ImagePullBackOff` 错误：

```
Error response from daemon: Get "https://registry-1.docker.io/v2/": context deadline exceeded
```

**原因**: 直接从 Docker Hub 拉取镜像时网络超时。

---

## 解决方案

使用 **EU Harbor → 本地 Harbor** 双重缓存策略：

```
Docker Hub (公网)
    ↓ (可能超时)
EU Harbor 缓存 (harbor.eu.lingjingwanxiang.cn)
    ↓ (快速稳定)
本地 Harbor (harbor.omniverseai.net:8080)
    ↓ (本地访问)
Kubernetes 集群
```

---

## 实施步骤

### 1. 通过 EU Harbor 拉取镜像并缓存到本地 Harbor

使用现有脚本 `/Users/brunogao/work/codes/tools/macos/harbor/pull-via-eu-harbor.sh`：

```bash
cd /Users/brunogao/work/codes/tools/macos/harbor

# 拉取 Dashboard 主镜像
./pull-via-eu-harbor.sh kubernetesui/dashboard:v2.7.0

# 拉取 Metrics Scraper 镜像
./pull-via-eu-harbor.sh kubernetesui/metrics-scraper:v1.0.8
```

**执行结果**:

```
✅ Dashboard 镜像缓存成功
  源镜像: harbor.eu.lingjingwanxiang.cn/dockerhub-proxy/kubernetesui/dashboard:v2.7.0
  本地路径: harbor.omniverseai.net:8080/library/kubernetesui/dashboard:v2.7.0
  架构: arm64

✅ Metrics Scraper 镜像缓存成功
  源镜像: harbor.eu.lingjingwanxiang.cn/dockerhub-proxy/kubernetesui/metrics-scraper:v1.0.8
  本地路径: harbor.omniverseai.net:8080/library/kubernetesui/metrics-scraper:v1.0.8
  架构: amd64
```

### 2. 更新 Kubernetes 部署使用本地 Harbor 镜像

```bash
# 更新 Dashboard 镜像
kubectl set image deployment/kubernetes-dashboard \
  kubernetes-dashboard=harbor.omniverseai.net:8080/library/kubernetesui/dashboard:v2.7.0 \
  -n kubernetes-dashboard

# 更新 Metrics Scraper 镜像
kubectl set image deployment/dashboard-metrics-scraper \
  dashboard-metrics-scraper=harbor.omniverseai.net:8080/library/kubernetesui/metrics-scraper:v1.0.8 \
  -n kubernetes-dashboard
```

**执行结果**:

```
deployment.apps/kubernetes-dashboard image updated
deployment.apps/dashboard-metrics-scraper image updated
```

### 3. 验证部署状态

```bash
kubectl get pods -n kubernetes-dashboard
```

**验证结果**:

```
NAME                                        READY   STATUS    RESTARTS   AGE
dashboard-metrics-scraper-f79d94544-9hhqw   1/1     Running   0          2m
kubernetes-dashboard-7865787d44-2tswq       1/1     Running   0          2m
```

```bash
kubectl get deployment -n kubernetes-dashboard
```

```
NAME                        READY   UP-TO-DATE   AVAILABLE   AGE
dashboard-metrics-scraper   1/1     1            1           45m
kubernetes-dashboard        1/1     1            1           45m
```

**状态**: ✅ **全部正常运行**

---

## 镜像路径对照表

| 角色 | 镜像路径 | 说明 |
|------|----------|------|
| **原始源** | `docker.io/kubernetesui/dashboard:v2.7.0` | Docker Hub 公网仓库 (可能超时) |
| **EU Harbor 缓存** | `harbor.eu.lingjingwanxiang.cn/dockerhub-proxy/kubernetesui/dashboard:v2.7.0` | 欧洲 Harbor 中转缓存 |
| **本地 Harbor** | `harbor.omniverseai.net:8080/library/kubernetesui/dashboard:v2.7.0` | 本地 Harbor 最终缓存 |
| **K8s 使用** | `harbor.omniverseai.net:8080/library/kubernetesui/dashboard:v2.7.0` | Kubernetes 部署使用 |

---

## 方案优势

✅ **避免公网超时**: 绕过 Docker Hub 访问限制
✅ **双重缓存加速**: EU Harbor + 本地 Harbor 两级缓存
✅ **架构自动适配**: 支持 arm64 和 amd64 自动选择
✅ **本地快速访问**: 后续部署直接从本地 Harbor 拉取
✅ **可复用流程**: 适用于所有公网镜像拉取问题

---

## 适用场景

此方案适用于以下场景：

1. **Docker Hub 访问超时** - 网络不稳定或被限流
2. **GCR/Quay 无法访问** - 墙内环境拉取镜像
3. **大镜像拉取慢** - 利用缓存加速
4. **企业内网部署** - 预先缓存所需镜像
5. **离线环境准备** - 提前缓存到本地 Harbor

---

## 脚本工作原理

`pull-via-eu-harbor.sh` 脚本执行流程：

```bash
[1/6] 登录 EU Harbor 和本地 Harbor
      ↓
[2/6] 尝试从 EU Harbor library 拉取
      如失败 → 尝试 dockerhub-proxy
      ↓
[3/6] 标记为本地 Harbor 镜像路径
      ↓
[4/6] 推送到本地 Harbor
      ↓
[5/6] 验证从本地 Harbor 拉取
      ↓
[6/6] 验证镜像架构 (arm64/amd64)
```

---

## 相关文档

- **部署指南**: [README.md](./README.md) - "镜像管理最佳实践"章节
- **企业增强报告**: [ENTERPRISE-K8S-IMPLEMENTATION-REPORT.md](./ENTERPRISE-K8S-IMPLEMENTATION-REPORT.md)
- **Harbor 脚本**: `/Users/brunogao/work/codes/tools/macos/harbor/pull-via-eu-harbor.sh`

---

## 执行摘要

**问题**: Kubernetes Dashboard 因 Docker Hub 超时无法部署
**方案**: EU Harbor → 本地 Harbor 双重缓存
**结果**: ✅ Dashboard 成功部署并正常运行
**用时**: ~3 分钟（镜像拉取 + 部署更新 + 验证）
**状态**: 已写入 README.md 作为最佳实践供后续参考

---

**生成时间**: 2025-12-24 14:30:00
**验证状态**: ✅ 完全通过