使用 Docker Compose 部署 Woodpecker CI/CD:server 与 agent 的完整安装配置指南
使用 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”),其注册与鉴权流程可以在源码中完整还原:
- agent 首次连接 server 时携带系统 token;
- server 校验后将该 agent 注册进数据库,并回发一个唯一
agent_id; - agent 把
agent_id写入WOODPECKER_AGENT_CONFIG_FILE(默认/etc/woodpecker/agent.conf,对应 Compose 中挂载的woodpecker-agent-config卷)——该读写逻辑见 cmd/agent/core/config.go,文件内容为 JSON 形式的{"agent_id": ...}; - 后续启动时,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 等能力。