# 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 仓库配置 - 制定灾难恢复计划