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