fix action for k8s deploy

2025-06-07 17:50:51 +08:00 · 2025-06-07 17:50:51 +08:00 · e1c681bfe9
commit e1c681bfe9
parent 5c7293be88
3 changed files with 505 additions and 9 deletions
--- a/.gitea/workflows/build-ubuntu.yaml
+++ b/.gitea/workflows/build-ubuntu.yaml
@ -166,8 +166,7 @@ jobs:
          docker tag nginx-local:latest ${{ secrets.HARBOR_REGISTRY }}/test/nginx:latest
          
          echo "推送镜像..."
-          docker push ${{ secrets.HARBOR_REGISTRY }}/test/nginx:${{ github.sha }}
-          docker push ${{ secrets.HARBOR_REGISTRY }}/test/nginx:latest
+          docker push ${{ secrets.HARBOR_REGISTRY }}/test/nginx:${{ github.sha }}          docker push ${{ secrets.HARBOR_REGISTRY }}/test/nginx:latest
          
          echo "清理本地镜像..."
          docker rmi nginx-local:latest || true
@ -181,18 +180,51 @@ jobs:
          
          # 检查是否配置了 Kubernetes 部署
          if [[ -n "${{ secrets.KUBE_CONFIG }}" ]]; then
-            # 安装 kubectl
-            curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
-            chmod +x kubectl
-            sudo mv kubectl /usr/local/bin/
+            # 检查并安装 kubectl (如果需要)
+            if ! command -v kubectl &> /dev/null; then
+              echo "kubectl 未安装，开始安装最新版本..."
+              KUBECTL_VERSION=$(curl -L -s https://dl.k8s.io/release/stable.txt)
+              echo "下载 kubectl 版本: $KUBECTL_VERSION"
+              
+              if curl -LO "https://dl.k8s.io/release/${KUBECTL_VERSION}/bin/linux/amd64/kubectl"; then
+                chmod +x kubectl
+                sudo mv kubectl /usr/local/bin/
+                echo "kubectl 安装完成，版本: $(kubectl version --client --short 2>/dev/null || kubectl version --client)"
+              else
+                echo "kubectl 下载失败，尝试使用包管理器安装..."
+                sudo apt-get update && sudo apt-get install -y kubectl || (echo "kubectl 安装失败" && exit 1)
+              fi
+            else
+              echo "kubectl 已存在，当前版本: $(kubectl version --client --short 2>/dev/null || kubectl version --client)"
+              # 可选：检查版本是否过旧，如果需要可以升级
+              # CURRENT_VERSION=$(kubectl version --client -o json 2>/dev/null | jq -r '.clientVersion.gitVersion' || echo "unknown")
+              # echo "当前 kubectl 版本: $CURRENT_VERSION"
+            fi
            
            # 配置 kubectl
+            echo "配置 kubectl 连接信息..."
            mkdir -p ~/.kube
-            echo "${{ secrets.KUBE_CONFIG }}" | base64 -d > ~/.kube/config
-            chmod 600 ~/.kube/config
+            if echo "${{ secrets.KUBE_CONFIG }}" | base64 -d > ~/.kube/config 2>/dev/null; then
+              chmod 600 ~/.kube/config
+              echo "kubectl 配置文件创建成功"
+            else
+              echo "ERROR: kubectl 配置文件创建失败，请检查 KUBE_CONFIG secret 是否正确"
+              echo "KUBE_CONFIG 应该是 base64 编码的 kubeconfig 文件内容"
+              exit 1
+            fi
            
            # 验证 kubectl 连接
-            kubectl cluster-info --short || (echo "Kubernetes 连接失败" && exit 1)
+            echo "验证 Kubernetes 集群连接..."
+            if kubectl cluster-info --short; then
+              echo "Kubernetes 集群连接成功"
+            else
+              echo "ERROR: 无法连接到 Kubernetes 集群"
+              echo "请检查:"
+              echo "  1. KUBE_CONFIG secret 是否正确"
+              echo "  2. 集群是否可访问"
+              echo "  3. 证书是否有效"
+              exit 1
+            fi
            
            # 设置环境变量
            export HARBOR_REGISTRY="${{ secrets.HARBOR_REGISTRY }}"
--- a/.github/CICD-SETUP.md
+++ b/.github/CICD-SETUP.md
@ -0,0 +1,233 @@
+# GitHub Actions CI/CD 配置说明
+
+本文档详细说明如何配置 GitHub Actions 的 Secrets，以实现自动构建、推送镜像到 Harbor 仓库，并部署到 Kubernetes 集群。
+
+## 📋 必需的 GitHub Secrets
+
+在 GitHub 仓库设置中添加以下 Secrets（Settings → Secrets and variables → Actions）：
+
+### Harbor 仓库配置
+
+| Secret 名称 | 描述 | 示例值 |
+|------------|------|--------|
+| `HARBOR_REGISTRY` | Harbor 仓库地址 | `harbor.example.com` |
+| `HARBOR_USERNAME` | Harbor 用户名 | `admin` |
+| `HARBOR_PASSWORD` | Harbor 密码 | `your-password` |
+
+### Kubernetes 配置（可选）
+
+| Secret 名称 | 描述 | 是否必需 |
+|------------|------|----------|
+| `KUBE_CONFIG` | base64 编码的 kubeconfig 文件 | 仅部署到 K8s 时需要 |
+| `K8S_NAMESPACE` | Kubernetes 命名空间 | 可选，默认为 `default` |
+
+## 🔧 配置步骤
+
+### 1. 配置 Harbor 仓库访问
+
+1. **获取 Harbor 仓库信息**
+   ```bash
+   # Harbor 仓库地址格式
+   https://harbor.example.com
+   # 或
+   harbor.example.com
+   ```
+
+2. **在 GitHub 中添加 Secrets**
+   - 进入仓库 Settings → Secrets and variables → Actions
+   - 点击 "New repository secret"
+   - 添加以下三个 secrets：
+     - `HARBOR_REGISTRY`: Harbor 仓库地址
+     - `HARBOR_USERNAME`: Harbor 用户名
+     - `HARBOR_PASSWORD`: Harbor 密码
+
+### 2. 配置 Kubernetes 部署（可选）
+
+如果需要自动部署到 Kubernetes 集群，需要配置以下 secrets：
+
+#### 生成 KUBE_CONFIG
+
+**方法一：从现有 kubeconfig 文件**
+```bash
+# 1. 找到您的 kubeconfig 文件
+ls ~/.kube/config
+
+# 2. 对内容进行 base64 编码
+cat ~/.kube/config | base64 -w 0
+
+# 3. 将输出的 base64 字符串作为 KUBE_CONFIG secret 的值
+```
+
+**方法二：从 Kubernetes 集群生成**
+```bash
+# 1. 创建服务账户
+kubectl create serviceaccount github-actions -n default
+
+# 2. 创建 ClusterRoleBinding（根据需要调整权限）
+kubectl create clusterrolebinding github-actions \
+  --clusterrole=cluster-admin \
+  --serviceaccount=default:github-actions
+
+# 3. 获取服务账户的 token（Kubernetes 1.24+）
+kubectl create token github-actions --duration=8760h > token.txt
+
+# 4. 生成 kubeconfig 文件
+CLUSTER_NAME=$(kubectl config current-context)
+SERVER=$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}')
+CA_DATA=$(kubectl config view --raw --minify --flatten -o jsonpath='{.clusters[0].cluster.certificate-authority-data}')
+TOKEN=$(cat token.txt)
+
+cat > kubeconfig-github-actions.yaml << EOF
+apiVersion: v1
+kind: Config
+clusters:
+- cluster:
+    certificate-authority-data: $CA_DATA
+    server: $SERVER
+  name: $CLUSTER_NAME
+contexts:
+- context:
+    cluster: $CLUSTER_NAME
+    user: github-actions
+  name: github-actions
+current-context: github-actions
+users:
+- name: github-actions
+  user:
+    token: $TOKEN
+EOF
+
+# 5. 编码为 base64
+cat kubeconfig-github-actions.yaml | base64 -w 0
+
+# 6. 清理临时文件
+rm token.txt kubeconfig-github-actions.yaml
+```
+
+#### 添加到 GitHub Secrets
+
+1. **KUBE_CONFIG**
+   - 将上述生成的 base64 编码字符串添加为 secret
+   - 注意：这应该是一个很长的字符串，没有换行符
+
+2. **K8S_NAMESPACE**（可选）
+   - 指定部署的命名空间，如 `production`、`staging`
+   - 如果不设置，默认使用 `default` 命名空间
+
+## 🚀 CI/CD 流程说明
+
+### 触发条件
+
+CI/CD 管道在以下情况下触发：
+- 推送代码到任何分支
+- 创建 Pull Request 到 main 分支
+
+### 自动部署条件
+
+Kubernetes 自动部署仅在以下情况下执行：
+- 推送到 `main` 分支
+- 且配置了 `KUBE_CONFIG` secret
+
+### 流程步骤
+
+1. **代码检出和环境准备**
+2. **编译 NGINX**
+3. **构建 Docker 镜像**
+4. **推送镜像到 Harbor**
+   - 标签：`${{ github.sha }}` 和 `latest`
+5. **部署到 Kubernetes**（条件触发）
+   - 检查 kubectl 是否已安装
+   - 配置 kubectl 连接
+   - 运行部署脚本
+
+## 🔍 故障排除
+
+### 常见问题
+
+1. **Harbor 登录失败**
+   ```
+   Error: unauthorized: unauthorized to access repository
+   ```
+   - 检查 `HARBOR_USERNAME` 和 `HARBOR_PASSWORD` 是否正确
+   - 确认用户有推送权限到 `test/nginx` 项目
+
+2. **Kubernetes 连接失败**
+   ```
+   ERROR: 无法连接到 Kubernetes 集群
+   ```
+   - 检查 `KUBE_CONFIG` 是否正确 base64 编码
+   - 验证集群是否可从 GitHub Actions runner 访问
+   - 检查证书是否已过期
+
+3. **kubectl 安装失败**
+   ```
+   kubectl 下载失败
+   ```
+   - 网络问题，会自动尝试使用 apt 安装
+   - 检查 GitHub Actions runner 的网络连接
+
+### 调试技巧
+
+1. **查看详细日志**
+   - GitHub Actions 提供详细的执行日志
+   - 每个步骤都有展开的日志输出
+
+2. **测试 kubeconfig**
+   ```bash
+   # 在本地测试 kubeconfig 是否正确
+   export KUBECONFIG=./kubeconfig-github-actions.yaml
+   kubectl cluster-info
+   kubectl get nodes
+   ```
+
+3. **验证 base64 编码**
+   ```bash
+   # 验证编码是否正确
+   echo "YOUR_BASE64_STRING" | base64 -d > test-config.yaml
+   kubectl --kubeconfig=test-config.yaml cluster-info
+   ```
+
+## 🔐 安全注意事项
+
+1. **最小权限原则**
+   - 为 GitHub Actions 创建专用的服务账户
+   - 只授予必要的权限
+   - 定期轮换访问凭据
+
+2. **Secret 管理**
+   - 不要在代码中硬编码敏感信息
+   - 定期检查和更新 secrets
+   - 使用组织级 secrets 共享通用配置
+
+3. **网络安全**
+   - 确保 Harbor 仓库启用 HTTPS
+   - 使用防火墙限制访问
+   - 启用 Harbor 的镜像安全扫描
+
+## 📚 相关文档
+
+- [GitHub Actions Secrets 文档](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions)
+- [kubectl 安装指南](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/)
+- [Harbor 用户指南](https://goharbor.io/docs/2.0.0/working-with-projects/working-with-images/)
+- [Kubernetes 服务账户](https://kubernetes.io/docs/concepts/security/service-accounts/)
+
+## 💡 最佳实践
+
+1. **环境分离**
+   - 为不同环境（dev、staging、prod）使用不同的 Harbor 项目
+   - 使用不同的 Kubernetes 命名空间
+
+2. **版本管理**
+   - 使用 `${{ github.sha }}` 作为主要标签
+   - 保留 `latest` 标签用于快速部署
+   - 考虑使用语义化版本标签
+
+3. **监控和告警**
+   - 配置 GitHub Actions 失败通知
+   - 监控 Harbor 仓库存储使用情况
+   - 设置 Kubernetes 集群监控
+
+4. **备份和恢复**
+   - 定期备份 kubeconfig 文件
+   - 保存 Harbor 仓库配置
+   - 制定灾难恢复计划
--- a/DEPLOYMENT-SUMMARY.md
+++ b/DEPLOYMENT-SUMMARY.md
@ -0,0 +1,231 @@
+# 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 部署能力！