私有化CI/CD实战基于Docker Compose的Gitea Actions深度部署指南在当今快速迭代的软件开发环境中拥有一个高效、可控的持续集成与交付CI/CD系统已成为中小型技术团队的刚需。本文将带您深入探索如何利用Gitea Actions这一轻量级自托管解决方案通过Docker Compose快速搭建专属的自动化工作流环境。1. 为什么选择Gitea ActionsGitea Actions作为Gitea生态的原生CI/CD工具与GitHub Actions有着相似的语法和工作机制却提供了完全自主可控的部署方案。相比传统CI工具如Jenkins它具有三大核心优势零成本迁移熟悉GitHub Actions的团队可以几乎无学习成本地切换到Gitea环境资源友好单个2核4G的云服务器即可流畅运行完整套件数据主权所有代码和构建过程都保留在自有基础设施中提示对于需要遵守严格数据合规要求的教育机构、金融机构自托管方案能有效避免第三方云服务的合规风险。2. 环境准备与Docker Compose部署2.1 基础环境配置确保您的宿主机满足以下要求组件最低要求推荐配置Docker20.10.0最新稳定版Docker Composev2.0.0v2.20.0系统资源2核CPU/2GB内存4核CPU/8GB内存# 验证Docker环境 docker --version docker-compose --version2.2 编写docker-compose.yml以下是最小化生产级配置示例包含Gitea服务与Runner的联动配置version: 3 services: gitea: image: gitea/gitea:1.20.4 container_name: gitea restart: unless-stopped ports: - 3000:3000 - 2222:22 volumes: - gitea_data:/data environment: - GITEA__server__PROTOCOLhttp - GITEA__server__DOMAINyour-domain.com - GITEA__actions__ENABLEDtrue runner: image: gitea/act_runner:nightly depends_on: - gitea volumes: - /var/run/docker.sock:/var/run/docker.sock - runner_data:/data environment: - GITEA_INSTANCE_URLhttp://gitea:3000 - GITEA_RUNNER_REGISTRATION_TOKENINITIAL_TOKEN - GITEA_RUNNER_LABELSself-hosted:docker volumes: gitea_data: runner_data:关键配置说明GITEA__actions__ENABLEDtrue显式启用Actions功能Runner使用nightly版本以获得最新功能支持通过Docker socket挂载实现DinD(Docker in Docker)模式3. 初始化配置与Runner注册3.1 首次启动与管理员设置docker-compose up -d访问http://your-server-ip:3000完成初始配置创建管理员账户进入站点管理→Actions→Runners生成新的Registration Token3.2 更新Runner配置修改docker-compose.yml中的环境变量environment: - GITEA_RUNNER_REGISTRATION_TOKEN新生成的Token然后重新部署docker-compose down docker-compose up -d验证Runner状态应显示为Online标签包含self-hosted:docker。4. 实战工作流开发4.1 基础工作流示例在仓库中创建.gitea/workflows/build.ymlname: CI Pipeline on: [push, pull_request] jobs: build: runs-on: [self-hosted:docker] steps: - uses: actions/checkoutv4 - name: Set up Node.js uses: actions/setup-nodev3 with: node-version: 18 - name: Install dependencies run: npm ci - name: Run tests run: npm test4.2 高级Docker构建示例name: Docker Build Push on: push: tags: - v*.*.* jobs: docker: runs-on: [self-hosted:docker] steps: - uses: actions/checkoutv4 - name: Login to Registry uses: docker/login-actionv2 with: registry: your-registry.com username: ${{ secrets.REGISTRY_USER }} password: ${{ secrets.REGISTRY_PASSWORD }} - name: Build and Push uses: docker/build-push-actionv4 with: context: . push: true tags: | your-registry.com/your-image:latest your-registry.com/your-image:${{ github.ref_name }}5. 生产环境优化策略5.1 资源隔离方案建议为不同团队/项目配置独立的Runner# docker-compose.yml片段 services: frontend-runner: image: gitea/act_runner:nightly environment: - GITEA_RUNNER_LABELSteam:frontend # 其他配置... backend-runner: image: gitea/act_runner:nightly environment: - GITEA_RUNNER_LABELSteam:backend对应工作流中指定jobs: build-frontend: runs-on: [self-hosted:team:frontend]5.2 缓存加速配置steps: - name: Cache Node modules uses: actions/cachev3 with: path: | ~/.npm node_modules key: ${{ runner.os }}-node-${{ hashFiles(**/package-lock.json) }}6. 异常排查指南6.1 常见问题与解决方案问题现象可能原因解决方案Runner注册失败Token过期/网络不通重新生成Token检查网络连通性工作流卡在Queued状态无匹配标签的可用Runner检查Runner标签配置Docker构建权限不足未正确挂载docker.sock验证volume挂载配置工作流执行超时默认超时时间过短在配置文件中调整超时设置6.2 日志收集方法查看Runner详细日志docker logs -f gitea-runner-container-idGitea服务日志定位docker exec gitea cat /data/gitea/log/gitea.log7. 安全加固建议网络隔离将Runner部署在独立Docker网络中访问控制配置防火墙规则限制3000/2222端口访问定期备份关键数据卷的备份策略示例# 备份Gitea数据 docker run --rm -v gitea_data:/volume -v $(pwd):/backup alpine \ tar czf /backup/gitea_backup_$(date %Y%m%d).tar.gz -C /volume ./证书配置通过Lets Encrypt添加HTTPS支持environment: - GITEA__server__PROTOCOLhttps - GITEA__server__CERT_FILE/data/ssl/fullchain.pem - GITEA__server__KEY_FILE/data/ssl/privkey.pem
Gitea Actions 实战：如何用 Docker Compose 一键部署私有化 CI/CD 环境（含常见报错解决）
发布时间：2026/6/15 4:08:22
私有化CI/CD实战基于Docker Compose的Gitea Actions深度部署指南在当今快速迭代的软件开发环境中拥有一个高效、可控的持续集成与交付CI/CD系统已成为中小型技术团队的刚需。本文将带您深入探索如何利用Gitea Actions这一轻量级自托管解决方案通过Docker Compose快速搭建专属的自动化工作流环境。1. 为什么选择Gitea ActionsGitea Actions作为Gitea生态的原生CI/CD工具与GitHub Actions有着相似的语法和工作机制却提供了完全自主可控的部署方案。相比传统CI工具如Jenkins它具有三大核心优势零成本迁移熟悉GitHub Actions的团队可以几乎无学习成本地切换到Gitea环境资源友好单个2核4G的云服务器即可流畅运行完整套件数据主权所有代码和构建过程都保留在自有基础设施中提示对于需要遵守严格数据合规要求的教育机构、金融机构自托管方案能有效避免第三方云服务的合规风险。2. 环境准备与Docker Compose部署2.1 基础环境配置确保您的宿主机满足以下要求组件最低要求推荐配置Docker20.10.0最新稳定版Docker Composev2.0.0v2.20.0系统资源2核CPU/2GB内存4核CPU/8GB内存# 验证Docker环境 docker --version docker-compose --version2.2 编写docker-compose.yml以下是最小化生产级配置示例包含Gitea服务与Runner的联动配置version: 3 services: gitea: image: gitea/gitea:1.20.4 container_name: gitea restart: unless-stopped ports: - 3000:3000 - 2222:22 volumes: - gitea_data:/data environment: - GITEA__server__PROTOCOLhttp - GITEA__server__DOMAINyour-domain.com - GITEA__actions__ENABLEDtrue runner: image: gitea/act_runner:nightly depends_on: - gitea volumes: - /var/run/docker.sock:/var/run/docker.sock - runner_data:/data environment: - GITEA_INSTANCE_URLhttp://gitea:3000 - GITEA_RUNNER_REGISTRATION_TOKENINITIAL_TOKEN - GITEA_RUNNER_LABELSself-hosted:docker volumes: gitea_data: runner_data:关键配置说明GITEA__actions__ENABLEDtrue显式启用Actions功能Runner使用nightly版本以获得最新功能支持通过Docker socket挂载实现DinD(Docker in Docker)模式3. 初始化配置与Runner注册3.1 首次启动与管理员设置docker-compose up -d访问http://your-server-ip:3000完成初始配置创建管理员账户进入站点管理→Actions→Runners生成新的Registration Token3.2 更新Runner配置修改docker-compose.yml中的环境变量environment: - GITEA_RUNNER_REGISTRATION_TOKEN新生成的Token然后重新部署docker-compose down docker-compose up -d验证Runner状态应显示为Online标签包含self-hosted:docker。4. 实战工作流开发4.1 基础工作流示例在仓库中创建.gitea/workflows/build.ymlname: CI Pipeline on: [push, pull_request] jobs: build: runs-on: [self-hosted:docker] steps: - uses: actions/checkoutv4 - name: Set up Node.js uses: actions/setup-nodev3 with: node-version: 18 - name: Install dependencies run: npm ci - name: Run tests run: npm test4.2 高级Docker构建示例name: Docker Build Push on: push: tags: - v*.*.* jobs: docker: runs-on: [self-hosted:docker] steps: - uses: actions/checkoutv4 - name: Login to Registry uses: docker/login-actionv2 with: registry: your-registry.com username: ${{ secrets.REGISTRY_USER }} password: ${{ secrets.REGISTRY_PASSWORD }} - name: Build and Push uses: docker/build-push-actionv4 with: context: . push: true tags: | your-registry.com/your-image:latest your-registry.com/your-image:${{ github.ref_name }}5. 生产环境优化策略5.1 资源隔离方案建议为不同团队/项目配置独立的Runner# docker-compose.yml片段 services: frontend-runner: image: gitea/act_runner:nightly environment: - GITEA_RUNNER_LABELSteam:frontend # 其他配置... backend-runner: image: gitea/act_runner:nightly environment: - GITEA_RUNNER_LABELSteam:backend对应工作流中指定jobs: build-frontend: runs-on: [self-hosted:team:frontend]5.2 缓存加速配置steps: - name: Cache Node modules uses: actions/cachev3 with: path: | ~/.npm node_modules key: ${{ runner.os }}-node-${{ hashFiles(**/package-lock.json) }}6. 异常排查指南6.1 常见问题与解决方案问题现象可能原因解决方案Runner注册失败Token过期/网络不通重新生成Token检查网络连通性工作流卡在Queued状态无匹配标签的可用Runner检查Runner标签配置Docker构建权限不足未正确挂载docker.sock验证volume挂载配置工作流执行超时默认超时时间过短在配置文件中调整超时设置6.2 日志收集方法查看Runner详细日志docker logs -f gitea-runner-container-idGitea服务日志定位docker exec gitea cat /data/gitea/log/gitea.log7. 安全加固建议网络隔离将Runner部署在独立Docker网络中访问控制配置防火墙规则限制3000/2222端口访问定期备份关键数据卷的备份策略示例# 备份Gitea数据 docker run --rm -v gitea_data:/volume -v $(pwd):/backup alpine \ tar czf /backup/gitea_backup_$(date %Y%m%d).tar.gz -C /volume ./证书配置通过Lets Encrypt添加HTTPS支持environment: - GITEA__server__PROTOCOLhttps - GITEA__server__CERT_FILE/data/ssl/fullchain.pem - GITEA__server__KEY_FILE/data/ssl/privkey.pem
