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代理是持续集成系统中的工作节点，负责实际执行构建任务。代理通过与主服务器通信获取任务，并在本地环境中运行这些任务。理解代理的配置对于构建高效可靠的CI/CD流水线至关重要。

基础配置

要启动一个Woodpecker CI代理，至少需要配置以下两个参数：

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

• WOODPECKER_SERVER：指定主服务器的地址和端口
• WOODPECKER_AGENT_SECRET：用于代理与服务器之间的安全通信的共享密钥

代理并行处理能力

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

WOODPECKER_MAX_WORKFLOWS=4

这个值应根据代理机器的CPU核心数和内存大小合理设置，过高的值可能导致系统资源耗尽。

代理身份验证机制

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

1. 系统共享密钥方式

这是最简单的验证方式，适用于小型部署：

1. 在服务器和所有代理上配置相同的WOODPECKER_AGENT_SECRET
2. 首次连接时，服务器会自动识别代理并分配唯一ID
3. 代理将ID保存在本地配置文件(WOODPECKER_AGENT_CONFIG_FILE指定路径)
4. 后续启动时，代理会使用共享密钥和ID进行身份验证

2. 独立密钥方式

适用于需要精细控制的生产环境：

1. 管理员在Web界面手动创建代理记录
2. 系统为每个代理生成唯一密钥
3. 将密钥通过WOODPECKER_AGENT_SECRET配置给对应代理
4. 代理使用专属密钥连接服务器

关键环境变量详解

网络连接配置

• 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_AGENT_LABELS：代理标签，用于工作流筛选

健康检查配置

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

高级网络设置

• WOODPECKER_KEEPALIVE_TIME：连接保持活跃时间
• WOODPECKER_KEEPALIVE_TIMEOUT：保持活跃超时时间(默认20s)
• WOODPECKER_CONNECT_RETRY_COUNT：连接重试次数(默认5)
• WOODPECKER_CONNECT_RETRY_DELAY：重试间隔(默认2s)

后端引擎选择

Woodpecker CI支持多种后端执行引擎：

• docker：使用Docker容器运行任务(最常见)
• kubernetes：在K8s集群中运行任务
• local：直接在主机上运行任务
• auto-detect：自动检测可用引擎(默认)

通过WOODPECKER_BACKEND变量指定使用的引擎，不同引擎有各自的配置参数。

最佳实践建议

1. 安全性：生产环境应使用独立密钥方式验证代理，并启用GRPC_SECURE
2. 资源分配：根据代理机器配置合理设置MAX_WORKFLOWS值
3. 标签管理：使用AGENT_LABELS对代理进行分类，便于工作流定向调度
4. 监控：保持健康检查启用，及时发现问题
5. 网络优化：在高延迟环境中适当调整keepalive参数

通过合理配置Woodpecker CI代理，可以构建出高效、可靠的持续集成环境，满足不同规模和复杂度的项目需求。

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