Woodpecker CI 代理(Agent)配置完全指南

Woodpecker CI 代理(Agent)配置完全指南

woodpecker Woodpecker is a simple CI engine with great extensibility. 项目地址: https://gitcode.com/gh_mirrors/wo/woodpecker

什么是 Woodpecker CI 代理

Woodpecker CI 代理是 Woodpecker 持续集成系统中的工作节点，负责实际执行构建任务。代理与服务器(Server)协同工作，构成分布式 CI/CD 流水线执行环境。理解如何正确配置代理对于构建稳定高效的 CI 系统至关重要。

基础配置要求

每个 Woodpecker 代理至少需要以下两个核心配置项：

WOODPECKER_SERVER=localhost:9000
WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here"

• WOODPECKER_SERVER：指定 Woodpecker 服务器地址
• WOODPECKER_AGENT_SECRET：用于代理与服务器之间的安全通信密钥

代理并行处理能力

默认情况下，每个代理同时只能执行一个工作流(workflow)。通过调整 WOODPECKER_MAX_WORKFLOWS 参数可以提升代理的并行处理能力：

WOODPECKER_MAX_WORKFLOWS=4

这个值应根据代理主机的 CPU 核心数、内存大小等资源情况合理设置。过高的并行度可能导致资源争用，反而降低整体性能。

代理身份验证机制

Woodpecker 提供两种代理身份验证方式，适用于不同场景：

1. 系统密钥(System Secret)方式

这是最简单的验证方式，适合小型部署环境：

1. 服务器和所有代理使用相同的 WOODPECKER_AGENT_SECRET
2. 首次连接时，服务器自动为代理生成唯一 ID
3. 代理将 ID 保存在 WOODPECKER_AGENT_CONFIG_FILE 指定路径
4. 后续启动时，代理同时使用系统密钥和 ID 进行身份验证

2. 代理密钥(Agent Secret)方式

适合需要精细控制的中大型部署环境：

1. 管理员在服务器 UI 中手动创建代理并获取唯一密钥
2. 将密钥通过 WOODPECKER_AGENT_SECRET 配置给特定代理
3. 代理使用专属密钥连接服务器

这种方式便于追踪每个代理的运行状态，也更容易实现代理的单独管理。

关键环境变量详解

网络连接配置

• WOODPECKER_SERVER：服务器 gRPC 地址(默认 localhost:9000)
• WOODPECKER_GRPC_SECURE：是否启用安全传输(默认 false)
• WOODPECKER_GRPC_VERIFY：是否验证服务器证书(默认 true)

身份认证配置

• WOODPECKER_AGENT_SECRET：认证密钥(必填)
• WOODPECKER_AGENT_SECRET_FILE：从文件读取密钥的路径
• WOODPECKER_USERNAME：gRPC 用户名(默认 x-oauth-basic)

运行参数配置

• WOODPECKER_HOSTNAME：代理主机名(默认使用系统主机名)
• WOODPECKER_MAX_WORKFLOWS：并行工作流数量(默认 1)
• WOODPECKER_BACKEND：执行引擎类型(docker/kubernetes/local)

健康检查配置

• WOODPECKER_HEALTHCHECK：是否启用健康检查(默认 true)
• WOODPECKER_HEALTHCHECK_ADDR：健康检查地址(默认 :3000)

连接保持配置

• WOODPECKER_KEEPALIVE_TIME：空闲连接保持时间
• WOODPECKER_KEEPALIVE_TIMEOUT：保持连接超时时间(默认 20s)

高级配置建议

代理标签管理

通过 WOODPECKER_AGENT_LABELS 可以为代理设置自定义标签，实现工作流定向调度：

WOODPECKER_AGENT_LABELS="gpu=true,os=linux,region=us-east"

标签支持通配符(*)，例如 repo=* 表示匹配所有代码库。

连接重试策略

在网络不稳定的环境中，可以调整连接重试参数：

WOODPECKER_CONNECT_RETRY_COUNT=10
WOODPECKER_CONNECT_RETRY_DELAY=5s

日志调试配置

调试时可调整日志级别和格式：

WOODPECKER_LOG_LEVEL=debug
WOODPECKER_DEBUG_PRETTY=true
WOODPECKER_DEBUG_NOCOLOR=false

最佳实践

1. 生产环境建议使用代理密钥方式验证
2. 根据主机资源配置合理的 MAX_WORKFLOWS 值
3. 为不同用途的代理设置明确的标签
4. 启用健康检查并监控代理状态
5. 安全传输应配合证书验证使用

通过合理配置 Woodpecker 代理，可以构建出稳定高效的 CI/CD 执行环境，满足从简单到复杂的各种自动化需求。

woodpecker Woodpecker is a simple CI engine with great extensibility. 项目地址: https://gitcode.com/gh_mirrors/wo/woodpecker