CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载本文以 Woodpecker CI/CD 引擎在 Kubernetes 环境中的部署为主线围绕官方 Helm Chart 的安装命令、Metrics 与 Prometheus PodMonitor 的开启方式展开并结合本仓库服务端源码cmd/server、server/metric、server/api/metrics讲解/metrics端点的底层实现与常见排障点。读者读完可独立完成helm install部署、通过values.yml打开指标采集并正确配置 Prometheus 的命名空间与选择器以稳定收集 Woodpecker 的监控数据。一、概述为什么选择 Helm Chart 部署Woodpecker 官方为 Kubernetes 环境维护了独立的 Helm Chart仓库位置https://github.com/woodpecker-ci/helm。与 docker-compose 部署 不同Helm Chart 适合需要将 Woodpecker Server、Agent 与数据库以声明式资源方式托管在集群中、并与既有 Ingress、Secret、监控体系Prometheus Operator打通的用户。二、最小安装一条命令完成部署在确认 Helm 已安装、kubeconfig已指向目标集群后执行helm install woodpecker oci://ghcr.io/woodpecker-ci/helm/woodpecker --version VERSION要点说明oci://前缀表示直接从 OCI 镜像仓库GHCR拉取 Chart 包无需先执行helm repo addVERSION请替换为与你的 Woodpecker 版本匹配的 Chart 版本可通过helm search repo woodpecker或 Chart 发布记录确认默认 Release 名称为woodpecker如需自定义可在命令中追加--name或改用--generate-name安装前建议先通过helm show values oci://ghcr.io/woodpecker-ci/helm/woodpecker --version VERSION查看该版本 Chart 支持的全部默认值以便基于下面的配置片段做合并覆盖。三、开启 Metrics暴露 /metrics 端点默认情况下 Chart 不会暴露指标端点。在values.yml中加入如下配置即可启用metrics: enabled: true port: 9001配置后的行为服务端会在9001端口提供/metrics端点返回 Prometheus 文本格式的指标该端口默认不对外暴露即不会自动生成 Service/Ingress 的公网访问入口避免未认证的指标端点被外部直接访问若你需要对集群外提供带认证的指标访问请参考 Prometheus 官方文档配置反向代理或认证层而不是直接把该端口暴露到公网。从源码看该端点由两个独立部分组成指标采集服务端启动时调用metric.StartMetricsCollector见 server/metric/metrics_server.go以后台协程周期性更新指标值其中队列类指标pending/waiting/running steps、worker 数每 500ms 刷新一次存储类指标pipeline/user/repo 总数每 10s 刷新一次指标服务仅当WOODPECKER_METRICS_SERVER_ADDR对应metrics-server-addr参数非空时服务端才会启动独立的 HTTP 服务监听/metrics见 cmd/server/server.go该服务直接使用promhttp.Handler()输出指标。Chart 中metrics.enabled与metrics.port正是用于控制此地址与端口的生成。四、开启 Prometheus PodMonitor 自动发现若你的集群使用 Prometheus Operator含 PodMonitor CRD可让 Prometheus 自动发现 Woodpecker 的指标端点prometheus: podmonitor: enabled: true interval: 60s labels: {}参数说明enabled: true创建 PodMonitor 资源将 Woodpecker Pod 的指标端点注册为抓取目标interval: 60sPrometheus 每 60 秒抓取一次可按需调整为30s、15s等更细粒度labels: {}可在此处追加自定义标签如team: platform这些标签会附加到 PodMonitor 资源上便于与podMonitorSelector匹配。五、常见排障PodMonitor 不生效文档明确提示了一个高频问题配置了 PodMonitor 但 Prometheus 始终收不到指标。此时应检查 Prometheus 自身的抓取配置确认命名空间选择器与选择器是否放行# Search all available namespaces podMonitorNamespaceSelector: matchLabels: {} # Enable all available pod monitors podMonitorSelector: matchLabels: {}原理分析Prometheus Operator 默认对 PodMonitor 做两层过滤podMonitorNamespaceSelector决定扫描哪些命名空间podMonitorSelector决定选用哪些 PodMonitor若 Woodpecker 所在的命名空间没有被显式包含且选择器未禁用PodMonitor 便不会被发现从而“静默”丢数据以上配置将两个选择器都置为空匹配matchLabels: {}即扫描所有命名空间、启用全部 PodMonitor。注意这属于放开策略在共享集群中建议改为显式列出 Woodpecker 命名空间或按自定义标签精确匹配避免意外抓取其他命名空间的 PodMonitor。六、深入Woodpecker 暴露了哪些指标启用指标后/metrics端点输出以woodpecker_为命名空间前缀的指标主要包括详见 docs/docs/30-administration/10-configuration/10-server.md 与 server/metric/metrics_server.go指标类型含义woodpecker_pending_stepsgauge等待调度的 pipeline step 数woodpecker_waiting_stepsgauge因依赖未就绪而等待的 step 数woodpecker_running_stepsgauge运行中的 step 数woodpecker_worker_countgauge当前连接的 workeragent数woodpecker_pipeline_total_countgauge历史 pipeline 总数woodpecker_user_countgauge用户总数woodpecker_repo_countgauge仓库总数woodpecker_step_failures_totalcounterstep 失败次数带workflow/repo/step/type标签woodpecker_step_duration_secondshistogramstep 耗时分布桶边界为 1~3600 秒其中step_failures_total与step_duration_seconds属于步骤级指标由WOODPECKER_STEP_LEVEL_METRICS对应参数step-level-metrics默认开启见 cmd/server/flags.go控制导出。若你在指标列表中看不到这两类指标请检查该环境变量是否被显式关闭。示例输出节选自仓库文档# HELP woodpecker_pending_steps Total number of pending pipeline steps. # TYPE woodpecker_pending_steps gauge woodpecker_pending_steps 0 # HELP woodpecker_step_duration_seconds Step duration in seconds. # TYPE woodpecker_step_duration_seconds histogram woodpecker_step_duration_seconds_bucket{repowoodpecker-ci/woodpecker,stepdeploy,workflowwoodpecker,le30} 1 woodpecker_step_duration_seconds_sum{repowoodpecker-ci/woodpecker,stepdeploy,workflowwoodpecker} 12七、进阶带认证的外部指标访问仓库服务端同时提供了另一条受保护的指标通道/api/metrics/prometheus见 server/api/metrics/prometheus.go。其行为如下仅当配置了WOODPECKER_PROMETHEUS_AUTH_TOKEN对应参数prometheus-auth-token见 cmd/server/flags.go时该端点才可用否则返回 404请求需携带Authorization: Bearer token头缺失返回 401令牌不匹配返回 403认证通过后由promhttp.Handler()输出与/metrics一致的指标内容。因此如需在集群外安全地抓取指标推荐在反向代理/Ingress 上暴露该 API 端点并配置 Bearer Token而不是直接开放 9001 端口。相关抓取配置可参考 docs/docs/30-administration/10-configuration/10-server.md 中的 Prometheusscrape_configs示例。八、部署后的验证清单helm list确认 Release 处于deployed状态kubectl get pods -l app.kubernetes.io/namewoodpecker确认 Server Pod 就绪kubectl port-forward server-pod 9001:9001后在本地访问http://localhost:9001/metrics应能看到woodpecker_前缀指标检查 Prometheus 的 Target 页面确认 PodMonitor 目标处于UP状态且interval生效若指标缺失优先按第五节检查命名空间/选择器配置再确认WOODPECKER_STEP_LEVEL_METRICS未被关闭。九、参考与延伸阅读其他安装方式Docker Compose 见 docs/versioned_docs/version-3.17/30-administration/05-installation/10-docker-compose.md发行版安装见 docs/versioned_docs/version-3.17/30-administration/05-installation/30-packages.md支持平台对照见 docs/versioned_docs/version-3.17/30-administration/05-installation/05-supported-platforms.md服务端全部配置项含WOODPECKER_METRICS_SERVER_ADDR、WOODPECKER_STEP_LEVEL_METRICS、WOODPECKER_PROMETHEUS_AUTH_TOKEN见 docs/docs/30-administration/10-configuration/10-server.md指标采集实现见 server/metric/metrics_server.go指标端点实现见 cmd/server/server.go 与 server/api/metrics/prometheus.go。赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐Woodpecker Helm Chart 安装与 Prometheus 监控配置完全指南Woodpecker Helm Chart 安装与 Prometheus 监控配置完全指南 Woodpecker 官方为 Kubernetes 环境提供了维护良CI/CDDevOps使用 Helm Chart 在 Kubernetes 上部署 ToolJet安装、配置与升级完整指南使用 Helm Chart 在 Kubernetes 上部署 ToolJet安装、配置与升级完整指南 Helm 是 Kubernetes 生态中最常用的应用打低代码后端前端AI 应用MCP 服务终极指南如何使用werf实现Kubernetes应用的自动化测试全流程终极指南如何使用werf实现Kubernetes应用的自动化测试全流程 werf是一个强大的解决方案旨在为Kubernetes实现高效且一致的软件交付流程人工智能AI 应用语音移动开发后端桌面应用智能硬件MCP 服务上一篇DeepSeek-Coder-V2终极指南打破闭源壁垒的开源代码智能革命下一篇终极指南如何用PsychoPy轻松构建专业心理学实验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考