轻量级开源 CI/CD：Woodpecker 从零部署到跑通完整流水线
内容提要
本文介绍轻量开源CI/CD工具Woodpecker，它源自Drone，用Go编写，包含Server与Agent，并复用Gitea等代码托管平台的认证。文章演示了用docker-compose部署Gitea、Woodpecker Server与Agent，编写Hello World流水线，并以Python项目为例，完整实现提交、测试、构建镜像、SSH自动部署的流程，同时介绍了when触发条件、Secrets、缓存及woodpecker-cli本地试跑等用法。
延伸解读
从 Drone 到 Woodpecker：许可证变更后的社区分叉
Woodpecker 起源于 Drone。2019 年 Drone 在 0.8 版本后将许可证从 Apache 2.0 改为私有协议，随后被 Harness 收购，开源版本更新放缓。社区开发者 laszlocph 基于最后一个 Apache 2.0 授权的 Drone 0.8 代码库创建分叉，三天后发布第一个版本，同年 8 月更名为 Woodpecker。此后项目由社区维护，始终保持 Apache 2.0 协议，2025 年初发布 3.0 版本，目前演进到 3.18，迭代活跃。
架构与执行模型：Server、Agent 与流水线层级
Woodpecker 用 Go 编写，主要分为 Server 和 Agent 两个角色。一个流水线内部的层级是：Pipeline（一次流水线执行）→ Workflow（一个 YAML 文件）→ Step（文件里的一个步骤）。每个步骤指定一个镜像和一组命令或设置，步骤之间共享同一个工作区，按定义顺序串行执行。这种模型让每个步骤都是一个容器，非零退出码即失败，心智模型简单清晰。
部署要点：OAuth 回调与目录权限
部署时需注意两个常见问题。一是 Gitea OAuth 应用的回调地址必须与 WOODPECKER_HOST + /authorize 完全一致，协议、端口、IP 任一项不同都会导致登录失败。二是 Woodpecker Server 容器以 UID 1000 运行，若挂载的 SQLite 数据目录属主不对，可能无法写入，需提前执行 chown -R 1000:1000 调整属主。
缓存与触发条件：提升流水线效率的关键
CI 的每一步都跑在一次性容器里，不做缓存的话，每次流水线都要从零下载依赖、重建镜像层。本文的流水线埋了两层缓存：test 步骤的宿主机缓存卷（依赖缓存）和 build-image 步骤的 cache: true（镜像层缓存）。此外，利用步骤级 when 可以控制触发条件，例如 PR 时只跑测试，合入默认分支后才构建镜像并部署，避免不必要的发布。
Q&A
Woodpecker CI 和 Jenkins、GitLab CI、GitHub Actions 相比有什么不同？
Woodpecker 是轻量、开源的 CI/CD 工具，适合自托管、小团队或个人 Homelab。Jenkins 功能强大但偏重；GitLab CI 要求整套流程构建在 GitLab 上；GitHub Actions 体验好但不开源，构建数据在第三方手里。Woodpecker 完全开源、支持多种代码托管平台、不与特定厂商绑定。
Woodpecker 的架构是怎样的？Server 和 Agent 分别负责什么？
Woodpecker 用 Go 编写，主要有两个角色：Server 和 Agent。Server 负责接收 SCM 的 webhook、调度流水线、提供 Web 界面；Agent 负责实际执行流水线步骤，通过 Docker 运行步骤容器。两者通过 WOODPECKER_AGENT_SECRET 通信。
如何用 docker-compose 部署 Gitea、Woodpecker Server 和 Agent？
在一台服务器上用一份 docker-compose.yml 同时运行 Gitea、Woodpecker Server、Woodpecker Agent，三者处于同一 Docker 网络。先创建 .env 存放敏感配置，再编写 compose 文件。启动分两步：先启动 Gitea 并初始化，创建 OAuth 应用获取 Client ID 和 Secret 回填 .env，再启动全部服务。注意 WOODPECKER_HOST 和回调地址必须完全一致。
Woodpecker 的流水线配置怎么写？when 触发条件有哪些用法？
流水线配置放在仓库根目录的 .woodpecker.yaml 或 .woodpecker/ 目录下，一个 YAML 文件就是一个 workflow。when 可在流水线级和步骤级使用，支持事件（push、pull_request、tag、manual、cron、deployment、release）、分支、路径等过滤。例如只在 main 分支 push 触发，或只在 src 下文件变化时触发。
Woodpecker 中如何使用 Secrets 管理敏感信息？
敏感信息不应写入 YAML，应在 Woodpecker 界面进入仓库 → Settings → Secrets 添加，如 registry_user、registry_password。在流水线中通过 from_secret 引用，可注入为环境变量或传给插件的 settings 参数。Secret 也分系统全局和项目级别两种。
如何用 woodpecker-cli 在本地试跑流水线？
安装 woodpecker-cli 后，用 woodpecker-cli setup --server <地址> --token <令牌> 连接服务器。在仓库目录执行 woodpecker-cli exec 即可读取本地 .woodpecker.yaml 并用本机 Docker 真实执行各步骤，不推代码就能验证语法和命令输出。可用 --workflow-name 只跑指定 workflow，用 --secrets 临时传入测试值。
Woodpecker 中缓存如何提升构建速度？
CI 每一步都跑在一次性容器里，不做缓存每次都要从零下载依赖、重建镜像层。缓存能成倍提升构建速度。本文流水线埋了两层缓存：test 步骤的宿主机缓存卷（依赖缓存）和 build-image 步骤的 cache: true（镜像层缓存）。耗时较长的步骤应优先考虑缓存优化。
