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 版本

🏗️ 基本使用

最简配置

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

完整配置

- 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 环境

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

仅 kubectl 环境

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

📝 完整工作流示例

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/

🔧 高级配置

自定义缓存策略

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

多环境部署

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 配置
   • 确认文件哈希是否变化

调试模式

启用详细日志输出：

- 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