# Kubernetes 集群快速修复指南（更新版）

**更新时间**: 2026-01-04（已修正重复部署问题）
**集群版本**: Kubernetes v1.33.5 (OrbStack)

---

## 🚨 紧急问题快速修复

### 问题 1: infra namespace 中的 loki 和 tempo 无法启动 ❌ 错误理解

**实际情况**:
- ✅ **logging namespace**: loki-0 正常运行（17天前部署）
- ✅ **tracing namespace**: tempo-0 正常运行（17天前部署）
- ❌ **infra namespace**: loki-0, tempo-0 重复部署（17小时前创建，ImagePullBackOff）

**正确做法**: 删除重复部署，而不是修复镜像拉取

**1分钟快速修复**:
```bash
cd /Users/brunogao/work/codes/tools/macos/k8s
./fix-cluster-issues-v2.sh delete-duplicates
```

**手动修复**:
```bash
kubectl delete statefulset -n infra loki tempo
kubectl delete service -n infra loki tempo

# 验证正确的实例运行正常
kubectl get pods -n logging -l app=loki
kubectl get pods -n tracing -l app.kubernetes.io/name=tempo
```

---

### 问题 2: dev 命名空间 Pod 无法启动

**症状**: `harbor.omniverseai.net/ljwx/xxx:dev` 镜像不存在

**解决方案 A**: 检查 CI/CD 是否构建了镜像
```bash
# 检查 Harbor 仓库
curl -u admin:admin123 http://192.168.1.83:8080/api/v2.0/projects/ljwx/repositories

# 检查 Gitea Actions CI/CD 日志
# 重新触发构建流程
```

**解决方案 B**: 暂时删除失败的 Deployment
```bash
./fix-cluster-issues-v2.sh clean-dev

# 或手动删除
kubectl delete deployment -n dev backend frontend quality-dashboard
```

---

### 问题 3: 提升集群性能和可靠性（可选）

**症状**: 部分 Pod 依赖外部 Docker Hub，可能拉取超时

**10分钟批量缓存**:
```bash
cd /Users/brunogao/work/codes/tools/macos/k8s
./fix-cluster-issues-v2.sh cache-p1
```

**一键全自动修复** (推荐):
```bash
./fix-cluster-issues-v2.sh auto
```

这将自动执行：
1. 删除重复的 loki/tempo 部署
2. 批量缓存 P1 高优先级镜像
3. 清理 dev 命名空间失败的 Deployment

---

## 📋 诊断工具

### 查看所有失败的 Pod
```bash
./fix-cluster-issues-v2.sh diagnose
```

### 查看镜像拉取错误
```bash
./fix-cluster-issues-v2.sh check-errors
```

### 手动检查命令
```bash
# 查看所有非正常 Pod
kubectl get pods --all-namespaces --field-selector=status.phase!=Running,status.phase!=Succeeded

# 查看镜像拉取事件
kubectl get events --all-namespaces --field-selector type=Warning | grep -i "image\|pull"

# 查看 Pod 详细状态
kubectl describe pod -n <namespace> <pod-name>

# 检查重复部署
kubectl get statefulset -n infra | grep -E "loki|tempo"
kubectl get statefulset -n logging | grep loki
kubectl get statefulset -n tracing | grep tempo
```

---

## 🛠️ 交互式修复工具（推荐）

启动交互式菜单:
```bash
cd /Users/brunogao/work/codes/tools/macos/k8s
./fix-cluster-issues-v2.sh
```

菜单选项:
1. 🧹 删除重复部署: 清理 infra namespace 中的 loki/tempo（推荐）
2. 📦 批量缓存 P1 镜像（可选，提升性能）
3. 🗑️ 清理 dev 命名空间
4. 📊 诊断失败的 Pod
5. 🔍 检查镜像拉取错误
6. ⚡ 全自动修复（推荐）
7. 📈 部署 Metrics Server

---

## 📁 生成的文件说明

| 文件 | 用途 |
|------|------|
| `K8S-CLUSTER-ANALYSIS-2026-01-04-UPDATED.md` | 更新后的完整集群分析（已修正） |
| `images-to-cache-priority-updated.txt` | 更新后的镜像缓存优先级列表 |
| `images-to-cache-p1.txt` | P1 高优先级镜像列表（批量缓存用） |
| `fix-cluster-issues-v2.sh` | 新版一键修复脚本（已修正）⭐ |
| `QUICK-FIX-GUIDE-UPDATED.md` | 本文档（更新版快速指南） |

**旧文件**（已过时）:
- ~~`fix-cluster-issues.sh`~~ - 请使用 v2 版本
- ~~`QUICK-FIX-GUIDE.md`~~ - 请查看 UPDATED 版本

---

## ⚡ 快捷命令清单

```bash
# 进入工作目录
cd /Users/brunogao/work/codes/tools/macos/k8s

# ===【最优先】删除重复部署 ===
kubectl delete statefulset -n infra loki tempo
kubectl delete service -n infra loki tempo

# 验证正确的实例
kubectl get pods -n logging -l app=loki
kubectl get pods -n tracing -l app.kubernetes.io/name=tempo

# ===【推荐】使用新版修复脚本 ===
./fix-cluster-issues-v2.sh auto

# === 镜像缓存（可选）===
# 缓存单个镜像
./cache-image.sh <image:tag>

# 批量缓存镜像
./cache-image.sh -f images-to-cache-p1.txt

# === Pod 管理 ===
# 查看所有 Pod 状态
kubectl get pods --all-namespaces -o wide

# 重启 Pod
kubectl delete pod -n <namespace> <pod-name>

# 查看 Pod 日志
kubectl logs -n <namespace> <pod-name> --tail=100

# === 诊断 ===
# 查看所有失败的 Pod
./fix-cluster-issues-v2.sh diagnose

# 查看镜像拉取错误
./fix-cluster-issues-v2.sh check-errors
```

---

## 📊 当前集群问题统计（更新版）

### 重复部署 (P0 - 最优先处理)
- `infra/statefulset/loki`: 重复部署，应删除 ❌
- `infra/statefulset/tempo`: 重复部署，应删除 ❌
- `logging/loki-0`: 正确的实例 ✅
- `tracing/tempo-0`: 正确的实例 ✅

### 镜像不存在 (P0)
- `dev/backend`: harbor.omniverseai.net/ljwx/backend-template:dev
- `dev/frontend`: harbor.omniverseai.net/ljwx/frontend-dashboard:dev
- `dev/quality-dashboard`: harbor.omniverseai.net/ljwx/quality-dashboard:dev

### 应用崩溃 (P1)
- `external-secrets-system/external-secrets`: 重启 764 次
- `observability/prometheus-adapter`: 重启 100 次
- `ljwx-project/pcc-backend`: 重启 1901 次
- `ljwx-project/pcc-frontend`: 重启 1907 次
- `ljwx-stock/claude-stock-backend`: 重启 2122 次

### 高重启次数 (P2)
- `cert-manager/cert-manager-webhook-dnspod`: 重启 2490 次
- `stock/stock-backend`: 重启 1154, 1194 次
- `infra/ingress-nginx-defaultbackend`: 重启 220 次

---

## 🎯 推荐执行顺序

### 第一步: 删除重复部署（2 分钟）⭐⭐⭐⭐⭐
```bash
./fix-cluster-issues-v2.sh delete-duplicates
```

### 第二步: 处理 dev 命名空间（可选）
```bash
./fix-cluster-issues-v2.sh clean-dev
```

### 第三步: 批量缓存镜像（可选，提升性能）
```bash
./fix-cluster-issues-v2.sh cache-p1
```

### 或者一键全自动修复
```bash
./fix-cluster-issues-v2.sh auto
```

### 第四步: 验证修复效果
```bash
./fix-cluster-issues-v2.sh diagnose
```

### 第五步: 部署 Metrics Server（可选）
```bash
./fix-cluster-issues-v2.sh metrics
```

---

## 💡 关键发现

### 重复部署问题
- **infra namespace**: loki/tempo 是 17 小时前创建的重复部署 ❌
- **logging namespace**: loki-0 是 17 天前部署的正确实例 ✅
- **tracing namespace**: tempo-0 是 17 天前部署的正确实例 ✅

**正确做法**: 删除 infra namespace 中的重复资源

### 镜像拉取策略
- infra/loki 和 infra/tempo 的 ImagePullBackOff 不需要修复
- 应该直接删除这些重复部署
- 正确的实例在 logging 和 tracing namespace 正常运行

---

## 📞 需要帮助?

查看完整分析报告（更新版）:
```bash
cat K8S-CLUSTER-ANALYSIS-2026-01-04-UPDATED.md
```

查看镜像缓存优先级（更新版）:
```bash
cat images-to-cache-priority-updated.txt
```

---

## 🔄 对比旧版修复方案

### ❌ 旧版（错误理解）
1. 缓存 grafana/loki:latest 和 grafana/tempo:latest 镜像
2. 重启 infra/loki-0 和 infra/tempo-0 Pod
3. 期望它们正常启动

### ✅ 新版（正确做法）
1. 删除 infra namespace 中的重复 StatefulSet
2. 删除 infra namespace 中的重复 Service
3. 验证 logging 和 tracing namespace 中的正确实例运行正常

---

**祝您修复顺利！** 🎉

**重要提示**: 请使用 `fix-cluster-issues-v2.sh` 而不是旧版脚本。