Woodpecker CI v3.19.0 介绍与选型指南

目标：面向需要在自托管代码托管平台上落地轻量 CI/CD 的团队，系统介绍 Woodpecker CI v3.19.0 的定位、架构、功能特性与同类工具选型对比。本文为认知篇，全部论断来自官方文档、GitHub Release 等公开资料并标注来源与查询日期，不做本地安装实测（部署实测见《Woodpecker CI Docker Compose 部署指南》）。

一、环境信息

本章为本文的信息基准：说明写作时的版本依据、查询日期与官方来源清单，保证读者可复核每一条论断。

• 信息基准（查询日期）：2026-10-18；
• 本文介绍的版本：Woodpecker CI v3.19.0（写作时官方最新稳定版，server 与 agent 版本号一致）；
• 版本依据：GitHub 仓库 woodpecker-ci/woodpecker 的 releases/latest 重定向实测指向 v3.19.0；Release 列表确认 3.19.0 发布于 2026-10-08（来源：https://github.com/woodpecker-ci/woodpecker/releases，查询日期 2026-10-18）；
• 官方来源清单（本文引用均出自以下公开资料）：
  • 官方网站与文档站：https://woodpecker-ci.org/、https://woodpecker-ci.org/docs/intro；
  • GitHub 仓库与 Release：https://github.com/woodpecker-ci/woodpecker；
  • 官方文档（3.18.x/3.19.x 版本页）：/docs/usage/intro、/docs/development/architecture、/docs/administration/configuration/forges/overview、/docs/administration/configuration/backends/*；
  • Docker Hub 官方镜像元数据：woodpeckerci/woodpecker-server、woodpeckerci/woodpecker-agent（用于社区活跃度量化，查询日期 2026-10-18）；
• 版本号说明：官方文档站当前维护 3.19.x 与 3.18.x 两个文档版本（3.17.x 已标记停止维护"💀"），说明 minor 版本的官方支持窗口约为一到两个周期。

二、软件概述

本章回答"Woodpecker CI 是什么、从哪来、现状如何"，并给出身份信息与分发方式，帮助读者快速建立整体认知。

Woodpecker CI 是一款开源的持续集成/持续交付（CI/CD）引擎，官方定位是"轻量（lightweight）、简单易用（simple to use）、快速（fast）"。项目源自 Drone CI 的开源分支（fork）：Drone 自 2.x 之后社区版转向商业化后，社区以 woodpecker-ci/woodpecker 为基础延续开源演进，如今已是独立发展的活跃项目（官方文档站与 Release 节奏见第一、七章，均为 2026-10-18 实查）。

💡 技术拓展：CI/CD 引擎的"事件驱动"模型。Woodpecker 与同类自托管 CI 一样，不自带代码托管能力，而是作为"执行引擎"挂靠在 Forge（代码托管平台）之后：代码推送到 Forge → Forge 通过 Webhook 通知 CI → CI 按仓库内的流水线配置文件调度执行并回写状态。选择 CI 引擎时，第一步应先确认它是否支持你正在使用的 Forge，这正是本文第七章兼容矩阵的意义所在。

核心身份信息一览（来源：官方文档与 GitHub 仓库，查询日期 2026-10-18）：

版本发布节奏（GitHub Releases 实查，查询日期 2026-10-18）：

解读：minor 版本约每 4～5 周发布一次、patch 跟随紧随其后，近半年保持稳定的月级迭代节奏，项目处于活跃维护期。

三、核心架构

本章拆解 Woodpecker 的进程模型与数据流。理解 server/agent 分离架构是后续做部署规划（端口、安全、扩缩容）的前提。

3.1 组件模型：server + agent + cli

Woodpecker 采用 server / agent 分离架构（来源：官方文档 /docs/development/architecture，查询日期 2026-10-18）：

• server：控制面。负责 Web UI 与 REST API、接收 Forge Webhook、编排流水线（解析 .woodpecker/ 配置）、维护队列（queue）、持久化数据（内置存储支持 SQLite/Postgres/MySQL），并通过 gRPC 接口向 agent 分发任务、回收日志与状态；
• agent：执行面。作为远端工作节点（remote worker）向 server 发起 gRPC 长连接拉取任务，在本地按流水线定义逐 step 执行，并把日志实时流式回传 server。agent 无状态、可水平扩展，可按标签（labels）承接特定任务；
• cli：命令行工具，提供本地流水线试运行（woodpecker-cli exec）、管理命令等能力（来源：官方 intro 页"run workflow files locally with woodpecker-cli exec"）。

💡 技术拓展：控制面/执行面分离的两种调度通道。server 与 agent 的任务分发不依赖 agent 侧开放端口——由 agent 主动向 server 的 gRPC 端口（默认 9000）发起连接。这与"server 反向 SSH/SSH 到节点"的老式 CI（如 Jenkins 经典 agent）不同，agent 侧无需入站端口，跨网段部署时网络规划更简单，也更利于安全收敛。部署实操中该 gRPC 连接由 WOODPECKER_SERVER 指向、WOODPECKER_AGENT_SECRET 共享口令鉴权（详见《Woodpecker CI Docker Compose 部署指南》）。

3.2 一次流水线的完整数据流

结合官方文档对模块的划分（pipeline 为核心引擎、rpc 为 agent-server 通信接口），一次 push 触发的数据流如下：

1. 开发者向 Forge（如 Gitea）推送代码；
2. Forge 通过 Webhook 通知 server（仓库激活时 Woodpecker 自动在 Forge 上注册 Webhook）；
3. server 解析仓库内 .woodpecker/*.yaml 配置，经 lint/编译校验后生成工作流入队；
4. 空闲 agent 经 gRPC 领取工作流，按 step 顺序执行（源码获取 → 各 step 依次运行），日志流式回传；
5. server 将状态与日志持久化，通过 Web UI / 状态徽章 / 通知呈现结果，并回写 commit 状态到 Forge。

上述流程中的关键机制——仓库激活（Repository Activation）与 Webhook 自动注册——官方文档 /docs/usage/intro 有明确描述："To enable a repository in Woodpecker you must have Admin rights on that repository, so that Woodpecker can add something that is called a webhook"（查询日期 2026-10-18）。本团队已在真实环境中完整复现该闭环（push → Webhook → 流水线执行 → 日志回传），全过程实测记录见《Woodpecker CI Docker Compose 部署指南》。

3.3 存储与 Forge 集成

• 存储：server 内置支持 SQLite、PostgreSQL、MySQL 三种后端（来源：官方文档 Administration/Storage 章节，查询日期 2026-10-18）。SQLite 适合单机与中小规模，Postgres/MySQL 适合多实例与更大规模；
• Forge 集成：原生支持 GitHub、Gitea、Forgejo、GitLab、Bitbucket、Bitbucket Datacenter/Server 六类 Forge，并另有 addon 机制支持自定义 Forge（来源：官方文档 /docs/administration/configuration/forges/overview，查询日期 2026-10-18）。各 Forge 的事件支持度差异（如 Release/Deploy 事件）见第七章兼容矩阵；
• 执行后端（backend）：agent 的 step 执行环境支持 docker、kubernetes、local（直接在 agent 主机执行）与 custom 自定义后端（来源：官方文档 /docs/administration/configuration/backends/*，查询日期 2026-10-18）。

💡 技术拓展：执行后端的取舍。docker 后端隔离性好、step 镜像即环境，是最常用选择；kubernetes 后端把每个 step 变成 Pod，适合已上 K8s 的组织统一调度；local 后端无隔离开销、直接复用主机环境，适合构建机即专机且追求速度的场景；custom 后端供团队实现自有执行协议。本文所述团队实测与《Woodpecker CI Docker Compose 部署指南》均采用官方默认推荐的 docker 后端。

四、功能特性

本章按"流水线定义、执行能力、安全与集成"三条线梳理 v3.19.x 的主要功能，全部条目以官方文档功能页为依据（查询日期 2026-10-18），不包含本地实测结论（功能实测属部署篇与运维篇职责）。

4.1 流水线定义（Pipeline as Code）

• 配置文件即代码：流水线以 YAML 定义在仓库 .woodpecker/ 目录下（支持 .woodpecker/*.yaml 多文件与单文件 .woodpecker.yaml，默认查找路径可配置）；
• when 条件过滤：支持按事件（push/tag/pull_request/release/deploy/manual/cron）、分支、路径（when.path）、平台等维度触发与过滤；
• 多 workflow：一个仓库可定义多个 workflow（.woodpecker/ 下多个文件），支持按需并行；
• matrix 构建：内置矩阵策略，同一 workflow 对多组变量组合分别执行（官方 /docs/usage/matrix-workflows）；
• services 与 volumes：workflow 内可声明伴随服务（如数据库容器）与挂载卷（官方 /docs/usage/services、/docs/usage/volumes）。

4.2 执行与调度能力

• 多 agent 弹性伸缩：agent 按标签承接任务，WOODPECKER_MAX_WORKFLOWS 控制单 agent 并行度，支持随规模横向加节点（官方 Administration/Agent 章节）；
• 自动伸缩器（Autoscaler）：官方提供 autoscaler 组件，按队列水位动态增减云上 agent（官方文档 Administration/Autoscaler）；
• cron 定时流水线：内置 cron 触发器（官方 /docs/usage/cron）；
• 手动触发与参数：支持 manual 事件的手动触发，并可传入自定义变量（官方 /docs/usage/intro 与 API 定义）；
• 本地执行：woodpecker-cli exec 可在本地直接运行 workflow 文件，便于提交前自测（官方 intro 页）。

4.3 安全与集成能力

• secrets 管理：支持全局/组织/仓库三级 secret，可按事件、镜像白名单限制使用范围，日志自动脱敏（官方 /docs/usage/secrets）；
• 注册表凭据：支持 registry 凭据配置用于拉取私有基础镜像（官方 /docs/usage/registries）；
• 插件生态：step 可直接使用社区插件（plugins.woodpecker-ci.org），插件本质是"带约定环境变量的标准 step"；
• 状态回写与徽章：构建状态自动回写 Forge commit 状态，支持 SVG 状态徽章（官方 Administration/Badges）；
• OpenAPI/REST API：server 内置 OpenAPI 文档（官方 /docs/api），全部 UI 能力均有对应 API。

五、快速上手

本章给出官方文档中的最小流水线示例，帮助读者在部署完成后立即建立直观认识。本章仅转述官方示例（标注官方来源），本地安装与真实触发实测见《Woodpecker CI Docker Compose 部署指南》。

官方"Your first pipeline"示例（来源：https://woodpecker-ci.org/docs/usage/intro，3.19.x 文档，查询日期 2026-10-18）：在仓库中创建 .woodpecker/my-first-workflow.yaml：

when:
  - event: push
    branch: main

steps:
  - name: build
    image: debian
    commands:
      - echo "This is the build step"
      - echo "some-data" > some-file.txt

  - name: a-test-step
    image: alpine
    commands:
      - echo "Testing ..."
      - cat some-file.txt

官方要点解读：

• when 段过滤触发条件：该 workflow 仅在 push 到 main 分支时执行；
• steps 段按声明顺序执行：build 先于 a-test-step，前一步产物（some-file.txt）对后续 step 可见；
• 每个 step 用 image 声明执行环境（官方示例使用 debian/alpine 基础镜像）、commands 逐条声明命令；
• 官方流程说明：仓库激活（需对该仓库有 Admin 权限，Woodpecker 会自动注册 Webhook）→ 推送代码 → Woodpecker 自动发现配置并执行。

本团队已按上述官方示例在真实环境（Woodpecker v3.19.0 + Gitea）跑通完整闭环：真实 push 触发、agent 拉取源码、两步顺序执行、日志与状态回写均实测成功，实测回显与步骤详见《Woodpecker CI Docker Compose 部署指南》。

六、适用场景与限制

本章从"什么该选它、什么不该选它"两端给结论，均基于官方定位与上述功能清单归纳。

6.1 适用场景

• 自托管 Gitea/Forgejo 私有代码平台的 CI 需求：Woodpecker 对 Gitea/Forgejo 是一等公民支持（官方 forge 矩阵），轻量组合（Gitea + Woodpecker 两个服务即可构成完整"托管 + CI"链路）是小型团队与内网环境的高性价比方案；
• 多代码平台并存的统一 CI：同一套 Woodpecker 可同时对接 GitHub/GitLab/Gitea/Bitbucket 等，流水线语法统一；
• 执行节点需要弹性扩展：server/agent 分离 + 标签调度 + autoscaler，适合构建任务波动大的团队；
• 资源受限环境：官方定位轻量（"even runs on a Raspberry Pi"），单机即可承载完整 CI 能力。

6.2 限制与注意

• 不含代码托管：必须搭配 Forge 使用，单独无法构成完整研发平台（需与 Gitea/GitLab 等组合）；
• 执行环境以容器后端为主：docker/kubernetes 后端均依赖容器运行时，非容器化的构建链路需改用 local 后端并接受其隔离性缺失；
• 构建产物分发非内置强项：与 GitLab CI 内置的制品库/依赖库（Package Registry）相比，Woodpecker 的制品发布通常借助插件或外部系统完成；
• 版本迭代快：minor 约 4～5 周一发（见第二章节奏表），升级频率需纳入运维预算，官方对旧文档版本仅保留一到两个周期（3.17.x 已停止维护）；
• 生态体量小于 Jenkins/GitLab：插件与模板生态规模受社区体量约束，复杂场景可能需要自研插件或 step 脚本。

七、同类选型对比

本章对主流自托管 CI/CD 方案做量化对比。所有数据均于 2026-10-18 实查：GitHub star/fork 经仓库页面实抓（jina reader 转储 GitHub 页面文本），Forgejo 取自 Codeberg 官方仓库 API，镜像拉取量取自 Docker Hub Registry API，版本与发布日期取自各项目 Release/Tag 源。因查询日期不同数据会漂移，读者引用时请注明查询日期。

7.1 候选对象与社区活跃度

注：Gitea 仓库 stars 因实抓页面波动标注为约值；act 定位是"本地跑 GitHub Actions 工作流"而非服务端 CI 平台，列入对比主要因其与 Gitea/Forgejo Actions 的 runner（act_runner）同源。

7.2 版本节奏对比

解读：追求稳定长周期选 Jenkins LTS / GitLab；追求活跃迭代且轻量，Woodpecker 与 Gitea/Forgejo 均处于月级活跃节奏；Drone 社区版已明显失速，新项目不建议再入坑。

7.3 兼容矩阵与语法体系

事件支持度差异（Woodpecker 官方 forge 矩阵，查询日期 2026-10-18）：Push/Tag/Pull-Request 事件六类 Forge 全支持；Release 事件仅 GitHub/Gitea/Forgejo/GitLab 支持（Bitbucket 系不支持）；Deploy 事件仅 GitHub 可由 Webhook 触发、其余 Forge 可从 Woodpecker 侧手动发起。

7.4 选型建议

• 已在用 Gitea/Forgejo 且要轻量 CI：首选 Woodpecker（独立引擎、Forge 一等支持、资源占用低），或直接用 Gitea/Forgejo 内置 Actions（零额外平台、语法与 GitHub Actions 兼容，但执行器与调度能力较新、平台锁定于单一 Forge）；
• 多平台、跨团队统一流水线语法：Woodpecker（一套语法接六类 Forge）优于各平台内置 Actions；
• 重量级流程编排、历史插件资产多：Jenkins 仍是保守稳妥之选，代价是运维与升级成本高；
• 一体化 DevSecOps 平台诉求（制品库/安全扫描/审计一体化）：GitLab CE 全家桶一步到位，代价是部署与资源规模显著高于"Gitea + Woodpecker"轻量组合；
• 从 Drone 迁移：Woodpecker 即其开源延续，官方提供迁移文档（woodpecker-ci.org/docs/migrations），老 Drone 用户迁移成本最低；
• 本地调试 GitHub Actions 工作流：act 定位不同，与上述服务端方案互补而非互斥。

本团队最终以"Gitea + Woodpecker CI v3.19.0"组合落地实测：部署、OAuth 对接、真实流水线触发全过程见《Woodpecker CI Docker Compose 部署指南》，上线后的巡检、备份、升级与排障见《Woodpecker CI 日常运维手册》。

八、参考链接

• Woodpecker CI 官方网站：https://woodpecker-ci.org/
• 官方文档（3.19.x）：https://woodpecker-ci.org/docs/intro
• GitHub 仓库：https://github.com/woodpecker-ci/woodpecker
• Release 页（版本节奏依据）：https://github.com/woodpecker-ci/woodpecker/releases
• 官方架构文档：https://woodpecker-ci.org/docs/3.18/development/architecture
• 官方 Forge 支持矩阵：https://woodpecker-ci.org/docs/3.18/administration/configuration/forges/overview
• 官方快速上手：https://woodpecker-ci.org/docs/usage/intro
• 官方插件目录：https://woodpecker-ci.org/plugins
• Drone（上游项目）：https://github.com/drone/drone
• Gitea（推荐搭配的 Forge）：https://github.com/go-gitea/gitea
• Forgejo：https://codeberg.org/forgejo/forgejo
• act：https://github.com/nektos/act
• Jenkins：https://github.com/jenkinsci/jenkins