使用 Docker Compose 部署 Woodpecker CI/CD:server 与 agent 的完整安装配置指南

原创2026-09-27 09:38:332,242 阅读
文章标签:CI/CDDevOps

使用 Docker Compose 部署 Woodpecker CI/CD:server 与 agent 的完整安装配置指南

Woodpecker 是采用 server/agent 架构的 CI/CD 引擎:server 负责 Web UI、API、调度与 Webhook 接收,agent 负责拉取并执行流水线步骤。本文基于官方 Docker Compose 安装方案,完整讲解如何通过 docker-compose.yaml 一次性拉起 server 与 agent 两个服务,并深入说明 WOODPECKER_HOST、WOODPECKER_AGENT_SECRET、gRPC 端口与 TLS、Docker socket 挂载、敏感数据注入(*_FILE 与 docker secrets)以及 SELinux 等关键配置。读完本文,你将能够独立部署一套生产可用、可扩展、可反向代理的 Woodpecker 实例,并理解其底层参数解析与 gRPC 通信原理。

部署架构:两个服务、两个端口

Compose 方案由两个服务组成,二者通过内部网络协作:

  • woodpecker-server(镜像 woodpeckerci/woodpecker-server:v3):对外暴露 HTTP 端口 8000,提供 Web UI、REST API、forge 认证回调,同时监听 gRPC 端口 9000 供 agent 连接。
  • woodpecker-agent(镜像 woodpeckerci/woodpecker-agent:v3):启动命令为 agent,通过 gRPC 从 server 拉取任务,并把流水线步骤作为 Docker 容器在宿主机上执行。

这一“双端口”设计在原文档中有明确提示,其默认值也可在源码中确认:cmd/server/flags.go 定义 HTTP 监听地址 WOODPECKER_SERVER_ADDR 默认为 :8000,cmd/server/flags.go 定义 gRPC 监听地址 WOODPECKER_GRPC_ADDR 默认为 :9000。两个端口可分别通过 *_ADDR 系列变量自定义(详见下文)。

前置准备:在 forge 注册 OAuth App

Woodpecker 自身不提供用户注册,用户体系完全来自所对接的 forge(如 GitHub、Gitea、GitLab、Bitbucket 等)。因此部署前必须先在 forge 上注册一个 OAuth App,并取得 Client ID 与 Client Secret。

以 GitHub 为例,需在 GitHub 的 Settings → Developer Settings → GitHub Apps → New OAuth2 App 中创建(注意:应使用 OAuth2 App 而非 GitHub App,详见 GitHub forge 配置文档):

  • Homepage URL:填写 Woodpecker 实例的地址;
  • Callback URL:https://<your-woodpecker-instance>/authorize;
  • 创建后生成 Client Secret,填入下文 Compose 文件中的 WOODPECKER_GITHUB_CLIENT 与 WOODPECKER_GITHUB_SECRET。

其他 forge 的注册方式与对应环境变量,可参考仓库内的 forge 总览 及 GitHub、Gitea、GitLab 等具体文档。切换 forge 时,只需将 WOODPECKER_GITHUB=true 换成对应驱动开关,并配套设置各自的 Client/Secret 变量即可。

完整的 docker-compose.yaml

以下为官方示例的完整版本(与仓库根目录的 docker-compose.example.yaml 同源),创建 docker-compose.yaml 后放在任意目录即可使用:

services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:v3
    ports:
      - 8000:8000
    volumes:
      - woodpecker-server-data:/var/lib/woodpecker/
    environment:
      - WOODPECKER_OPEN=true
      - WOODPECKER_HOST=${WOODPECKER_HOST}
      - WOODPECKER_GITHUB=true
      - WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
      - WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
      - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}

  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:v3
    command: agent
    restart: always
    depends_on:
      - woodpecker-server
    volumes:
      - woodpecker-agent-config:/etc/woodpecker
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WOODPECKER_SERVER=woodpecker-server:9000
      - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}

volumes:
  woodpecker-server-data:
  woodpecker-agent-config:

关键设计点说明:

  • 持久化:woodpecker-server-data 卷挂载到 /var/lib/woodpecker/,内置 SQLite 数据库(woodpecker.sqlite)存放于此,包含全部用户与仓库信息,是必须持久化的核心数据。源码层面,cmd/server/flags.go 通过检测 WOODPECKER_IN_CONTAINER 环境变量自动把默认数据库路径切换为 /var/lib/woodpecker/woodpecker.sqlite,与 Compose 挂载点完全对应。
  • depends_on:确保 agent 在 server 之后启动;仓库示例中还使用了 condition: service_healthy 等待 server 健康检查通过,生产环境建议补充 healthcheck。
  • agent 配置目录:woodpecker-agent-config:/etc/woodpecker 用于持久化 agent 自身配置(注册后获得的 agent ID,见后文“agent 注册原理”)。

必须配置的核心环境变量

WOODPECKER_HOST:告知实例自身公网地址

server 必须知道自己的对外地址,用于生成 Webhook 回调、OAuth 跳转与克隆 URL。格式为 <scheme>://<hostname>,不要带尾部斜杠。在原文档基础上,完整格式支持 WOODPECKER_HOST=http://example.org/woodpecker(路径前缀)以及 http://example.org:1234/woodpecker(非默认端口 + 前缀)等变体,详见 server 配置文档。

 services:
   woodpecker-server:
     [...]
     environment:
       - [...]
+      - WOODPECKER_HOST=${WOODPECKER_HOST}

WOODPECKER_AGENT_SECRET:server 与 agent 的共享密钥

server 与所有 agent 使用同一个随机字符串完成相互认证。该值应严格保密,可用以下命令生成:

openssl rand -hex 32

必须同时配置在 server 与 agent 两侧:

 services:
   woodpecker-server:
     [...]
     environment:
       - [...]
+      - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
   woodpecker-agent:
     [...]
     environment:
       - [...]
+      - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}

该变量在源码中被定义为带 _FILE 支持的值源链(见 cmd/server/flags.go 与 agent 配置文档),因此既可以写死值,也可以从文件读取(下文“敏感数据处理”详述)。

WOODPECKER_SERVER:agent 连接 server 的 gRPC 地址

agent 通过该变量找到 server 的 gRPC 端口(默认 9000)。在 Compose 网络内可直接使用服务名:

 services:
   woodpecker-agent:
     [...]
     environment:
+      - WOODPECKER_SERVER=woodpecker-server:9000

当 server 与 agent 部署在同一宿主机且非容器网络时,也可以写作 localhost:9000。若使用 unix socket,则需加 unix:// 前缀(agent 端在 agent/rpc/dial.go 中会先检查 socket 文件是否存在再连接)。

自定义端口与 gRPC 通信

Woodpecker 将 HTTP(Web/API) 与 gRPC(agent 通信) 分为两个独立监听器,均可通过 *_ADDR 变量调整(默认值与源码依据见 cmd/server/flags.go 与 cmd/server/flags.go):

 services:
   woodpecker-server:
     [...]
     environment:
       - [...]
+      - WOODPECKER_GRPC_ADDR=${WOODPECKER_GRPC_ADDR}
+      - WOODPECKER_SERVER_ADDR=${WOODPECKER_HTTP_ADDR}
  • WOODPECKER_GRPC_ADDR:gRPC 监听地址,默认 :9000;
  • WOODPECKER_SERVER_ADDR:HTTP 监听地址,默认 :8000,也支持 unix:// 前缀监听 unix socket。

若 agent 通过公网/跨网络连接 server,必须为 gRPC 开启 TLS 加密,并在 agent 侧做对应配置:

 services:
   woodpecker-agent:
     [...]
     environment:
       - [...]
+      - WOODPECKER_GRPC_SECURE=true # defaults to false
+      - WOODPECKER_GRPC_VERIFY=true # default
  • WOODPECKER_GRPC_SECURE:是否使用 TLS 连接(默认 false);
  • WOODPECKER_GRPC_VERIFY:是否校验 server 证书(默认 true,仅当 GRPC_SECURE=true 时生效)。

从源码看,agent 拨号时正是依据这两个开关选择传输层:Secure 为真时使用 crypto/tls 凭据(InsecureSkipVerify 对应 SkipTLSVerify),否则使用 insecure.NewCredentials(),同时还会设置 gRPC keepalive 参数(见 agent/rpc/dial.go)。注意:这里的 TLS 指的是 server 与 agent 之间的 gRPC 通道,与反向代理终止的 HTTPS 是两回事。

挂载 Docker socket:agent 执行容器的前提

agent 默认使用 Docker backend,把每个流水线步骤作为独立容器运行,因此必须能访问宿主机的 Docker daemon:

 services:
   [...]
   woodpecker-agent:
     [...]
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock

挂载后,agent 即拥有宿主机的 Docker 权限,可通过它启动、停止步骤容器。若需限制并发,可额外为 agent 设置 WOODPECKER_MAX_WORKFLOWS(默认 1,详见 agent 配置文档)。agent 执行容器的完整行为由 Docker backend 定义,可参考 Docker backend 文档。

敏感数据的处理方式

Compose 配置中难免出现 WOODPECKER_AGENT_SECRET、WOODPECKER_GITHUB_SECRET 等敏感值,原文档给出了三种递进方案:

方案一:.env 文件

在 Compose 文件同目录放置 .env 文件,通过 ${VAR} 占位符引用。这能将密钥与配置分离,但明文存储安全性有限:

WOODPECKER_HOST=https://ci.example.com
WOODPECKER_GITHUB_CLIENT=your_client_id
WOODPECKER_GITHUB_SECRET=your_client_secret
WOODPECKER_AGENT_SECRET=your_agent_secret

方案二:Docker secrets + *_FILE 变量

Compose/Swarm 的 secrets 机制可将敏感值注入容器文件系统(如 /run/secrets/)。考虑到直接用 secrets 填充环境变量比较繁琐,Woodpecker 为所有敏感配置变量提供了对应的 *_FILE 变体:server 会优先尝试从指定文件读取值;若同名环境变量同时存在,则以环境变量为准(该优先级关系体现在源码的 cli.NewValueSourceChain(cli.File(...), cli.EnvVar(...)) 值源链中,见 cmd/server/flags.go)。

 services:
   woodpecker-server:
     [...]
     environment:
       - [...]
+      - WOODPECKER_AGENT_SECRET_FILE=/run/secrets/woodpecker-agent-secret
+    secrets:
+      - woodpecker-agent-secret
+
+ secrets:
+   woodpecker-agent-secret:
+     external: true

创建外部 secret 的命令:

echo "my_agent_secret_key" | docker secret create woodpecker-agent-secret -

除 WOODPECKER_AGENT_SECRET_FILE 外,同类 *_FILE 变体还包括 WOODPECKER_GRPC_SECRET_FILE、WOODPECKER_DATABASE_DATASOURCE_FILE、WOODPECKER_PROMETHEUS_AUTH_TOKEN_FILE、WOODPECKER_GITHUB_CLIENT_FILE/WOODPECKER_GITHUB_SECRET_FILE 等,完整清单见 server 配置文档 与 agent 配置文档。

补充:对于多副本高可用部署,server 配置文档 建议同时显式配置并持久化 WOODPECKER_GRPC_SECRET(gRPC JWT 签名密钥)。若留空,server 每次启动都会生成临时密钥并打印警告,导致 HA 多副本互相拒绝对方签发的 gRPC token。

SELinux 环境注意事项

在启用 SELinux 的系统(RHEL、CentOS、Fedora 等)上,容器挂载宿主机路径时可能需要给卷挂载附加 :z 或 :Z 选项,例如 Docker socket:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock:z
  • :z:共享挂载(多个容器可访问);
  • :Z:私有挂载(仅当前容器可访问)。

更完整的 SELinux 解决方案(含 server 数据卷等场景)参见仓库内的 Troubleshooting 文档。

进阶:反向代理与外部数据库

原文档与本仓库的安装体系还覆盖了常见的生产化改造:

  • 反向代理:server 仅需暴露 8000 端口,前置 Nginx 时务必透传 X-Forwarded-For、X-Forwarded-Proto、Host 头,并关闭缓冲(proxy_buffering off);若需为 gRPC 也做代理,可用 Caddy 的 h2c:// 或 Traefik 的 h2c scheme 转发到 9000 端口。完整配置示例见 server 配置文档。

  • 替换 SQLite:默认内置 SQLite 零配置即可运行,但生产环境可切换到 MySQL/MariaDB 或 PostgreSQL(后者要求版本 ≥ 11)。注意 Woodpecker 不会自动建库,需手动 CREATE DATABASE,且数据库迁移会自动执行、备份需自行通过第三方工具完成。配置示例:

    WOODPECKER_DATABASE_DRIVER=postgres
    WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/woodpecker?sslmode=disable
    

    详见 server 配置文档。

底层原理:agent 如何注册与拨号

Compose 方案中所有 agent 共用同一个 WOODPECKER_AGENT_SECRET(即“系统 token”),其注册与鉴权流程可以在源码中完整还原:

  1. agent 首次连接 server 时携带系统 token;
  2. server 校验后将该 agent 注册进数据库,并回发一个唯一 agent_id;
  3. agent 把 agent_id 写入 WOODPECKER_AGENT_CONFIG_FILE(默认 /etc/woodpecker/agent.conf,对应 Compose 中挂载的 woodpecker-agent-config 卷)——该读写逻辑见 cmd/agent/core/config.go,文件内容为 JSON 形式的 {"agent_id": ...};
  4. 后续启动时,agent 同时使用系统 token 与 agent_id 向 server 表明身份。

实际建连过程由 agent/rpc/dial.go 的 Dial 函数完成:先建立一条认证 gRPC 连接完成鉴权,再基于鉴权结果创建带 unary/stream 拦截器的主连接,同时按配置决定是否启用 TLS。agent 端还支持 WOODPECKER_AGENT_SECRET_FILE 从文件读取共享密钥(见 agent 配置文档)。

补充:若希望为单个 agent 分配独立 token,可在 server Web UI 的 Settings → Agents → Add agent 手动注册并生成专属 token(即“agent token”),再将其配置到该 agent 的 WOODPECKER_AGENT_SECRET,注册流程详见 agent 配置文档。

启动与验证

在 docker-compose.yaml 所在目录执行:

docker compose up -d

启动后:

  • 通过 http://<host>:8000 访问 Web UI,首次访问使用 forge 账号完成 OAuth 登录;
  • 在 UI 的 Agents 页面应能看到已注册的 agent 处于在线状态;
  • 若需要调试,可在 server 上设置 WOODPECKER_LOG_LEVEL=debug(可选值 trace/debug/info/warn/error/fatal/panic/disabled)查看 gRPC 与调度日志。

至此,一套连接 GitHub、内置 SQLite、具备持久化与基本安全措施的 Woodpecker 实例即部署完成。后续可按需叠加反向代理、外部数据库、多 agent 扩容(WOODPECKER_MAX_WORKFLOWS、自定义 agent labels)以及 autoscaler 等能力。

登录后查看全文
woodpecker