Woodpecker CI 代理(Agent)配置完全指南
概述
Woodpecker CI 是一个简单而强大的持续集成/持续部署(CI/CD)引擎，其代理(Agent)系统是其分布式架构的核心组件。代理负责执行实际的流水线任务，与服务器(Server)协同工作，实现高效的CI/CD流程。
本文将深入探讨Woodpecker Agent的完整配置指南，涵盖从基础设置到高级优化的各个方面。
核心架构
基础配置
最小配置要求
每个Woodpecker Agent至少需要以下两个环境变量：
WOODPECKER_SERVER=localhost:9000
WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here"
环境变量详解
| 变量名 | 默认值 | 描述 | 必需 |
|---|---|---|---|
WOODPECKER_SERVER | localhost:9000 | 服务器gRPC地址 | ✅ |
WOODPECKER_AGENT_SECRET | 无 | 共享密钥，用于身份验证 | ✅ |
WOODPECKER_HOSTNAME | 系统主机名 | 代理主机名标识 | ❌ |
WOODPECKER_MAX_WORKFLOWS | 1 | 并行工作流数量 | ❌ |
代理认证机制
Woodpecker支持两种代理认证方式：
1. 系统令牌(System Token)方式
2. 代理令牌(Agent Token)方式
完整配置示例
Docker Compose部署
version: '3'
services:
woodpecker-agent:
image: woodpeckerci/woodpecker-agent:latest
environment:
- WOODPECKER_SERVER=woodpecker-server:9000
- WOODPECKER_AGENT_SECRET=your-secret-key-here
- WOODPECKER_MAX_WORKFLOWS=4
- WOODPECKER_HOSTNAME=agent-01
- WOODPECKER_BACKEND=docker
- WOODPECKER_LOG_LEVEL=info
volumes:
- /var/run/docker.sock:/var/run/docker.sock
depends_on:
- woodpecker-server
restart: unless-stopped
系统服务配置(Systemd)
创建服务文件 /etc/systemd/system/woodpecker-agent.service：
[Unit]
Description=Woodpecker CI Agent
After=network.target
Requires=network.target
[Service]
Type=simple
User=woodpecker
Group=woodpecker
EnvironmentFile=/etc/woodpecker/agent.env
ExecStart=/usr/local/bin/woodpecker-agent
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
环境配置文件 /etc/woodpecker/agent.env：
WOODPECKER_SERVER=woodpecker.example.com:9000
WOODPECKER_AGENT_SECRET=your-generated-secret
WOODPECKER_MAX_WORKFLOWS=2
WOODPECKER_HOSTNAME=production-agent-01
WOODPECKER_LOG_LEVEL=info
WOODPECKER_BACKEND=docker
高级配置选项
后端引擎配置
Woodpecker支持多种后端引擎：
| 后端类型 | 配置变量 | 适用场景 |
|---|---|---|
| Docker | WOODPECKER_BACKEND=docker | 单机/开发环境 |
| Kubernetes | WOODPECKER_BACKEND=kubernetes | 生产集群环境 |
| Local | WOODPECKER_BACKEND=local | 直接本地执行 |
Docker后端配置示例
WOODPECKER_BACKEND=docker
WOODPECKER_BACKEND_DOCKER_NETWORK=woodpecker
WOODPECKER_BACKEND_DOCKER_VOLUMES=/var/run/docker.sock:/var/run/docker.sock
Kubernetes后端配置示例
WOODPECKER_BACKEND=kubernetes
WOODPECKER_BACKEND_K8S_NAMESPACE=woodpecker
WOODPECKER_BACKEND_K8S_STORAGE_CLASS=standard
网络与安全配置
# gRPC安全连接
WOODPECKER_GRPC_SECURE=true
WOODPECKER_GRPC_VERIFY=true
# 连接重试配置
WOODPECKER_CONNECT_RETRY_COUNT=10
WOODPECKER_CONNECT_RETRY_DELAY=5s
# 健康检查
WOODPECKER_HEALTHCHECK=true
WOODPECKER_HEALTHCHECK_ADDR=:3000
标签过滤系统
Woodpecker Agent支持标签系统，用于工作流过滤：
WOODPECKER_AGENT_LABELS=env=production,arch=amd64,team=backend
在流水线配置中使用标签过滤：
labels:
- env=production
- arch=amd64
性能优化配置
并行处理优化
# 增加并行工作流数量
WOODPECKER_MAX_WORKFLOWS=8
# 调整资源限制
WOODPECKER_BACKEND_DOCKER_MEMORY_LIMIT=4g
WOODPECKER_BACKEND_DOCKER_CPU_LIMIT=4
连接池优化
# gRPC连接保持
WOODPECKER_KEEPALIVE_TIME=30s
WOODPECKER_KEEPALIVE_TIMEOUT=10s
监控与日志配置
日志级别配置
WOODPECKER_LOG_LEVEL=debug
WOODPECKER_DEBUG_PRETTY=true
WOODPECKER_DEBUG_NOCOLOR=false
健康监控端点
# 检查代理健康状态
curl http://localhost:3000/healthz
故障排除指南
常见问题及解决方案
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 代理无法连接服务器 | 网络问题或密钥错误 | 检查网络连通性和密钥配置 |
| 工作流执行失败 | 资源不足或权限问题 | 调整资源限制和权限配置 |
| 并行处理性能差 | MAX_WORKFLOWS设置过低 | 增加并行工作流数量 |
诊断命令
# 检查代理状态
systemctl status woodpecker-agent
# 查看代理日志
journalctl -u woodpecker-agent -f
# 测试服务器连接
nc -zv woodpecker-server 9000
最佳实践
安全实践
-
使用强密钥：生成32字节的随机密钥
openssl rand -hex 32 -
最小权限原则：为代理配置最小必要的系统权限
-
网络隔离：将代理部署在隔离的网络环境中
高可用部署
监控告警配置
建议监控以下指标：
- 代理连接状态
- 工作流执行成功率
- 系统资源使用率
- 网络延迟和吞吐量
总结
Woodpecker CI Agent的配置虽然简单，但提供了丰富的定制选项来满足不同场景的需求。通过合理的配置，可以实现：
- 高性能：通过并行处理和资源优化
- 高可用：通过集群部署和负载均衡
- 安全性：通过严格的权限控制和网络隔离
- 可维护性：通过完善的监控和日志系统
掌握Woodpecker Agent的配置技巧，将帮助您构建稳定、高效的CI/CD流水线，提升软件交付效率和质量。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
