Woodpecker CI 入门速查

2026-05-22

Woodpecker CI 是一个轻量级开源 CI/CD 引擎。每个步骤跑在 Docker 容器里，也支持 Kubernetes 和 local 后端。用 Go 写，从 Drone CI fork 出来（Drone 换许可证之后社区维护的延续）。

架构

三个组件：

组件	职责
Server	UI、API、接收 Webhook、解析 YAML
Agent	执行 workflow，通过 gRPC 连 Server
Autoscaler（可选）	按需创建云 VM 处理构建

Server 默认用 SQLite，大实例建议切到 Postgres 或 MariaDB。

快速部署（Docker Compose）

# docker-compose.yml
services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:v3.14
    ports:
      - 8000:8000
    environment:
      WOODPECKER_OPEN: "true"
      WOODPECKER_HOST: "https://ci.yourdomain.com"
      WOODPECKER_GITHUB: "true"
      WOODPECKER_GITHUB_CLIENT: your_client_id
      WOODPECKER_GITHUB_SECRET: your_client_secret
      WOODPECKER_AGENT_SECRET: change_me
    volumes:
      - woodpecker-server-data:/var/lib/woodpecker

  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:v3.14
    environment:
      WOODPECKER_SERVER: woodpecker-server:9000
      WOODPECKER_AGENT_SECRET: change_me
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

volumes:
  woodpecker-server-data:

启动后访问 localhost:8000，用 GitHub/GitLab/Gitea 登录，激活仓库即可。

第一个流水线

在仓库根目录创建 .woodpecker/workflow.yaml：

when:
  - event: push
    branch: main
steps:
  - name: build
    image: golang:1.22
    commands:
      - go build
      - go test
  - name: deploy
    image: woodpeckerci/plugin-s3
    settings:
      bucket: my-bucket
      source: ./dist/**
      target: /app

推到 main 分支，Woodpecker 自动触发。

Workflow 语法速查

Step 关键字段

字段	说明
`image`	任意 Docker 镜像
`commands`	shell 命令（plugin 和 service 不可用）
`settings`	plugin 参数
`when`	条件过滤
`depends_on`	声明依赖，形成 DAG，不写则串行
`failure: ignore`	允许失败，不影响后续
`failure: cancel`	失败则取消整个 pipeline
`pull: true`	总是拉取最新镜像

When 条件

多个条件在列表里是 OR，单个条件内是 AND。

when:
  - event: pull_request
    repo: my-org/my-repo
    path:
      include: ['.woodpecker/*.yaml', 'src/**']
  - event: push
    branch: main
  - evaluate: 'CI_COMMIT_AUTHOR != "dependabot[bot]"'

可用的事件：push、pull_request、tag、release、deployment、cron、manual。

evaluate 使用 expr-lang，能做复杂逻辑：

when:
  - evaluate: 'CI_PIPELINE_EVENT == "push" && CI_COMMIT_BRANCH == CI_REPO_DEFAULT_BRANCH'

DAG 并行

steps:
  - name: lint
    image: golang
    commands: golangci-lint run
    depends_on: []   # 立即开始
  - name: test
    image: golang
    commands: go test ./...
    depends_on: []   # 与 lint 并行
  - name: build
    image: golang
    commands: go build
    depends_on: [lint, test]  # 等前两个完成

Plugin 与 Service

Plugin — 复用的 Docker 镜像，通过 settings 传参。官方和社区插件在 plugins 页面可查。
Service — 后台容器（数据库、缓存等），step 可以直接连。

services:
  - name: db
    image: postgres:16
    environment:
      - POSTGRES_PASSWORD=test
      - POSTGRES_DB=myapp_test

steps:
  - name: test
    image: golang
    commands:
      - go test -v ./...
    environment:
      - DATABASE_DSN=postgres://postgres:test@db:5432/myapp_test?sslmode=disable

实用技巧

技巧	做法
跳过本次构建	Commit message 加 `[CI SKIP]`
文件变更跨 step 保留	同一 volume 挂载所有 step（默认行为）
路由到指定 agent	用 `labels` 匹配 agent 标签
多平台构建	`labels: platform: linux/arm64`
Matrix 测试	用 `matrix` 跑多版本组合
定时任务	用 `cron` 事件

与主流方案对比

特性	Woodpecker	GitHub Actions	GitLab CI
托管方式	自托管	SaaS / 自托管	SaaS / 自托管
执行环境	Docker 容器	VM / 容器	Docker / Shell
价格	免费	有免费额度	有免费层
配置文件	`.woodpecker/*.yaml`	`.github/workflows/*.yml`	`.gitlab-ci.yml`
Forge 支持	GitHub / GitLab / Gitea 等多 forge	仅 GitHub	仅 GitLab
多 workflow	支持 `depends_on` 跨 workflow 依赖	支持 `workflow_call` 复用	支持 stages + needs + parallel
插件机制	Docker 镜像	Actions 市场	自定义镜像

注意事项

镜像没有 latest 标签，用 SemVer 如 v3.14
trusted 仓库才可用 privileged 模式（跑 Docker-in-Docker 等）
自用或小团队很合适；大规模场景建议上 Postgres + autoscaler