引言
在现代软件交付中，CI/CD 流水线已经成为研发团队的基础设施。Woodpecker CI 是一个基于容器的轻量级开源 CI/CD 引擎，脱胎于社区对早期 Drone 的分叉，主打”无中心数据库、以容器为执行单元、配置即代码”的极简哲学。相比动辄需要 Java 运行时和海量插件的 Jenkins，Woodpecker 只由两个核心组件——server 与 agent——构成，整个服务可以用一份 docker-compose 在十分钟内跑起来。本文将手把手带你部署 Woodpecker CI、编写第一条 .woodpecker.yaml 流水线，并给出与 Drone、GitHub Actions 的选型对比，帮助你判断它是否适合你的团队。
一、Woodpecker CI 的核心架构
Woodpecker 的设计极其精简，整个系统只有两类角色，理解它们就理解了这套引擎的运转方式。
1.1 Server：调度与控制台
Server 负责接收代码托管平台（GitHub、Gitea、GitLab 等）的 Webhook、解析流水线配置、向 Agent 派发任务，并对外提供 Web 控制台。它把运行状态存储在一个嵌入式数据库（默认 SQLite，也支持 PostgreSQL）中，因此你不需要再单独维护一套 MySQL 或 Redis，部署负担被压到最低。
1.2 Agent：真正干活的节点
Agent 通过 gRPC 与 Server 保持长连接，拉取任务后在本地用 Docker 容器逐步执行流水线步骤。每一步都是一个独立容器，天然隔离、随用随销，这也是它”容器原生”的真正含义——没有常驻进程堆积，也没有环境串味。
1.3 与 Drone 的关系
很多读者会问：Woodpecker 和 Drone 到底有什么区别？二者早期同源，但开源策略走向不同。下面这张表可以快速看清差异（如果你想了解 Drone 本身的玩法，可参考我们之前发布的 Drone CI 实战：容器原生 CI/CD 流水线）：
| 维度 | Woodpecker CI | Drone CI |
|---|---|---|
| 许可证 | Apache-2.0 全功能开源 | 社区版功能受限，企业版收费 |
| 状态存储 | 嵌入式 SQLite / Postgres | 需外部数据库 |
| 流水线语法 | .woodpecker.yaml | .drone.yml |
| 插件生态 | 官方 plugins/* 同构 | 自有插件体系 |
| 自托管门槛 | 极低，单份 compose 起 | 中等 |
可以看到，在”完全开源、零外部依赖”这一点上，Woodpecker 对中小团队更友好，而 Drone 的企业版能力则更适合有合规采购需求的组织。
二、十分钟快速部署
最省心的方式是用 docker-compose 同时拉起 server 和 agent。下面是一份可直接使用的配置（请将域名、OAuth 凭据替换为你自己的）：
version: '3'
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
container_name: woodpecker-server
ports:
- "8000:8000"
environment:
- WOODPECKER_HOST=https://ci.example.com
- WOODPECKER_SERVER_ADDR=:9000
- WOODPECKER_GITHUB_CLIENT=your_github_client_id
- WOODPECKER_GITHUB_SECRET=your_github_client_secret
- WOODPECKER_AGENT_SECRET=change_me_to_a_long_random_string
volumes:
- woodpecker-data:/var/lib/woodpecker
restart: unless-stopped
woodpecker-agent:
image: woodpeckerci/woodpecker-agent:latest
container_name: woodpecker-agent
command: agent
depends_on:
- woodpecker-server
environment:
- WOODPECKER_SERVER=woodpecker-server:9000
- WOODPECKER_AGENT_SECRET=change_me_to_a_long_random_string
volumes:
- /var/run/docker.sock:/var/run/docker.sock
restart: unless-stopped
volumes:
woodpecker-data:
把这份文件保存为 docker-compose.yml 后执行 docker compose up -d 即可。注意 agent 必须挂载宿主机的 /var/run/docker.sock，因为它要靠宿主 Docker 来创建执行容器。如果你还希望把控制台通过域名对外暴露，可以参考我们之前的 Nginx 反向代理完整配置 一文做 HTTPS 反代。
三、编写第一条流水线
Woodpecker 的流水线配置文件放在仓库根的 .woodpecker/ 目录，也可以直接放在根目录的 .woodpecker.yaml。下面是一个 Node.js 项目的典型流水线：
steps:
install:
image: node:20
commands:
- npm ci
- npm run lint
test:
image: node:20
commands:
- npm test
build:
image: plugins/docker
settings:
repo: yourname/my-app
tags: ${CI_COMMIT_TAG:-latest}
username:
from_secret: docker_user
password:
from_secret: docker_pass
when:
event: [push, tag]
每个 step 都用 image 指定运行容器，命令在容器内顺序执行；只要某一步非零退出，整条流水线即判定失败。最后的 plugins/docker 是官方构建并推送镜像的插件，凭据通过 from_secret 从 Woodpecker 后台密钥中心注入，绝不会明文出现在仓库里。关于 Docker 容器编排的基础，也可以回看 Docker Compose 一键编排。
四、三个必须掌握的配置技巧
4.1 密钥管理
在 Server 控制台或通过 CLI 为仓库配置密钥后，配置文件里用 from_secret: 名称 引用即可，例如上面的 Docker 凭据。密钥在 Web 界面不可回看，安全性足够日常使用，也避免了把 token 提交进 Git 的历史风险。
4.2 矩阵构建
需要跨版本验证时，矩阵（matrix）能一次性展开多组任务，省去复制粘贴步骤：
steps:
test:
image: node:${matrix.node}
commands:
- npm ci
- npm test
matrix:
node:
- "18"
- "20"
- "22"
4.3 触发条件
通过 when 精确控制阶段在什么事件下执行：push、tag、pull_request、cron 都能自由组合。比如只在打 tag 时才构建并推送镜像，平时 push 只跑测试，避免无谓地往镜像仓库写 tag，也加快反馈速度。
五、进阶：缓存、插件与 Kubernetes Runner
流水线跑得慢，往往卡在依赖安装。Woodpecker 支持用 plugins/s3-cache 或本地 volume 缓存 node_modules，能把单轮构建从几分钟压到几十秒。插件方面，官方维护的 plugins/* 覆盖了 Docker 构建、Slack 通知、SSH 部署等常见需求；若官方没有现成插件，你也可以直接写一段任意镜像的 shell 命令，灵活性很高。
当单机 Docker 不够用时，Woodpecker 还提供 Kubernetes、Nomad 等 Runner，把任务调度到集群里执行，体验与 GitHub Actions 的 self-hosted runner 类似，但完全跑在你自己的基础设施上，数据不出内网。
六、Woodpecker 与同类工具怎么选
| 工具 | 部署成本 | 适用规模 | 突出优势 |
|---|---|---|---|
| Woodpecker CI | 低（单 compose） | 小到中型团队 | 全开源、零外部依赖 |
| Drone CI | 中 | 中小团队 | 生态成熟 |
| GitHub Actions | 极低（SaaS） | 全规模 | 与 GitHub 深度集成 |
| Jenkins | 高 | 大型 / 复杂 | 插件海量、可编程极强 |
选型没有银弹：如果你的代码已经托管在 GitHub 且追求零运维，Actions 最省事；如果你坚持数据自持、想要一个干净不臃肿的自托管引擎，Woodpecker 是非常值得考虑的选项。我们也写过 Jenkins 实战 与 GitHub Actions 从零搭建，可以对照阅读。
七、生产落地建议
- 给 agent 单独的资源配额，避免构建任务吃光宿主机内存触发 OOM，影响同机其他服务。
- 用反向代理为 Server 开启 HTTPS，并开启注册白名单，防止陌生人滥用你的构建算力。
- 把流水线运行状态接进 Prometheus + Grafana 监控，重点关注失败率与平均耗时，及时揪出”习惯性红构建”。
- 定期清理旧的构建产物与镜像标签，别让镜像仓库被无限膨胀的 tag 撑爆磁盘。
总结
Woodpecker CI 用”两个组件、一份 compose、以容器为执行单元”的极简设计，把自托管 CI/CD 的门槛降到了最低。它完全开源、无外部数据库依赖，配置语法与 Drone 一脉相承却又更轻，是中小团队摆脱重型 Jenkins、又不愿把源码托付给 SaaS 的优质折中方案。从今天这份 docker-compose 起步，配合矩阵构建、密钥管理与插件体系，你很快就能拥有一套属于自己的、干净利落的持续交付流水线。
