Woodpecker CI 设计分析｜一个 Go 编写的开源持续集成引擎-每日运维

一、前言

大家好，这里是白泽。随着 Go 语言在云原生领域大放异彩，开发者逐渐将目光转移到了这门语言上，而容器则是云原生时代最核心的载体。

《Woodpecker CI 设计分析》系列文章将分析开源 CI 引擎 Woodpecker 的架构设计，探究 Go 协程是如何支持由 Workflow 定义的大量 Task 的频繁创建和调度。

而 Task 的一切活动都将在容器内进行。因此这个系列的文章也是帮助你开拓 Go 云原生领域编程的一柄利剑。

这是《Woodpecker CI 设计分析》系列的第一篇文章，主要讲解 Woodpecker 的整体架构设计和体验部署使用，后续文章将讲解核心组件源码设计，并从0开始仿写 Woodpecker 核心组件，欢迎追更～

公众号「白泽talk」，白泽目前正在打造一个氛围良好的行业交流群，文章的更新也会提前预告，欢迎加入：622383022。

我也开源了一个 Go 学习仓库：包含 Go 各阶段学习文章、读书笔记、电子书、简历模板等，欢迎 star。

二、CI 配置前瞻

🌟 为了帮助理解，本文在讲述知识点时会对比 Woodpecker 和 GitHub Actions 两种持续集成方案，下文 Pipeline 和 Workflow 两个概念在不同的语境下有时可以当作相同语意，注意不要教条。

🌟 关于 CD 这里不展开论述，因为 CD 与 CI 的不同点是业务关注点不同，关注的是 Pipeline 的不同的阶段，对于一个 CI Engine 来说，其实都是可以完成的，换句话说：CI 的阶段能构建镜像，自然也能发布镜像。

接下来对 GitHub 自带的持续集成（GitHub Actions）和 Woodpecker CI 展开介绍与对比，让你对 CI 有一个大致概念。

2.1 GitHub Actions Workflow for CI

GitHub 本身也是支持持续集成（CI）的，可以通过在项目 .github/workflows/ 路径下创建配置文件定制 Pipeline。

此 GitHub Actions Workflow 在每次推送到 main 分支时触发。它设置一个 Go 环境，构建应用程序，运行测试，最后部署。

# .github/workflows/main.yml
name: CI

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout Code
      uses: actions/checkout@v2

    - name: Set up Go
      uses: actions/setup-go@v2
      with:
        go-version: 1.17
      id: go

    - name: Build
      run: |
        # 在这里执行构建命令
        go build

    - name: Unit Tests
      run: |
        # 在这里执行单元测试命令
        go test ./...

    - name: Deploy
      run: |
        # 在这里执行部署命令
        echo "Deployment steps go here"

2.2 Woodpecker Pipeline for CI

Woodpecker 也是类似的，有一个 Woodpecker 管道配置文件，实现了与 GitHub Actions 相同的 CI 流程。

# .woodpecker.yml
pipelines:
  main:
    trigger:
      branches:
        - main

    steps:
      - name: Checkout Code
        image: docker://alpine
        commands:
          - git clone $CI_REPOSITORY_URL $CI_WORKSPACE

      - name: Set up Go
        image: docker://golang:1.17
        commands:
          - cd $CI_WORKSPACE
          - go build

      - name: Unit Tests
        image: docker://golang:1.17
        commands:
          - cd $CI_WORKSPACE
          - go test ./...

      - name: Deploy
        image: docker://alpine
        commands:
          - echo "Deployment steps go here"

2.3 对比

GitHub Actions 提供有限的免费套餐，但对于较大或需要更多资源的项目，需要购买付费套餐。

🌟 Woodpecker 作为开源项目，通常可以在自己的服务器上自行部署和扩展，用户可以按照 Woodpecker 的文档或项目说明进行设置。

三、术语

看完第二节后，引入了不少 CI/CD 流程中的术语，这里以 Woodpecker 和 GitHub Actions 为例进行对比讲解。

CI: 持续集成是一种软件开发实践，旨在通过将代码集成到共享存储库中，然后自动构建和测试代码，来频繁地检测和解决集成问题。

CD: 是一种软件开发实践，旨在确保软件随时都能够通过自动化流程进行交付，但并不一定立即部署到生产环境。持续交付的目标是使软件交付的过程更加可靠和可重复，以便在需要时能够迅速进行部署。

Pipeline:
- Woodpecker: 一个 Pipeline 是一系列有序的操作步骤，这些步骤按照定义的顺序执行。Pipeline 可以包含一个或多个 Workflow。
- GitHub Actions: 一个 GitHub Actions Workflow 也可以看作是一个 Pipeline。在 GitHub Actions 中，Workflow 是 CI/CD 的基本单元。
Workflow:
- Woodpecker: Workflow 是一组相关的步骤，通常代表了一个完整的 CI/CD 流程。在 Workflow 中，可以定义触发条件、环境变量和步骤顺序。
- GitHub Actions: GitHub Actions Workflow 是 CI/CD 流程的定义，由一系列 jobs 和 steps 组成。Workflow 可以根据事件触发，例如 push、pull request 等。
Step:
- Woodpecker: Step 是 Workflow 或 Pipeline 中的一个单一操作单元。每个 Step 代表了一个执行的任务，例如构建、测试或部署。
- GitHub Actions: GitHub Actions 也使用 Step 的概念，每个 Step 包含一个或多个指令，用于执行特定的操作，例如运行脚本、调用 API 或使用预定义的 action。
语法和配置:
- Woodpecker: Woodpecker 使用 YAML 格式的配置文件定义 Pipeline 和 Workflow。配置文件包含了触发条件、步骤的定义以及其他设置。
- GitHub Actions: GitHub Actions 同样使用 YAML 格式的配置文件，其中定义了 Workflow、Job 和 Step 的结构。GitHub Actions 还支持通过 UI 可视化配置。
触发条件:
- Woodpecker: 您可以定义 Workflow 的触发条件，例如当代码推送到特定分支时触发 Workflow。
- GitHub Actions: 支持多种触发条件，例如 push、pull request、定时触发等。

四、Woodpecker 架构

🌟 在 Woodpecker 中，"Server"、"Forge" 和 "Agent" 是三个关键组件，它们各自承担不同的角色和功能：

Server:
- 含义： Woodpecker Server 是整个 CI/CD 系统的核心组件，负责协调和管理整个构建和部署流程。
- 功能：
  - 处理用户请求和操作，提供 Web 界面和 API。
  - 管理构建和部署的任务队列。
  - 与 Forge 和 Agent 进行通信，协调任务的执行。

Forge:
- 含义： Forge 是与外部代码仓库集成的组件（GitHub、Gitea 等），负责从代码仓库拉取源代码、触发构建，并将构建结果反馈给 Woodpecker Server。
- 功能：
  - 与代码仓库进行集成，监听代码变更并触发构建。
  - 将构建任务推送到 Woodpecker Server 的任务队列。
  - 向 Woodpecker Server 报告构建结果。

Agent:
- 含义： Agent 是运行在构建和部署节点上的代理程序，负责执行具体的构建和部署任务。
- 功能：
  - 从 Woodpecker Server 获取任务并执行。
  - 将任务执行的结果报告给 Woodpecker Server。
  - 与构建环境进行交互，执行构建脚本、部署应用等操作。

这三个组件协同工作，构成了 Woodpecker CI/CD 系统的基础架构。用户通过 Woodpecker Server 进行配置和管理，Forge 负责与代码仓库集成，Agent 负责执行实际的构建和部署任务。这种分工让 Woodpecker 可以支持多种代码仓库和构建环境，实现灵活的 CI/CD 流程。

🤔 思考几个问题：

Agent 是如何从 Server 获取需要执行的 Step 的？（Agent 通过 Grpc 注册到 Server，调用 RPC 方法获取下一个待执行任务）

运行 Step 的环境是什么（每个 Step 都将启动一个 Container）

一个有多个 Step 的 Workflow 在 Server 上如何存放 Step？（Work Queue）

同时有多个项目 Repo 的 Pipeline 同时被 Server 调度运行时，多个 Workflow 分属不同的 Pipeline，而每个 Workflow 又拥有多个 Step，这些 Step 在 Server 的工作队列中是如何被并发调度的？（多协程）

🌟 这些问题会在后续分析 Woodpecker 核心组件设计实现的文章中一一解答，同时我们也会手写自己的 Woodpecker。

五、Woodpecker 部署

官方部署文档中提供了多种部署方式，这里使用 docker-compose 部署。docker 的前置知识这里不再赘述。

🌟 往期收藏过百的 Docker 学习文章

docker | jenkins 实现自动化部署项目，后端躺着把运维的钱挣了！(上)

docker | jenkins 自动化CI/CD，后端躺着把运维的钱挣了！(下)

5.1 配置文件

创建 docker-compose.yml 配置文件。

version: '3'

services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:latest
    ports:
      - 8000:8000
    volumes:
      - woodpecker-server-data:/var/lib/woodpecker/
    environment:
      - WOODPECKER_OPEN=true
      - WOODPECKER_HOST=${WOODPECKER_HOST}
      - WOODPECKER_GITHUB=true
      - WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
      - WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
      - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}

  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:latest
    command: agent
    restart: always
    depends_on:
      - woodpecker-server
    volumes:
      - woodpecker-agent-config:/etc/woodpecker
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WOODPECKER_SERVER=woodpecker-server:9000
      - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}

volumes:
  woodpecker-server-data:
  woodpecker-agent-config:

创建同目录下创建 .env 环境变量文件。

WOODPECKER_HOST=http://localhost:8000
WOODPECKER_AGENT_SECRET=e61a65af26d998aa303a7b4ce4015ecde83d3caaa3354a91a1120a09e961269e
WOODPECKER_GITHUB_CLIENT=在GitHub生成
WOODPECKER_GITHUB_SECRET=在GitHub生成

5.2 OAuth App

🌟 OAuth App 是什么：

在 GitHub 的上下文中，OAuth App 是一种允许开发者使用 GitHub 用户帐户进行身份验证和访问的应用程序。开发者可以创建自己的 OAuth App，并通过 GitHub 的 OAuth 流程获得对用户帐户的有限访问权限。

OAuth App 在 GitHub 上注册后，会获得一个客户端 ID 和一个客户端密钥（Client Secret）。这些凭据用于在用户授权后获取访问令牌，以便应用程序可以代表用户执行某些操作。

在当前场景中，Woodpecker 为了获得访问 GitHub 的能力（监听仓库变动等），需要在 GitHub 开发者配置中心注册为一个 Oauth App。

🌟 创建 OAuth App：

获取 WOODPECKER_GITHUB_CLIENT 和 WOODPECKER_GITHUB_SECRET 的值通常涉及在 GitHub 上创建 OAuth App。以下是如何获取这两个值的步骤：

登录到您的 GitHub 帐户。

转到 GitHub Developer Settings。

单击右上角的 "New OAuth App"。

在 "Application name" 中输入应用程序的名称。

在 "Homepage URL" 中输入应用程序的主页 URL。这可以是任何有效的 URL，因为我是本地部署，因此填入http://localhost:8000 作为占位符。

在 "Authorization callback URL" 中输入授权回调 URL。这是 GitHub 在用户授权后将用户重定向回您的应用程序的 URL。如果在本地测试，可以使用 http://localhost:8000/authorize 作为占位符。

单击 "Register application"。

您将在页面上看到生成的 "Client ID" 和 "Client Secret"。将它们分别赋值给 .env 文件的 WOODPECKER_GITHUB_CLIENT 和 WOODPECKER_GITHUB_SECRET：

# .env
WOODPECKER_GITHUB_CLIENT=<Your Client ID>
WOODPECKER_GITHUB_SECRET=<Your Client Secret>

5.3 部署与登录

运行 docker-compose up -d 命令后将于本机 docker 上成功部署 woodpecker。

访问 http://localhost:8000/ 点击 Login。

跳转至 OAuth 授权页面完成授权登录。

自动跳转至 Repo 管理页面。

5.4 体验持续集成（CI）

点击页面上 Add repository 可以看到 OAuth 关联账号拥有的仓库列表，查找一个事先准备好的 test-repo。

点击 Enable 提示报错。

🌟 查看 docker 日志分析原因，提示创建 webhook 需要一个公共可访问的 Host 地址，“localhost” 不满足。

docker logs woodpecker_woodpecker-server_1

代替方案
将上述部署行为放到一台可以被公共访问的服务器上进行。
🌟 将 GitHub 替换为 Gitea，同样部署在 localhost 进行测试。（这里选择这种方案）

5.5 本地部署 Gitea 代替 GitHub

Gitea 是一个轻量级的、自助的 Git 服务。它是一个开源的、基于 Go 语言的项目，提供了类似于 GitHub、GitLab 等平台的版本控制仓库管理功能。Gitea 允许您在自己的服务器上架设一个 Git 服务，以便团队或个人能够方便地进行代码托管、协作和版本控制。（GitHub 🌟 Star 40k+）

白泽曾经在 Gitea 有过一段时间的实习，后续可以给大家分享一下～

🌟 在本地部署 Gitea 之后，白泽在继续这个 CI 体验流程时遇到了 Woodpecker 和 Gitea 本地通信时一个访问授权 BUG，事后，我发现整个流程也十分值得记录分享。

所以下一篇文章白泽将讲解解决 BUG 的流程，过程中会配合阅读 Gitea & Woodpecker 的代码。为大家梳理使用开源软件遇到问题时的解决思路和步骤。

六、小结

🌟 未完待续，欢迎追更。

公众号「白泽talk」，白泽目前正在打造一个氛围良好的行业交流群，文章的更新也会提前预告，欢迎加入：622383022。

我也开源了一个 Go 学习仓库：包含 Go 各阶段学习文章、读书笔记、电子书、简历模板等，欢迎 star。

Woodpecker CI 设计分析｜一个 Go 编写的开源持续集成引擎

一、前言

二、CI 配置前瞻

2.1 GitHub Actions Workflow for CI

2.2 Woodpecker Pipeline for CI

2.3 对比

三、术语

四、Woodpecker 架构

五、Woodpecker 部署

5.1 配置文件

5.2 OAuth App

5.3 部署与登录

5.4 体验持续集成（CI）

5.5 本地部署 Gitea 代替 GitHub

六、小结

相关文章

发布评论取消回复

大白菜程序猿

服务器端口转发，带你了解服务器端口转发

百度搜索：蓝易云 – Linux之查看系统性能命令大全

MySQL 主从复制的问题及解决方案

Woodpecker CI 设计分析｜一个 Go 编写的开源持续集成引擎

一、前言

二、CI 配置前瞻

2.1 GitHub Actions Workflow for CI

2.2 Woodpecker Pipeline for CI

2.3 对比

三、术语

四、Woodpecker 架构

五、Woodpecker 部署

5.1 配置文件

5.2 OAuth App

5.3 部署与登录

5.4 体验持续集成（CI）

5.5 本地部署 Gitea 代替 GitHub

六、小结

相关文章

发布评论 取消回复

大白菜程序猿

服务器端口转发，带你了解服务器端口转发

百度搜索：蓝易云 – Linux之查看系统性能命令大全

MySQL 主从复制的问题及解决方案

发布评论取消回复