gao/ljwx-k8s

Fork 0

Files

T

bruno 2a56d7fd6c first commit

2026-02-20 22:50:45 +08:00

17 KiB

Raw Permalink Blame History

自动镜像修复系统 - 部署指南

基于你当前环境的定制化部署方案生成时间: 2025-12-24 18:09 环境状态: OrbStack + 本地 Harbor 已配置

📊 当前环境状态

✅ 已就绪

OrbStack: 已安装并运行
本地 Harbor: harbor.omniverseai.net:8080 (已配置为 insecure-registry)
EU Harbor: harbor.eu.lingjingwanxiang.cn (镜像源)
cache-image.sh: 核心缓存脚本 (14KB)

⚠️ 待配置

Registry Mirror: OrbStack 配置中 registry-mirrors 为空数组
kubectl wrapper: 未安装
后台监控: 未安装

🚀 快速部署（推荐）

一键部署所有组件

cd /Users/brunogao/work/codes/tools/macos/k8s
./deploy-auto-fix.sh

这个脚本会：

✅ 保留你现有的 OrbStack 配置（不会破坏）
✅ 添加 Registry Mirror 到配置
✅ 安装 kubectl wrapper（可选）
✅ 配置后台监控服务（可选）
✅ 提供交互式选项（你可以选择安装哪些组件）
✅ 自动备份现有配置

部署过程预览

═══════════════════════════════════════════════════════════════
自动镜像修复系统 - 定制化部署
═══════════════════════════════════════════════════════════════

[STEP] 1/4 环境检查
  ✓ OrbStack 配置文件存在
  ! Registry Mirrors: 未配置 (将添加)
  ✓ Insecure Registries: 已配置 2 个
  ! kubectl wrapper: 未安装 (将添加)
  ! 后台监控: 未安装 (可选)

[STEP] 2/4 配置 Registry Mirror（保留现有配置）
  ✓ 已备份配置到: ~/.orbstack/config/docker.json.backup.20251224_180900
  ✓ 已添加 Registry Mirror: http://harbor.omniverseai.net:8080

[STEP] 3/4 安装 kubectl wrapper
  ✓ 已添加 kubectl alias 到 ~/.zshrc

[STEP] 4/4 配置后台监控服务（可选）
  是否安装后台监控服务? (y/n)

📋 分步部署（手动控制）

如果你想更精细地控制安装过程，可以分步执行：

Step 1: 配置 Registry Mirror

# 使用 jq 安全地添加 registry-mirrors（保留所有现有配置）
cd /Users/brunogao/work/codes/tools/macos/k8s

# 备份现有配置
cp ~/.orbstack/config/docker.json ~/.orbstack/config/docker.json.backup

# 添加 registry-mirrors
jq '.["registry-mirrors"] = ["http://harbor.omniverseai.net:8080"]' \
   ~/.orbstack/config/docker.json > /tmp/docker.json.tmp

mv /tmp/docker.json.tmp ~/.orbstack/config/docker.json

# 重启 OrbStack
orb restart

# 验证
docker info | grep -A 3 "Registry Mirrors"

预期结果：

Registry Mirrors:
  http://harbor.omniverseai.net:8080

Step 2: 安装 kubectl wrapper

# 添加 alias 到 .zshrc
cat >> ~/.zshrc << 'EOF'

# ═══════════════════════════════════════════════════════════════
# kubectl auto-fix wrapper
# 自动检测并修复 ImagePullBackOff 错误
# ═══════════════════════════════════════════════════════════════
alias kubectl="/Users/brunogao/work/codes/tools/macos/k8s/kubectl-auto-fix"

EOF

# 使 alias 生效
source ~/.zshrc

# 测试（应该看到 kubectl 正常输出，但会经过 wrapper）
kubectl version --client

Step 3: 配置后台监控（可选）

# 创建 LaunchAgent
cat > ~/Library/LaunchAgents/com.k8s.image-watcher.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.k8s.image-watcher</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/brunogao/work/codes/tools/macos/k8s/watch-and-fix-images.sh</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/image-watch.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/image-watch-error.log</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin</string>
    </dict>
</dict>
</plist>
EOF

# 启动服务
launchctl load ~/Library/LaunchAgents/com.k8s.image-watcher.plist

# 查看日志
tail -f /tmp/image-watch.log

🧪 测试验证

测试 1: Registry Mirror 工作验证

# 清除本地镜像（如果存在）
docker rmi nginx:alpine 2>/dev/null || true

# 拉取镜像（应该从本地 Harbor 拉取）
time docker pull nginx:alpine

# 检查来源（查看拉取日志，应该显示从本地 Harbor）
docker images nginx:alpine

预期输出：

拉取速度很快（如果 Harbor 已缓存）
或者第一次稍慢（Harbor 从上游拉取并缓存）

测试 2: kubectl wrapper 自动修复

创建一个测试 Deployment（故意使用可能拉取失败的镜像）：

cat > /tmp/test-imagepull.yaml << 'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
  name: test-imagepull
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: test
  template:
    metadata:
      labels:
        app: test
    spec:
      containers:
      - name: test
        image: gcr.io/google-containers/pause:3.8
        imagePullPolicy: Always
EOF

# 应用 Deployment
kubectl apply -f /tmp/test-imagepull.yaml

# kubectl wrapper 会：
# 1. 执行原始 kubectl apply
# 2. 等待 3 秒
# 3. 检查是否有 ImagePullBackOff
# 4. 如果有，自动调用 cache-image.sh
# 5. 修复并更新 Deployment

# 查看状态
kubectl get pods -n default | grep test-imagepull

# 查看 wrapper 日志
tail -20 /tmp/kubectl-auto-fix.log

测试 3: 后台监控验证

# 查看监控日志（实时）
tail -f /tmp/image-watch.log

# 你应该看到类似输出：
# [2025-12-24 18:15:00] [INFO] === 启动 Kubernetes 镜像拉取监控 ===
# [2025-12-24 18:15:00] [INFO] 检查间隔: 30s
# [2025-12-24 18:15:30] [INFO] 统计: 检查 1 次, 修复 0 次, 失败 0 次

🎯 部署后的系统架构

┌─────────────────────────────────────────────────────────────┐
│                      Kubernetes / Docker                     │
│                                                              │
│  需要拉取镜像: docker.io/nginx:alpine                        │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────────┐
│  Layer 1: OrbStack Registry Mirror (透明)                   │
│  ✓ 配置: ~/.orbstack/config/docker.json                    │
│  ✓ 镜像: http://harbor.omniverseai.net:8080                │
│  ✓ 成功率: 90% (Docker Hub 镜像)                           │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        │ 如果失败 (GCR, Quay 等)
                        ▼
┌─────────────────────────────────────────────────────────────┐
│  Layer 2: kubectl wrapper (自动检测)                        │
│  ✓ 脚本: kubectl-auto-fix                                  │
│  ✓ 触发: kubectl apply/create/replace                      │
│  ✓ 检测: ImagePullBackOff 错误                             │
│  ✓ 动作: 自动调用 cache-image.sh                           │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        │ 调用
                        ▼
┌─────────────────────────────────────────────────────────────┐
│  Layer 3: 后台监控 (持续巡检)                               │
│  ✓ 脚本: watch-and-fix-images.sh                           │
│  ✓ 间隔: 30 秒                                             │
│  ✓ 监控: 所有命名空间的 Pods                                │
│  ✓ 动作: 自动修复检测到的失败                               │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        │ 都调用
                        ▼
┌─────────────────────────────────────────────────────────────┐
│  核心: cache-image.sh                                       │
│  ✓ 从 EU Harbor 拉取: harbor.eu.lingjingwanxiang.cn        │
│  ✓ 推送到本地: harbor.omniverseai.net:8080                 │
│  ✓ 更新 K8s 资源                                           │
│  ✓ 触发 Pod 重启                                           │
└─────────────────────────────────────────────────────────────┘
                        │
                        ▼
                     成功运行 ✅

📝 配置文件说明

~/.orbstack/config/docker.json（更新后）

{
  "max-concurrent-downloads": 6,
  "max-download-attempts": 5,
  "max-concurrent-uploads": 5,
  "insecure-registries": [
    "harbor.omniverseai.net:8080",
    "192.168.1.83:8080"
  ],
  "registry-mirrors": [
    "http://harbor.omniverseai.net:8080"
  ],
  "debug": false,
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

关键变化：

✅ registry-mirrors 从 [] 改为 ["http://harbor.omniverseai.net:8080"]
✅ 保留所有其他配置不变

~/.zshrc（新增内容）

# ═══════════════════════════════════════════════════════════════
# kubectl auto-fix wrapper
# 自动检测并修复 ImagePullBackOff 错误
# ═══════════════════════════════════════════════════════════════
alias kubectl="/Users/brunogao/work/codes/tools/macos/k8s/kubectl-auto-fix"

🔧 常用操作

查看系统状态

# 检查 Registry Mirror
docker info | grep -A 3 "Registry Mirrors"

# 检查 kubectl wrapper
type kubectl

# 检查后台监控
launchctl list | grep k8s.image-watcher
tail -20 /tmp/image-watch.log

# 检查所有日志
ls -lh /tmp/*image*.log

手动修复镜像问题

# 方式 1: 自动修复整个 Deployment
./cache-image.sh --update-deployment namespace/deployment-name

# 方式 2: 手动缓存单个镜像
./cache-image.sh nginx:alpine

# 方式 3: 批量缓存
./cache-image.sh nginx:alpine redis:7 mysql:8.0

# 方式 4: 从文件批量缓存
echo "nginx:alpine" > images.txt
echo "redis:7" >> images.txt
./cache-image.sh -f images.txt

管理后台监控

# 启动
launchctl load ~/Library/LaunchAgents/com.k8s.image-watcher.plist

# 停止
launchctl unload ~/Library/LaunchAgents/com.k8s.image-watcher.plist

# 查看状态
launchctl list | grep k8s.image-watcher

# 实时日志
tail -f /tmp/image-watch.log

# 错误日志
tail -f /tmp/image-watch-error.log

临时禁用 kubectl wrapper

# 方式 1: 使用完整路径
/usr/local/bin/kubectl get pods

# 方式 2: 临时取消 alias（当前终端）
unalias kubectl
kubectl get pods
alias kubectl="/Users/brunogao/work/codes/tools/macos/k8s/kubectl-auto-fix"  # 恢复

# 方式 3: 使用 command
command kubectl get pods

⚠️ 故障排查

问题 1: Registry Mirror 不工作

症状： 镜像拉取仍然很慢或失败

排查步骤：

# 1. 检查配置
cat ~/.orbstack/config/docker.json | jq '.["registry-mirrors"]'

# 2. 检查 OrbStack 是否重启
docker info | grep "Registry Mirrors"

# 3. 检查本地 Harbor 是否运行
curl -I http://harbor.omniverseai.net:8080

# 4. 查看 Docker 日志
tail -f ~/Library/Containers/com.orbstack.OrbStack/Data/docker.log

解决方案：

# 重启 OrbStack
orb restart

# 等待启动
sleep 10

# 验证
docker info | grep -A 3 "Registry Mirrors"

问题 2: kubectl wrapper 不生效

症状： kubectl apply 后没有自动修复

排查步骤：

# 1. 检查 alias
type kubectl

# 2. 应该看到：
# kubectl is aliased to `/Users/brunogao/work/codes/tools/macos/k8s/kubectl-auto-fix'

# 3. 如果不是，重新加载配置
source ~/.zshrc

# 4. 检查脚本权限
ls -l /Users/brunogao/work/codes/tools/macos/k8s/kubectl-auto-fix

# 5. 查看日志
tail -50 /tmp/kubectl-auto-fix.log

问题 3: 后台监控不运行

排查步骤：

# 1. 检查服务状态
launchctl list | grep k8s.image-watcher

# 2. 查看错误日志
cat /tmp/image-watch-error.log

# 3. 手动运行脚本测试
/Users/brunogao/work/codes/tools/macos/k8s/watch-and-fix-images.sh

# 4. 检查权限
ls -l /Users/brunogao/work/codes/tools/macos/k8s/watch-and-fix-images.sh

解决方案：

# 卸载并重新加载
launchctl unload ~/Library/LaunchAgents/com.k8s.image-watcher.plist
launchctl load ~/Library/LaunchAgents/com.k8s.image-watcher.plist

# 查看日志确认启动
tail -f /tmp/image-watch.log

问题 4: cache-image.sh 失败

症状： 手动或自动调用 cache-image.sh 失败

排查步骤：

# 1. 检查 EU Harbor 连接
curl -I https://harbor.eu.lingjingwanxiang.cn

# 2. 检查本地 Harbor
curl -I http://harbor.omniverseai.net:8080

# 3. 测试登录
docker login harbor.omniverseai.net:8080
# 用户名: admin
# 密码: admin123

# 4. 手动测试拉取
docker pull harbor.eu.lingjingwanxiang.cn/dockerhub/library/nginx:alpine

🎯 使用场景

场景 1: 部署新应用到 K8s

# 正常部署（kubectl wrapper 自动处理）
kubectl apply -f myapp-deployment.yaml

# 如果有 ImagePull 错误，wrapper 会：
# 1. 检测到错误
# 2. 自动调用 cache-image.sh
# 3. 从 EU Harbor 拉取并缓存
# 4. 更新 Deployment
# 5. 触发 Pod 重启

场景 2: 大量镜像预热

# 创建镜像列表
cat > /tmp/preload-images.txt << 'EOF'
nginx:alpine
redis:7-alpine
mysql:8.0
postgres:15-alpine
grafana/grafana:latest
prom/prometheus:latest
EOF

# 批量缓存
./cache-image.sh -f /tmp/preload-images.txt

场景 3: CI/CD 集成

在 Gitea Actions 或其他 CI 中：

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: 预缓存镜像
        run: |
          /Users/brunogao/work/codes/tools/macos/k8s/cache-image.sh \
            myapp:${{ github.sha }}

      - name: 部署到 K8s
        run: |
          kubectl apply -f k8s/deployment.yaml
          # kubectl wrapper 会自动处理任何 ImagePull 错误

场景 4: Claude Code 自动执行

当 Claude Code 遇到 ImagePull 错误时，会自动：

识别错误（通过 CLAUDE.md 配置）
执行：./cache-image.sh --update-deployment namespace/deployment
等待修复完成
继续后续操作

📚 相关文档

AUTO-IMAGE-CACHE-SOLUTIONS.md - 详细方案比较
CACHE-IMAGE-GUIDE.md - cache-image.sh 使用指南
QUICK-FIX-IMAGEPULL.md - 快速修复参考
CLAUDE.md - Claude Code 配置

🚀 立即开始

推荐执行：

cd /Users/brunogao/work/codes/tools/macos/k8s
./deploy-auto-fix.sh

快速验证：

# 1. 重启 OrbStack
orb restart

# 2. 刷新终端
source ~/.zshrc

# 3. 测试镜像拉取
docker pull nginx:alpine

# 4. 测试 kubectl
kubectl get pods --all-namespaces

生成时间: 2025-12-24 18:09 脚本版本: v1.0 环境: macOS + OrbStack + Harbor

17 KiB Raw Permalink Blame History

自动镜像修复系统 - 部署指南

📊 当前环境状态

✅ 已就绪

⚠️ 待配置

🚀 快速部署（推荐）

一键部署所有组件

部署过程预览

📋 分步部署（手动控制）

Step 1: 配置 Registry Mirror

Step 2: 安装 kubectl wrapper

Step 3: 配置后台监控（可选）

🧪 测试验证

测试 1: Registry Mirror 工作验证

测试 2: kubectl wrapper 自动修复

测试 3: 后台监控验证

🎯 部署后的系统架构

📝 配置文件说明

~/.orbstack/config/docker.json（更新后）

~/.zshrc（新增内容）

🔧 常用操作

查看系统状态

手动修复镜像问题

管理后台监控

临时禁用 kubectl wrapper

⚠️ 故障排查

问题 1: Registry Mirror 不工作

问题 2: kubectl wrapper 不生效

问题 3: 后台监控不运行

问题 4: cache-image.sh 失败

🎯 使用场景

场景 1: 部署新应用到 K8s

场景 2: 大量镜像预热

场景 3: CI/CD 集成

场景 4: Claude Code 自动执行

📚 相关文档

🚀 立即开始

17 KiB

Raw Permalink Blame History