轻量级开源 CI/CD：Woodpecker 从部署到跑通完整流水线
内容提要
本文介绍轻量开源 CI/CD 工具 Woodpecker：源自 Drone 分叉，采用 Apache 2.0 协议，用 Go 编写，架构分 Server 与 Agent。文章演示在 Linux 上用 docker-compose 部署 Gitea、Woodpecker Server 和 Agent，配置 OAuth 登录，编写 Hello World 流水线，并以 Python 项目为例实现提交、测试、构建镜像、SSH 自动部署，同时介绍缓存、密钥管理与 woodpecker-cli 的用法。
延伸解读
从 Drone 分叉看 Woodpecker 的定位
Woodpecker 源自 Drone 0.8 的社区分叉，因 Drone 更改许可证并转向商业版而诞生。它始终保持 Apache 2.0 协议，由社区维护，2025 年初发布 3.0 版本，目前迭代到 3.18。对于自托管、开源、轻量的需求，尤其是已使用 Gitea 等自建代码托管平台的用户，Woodpecker 是一个值得考虑的替代方案。
部署要点：OAuth 回调与目录权限
部署时需先启动 Gitea 并创建 OAuth 应用，回调地址必须与 WOODPECKER_HOST + /authorize 完全一致，否则登录失败。Woodpecker Server 容器以 UID 1000 运行，需确保数据目录属主正确，否则 SQLite 可能无法写入。默认使用 SQLite，生产环境建议换用高可用数据库并做好备份。
流水线设计：步骤级 when 与缓存策略
通过步骤级 when 可以控制不同事件下的执行范围，例如 PR 只跑测试，push 才构建和部署。缓存能显著提升速度：test 步骤使用宿主机缓存卷缓存依赖，build-image 步骤开启 kaniko 缓存镜像层。合理利用缓存可减少重复下载和构建时间。
密钥管理与 CLI 提效
敏感信息应通过 Woodpecker 的 Secrets 管理，支持系统级和项目级，在流水线中用 from_secret 引用。woodpecker-cli 可将操作搬到终端，exec 命令甚至能在本地运行流水线，lint 可校验配置，减少“推一次等一次”的调试成本。
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 负责处理 Web 界面、接收 SCM 的 webhook、调度流水线；Agent 负责实际执行流水线步骤，通过 Docker 运行每个步骤的容器。
Woodpecker 的流水线配置中，Pipeline、Workflow、Step 是什么关系？
一个流水线内部的层级是：Pipeline（一次流水线执行）→ Workflow（一个 YAML 文件）→ Step（文件里的一个步骤）。每个步骤指定一个镜像和一组命令或设置，步骤之间共享同一个工作区，按定义顺序串行执行。
如何用 docker-compose 部署 Gitea、Woodpecker Server 和 Agent？
在一台服务器上，用一份 docker-compose.yml 同时运行 Gitea、Woodpecker Server、Woodpecker Agent，三者处于同一个 Docker 网络。需要创建 .env 文件存放敏感配置，如 WOODPECKER_HOST、WOODPECKER_GITEA_CLIENT、WOODPECKER_GITEA_SECRET、WOODPECKER_AGENT_SECRET 等。先启动 Gitea 并初始化，创建 OAuth 应用获取 Client ID 和 Secret 回填 .env，再启动全部服务。
Woodpecker 如何管理敏感信息（如密码、密钥）？
敏感信息不应写入 YAML，应在 Woodpecker 界面进入仓库 → Settings → Secrets 添加，然后在流水线中通过 from_secret 引用，可以注入为环境变量或传给插件的 settings 参数。Secret 分系统全局和项目级别两种。
Woodpecker 的缓存机制如何提升构建速度？
CI 每一步都跑在一次性容器里，不做缓存每次都要从零下载依赖、重建镜像层。缓存能成倍提升构建速度。本文示例中埋了两层缓存：test 步骤的宿主机缓存卷（依赖缓存）和 build-image 步骤的 cache: true（镜像层缓存）。
woodpecker-cli 有哪些常用命令？
woodpecker-cli 常用命令包括：woodpecker-cli info、woodpecker-cli repo ls、woodpecker-cli pipeline ls、woodpecker-cli pipeline log show、woodpecker-cli lint .woodpecker.yaml --strict。安装后需先执行 woodpecker-cli setup --server <地址> --token <令牌> 连接服务器。
