xgj/setup-env/README.md

# Setup Build Environment Action

这是一个用于配置构建和部署环境的 GitHub Action，专门为 CI/CD 流水线设计。它能够自动安装和配置 Docker、kubectl 以及其他必要的构建工具。

## 🚀 特性

- ✅ 自动配置 Git 用户信息
- 🐳 安装 Docker CLI 和相关插件
- ☸️ 安装和配置 kubectl
- 🗄️ 智能缓存机制，提高构建速度
- 🌏 支持阿里云镜像源，提升国内访问速度
- 🔐 自动登录私有 Docker 仓库
- 📋 详细的日志输出和错误处理
- ⚡ 灵活的配置选项

## 📋 输入参数

| 参数名              | 描述                           | 必填 | 默认值                      |
| ------------------- | ------------------------------ | ---- | --------------------------- |
| `docker-registry`   | Docker 私有仓库地址            | ❌   | `docker-registry.bjxgj.com` |
| `docker-username`   | Docker 仓库用户名              | ❌   | `ci-action`                 |
| `docker-password`   | Docker 仓库密码                | ✅   | -                           |
| `kube-config`       | Base64 编码的 kubectl 配置文件 | ❌   | `''`                        |
| `cache-key`         | 缓存键值                       | ❌   | `setup-env`                 |
| `use-aliyun-mirror` | 是否使用阿里云镜像源           | ❌   | `true`                      |
| `git-user-name`     | Git 用户名                     | ❌   | `GiteaActions`              |
| `git-user-email`    | Git 用户邮箱                   | ❌   | `actions@gitea.com`         |
| `skip-kubectl`      | 跳过 kubectl 安装和配置        | ❌   | `false`                     |
| `skip-docker-login` | 跳过 Docker 登录               | ❌   | `false`                     |

## 📤 输出参数

| 参数名            | 描述                |
| ----------------- | ------------------- |
| `cache-hit`       | 缓存是否命中        |
| `kubectl-version` | 安装的 kubectl 版本 |
| `docker-version`  | 安装的 Docker 版本  |

## 🏗️ 基本使用

### 最简配置

```yaml
- name: 配置构建环境
  uses: actions/xgj/setup-env@v1
  with:
    docker-password: ${{ secrets.DOCKER_PASSWORD }}
```

### 完整配置

```yaml
- name: 配置构建环境
  uses: actions/xgj/setup-env@v1
  with:
    docker-registry: "your-registry.com"
    docker-username: "your-username"
    docker-password: ${{ secrets.DOCKER_PASSWORD }}
    kube-config: ${{ secrets.KUBE_CONFIG }}
    cache-key: "my-project-env"
    use-aliyun-mirror: "true"
    git-user-name: "CI Bot"
    git-user-email: "ci@yourcompany.com"
```

### 仅 Docker 环境

```yaml
- name: 配置 Docker 环境
  uses: actions/xgj/setup-env@v1
  with:
    docker-password: ${{ secrets.DOCKER_PASSWORD }}
    skip-kubectl: "true"
```

### 仅 kubectl 环境

```yaml
- name: 配置 Kubernetes 环境
  uses: actions/xgj/setup-env@v1
  with:
    kube-config: ${{ secrets.KUBE_CONFIG }}
    skip-docker-login: "true"
```

## 📝 完整工作流示例

```yaml
name: Build and Deploy
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: 检出代码
        uses: actions/checkout@v4

      - name: 配置构建环境
        id: setup
        uses: actions/xgj/setup-env@v1
        with:
          docker-password: ${{ secrets.DOCKER_PASSWORD }}
          kube-config: ${{ secrets.KUBE_CONFIG }}
          cache-key: "build-${{ github.sha }}"

      - name: 检查环境信息
        run: |
          echo "缓存命中: ${{ steps.setup.outputs.cache-hit }}"
          echo "Docker 版本: ${{ steps.setup.outputs.docker-version }}"
          echo "kubectl 版本: ${{ steps.setup.outputs.kubectl-version }}"

      - name: 构建 Docker 镜像
        run: |
          docker build -t my-app:latest .

      - name: 部署到 Kubernetes
        run: |
          kubectl apply -f k8s/
```

## 🔧 高级配置

### 自定义缓存策略

```yaml
- name: 配置环境（自定义缓存）
  uses: actions/xgj/setup-env@v1
  with:
    docker-password: ${{ secrets.DOCKER_PASSWORD }}
    cache-key: 'env-${{ matrix.os }}-${{ hashFiles("Dockerfile") }}'
```

### 多环境部署

```yaml
strategy:
  matrix:
    environment: [dev, staging, prod]
steps:
  - name: 配置环境
    uses: actions/xgj/setup-env@v1
    with:
      docker-password: ${{ secrets.DOCKER_PASSWORD }}
      kube-config: ${{ secrets[format('KUBE_CONFIG_{0}', matrix.environment)] }}
      cache-key: "deploy-${{ matrix.environment }}"
```

## 🛠️ 故障排除

### 常见问题

1. **Docker 登录失败**

   - 检查 `docker-password` 是否正确设置
   - 确认 Docker 仓库地址和用户名

2. **kubectl 连接失败**

   - 验证 `kube-config` 是否正确的 Base64 编码
   - 检查集群网络连接

3. **缓存未命中**
   - 检查 `cache-key` 配置
   - 确认文件哈希是否变化

### 调试模式

启用详细日志输出：

```yaml
- name: 配置环境（调试模式）
  uses: actions/xgj/setup-env@v1
  with:
    docker-password: ${{ secrets.DOCKER_PASSWORD }}
  env:
    ACTIONS_STEP_DEBUG: true
```

## 📋 环境要求

- **操作系统**: Ubuntu 18.04+, Debian 10+
- **权限**: 需要 sudo 权限安装软件包
- **网络**: 需要访问外部软件包仓库

## 🔒 安全考虑

- 使用 GitHub Secrets 存储敏感信息
- 定期更新依赖版本
- 限制 kubectl 权限范围
- 使用最小权限原则

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License