Woodpecker 的 Docker Compose 部署指南:Server 与 Agent 双容器配置详解

原创2026-09-26 20:57:282,161 阅读
文章标签:CI/CDDevOps

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.org
  • WOODPECKER_HOST=http://example.org/woodpecker
  • WOODPECKER_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:包含健康检查依赖与自定义网络的生产级模板。
登录后查看全文
woodpecker