# Kubernetes 自动部署优化总结

## 🎯 主要改进

### 1. kubectl 智能安装检查
**问题**: 原来的配置会无条件下载和安装 kubectl，即使系统已经安装。
**解决方案**: 
- 添加 `command -v kubectl` 检查
- 只在 kubectl 不存在时才安装
- 提供详细的版本信息反馈
- 添加备用安装方法（apt 包管理器）

```bash
# 改进前
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

# 改进后  
if ! command -v kubectl &> /dev/null; then
  echo "kubectl 未安装，开始安装最新版本..."
  # 安装逻辑...
else
  echo "kubectl 已存在，当前版本: $(kubectl version --client)"
fi
```

### 2. 增强错误处理和验证
**改进内容**:
- KUBE_CONFIG base64 解码验证
- Kubernetes 集群连接测试
- 详细的错误提示和排查建议
- 安装失败时的备用方案

### 3. 完整的部署工具链

#### 📁 新增文件结构
```
k8s/
├── deploy.sh              # Linux/macOS 自动部署脚本
├── deploy.bat             # Windows 自动部署脚本  
├── quickstart.sh          # 交互式快速启动
├── nginx-deployment.yaml  # K8s 部署配置
├── Makefile               # 简化操作命令
├── .env.template          # 环境变量模板
└── README.md             # 详细部署文档
```

#### 🛠️ 多种部署方式

1. **快速启动（新手友好）**
   ```bash
   ./quickstart.sh  # 交互式配置向导
   ```

2. **脚本自动化（运维推荐）**
   ```bash
   ./deploy.sh      # 一键部署
   ```

3. **Make 命令（开发推荐）**
   ```bash
   make deploy      # 部署
   make status      # 查看状态
   make logs        # 查看日志
   make scale REPLICAS=5  # 扩缩容
   ```

### 4. CI/CD 集成优化

#### GitHub Actions 改进
- **条件部署**: 仅在 main 分支推送时触发 K8s 部署
- **智能检查**: 验证所需 secrets 是否配置
- **详细日志**: 每个步骤都有清晰的状态输出
- **失败处理**: 提供具体的错误原因和解决建议

#### 环境变量和 Secrets
| Secret | 用途 | 必需性 |
|--------|------|--------|
| `HARBOR_REGISTRY` | Harbor 仓库地址 | 必需 |
| `HARBOR_USERNAME` | Harbor 用户名 | 必需 |
| `HARBOR_PASSWORD` | Harbor 密码 | 必需 |
| `KUBE_CONFIG` | base64 编码的 kubeconfig | K8s 部署时必需 |
| `K8S_NAMESPACE` | K8s 命名空间 | 可选，默认 default |

## 🚀 使用流程

### 首次设置
1. **配置 GitHub Secrets**
   ```bash
   # 必需的 Harbor 配置
   HARBOR_REGISTRY=harbor.example.com
   HARBOR_USERNAME=admin
   HARBOR_PASSWORD=your-password
   
   # K8s 部署配置（可选）
   KUBE_CONFIG=<base64-encoded-kubeconfig>
   K8S_NAMESPACE=production
   ```

2. **生成 KUBE_CONFIG**
   ```bash
   # 方法一：使用现有 kubeconfig
   cat ~/.kube/config | base64 -w 0
   
   # 方法二：创建服务账户
   kubectl create serviceaccount github-actions
   kubectl create clusterrolebinding github-actions \
     --clusterrole=cluster-admin \
     --serviceaccount=default:github-actions
   ```

### 自动化流程
1. **推送代码** → 触发 CI/CD
2. **构建 NGINX** → 编译和测试
3. **构建镜像** → Docker 镜像打包
4. **推送 Harbor** → 上传到私有仓库
5. **部署 K8s** → 自动部署到集群（仅 main 分支）

### 本地管理
```bash
cd k8s

# 快速开始
./quickstart.sh

# 查看状态
make status

# 查看日志
make logs

# 扩缩容
make scale REPLICAS=5

# 更新镜像
make update NGINX_IMAGE_TAG=v2.0.0

# 回滚
make rollback

# 清理
make clean
```

## 🔍 故障排除

### kubectl 相关问题
1. **安装失败**
   - 网络问题：自动尝试 apt 安装
   - 权限问题：检查 sudo 权限

2. **连接失败**
   - 检查 KUBE_CONFIG 格式
   - 验证集群网络访问
   - 确认证书有效性

### Harbor 相关问题
1. **登录失败**
   - 验证用户名密码
   - 检查仓库访问权限

2. **推送失败**
   - 确认项目存在
   - 检查存储配额

### 部署相关问题
1. **镜像拉取失败**
   - 验证 Harbor 凭据 Secret
   - 检查镜像标签是否正确

2. **Pod 启动失败**
   - 查看 Pod 日志：`make logs`
   - 检查资源配额
   - 验证配置文件

## 🔐 安全最佳实践

1. **最小权限原则**
   - 为 CI/CD 创建专用服务账户
   - 只授予必要的 K8s 权限
   - 定期轮换访问凭据

2. **网络安全**
   - Harbor 启用 HTTPS
   - K8s 集群网络策略
   - 防火墙规则配置

3. **镜像安全**
   - 启用 Harbor 漏洞扫描
   - 使用非 root 用户运行
   - 定期更新基础镜像

## 📊 监控和维护

### 日常操作
```bash
# 查看部署状态
make status

# 监控日志
make logs

# 性能监控
kubectl top pods -l app=nginx

# 事件查看
kubectl get events --sort-by=.metadata.creationTimestamp
```

### 维护任务
- 定期更新镜像版本
- 监控资源使用情况
- 备份关键配置
- 更新安全证书

## 🎉 总结

通过这次优化，我们实现了：

1. **智能化**: kubectl 安装检查，避免重复操作
2. **自动化**: 完整的 CI/CD 到 K8s 部署流程
3. **用户友好**: 多种部署方式，适合不同技术水平
4. **健壮性**: 详细的错误处理和恢复机制
5. **可维护性**: 完善的工具链和监控机制

现在您可以：
- 推送代码自动触发构建和部署
- 本地快速管理 K8s 部署
- 灵活选择部署方式
- 轻松排查和解决问题

这套解决方案为 NGINX 项目提供了产品级的 CI/CD 和 K8s 部署能力！
