使用 Docker Compose 部署 Woodpecker：Server 与 Agent 容器化安装实战指南

CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载本指南以 Woodpecker 官方 Docker Compose 部署方案为主线完整讲解如何在一台主机上用docker compose同时启动 Woodpecker 服务端server与执行器agent并接入 GitHub或其他 Forge实现 CI/CD。读完本文你将掌握完整可运行的 compose 配置、各关键环境变量的含义与默认值、gRPC 通信与 TLS 安全配置、敏感数据的多种处理方式以及 SELinux 环境下常见问题的排查思路所有结论均对照当前仓库的文档与源码逐一验证。部署架构与前置条件组件构成Server 与 Agent 的职责分工Woodpecker 的容器化部署由两个核心镜像组成woodpeckerci/woodpecker-server:v3负责 Web UI、REST API、与 ForgeGitHub、Gitea、GitLab 等的 OAuth 集成、调度与状态管理内嵌 SQLite 数据库woodpeckerci/woodpecker-agent:v3负责实际执行流水线将每个 step 作为独立容器运行在 Docker daemon 上。官方推荐的 compose 示例对应 docs/versioned_docs/version-3.16/30-administration/05-installation/10-docker-compose.md默认连接 GitHubWOODPECKER_GITHUBtrue。若使用其他 Forge需同步替换相应的环境变量与密钥设置例如 GitLab 使用WOODPECKER_GITLAB_*、Gitea 使用WOODPECKER_GITEA_*系列变量详见 12-forges 目录。前置步骤注册 OAuth App启动前必须在你的 Forge 上注册一个 OAuth App。以 GitHub 为例详见 20-github.md在 GitHub 的Settings - Developer Settings - GitHub Apps - New OAuth2 App注册Homepage URL 填写 Woodpecker 实例的地址Callback URL 填写https://your-woodpecker-instance/authorize注册后生成的 Client ID 与 Client Secret 分别对应WOODPECKER_GITHUB_CLIENT与WOODPECKER_GITHUB_SECRET。注意请使用 OAuth2 App 而非 GitHub App后者目前无法与 Woodpecker 正确配合工作用户访问令牌不会被自动刷新。用 .env 文件管理变量compose 文件中的${WOODPECKER_HOST}、${WOODPECKER_GITHUB_CLIENT}等占位符由同目录下的.env文件提供。建议在部署目录创建.env并写入以下内容WOODPECKER_HOSThttps://ci.example.com WOODPECKER_GITHUB_CLIENTYOUR_GITHUB_CLIENT_ID WOODPECKER_GITHUB_SECRETYOUR_GITHUB_CLIENT_SECRET WOODPECKER_AGENT_SECRETopenssl-rand-生成的随机字符串仓库根目录还提供了一个可参考的完整示例 docker-compose.example.yaml其中额外展示了自定义网络、健康检查等待条件与WOODPECKER_MAX_WORKFLOWS的用法可作为进一步定制的模板。完整的 docker-compose.yaml 与逐项解读基础示例可复制运行以下为官方文档提供的完整 compose 配置services: woodpecker-server: image: woodpeckerci/woodpecker-server:v3 ports: - 8000:8000 volumes: - woodpecker-server-data:/var/lib/woodpecker/ environment: - WOODPECKER_OPENtrue - WOODPECKER_HOST${WOODPECKER_HOST} - WOODPECKER_GITHUBtrue - 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_SERVERwoodpecker-server:9000 - WOODPECKER_AGENT_SECRET${WOODPECKER_AGENT_SECRET} volumes: woodpecker-server-data: woodpecker-agent-config:关键设计点说明持久化卷woodpecker-server-data挂载到/var/lib/woodpecker/。内嵌的 SQLite 数据库就存储于此容器内默认路径为/var/lib/woodpecker/woodpecker.sqlite见 10-server.md它保存着全部用户与仓库信息是整个部署中最需要持久化的部分务必使用命名卷或绑定挂载否则容器重建即数据丢失。端口映射server 默认监听 HTTP 端口8000此处直接暴露到宿主机。你可以通过该端口直接访问也可以在其前方再架设反向代理如 Nginx、Caddy、Traefik。agent 配置目录woodpecker-agent-config挂载到/etc/woodpecker用于保存 agent 的配置文件。agent 首次连接 server 后会把服务器下发的唯一 ID 写入该目录下的配置文件中后续重启即可凭此识别身份详见下文“Agent 注册机制”。Docker socketagent 以 Docker 后端执行流水线因此必须挂载宿主机的/var/run/docker.sock。该 socket 具备宿主机的高权限部署时应确保主机本身安全可信。启动命令为docker compose up -dWOODPECKER_HOST必须显式指定对外地址Woodpecker 必须知道自己的对外地址用于生成 OAuth 回调、Webhook 与各类链接。该变量格式为scheme://hostname不要带尾部斜杠services: woodpecker-server: [...] environment: - [...] - WOODPECKER_HOST${WOODPECKER_HOST}从 10-server.md 的环境变量参考可见WOODPECKER_HOST表示“面向用户的主机名、端口非 HTTP/HTTPS 默认端口时及路径前缀的完整 URL”支持以下形式WOODPECKER_HOSThttp://woodpecker.example.org WOODPECKER_HOSThttp://example.org/woodpecker WOODPECKER_HOSThttp://example.org:1234/woodpecker这也意味着当你在 Nginx 等反向代理后以子路径如/woodpecker暴露服务时同样应在此变量中体现。WOODPECKER_OPEN用户注册开关示例中设置了WOODPECKER_OPENtrue表示允许任何拥有所接入 Forge 账号的用户登录。默认值为false注册关闭。关闭注册时可用 CLIwoodpecker-cli user手动管理用户开放注册时还可以通过WOODPECKER_ADMINuser1,user2指定管理员或用WOODPECKER_ORGSorg1,org2按组织成员身份过滤登录权限。端口定制与 gRPC/HTTP 双通道Woodpecker 的 server 使用两个独立的监听端口HTTP 端口默认:8000变量WOODPECKER_SERVER_ADDR服务 Web UI 与 REST APIgRPC 端口默认:9000变量WOODPECKER_GRPC_ADDR供 agent 连接并上报状态、领取任务。两者分别可用*_ADDR变量自定义且都支持unix://前缀使用 Unix socket例如unix:///run/woodpecker-grpc.sock。对应源码位于 cmd/server/flags.gogrpc-addr与server-addr两个 flag 的默认值分别为:9000与:8000。services: woodpecker-server: [...] environment: - [...] - WOODPECKER_GRPC_ADDR${WOODPECKER_GRPC_ADDR} - WOODPECKER_SERVER_ADDR${WOODPECKER_HTTP_ADDR}修改端口后agent 侧的WOODPECKER_SERVER必须同步指向新的 gRPC 端口。Agent 与 Server 之间的安全通信共享密钥WOODPECKER_AGENT_SECRETserver 与 agent 使用同一个共享密钥认证彼此的通信该密钥应为随机字符串并妥善保密。官方推荐用以下命令生成openssl rand -hex 32然后在两个服务中同时配置services: woodpecker-server: [...] environment: - [...] - WOODPECKER_AGENT_SECRET${WOODPECKER_AGENT_SECRET} woodpecker-agent: [...] environment: - [...] - WOODPECKER_AGENT_SECRET${WOODPECKER_AGENT_SECRET}从源码 cmd/agent/core/flags.go 可以看到agent 侧WOODPECKER_AGENT_SECRET与WOODPECKER_AGENT_SECRET_FILE构成取值链File 优先读取文件内容未指定时回落到环境变量。server 侧的对应实现见 cmd/server/flags.go 中agent-secretflag。另外server 还有一个独立于 agent 共享密钥的WOODPECKER_GRPC_SECRET用于签发 gRPC 连接的 JWT。若该值留空server 每次启动都会生成一个临时密钥并打印警告——这会导致重启后所有 agent 令牌失效因此在多副本高可用HA部署中必须显式配置并持久化可用openssl rand -hex 32生成。Agent 连接地址WOODPECKER_SERVERAgent 需要知道 server 的 gRPC 地址才能建立连接。在 compose 网络中直接使用服务名即可services: woodpecker-agent: [...] environment: - WOODPECKER_SERVERwoodpecker-server:9000WOODPECKER_SERVER的默认值为localhost:9000见 30-agent.md支持unix://前缀的 Unix socket。若 agent 与 server 不在同一主机则填写 server 宿主机的可达地址与 gRPC 端口。Agent 注册机制Agent 启动后使用WOODPECKER_AGENT_SECRET中的令牌连接 server。系统令牌system token模式下注册流程如下详见 30-agent.mdagent 首次与 server 通信时使用系统令牌server 若未见过该 agent则将其登记进数据库并生成唯一 ID 回传给 agentagent 将收到的 ID 存入配置文件默认/etc/woodpecker/agent.conf可用WOODPECKER_AGENT_CONFIG_FILE修改后续启动时agent 使用系统令牌加上收到的 ID 共同标识自己。这也解释了为什么 compose 中要为 agent 挂载持久卷——ID 文件丢失会导致 agent 被当作新节点重新注册。此外管理员也可以在 UI 的Settings - Agents中为每个 agent 单独签发唯一的 agent token。公网场景为 gRPC 启用 TLS如果 agent 通过公网连接 server应当为 gRPC 启用 TLS 加密并同步配置 agentservices: woodpecker-agent: [...] environment: - [...] - WOODPECKER_GRPC_SECUREtrue # defaults to false - WOODPECKER_GRPC_SKIP_VERIFYfalse # 默认跳过校验公网部署建议显式关闭以校验证书其中WOODPECKER_GRPC_SECURE决定是否使用 TLS 传输默认falseWOODPECKER_GRPC_SKIP_VERIFY决定是否校验 server 证书agent 侧默认true即默认跳过校验两者均可在 cmd/agent/core/flags.go 中找到对应定义。请注意WOODPECKER_GRPC_SKIP_VERIFY仅在WOODPECKER_GRPC_SECUREtrue时生效。Agent 执行流水线Docker 后端与 Docker socket挂载 Docker socketAgent 将每个流水线 step 作为独立 Docker 容器执行因此必须访问宿主机的 Docker daemonservices: [...] woodpecker-agent: [...] volumes: - /var/run/docker.sock:/var/run/docker.sock这是 Docker 后端WOODPECKER_BACKEND默认auto-detect时会自动选择 docker的基本要求。关于后端行为的更多说明可参考 11-backends/10-docker.md例如 agent不会自动清理宿主机镜像需要由主机侧的 cron 任务定期执行docker image rm $(docker images --filter danglingtrue -q --no-trunc)与docker volume rm $(docker volume ls --filter name^wp_* --filter danglingtrue -q)等清理工作。并行度与其他常用 Agent 参数WOODPECKER_MAX_WORKFLOWS单个 agent 并行执行的工作流数量默认1。设置更高的值可提升吞吐例如 docker-compose.example.yaml 中使用了WOODPECKER_MAX_WORKFLOWS2WOODPECKER_AGENT_LABELS为 agent 声明标签如platformlinux/amd64流水线可通过标签筛选执行节点WOODPECKER_HOSTNAMEagent 主机名未设置时取操作系统主机名。敏感数据的处理方式docker compose/docker swarm配置中的敏感数据如WOODPECKER_AGENT_SECRET、OAuth 密钥等有以下几种处理途径方式一.env 文件在 compose 文件同目录放置.env文件将密钥存放在 compose 文件之外。这实现了“配置与密钥分离”但.env仍是明文文件安全性有限。方式二Docker Secrets *_FILE 变量推荐用于 swarmdocker-secrets直接用于环境变量比较困难因此 Woodpecker 为所有敏感配置变量都提供了对应的*_FILE选项配置后 Woodpecker 会直接从指定文件读取值。需要注意如果同名环境变量同时存在环境变量的值会覆盖文件读取的值。services: woodpecker-server: [...] environment: - [...] - WOODPECKER_AGENT_SECRET_FILE/run/secrets/woodpecker-agent-secret secrets: - woodpecker-agent-secret secrets: woodpecker-agent-secret: external: true先用以下命令创建 docker secretecho my_agent_secret_key | docker secret create woodpecker-agent-secret -从源码来看这套机制在 server 与 agent 两侧均有落地例如 cmd/server/flags.go 中grpc-secret、agent-secret、database-datasource、prometheus-auth-token等 flag 均通过cli.NewValueSourceChain(cli.File(...), cli.EnvVar(...))实现“文件优先、环境变量兜底”的取值链agent 侧同样为WOODPECKER_AGENT_SECRET提供了WOODPECKER_AGENT_SECRET_FILE。可用的*_FILE变量覆盖范围很广包括 Forge 的 client/secret如WOODPECKER_GITHUB_CLIENT_FILE、WOODPECKER_GITHUB_SECRET_FILE、数据库连接串WOODPECKER_DATABASE_DATASOURCE_FILE、监控令牌WOODPECKER_PROMETHEUS_AUTH_TOKEN_FILE等。更完整的 server 端变量清单可查阅 10-server.mdagent 端见 30-agent.md。SELinux 环境下的特殊处理如果宿主系统启用了 SELinux如 RHEL、CentOS、Fedora 等 Enterprise Linux 发行版SELinux 可能会阻止 agent 访问 Docker socket典型报错为permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock最简单的解决方式是给卷挂载加上:z或:Z选项volumes: - /var/run/docker.sock:/var/run/docker.sock:zz选项让 Docker 自动重新标记卷内容以适配 SELinuxZ则将该卷标记为仅此容器独占使用需谨慎。若仍有问题Troubleshooting 页面 还给出了另外几种思路临时以setenforce 0进入 permissive 模式验证问题仅建议测试环境、使用ausearch/audit2allow生成并加载自定义 SELinux 策略模块推荐做法或改用 SELinux 集成更友好的 Podman 作为替代方案。进阶数据库、健康检查与反向代理替换默认的 SQLite 数据库默认数据库为内嵌 SQLite零配置。若需替换为 MySQL/MariaDB 或 PostgreSQL需注意Woodpecker不会自动创建数据库需自行CREATE DATABASE也不负责备份与数据归档但会自动完成表结构与索引的迁移。示例配置WOODPECKER_DATABASE_DRIVERmysql WOODPECKER_DATABASE_DATASOURCEroot:passwordtcp(1.2.3.4:3306)/woodpecker?parseTimetrue或WOODPECKER_DATABASE_DRIVERpostgres WOODPECKER_DATABASE_DATASOURCEpostgres://root:password1.2.3.4:5432/postgres?sslmodedisablePostgreSQL 请使用11 及以上版本。这两个变量的默认值、可选驱动等完整说明见 10-server.md。等待 Server 就绪后再启动 Agentdocker-compose.example.yaml 展示了比基础示例更稳妥的依赖写法——使用健康检查条件避免 agent 在 server 尚未就绪时反复连接失败services: woodpecker-agent: depends_on: woodpecker-server: condition: service_healthy通过反向代理暴露 HTTP 与 gRPC生产环境通常会用反向代理终结 TLS。server 的 HTTP8000与 gRPC9000是两个独立入口代理时需要分别处理。Caddy 的示例如下完整示例见 10-server.md 的 Reverse Proxy 一节# expose WebUI and API woodpecker.example.com { reverse_proxy woodpecker-server:8000 } # expose gRPC woodpecker-agent.example.com { reverse_proxy h2c://woodpecker-server:9000 }gRPC 走 h2c 明文升级由 Caddy 在边缘完成 TLS 终结。此时 agent 侧应设置WOODPECKER_GRPC_SECUREtrue并视证书情况决定WOODPECKER_GRPC_SKIP_VERIFY的值。若使用 Nginx 或 Apache还需注意正确传递X-Forwarded-Proto等代理头否则会因协议判断错误导致回调与 Webhook 异常。常见问题速查重启后 agent 变成新节点多为 agent 配置卷未持久化导致WOODPECKER_AGENT_CONFIG_FILE默认/etc/woodpecker/agent.conf中的 agent ID 丢失请保留woodpecker-agent-config卷。agent 连不上 server确认WOODPECKER_SERVER指向的是 gRPC 端口默认 9000而非 HTTP 端口并确认两个服务的WOODPECKER_AGENT_SECRET完全一致。修改了端口后 Web UI 或回调异常同步检查WOODPECKER_HOST是否包含正确的对外端口以及反向代理是否透传了正确协议头。SELinux 拒绝访问 Docker socket为卷挂载添加:z选项或参考 Troubleshooting 页面 的自定义策略方案。多副本高可用部署必须显式配置并持久化WOODPECKER_GRPC_SECRET否则各副本各自生成临时密钥会互相拒绝对方签发的 gRPC 令牌。以上部署细节均可在仓库中进一步深挖完整的 compose 模板见 docker-compose.example.yamlserver 全部环境变量见 10-server.mdagent 全部环境变量见 30-agent.md对应的参数解析源码可分别查阅 cmd/server/flags.go 与 cmd/agent/core/flags.go。赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐使用 Docker 与 Docker Compose 容器化部署 PostGraphile 与 PostgreSQL 实战指南使用 Docker 与 Docker Compose 容器化部署 PostGraphile 与 PostgreSQL 实战指南 本文是一份面向 V5 版本的完整后端API网关5分钟快速上手Qwen3-ASR-1.7B语音识别服务部署实战教程5分钟快速上手Qwen3 ASR 1.7B语音识别服务部署实战教程 Qwen3 ASR 1.7B是一款基于昇腾NPU优化的语音识别服务能够在华为云昇腾910模型推理服务语音/音频大模型后端KaTeX 社区生态实用指南5 个 contrib 扩展从接入到踩坑KaTeX 社区生态实用指南5 个 contrib 扩展从接入到踩坑 本文按 5 个常见网页场景带你走一遍 KaTeX 扩展在社区生态里的用法自动渲染、公式前端上一篇攻克分布式死锁难题TiDB企业级死锁检测与优化实战指南下一篇YDFID-1色织物图像数据集计算机视觉驱动的纺织品质量检测解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考