Woodpecker 的 Docker Compose 部署指南:Server 与 Agent 双容器配置详解
Woodpecker 的 Docker Compose 部署指南:Server 与 Agent 双容器配置详解
本篇技术指南以 Woodpecker 官方安装文档为主体,讲解如何使用 Docker Compose 在单台主机上以「Server + Agent」双容器方式部署一套完整的 CI/CD 实例,并接入 GitHub 作为代码托管平台(Forge)。阅读完本文,你将能够:编写一份可直接运行的 docker-compose.yaml;正确配置 WOODPECKER_HOST、WOODPECKER_AGENT_SECRET、gRPC 端口与 TLS 等关键参数;使用 Docker Secrets 与 *_FILE 环境变量妥善处理敏感数据;并在 SELinux 环境下正确挂载 Docker Socket。
部署架构与前置准备
Compose 部署模式将 Woodpecker 拆分为两个服务:
- woodpecker-server:负责 Web UI、REST API、调度与状态持久化,容器内监听 HTTP 端口
8000与 gRPC 端口9000; - woodpecker-agent:作为执行者,向 Server 的 gRPC 端口发起长连接领取任务,并通过挂载的
/var/run/docker.sock以 Docker 容器方式运行流水线步骤。
官方安装文档中的示例默认连接 GitHub(WOODPECKER_GITHUB=true)。如果使用 Gitea、Forgejo、GitLab、Bitbucket 等其他 Forge,只需要切换对应的开关与密钥变量,参见 Forge 总览 与各 Forge 的配置文档(如 GitHub 配置)。
在启动之前,你需要先在 Forge 上注册一个 OAuth App(GitHub 路径为 Settings -> Developer Settings -> GitHub Apps -> New Oauth2 App),获取 Client ID 与 Client Secret。注意:应注册 OAuth2 App 而非 "GitHub App",后者因用户访问令牌不会自动刷新,当前无法与 Woodpecker 正常工作。注册时:
- Homepage URL 填你的 Woodpecker 实例地址;
- Callback URL 填
https://<your-woodpecker-instance>/authorize。
一份完整的 docker-compose.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:
使用 docker compose up -d 即可启动。仓库根目录还提供了一份带网络隔离与健康检查的参考示例 docker-compose.example.yaml,其中增加了自定义 networks、WOODPECKER_ADMIN、WOODPECKER_MAX_WORKFLOWS 以及 depends_on 的 condition: service_healthy 等待逻辑,可作为进阶模板参考。
关键配置逐项解读
数据持久化:/var/lib/woodpecker 必须挂载
Server 默认使用内嵌的 SQLite 数据库,存储于容器内 /var/lib/woodpecker/,其中保存了全部用户与仓库信息,是整个部署中最重要的数据。Compose 示例通过命名卷 woodpecker-server-data 挂载该目录:
volumes:
- woodpecker-server-data:/var/lib/woodpecker/
从源码看,容器环境下数据库文件的默认路径就是 /var/lib/woodpecker/woodpecker.sqlite——datasourceDefaultValue() 在检测到 WOODPECKER_IN_CONTAINER 环境变量后返回该路径(见 cmd/server/flags.go)。若希望切换到 MySQL/MariaDB 或 PostgreSQL,可参考 Server 数据库配置 中的 WOODPECKER_DATABASE_DRIVER 与 WOODPECKER_DATABASE_DATASOURCE 说明。
同时,Agent 的配置卷 woodpecker-agent-config:/etc/woodpecker 也不是摆设:Agent 首次连接 Server 时,Server 会为其分配唯一 ID,Agent 将其持久化到配置文件(默认 /etc/woodpecker/agent.conf,由 WOODPECKER_AGENT_SECRET 之外的 WOODPECKER_AGENT_CONFIG_FILE 指定),后续重启时凭「系统令牌 + Agent ID」重新识别身份。读写逻辑可见 cmd/agent/core/config.go 中的 readAgentConfig / writeAgentConfig:配置不存在时以默认 ID(-1)启动并打印日志,存在且内容有变化时才写回磁盘。因此务必持久化该目录,否则 Agent 每次重启都会被当作新节点。
声明自身地址:WOODPECKER_HOST
Woodpecker 必须知道自己的对外地址,格式为 <scheme>://<hostname>,不要带末尾斜杠:
services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_HOST=${WOODPECKER_HOST}
该变量同时影响 OAuth 回调、Webhook 推送与 UI 内链接的生成。支持带端口与路径前缀的形式,例如:
WOODPECKER_HOST=http://woodpecker.example.orgWOODPECKER_HOST=http://example.org/woodpeckerWOODPECKER_HOST=http://example.org:1234/woodpecker
更多细节见 Server 配置文档 中的 HOST 小节。
定制监听端口:HTTP 与 gRPC 分离
Woodpecker 为 HTTP 与 gRPC 使用两个独立端口:Agent 通过 gRPC 与 Server 通信,默认监听 :9000;Web UI / API 走 HTTP,默认监听 :8000。两者均可通过 *_ADDR 系列变量覆盖:
services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_GRPC_ADDR=${WOODPECKER_GRPC_ADDR}
+ - WOODPECKER_SERVER_ADDR=${WOODPECKER_HTTP_ADDR}
对应源码见 cmd/server/flags.go:--server-addr(默认 :8000)、--grpc-addr(默认 :9000),两者均支持 unix:// 前缀以 unix socket 方式监听。Compose 示例中 ports: - 8000:8000 将 HTTP 端口暴露到宿主机,供浏览器访问或置于反向代理之后;gRPC 端口默认不对外暴露,仅用于容器网络内 Agent 连接。
公网连接时的 gRPC TLS
如果 Agent 与 Server 之间通过互联网建立连接,应为 gRPC 开启 TLS 加密,并同步配置 Agent:
services:
woodpecker-agent:
[...]
environment:
- [...]
+ - WOODPECKER_GRPC_SECURE=true # defaults to false
+ - WOODPECKER_GRPC_SKIP_VERIFY=false # default
WOODPECKER_GRPC_SECURE:是否使用 TLS 安全传输,默认false;WOODPECKER_GRPC_SKIP_VERIFY:是否校验证书,默认值官方文档标注为false(Agent 配置文档中标注默认true,建议按你的部署环境显式设置),仅在GRPC_SECURE=true时生效。
Agent 侧完整变量说明见 Agent 配置文档。
挂载 Docker Socket
Agent 以 Docker 容器方式执行流水线步骤,因此必须访问宿主机的 Docker 守护进程:
services:
[...]
woodpecker-agent:
[...]
+ volumes:
+ - /var/run/docker.sock:/var/run/docker.sock
这是 Agent 能够创建、启动流水线步骤容器的前提;在 SELinux 系统上还需要为挂载附加 :z 或 :Z 标签(见下文)。
指定 Server 地址:WOODPECKER_SERVER
Agent 需要知道 Server 的 gRPC 地址才能建立连接。在 Compose 网络中,直接使用服务名即可:
services:
woodpecker-agent:
[...]
environment:
+ - WOODPECKER_SERVER=woodpecker-server:9000
该变量默认值为 localhost:9000,同样支持 unix:// 前缀的 unix socket(见 Agent 配置文档 的 SERVER 小节)。
共享认证密钥:WOODPECKER_AGENT_SECRET
Server 与 Agent 使用同一个共享密钥认证彼此通信,该值必须是随机字符串且严格保密,可通过如下命令生成:
openssl rand -hex 32
services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
woodpecker-agent:
[...]
environment:
- [...]
+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
该密钥在源码中通过 --agent-secret 参数解析,支持环境变量与文件两种取值来源(见 cmd/server/flags.go)。它属于“系统令牌”模式——所有 Agent 共享同一令牌;如需为单个 Agent 分配独立令牌,可在 UI 的 Settings -> Agents -> Add agent 中手动注册后,将生成的令牌作为该 Agent 的 WOODPECKER_AGENT_SECRET,详见 Agent 配置文档 的「Agent registration」一节。
敏感数据处理的三种方式
在 docker compose 或 docker swarm 配置中处理敏感数据有以下几种可选方案:
方式一:.env 文件
在 Compose 配置文件旁放置 .env 文件,把 WOODPECKER_GITHUB_CLIENT、WOODPECKER_GITHUB_SECRET、WOODPECKER_AGENT_SECRET、WOODPECKER_HOST 等变量值存放其中,实现“配置与密钥分离”。官方文档明确指出:这种方式只是把密钥移出了 Compose 文件,安全性仍然有限,适合快速上手,不建议生产环境仅依赖它。
方式二:Docker Secrets + *_FILE 变量(推荐)
直接用 docker-secrets 为环境变量注入值通常较为繁琐,因此 Woodpecker 为所有敏感配置变量提供了对应的 *_FILE 选项:设置后,Woodpecker 会尝试直接从该文件读取值。注意文档强调:如果同一时刻同时指定了原环境变量,环境变量的值会覆盖从文件读取的值。对应实现同样在 cmd/server/flags.go 的取值链(cli.File(...) 与 cli.EnvVar(...) 组合)中,AGENT_SECRET_FILE、GRPC_SECRET_FILE、DATABASE_DATASOURCE_FILE、PROMETHEUS_AUTH_TOKEN_FILE 以及各 Forge 的 *_CLIENT_FILE / *_SECRET_FILE 均采用此机制。
以 WOODPECKER_AGENT_SECRET 为例:
services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_AGENT_SECRET_FILE=/run/secrets/woodpecker-agent-secret
+ secrets:
+ - woodpecker-agent-secret
+
+ secrets:
+ woodpecker-agent-secret:
+ external: true
在 Swarm 模式下创建该 Secret:
echo "my_agent_secret_key" | docker secret create woodpecker-agent-secret -
创建后,Compose 会把它挂载为容器内 /run/secrets/woodpecker-agent-secret 文件,Server 启动时自动读取。该模式同样适用于 WOODPECKER_GITHUB_SECRET_FILE、WOODPECKER_GRPC_SECRET_FILE 等其余敏感项,且文件值优先于冗长的内联环境变量,更利于审计与轮换。
SELinux 环境注意事项
如果你的主机启用了 SELinux(RHEL、CentOS、Fedora 等),SELinux 可能拦截 Agent 访问 Docker Socket,典型报错为:
permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock
最简单的修复方式是为 Socket 挂载附加 :z 或 :Z 标签,让 Docker 自动为卷内容重打 SELinux 标签:
volumes:
- /var/run/docker.sock:/var/run/docker.sock:z
:z 表示自动重标卷内容(共享语义),:Z 则将卷标记为仅此容器可用,使用时需谨慎。更多 SELinux 解决方案(临时/永久设为 Permissive 模式、通过 audit2allow 生成自定义策略模块、改用 Podman 等)参见 Troubleshooting 文档。
从源码看配置解析的底层逻辑
上述所有 WOODPECKER_* 环境变量最终都会映射为 Server / Agent 进程的 CLI 标志,统一由 cmd/server/flags.go 与 cmd/agent 下的标志定义解析。几个值得注意的细节:
- 取值链(Value Source Chain):敏感项普遍采用「文件优先、环境变量兜底」的链式取值,例如
WOODPECKER_AGENT_SECRET_FILE与WOODPECKER_AGENT_SECRET共用同一个--agent-secret标志,避免在进程参数中泄漏密钥; - 容器感知的默认值:通过
WOODPECKER_IN_CONTAINER环境变量判断运行环境,容器内 SQLite 默认路径为/var/lib/woodpecker/woodpecker.sqlite(cmd/server/flags.go); - Agent 配置持久化:Agent 的 ID 等元数据写入
WOODPECKER_AGENT_CONFIG_FILE(默认/etc/woodpecker/agent.conf),与 Compose 中woodpecker-agent-config:/etc/woodpecker卷一一对应(cmd/agent/core/config.go)。
启动后的验证与延伸
启动后通过宿主机的 8000 端口(或你配置的反向代理)访问 Web UI。若流水线克隆仓库时出现 fatal: could not read Username 之类的问题,可参考 Troubleshooting 文档 中的「How to debug clone issues」一节排查网络与认证问题。
如需进一步调优,可重点阅读:
- Server 配置文档:数据库、TLS、反向代理(Apache/Nginx/Caddy/Traefik)、Prometheus 指标等;
- Agent 配置文档:
WOODPECKER_MAX_WORKFLOWS并行数、Agent 标签与过滤器、重连策略等; - GitHub Forge 配置:
WOODPECKER_GITHUB_URL、WOODPECKER_GITHUB_PUBLIC_ONLY等进阶选项; - 仓库自带的 docker-compose.example.yaml:包含健康检查依赖与自定义网络的生产级模板。