文档教程【免费下载链接】pikvmOpen and inexpensive DIY IP-KVM based on Raspberry Pi项目地址https://gitcode.com/gh_mirrors/pi/pikvm点击查看免费下载PiKVM基于 Raspberry Pi 的开源 DIY IP-KVM内置了对 Prometheus 监控系统的支持可将 PiKVM 自身以及被控服务器的状态以标准文本格式暴露给监控端。本文介绍 Prometheus 的抓取scrape配置、HTTP 接口的认证方式、完整指标清单及其语义并结合作者的源码与配置背景帮助你理解每个指标背后的数据来源从而把 PiKVM 纳入现有的监控告警体系。PiKVM 为什么需要 Prometheus 指标Prometheus 是一种主流的开源监控系统采用拉取pull模型由 Prometheus 服务器周期性地访问被监控服务暴露的 HTTP 端点读取简单的文本格式指标。PiKVM 在其 KVMD 守护进程中实现了/api/export/prometheus/metrics导出端点把以下信息以 gauge 指标的形式暴露出来ATX 状态被控服务器电源开关是否启用、当前电源状态用于远程开机/关机/重启场景硬件健康树莓派 CPU / GPU 温度以及树莓派的电压不足undervoltage、降频frequency capping、节流throttling等电源保护状态GPIO 状态通过 docs/gpio.md 配置的输入如 LED 检测与输出如按钮、继电器通道的在线状态与逻辑状态。该端点自 KVMD 1.982020 年 8 月技术预览起加入并在 KVMD 1.100 中正式稳定并文档化同期发布了用于兼容 Prometheus 等监控系统的Authorization: Basic支持见 docs/blog/posts/2020/2020-08-31/index.md 与 docs/blog/posts/2020/2020-09-11/index.md。配置 Prometheus 抓取 PiKVM在 Prometheus 的配置文件如prometheus.yml中加入一个 scrape job即可让 Prometheus 定期访问 PiKVM 的指标端点。官方文档给出的最小可用配置如下scrape_configs: - job_name: pikvm metrics_path: /api/export/prometheus/metrics basic_auth: username: admin password: admin scheme: https static_configs: - targets: [pikvm] tls_config: insecure_skip_verify: true # For self-signed certificate配置要点说明metrics_path指向 PiKVM 的指标导出路径/api/export/prometheus/metrics。该路径由 KVMD 的 HTTP 导出处理器提供与 docs/api.md 中描述的 RESTful API 共用同一 Nginx 入口。basic_authPrometheus 侧使用 HTTP Basic Auth 提供凭据。admin/admin是 PiKVM 出厂默认用户名与密码见 docs/auth.md 中的默认凭据说明实际部署时应替换为已配置的用户若开启了两因素认证2FAPrometheus 的 Basic Auth 无法附带 TOTP 一次性密码因此这类监控抓取通常使用未启用 2FA 的专用账户。scheme: httpsPiKVM 默认安装使用自签名证书提供 HTTPS 服务。tls_config.insecure_skip_verify: true由于自签名证书无法被公开信任的 CA 链验证需要跳过证书校验。若你已通过 docs/letsencrypt.md 等方案为 PiKVM 配置了受信任证书则可以移除该选项并开启真正的证书校验。targets将pikvm替换为 PiKVM 实际的主机名或 IP 地址。指标端点的认证方式PiKVM 的全部 API 都受认证保护。抓取指标时有两种单请求认证方式详见 docs/api.mdHTTP Basic Authcurl -k -u admin:admin https://pikvm-ip/api/export/prometheus/metrics。官方文档特别注明该实现与标准 Basic Auth 略有差异不使用WWW-Authenticate头仅用于与 Prometheus 等外部监控系统的兼容。X-Headers 方式curl -k -H X-KVMD-User:admin -H X-KVMD-Passwd:admin https://pikvm/api/export/prometheus/metrics即 docs/prometheus.md 中输出示例所使用的调用方式。两种方式对 Prometheus 的basic_auth配置均透明Prometheus 抓取时发送的是标准 Basic Auth 头KVMD 会将其映射到兼容认证流程中。手动验证指标输出在配置 Prometheus 之前可以先直接用curl验证端点是否可用、认证是否通过。以下命令使用 X-Headers 认证-k用于跳过自签名证书校验$ curl -k -H X-KVMD-User:admin -H X-KVMD-Passwd:admin https://pikvm/api/export/prometheus/metrics # TYPE pikvm_atx_enabled gauge pikvm_atx_enabled 1 # TYPE pikvm_atx_power gauge pikvm_atx_power 0 ...官方文档同时给出了curl -k -u admin:admin https://pikvm-ip/api/export/prometheus/metrics的等价写法两种认证方式返回的内容一致。指标清单与语义详解以下输出示例取自 docs/prometheus.md其中的 GPIO 通道对应 KVMD 测试环境配置v2-hdmi-rpi4 平台中定义的led1、led2两个输入与button1、button2、relay1、relay2三个输出通道。所有指标均为gauge类型0/1分别表示否/是或关闭/开启。ATX 状态指标# TYPE pikvm_atx_enabled gauge pikvm_atx_enabled 1 # TYPE pikvm_atx_power gauge pikvm_atx_power 0pikvm_atx_enabledPiKVM 的 ATX 控制器电源管理板是否已启用1 为启用。ATX 功能通过 docs/atx_board.md 描述的板卡实现用于远程控制被控服务器电源。pikvm_atx_power当前 ATX 电源开关状态。1表示电源处于开启状态0表示关闭。可用于监控被控服务器是否带电运行。GPIO 状态指标# TYPE pikvm_gpio_input_online_led1 gauge pikvm_gpio_input_online_led1 0 # TYPE pikvm_gpio_input_state_led1 gauge pikvm_gpio_input_state_led1 0 # TYPE pikvm_gpio_input_online_led2 gauge pikvm_gpio_input_online_led2 0 # TYPE pikvm_gpio_input_state_led2 gauge pikvm_gpio_input_state_led2 0 # TYPE pikvm_gpio_output_online_button1 gauge pikvm_gpio_output_online_button1 0 # TYPE pikvm_gpio_output_state_button1 gauge pikvm_gpio_output_state_button1 0 # TYPE pikvm_gpio_output_online_button2 gauge pikvm_gpio_output_online_button2 0 # TYPE pikvm_gpio_output_state_button2 gauge pikvm_gpio_output_state_button2 0 # TYPE pikvm_gpio_output_online_relay1 gauge pikvm_gpio_output_online_relay1 0 # TYPE pikvm_gpio_output_state_relay1 gauge pikvm_gpio_output_state_relay1 0 # TYPE pikvm_gpio_output_online_relay2 gauge pikvm_gpio_output_online_relay2 0 # TYPE pikvm_gpio_output_state_relay2 gauge pikvm_gpio_output_state_relay2 0GPIO 指标的命名遵循pikvm_gpio_{input|output}_{online|state}_{通道名}的规律online系列该通道对应的驱动/硬件是否在线可达。例如 USB HID 继电器hidrelay驱动掉线、GPIO 芯片不可用时online会变为0可用于硬件故障告警。state系列通道的当前逻辑状态。对输入如检测外部信号的led1反映引脚电平对输出如button1、relay1反映开关状态。通道名led1、button1、relay1等直接来自 docs/gpio.md 中/etc/kvmd/override.yaml的kvmd.gpio.scheme配置因此指标数量与名称随你的 GPIO 配置动态变化——只配置了两个继电器就只会出现对应的relay1/relay2指标。GPIO 通道支持input/output两种模式、pulse/switch两种输出行为以及inverted、initial等参数这些配置都会反映到导出指标的状态语义中。树莓派硬件健康指标# TYPE pikvm_hw_temp_cpu gauge pikvm_hw_temp_cpu 36.511 # TYPE pikvm_hw_temp_gpu gauge pikvm_hw_temp_gpu 35.0 # TYPE pikvm_hw_throttling_freq_capped_now gauge pikvm_hw_throttling_freq_capped_now 0 # TYPE pikvm_hw_throttling_freq_capped_past gauge pikvm_hw_throttling_freq_capped_past 0 # TYPE pikvm_hw_throttling_throttled_now gauge pikvm_hw_throttling_throttled_now 0 # TYPE pikvm_hw_throttling_throttled_past gauge pikvm_hw_throttling_throttled_past 0 # TYPE pikvm_hw_throttling_undervoltage_now gauge pikvm_hw_throttling_undervoltage_now 0 # TYPE pikvm_hw_throttling_undervoltage_past gauge pikvm_hw_throttling_undervoltage_past 0 # TYPE pikvm_hw_throttling_raw_flags gauge pikvm_hw_throttling_raw_flags 0pikvm_hw_temp_cpu/pikvm_hw_temp_gpuCPU 与 GPU 温度单位摄氏度。示例中 CPU 为 36.5°C、GPU 为 35.0°C属正常待机水平。pikvm_hw_throttling_*反映树莓派底层电源/温度保护状态对应内核的 throttling 标志位undervoltage供电电压不足电源适配器功率不足或线材压降过大freq_capped因保护机制被强制降频throttled已被节流可能因过热或欠压后缀_now表示当前状态_past表示曾经发生累计重启后清零——past类指标对排查间歇性欠压非常有用raw_flags底层原始标志位的数值汇总供深度排查使用。这些指标对应 README 中Health monitoring of the Pi特性PiKVM 会持续监测树莓派主板的健康状态在温度过高或供电不足时给出警告。配合 Prometheus 告警规则可以在 PiKVM 因欠压降频影响视频流或 HID 稳定性之前提前发现异常。构建监控与告警抓取到指标后可以按自己的需求编写 PromQL 查询与告警规则常见示例groups: - name: pikvm rules: - alert: PiKVMCpuHighTemp expr: pikvm_hw_temp_cpu 75 for: 5m labels: severity: warning - alert: PiKVMUndervoltage expr: pikvm_hw_throttling_undervoltage_now 1 labels: severity: critical - alert: PiKVMAttachedServerDown expr: pikvm_atx_power 0 for: 10m labels: severity: warning - alert: PiKVMGpioRelayOffline expr: pikvm_gpio_output_online_relay1 0 labels: severity: critical需要说明的是温度阈值如 75°C与告警策略应结合你的实际硬件、机箱散热与使用环境确定本文仅演示写法不构成普适阈值建议。GPIO 指标的可组合性很强——例如online指标可以当作硬件存活探针state指标可以当作被控设备如门锁、指示灯、PDU 插座的状态源配合 docs/gpio.md 中任意数量的通道配置几乎可以为任何外设建立监控面板。常见问题与注意事项认证失败401/403确认用户名密码正确且该账户未被 2FA 强制约束Prometheus 无法附加 TOTP 码如已启用 2FA请为监控抓取使用专用非 2FA 账户或参考 docs/auth_advanced.md 的方案。TLS 校验失败自签名证书需要insecure_skip_verify: true若仍失败请检查scheme是否为https且端口正确默认 443。指标缺失GPIO 相关指标只会在 docs/gpio.md 中配置了对应通道时出现未配置 ATX 板时pikvm_atx_*指标也不会出现。指标集合随/etc/kvmd/override.yaml的配置动态变化这是正常现象。pikvm_hw_throttling_*_past为 1表示历史上曾发生过欠压/节流建议检查电源适配器功率与供电线材。curl 输出末尾的* Connection #0 to host localhost left intact这是 curl 的调试输出表示连接保持并正常关闭不属于指标内容无需担心。总结通过 docs/prometheus.md 中给出的配置只需几十行 YAML 即可将 PiKVM 纳入 Prometheus 生态/api/export/prometheus/metrics端点以标准文本格式输出 ATX 电源状态、GPIO 通道在线/状态、树莓派温度与电源保护标志三类 gauge 指标。结合 PromQL 告警规则你可以对被控服务器掉电“GPIO 外设离线”“树莓派欠压/过热”等关键事件进行实时监控让远程管理基础设施的每个环节都可见、可告警、可追溯。赞分享文档教程【免费下载链接】pikvmOpen and inexpensive DIY IP-KVM based on Raspberry Pi项目地址https://gitcode.com/gh_mirrors/pi/pikvm点击查看免费下载相关推荐Crater服务健康监控Prometheus与Grafana集成实践Crater服务健康监控Prometheus与Grafana集成实践 监控需求与架构设计 Crater作为开源发票管理系统需确保支付处理、PDF生成等核心功后端前端企业应用Buildah容器健康检查集成Prometheus监控Buildah容器健康检查集成Prometheus监控 引言 你是否在管理容器化应用时遇到过这些问题容器明明运行着但服务却无响应应用异常时无法及时告警本云原生Spring Boot健康监控实战Actuator与Prometheus集成指南Spring Boot健康监控实战Actuator与Prometheus集成指南 你是否还在为Spring Boot应用的实时监控发愁服务崩溃前毫无预警本示例工程后端教程上一篇NCM格式转换终极指南3步轻松解密网易云音乐加密文件下一篇A2UI三步让 AI 代理为每个需求生成专属界面的开源框架创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考