Pulse 温度监控实战指南:Agent 本地采集、Windows 集成与 SSH 回退机制全解析
Pulse 温度监控实战指南:Agent 本地采集、Windows 集成与 SSH 回退机制全解析
Pulse 是一款面向 Proxmox VE、PBS、Docker、Kubernetes、TrueNAS 与 vSphere 的自托管实时监控平台,其温度监控子系统遵循"复用宿主机已有传感器驱动"的设计原则:统一 Agent 在宿主机本地读取温度,SSH 采集仅作为遗留回退手段。本文以 docs/TEMPERATURE_MONITORING.md 为核心骨架,结合仓库内 internal/monitoring、internal/sensors、internal/hostagent 等模块的真实实现,完整讲解 Linux/Proxmox 与 Windows 两种场景的温度采集部署、安全的本地与远程诊断方法、SSH 回退的配置与验证,以及旧版 pulse-sensor-proxy 的升级清理流程。读完本文,你将能独立为宿主机部署 Pulse 温度采集链路,并掌握区分"无读数"与"硬件故障"的排查方法。
采集架构总览:Agent 优先,SSH 兜底
Pulse 并不自行探测硬件或加载驱动,而是收集宿主已有驱动程序暴露的温度数据。对整个温度采集链路而言,有两条并列路径:
- Pulse Agent(推荐):统一 Agent 直接运行在每台 Proxmox 主机上,在本地读取传感器,无需 SSH 密钥、无需在 Pulse 服务器与被监控主机之间维护任何远程登录凭据。
- SSH 采集(回退):当某台主机没有可用的 Agent 温度数据时,Pulse 服务器可以 SSH 到该主机执行传感器包装脚本(sensor wrapper),逐级回退到
sensors -j与/sys/class/thermal/thermal_zone0/temp(典型场景是树莓派)。
如果你的部署来自较老版本且仍在使用 pulse-sensor-proxy,请直接阅读本文末尾的"遗留清理"一节——传感器代理在 Pulse 中已不再受支持。
从源码结构看,这条双通道设计对应两个独立的实现:Agent 侧采集逻辑位于 internal/hostagent/agent.go(其中 collectTemperatures 按平台分发),而服务器侧 SSH 回退由 internal/monitoring/temperature.go 中的 TemperatureCollector 负责。两者共享同一套 sensors -j JSON 解析器 internal/sensors/parser.go。
推荐方案:在 Proxmox 主机上部署 Pulse Agent
统一 Agent 在每台 Proxmox 主机本地上报温度,全程不需要 SSH 密钥。首次部署前,请先在被监控主机上完成 private-file 准备:保护 Pulse Agent token、从你的 Pulse 服务器经验证的 HTTPS 下载安装器并检查其内容。随后使用同一个 Pulse 地址并追加 Proxmox 采集器标志完成安装:
bash "$HOME/.config/pulse/agent-install.sh" \
--url https://pulse.example.com \
--token-file "$HOME/.config/pulse/agent-token" --enable-proxmox
注意:Pulse Agent token 不是 Proxmox API token。务必不要把机密放进命令行参数(避免进入 shell 历史与进程列表),并且为监控用途保留"命令执行"功能为关闭状态。
关于 Linux 上 Agent 的采集行为,以下几点来自实现层面可以直接确认:
- Agent 在 Linux 上优先执行
sensors -j(经 internal/hostagent/sysinfo.go 的SensorsLocal封装),并用已识别的 CPU/SoC 热区 sysfs 源补充缺失的 CPU 读数;lm-sensors对这条补充路径不是硬性依赖。 - 空输出不等于零度:
sensors -j失败或输出为空时,Agent 只记录"不可用",不会把数值当作 0°C 上报。 - 其他传感器类型(如磁盘 SMART 温度)需要各自受支持的驱动/提供方,Agent 不会为它们发明数据。
- 当某台 Proxmox 主机已有近期可用的 Agent 温度数据时,Pulse 会把 Agent 视为该主机的权威数据源,不再为该主机发起 SSH 温度采集——这一"二选一"语义避免了两条链路的数据冲突。
在改动任何 Agent 配置前,先核对三件事:活动 Agent 的版本、最近一次上报记录、受影响主机的实际读数。当前版本的服务器并不会自动升级每一台已部署的 Agent,版本差异可能导致行为差异。
安全地检查 Linux 主机已有读数
如果 Pulse 界面没有温度,请在被监控主机受信任的本地控制台上检查,而不是在 Pulse 的 LXC 或容器内操作。不要仅仅因为 Pulse 无读数就执行 sensors-detect --auto、总线扫描、驱动加载或重启主机——硬件探测可能干扰正在运行的主机。任何必要的驱动配置都属于该主机正常维护窗口的工作,应当遵循其硬件文档执行,而不是进入诊断重试循环。
若 sensors 已安装,下面的 Bash 检查只读取一次、把命令限制在 5 秒内(附 2 秒强制停止宽限期)、把两路输出都保存在私有目录中,不安装任何东西,只打印状态与路径:
(
set -eu
umask 077
command -v sensors >/dev/null || { printf 'sensors is not installed; check the agent sysfs fallback.\n'; exit 1; }
command -v timeout >/dev/null || { printf 'GNU timeout is required for this bounded check.\n'; exit 1; }
result_dir=$(mktemp -d "${TMPDIR:-/tmp}/pulse-temperature.XXXXXX") || exit $?
check_exit=0
timeout --signal=TERM --kill-after=2s 5s sensors -j \
> "$result_dir/sensors.json" 2> "$result_dir/sensors.err" || check_exit=$?
printf 'Sensor command exit %s; private output in %s\n' "$check_exit" "$result_dir"
exit "$check_exit"
)
在本地查看这些文件。需要强调的语义:非零退出码可能与部分传感器数据并存;退出码为零或输出为 {} 也不能证明存在可用的 CPU 读数;超时是一次失败检查,而不是"空读数",更不是重复执行该命令的许可。不要把完整输出贴到外部——传感器输出可能泄露硬件型号与磁盘标识。
sysfs 手工核对:毫摄氏度换算与 CPU 识别
没有可用的 CPU 输出时,可查看宿主机已暴露的 sysfs 文件:
- 将
/sys/class/thermal/thermal_zone*/type与对应的temp配对; - 或将
/sys/class/hwmon/hwmon*/name与对应的temp1_input配对。
这些文件的值单位是毫摄氏度(millidegrees Celsius),例如 57000 表示 57 °C。注意 thermal_zone0 并不一定就是 CPU——判断依据是传感器的 type/name 而不是编号。对照仓库内 internal/sensors/parser.go 的 isCPUChip 列表,Pulse 只把下列已知 CPU/SoC 芯片名视为 CPU 源:
- Intel/AMD 传统芯片:
coretemp、k10temp、zenpower、k8temp、acpitz - SuperIO 主板芯片:
it87、nct6687、nct6775、nct6776、nct6779、nct6791~nct6798、w83627、f71882 - ARM SoC / 树莓派:
cpu_thermal、rp1_adc、rpitemp、armada_thermal
也就是说,Agent 只接受已识别的 CPU/SoC 名称,不会把任意 thermal zone 当作 CPU。缺失、不可读、无效或不支持的读数一律保持"不可用"——不要为了通过这次检查而修改权限,或把宿主的 device tree 挂载进容器。
把已有本地读数与同一主机、同一传感器在对应时刻的 Machines 当前值与 CPU-temperature History 进行对照。还要记住:CPU/SoC 温度不是物理磁盘的 SMART 温度;某个传感器值合理并不能证明所有传感器正常,也不能证明历史数据连续。
Windows 主机的温度采集
Windows 上的温度采集由统一 Agent 完成,分为三个相互独立的来源(实现分别位于 internal/hostagent/ 下)。
NVIDIA GPU:nvidia-smi
在装有 NVIDIA 驱动的 Windows 主机上,Agent 调用驱动的 nvidia-smi 可执行文件上报 GPU 温度、利用率与显存占用,无需任何额外的 Pulse 配置,但 nvidia-smi.exe 必须位于 Agent 服务的 PATH 上。对应实现 internal/hostagent/nvidia_smi.go 使用 --query-gpu=index,name,temperature.gpu,utilization.gpu,memory.used,memory.total 查询并以 CSV 解析,单次查询超时为 5 秒;n/a、unknown 等无效值会被静默丢弃。
物理磁盘:Windows Storage 可靠性计数器
受支持的物理磁盘温度通过 Windows Storage reliability counters 单独读取。对应的 PowerShell 脚本(固定内置于 Agent 代码中)枚举 Get-PhysicalDisk 并调用 Get-StorageReliabilityCounter 提取 Temperature 字段,见 internal/hostagent/windows_storage_sensors.go。缺失的计数器或不支持的设备会直接省略,不影响整机报告。
CPU 与主板:LibreHardwareMonitor(仅回环)
Windows 没有可靠的 CPU/主板温度内置 API,因此需要第三方工具:以管理员身份安装并运行 LibreHardwareMonitor,端口保持默认的 8085,启用 Options → Remote Web Server → Run。安全边界非常明确:
- 不要在 Windows 防火墙中放行
8085端口的入站访问——Pulse 只读取本机回环端点http://127.0.0.1:8085/data.json; - 该回环集成的 Web 认证必须禁用;
- Pulse 只接受来自该端点、范围受限的 CPU 与主板摄氏度读数,忽略 LibreHardwareMonitor 的磁盘与 GPU 节点,使原生的 Windows Storage 与
nvidia-smi提供方保持权威地位; - 若该辅助工具缺失或不可用,Windows 报告的其余部分不受影响。
实现层面(internal/hostagent/windows_librehardwaremonitor.go)把解析约束得非常严格:2 秒查询超时、响应上限 1 MiB、树节点上限 2048、深度上限 16、温度传感器上限 256,且只接受 0~150°C 范围内的 RawValue。分类逻辑只把 hardwareID 含 /intelcpu/、/amdcpu/、/cpu/ 的节点归为 CPU,把含 /lpc/、/motherboard/、/superio/、/embeddedcontroller/ 的节点归为主板,其余一律忽略。读取超时、响应过大等错误只记录日志,不会让 Agent 崩溃。
SSH 采集(回退通道)
Pulse 也可以 SSH 进入每台没有可用 Agent 温度数据的主机执行温度采集。SSH 路径的运行顺序是:优先运行 Pulse sensor wrapper(/usr/local/sbin/pulse-sensors),wrapper 不存在时回退到 sensors -j,仍不可用时再回退到 /sys/class/thermal/thermal_zone0/temp(例如树莓派)。这条命令链直接体现在 internal/monitoring/temperature.go 的 pulseSensorsSSHCommand 常量中。
前置要求
- Pulse 服务器到每台主机的 SSH 连通性;
- 主机上已有可用的传感器数据,通常是
sensors -j的 JSON 输出; - 一条受限的 SSH key 条目,只允许执行 Pulse sensor wrapper。
设置步骤
- 从 UI 生成节点设置命令:Settings → Infrastructure → Add Node;
- 在每台 Proxmox 主机上运行该命令。设置脚本可以完成:
- 创建所需 API 用户与权限;
- 添加一条受限的 SSH key 条目用于温度采集;
- (可选)安装
lm-sensors。
写入 authorized_keys 的条目被限制为只执行 Pulse sensor wrapper,形如:
command="/usr/local/sbin/pulse-sensors",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty <public-key> # pulse-sensors
如果使用非标准 SSH 端口,请设置 SSH_PORT(系统级),或在 Settings → System 中配置。源码中 NewTemperatureCollectorWithPort 会保留配置的端口号并在每次 SSH 调用时通过 -p 传入,默认端口为 22。
容器化 Pulse 的注意事项
优先使用本地 Agent。一个遗留配置的 key 仍可能让容器内的 Pulse 发起 SSH 回退,并产生生产安全警告;开发覆盖开关(源码中的环境变量 PULSE_DEV_ALLOW_CONTAINER_SSH)只改变那条警告,并不会改变传感器数据是否存在。不要把 root 的 SSH key 挂载进 Pulse 容器,也不要为了修复缺失读数而启用开发覆盖——容器被攻破意味着 SSH key 被攻破,等于把基础设施的 root 权限拱手让人。
验证既有 SSH 回退(只读、有界、私有)
仅对已经配置好的 SSH 回退执行验证:使用其既有的受限 key,以及 Pulse 服务器账户中已单独验证过的主机密钥信任关系。不要为了获得一个温度而接受新的或变更的主机密钥。下面的 Bash 检查只请求 sensor wrapper 一次,总时长限制 15 秒、2 秒强制停止宽限,输出保持私有:
(
set -eu
umask 077
command -v timeout >/dev/null || { printf 'GNU timeout is required for this bounded check.\n'; exit 1; }
result_dir=$(mktemp -d "${TMPDIR:-/tmp}/pulse-temperature-ssh.XXXXXX") || exit $?
check_exit=0
timeout --signal=TERM --kill-after=2s 15s \
ssh -T -i /path/to/pulse-key -o BatchMode=yes -o IdentitiesOnly=yes \
-o StrictHostKeyChecking=yes -o ConnectTimeout=5 -o ConnectionAttempts=1 \
-o ServerAliveInterval=5 -o ServerAliveCountMax=1 \
root@node /usr/local/sbin/pulse-sensors \
> "$result_dir/wrapper.json" 2> "$result_dir/ssh.err" || check_exit=$?
printf 'SSH command exit %s; private output in %s\n' "$check_exit" "$result_dir"
exit "$check_exit"
)
只把其中的 key 路径和节点替换成你配置好的值。仓库测试 scripts/installtests/temperature_guidance_test.go 会逐一校验上述检查命令的参数(BatchMode=yes、IdentitiesOnly=yes、StrictHostKeyChecking=yes、ConnectionAttempts=1 以及 wrapper 路径),确保文档与实现保持一致。
几个必须理解的语义:
- 强制的 key command 可能忽略你请求的命令:当前版本的 wrapper 会返回
sensors与smart两类数据,而旧 key 可能只返回裸的sensors -jJSON——这两种格式解析器都能处理(见下文); - 不要为了跑另一个探针而移除 key 的
command=限制,也不要把 wrapper 的 JSON 当成裸的 thermal-zone 数值; - SSH 失败、部分输出或超时并不能证明硬件缺失;
- wrapper 输出与错误输出要保持私有,需要求助时才分享退出码、脱敏后的相关错误与受影响传感器。
源码中这条检查对应的运行时行为是:TemperatureCollector 的单次 SSH 命令默认 15 秒超时(defaultSSHCommandTimeout),stdout/stderr 各限制 1 MiB(maxTemperatureCommandOutputSize);SSH 调用固定携带 StrictHostKeyChecking=yes、BatchMode=yes、LogLevel=ERROR(抑制会破坏 JSON 解析的主机密钥警告)、ConnectTimeout=5,并优先使用 ~/.ssh/known_hosts_sensors 这个独立主机密钥库。值得一提的是其失败退避机制(对应 issue #1638):对反复失败的主机,初次退避 30 秒、逐次翻倍、封顶 15 分钟,且只对"主机真实应答失败"(认证拒绝、输出不可用)累进退避,而自己超时这类瞬时失败不会加倍;成功采集会立即清除退避。若你修复了 SSH key 或主机密钥,调用 ResetSSHFailures 即可让下一个轮询周期立即重试,而不是等满 15 分钟。
疑难排查
- 温度不可用时,先执行上面的 本地读数检查再考虑改动设置——空读数不是自动硬件探测的理由;
- 如果统一 Agent 已在为某台 Proxmox 主机上报温度,该主机无需 SSH 采集;
- 确认 SSH key 条目存在,且限制为
/usr/local/sbin/pulse-sensors。
遗留清理:移除 pulse-sensor-proxy(升级场景)
如果你是从较早版本升级且仍装有旧传感器代理,请在每台 Proxmox 主机(不是 Pulse 容器)上用受支持的清理辅助脚本移除它。在该主机受信任的管理 shell 中私有下载该脚本。下载逻辑具备多重防护:拒绝已存在的目标文件、拒绝符号链接的配置目录、拒绝失败/部分下载;它不会覆盖早先版本的辅助脚本,也不会把网络响应当作命令执行:
(
set -eu
umask 077
config_dir="$HOME/.config/pulse"
helper_file="$config_dir/sensor-proxy-uninstall.sh"
if [ -L "$HOME/.config" ] || [ -L "$config_dir" ]; then
printf 'Refusing a symlinked configuration directory.\n'; exit 1
fi
mkdir -p "$config_dir" || exit $?
chmod 700 "$config_dir" || exit $?
if [ -e "$helper_file" ] || [ -L "$helper_file" ]; then
printf 'Helper path already exists; inspect it locally before choosing a replacement.\n'; exit 1
fi
download_file=$(mktemp "$config_dir/sensor-cleanup-download.XXXXXX") || exit $?
curl_exit=0
# HELPER_URL 指向当前 Pulse 仓库 main 分支的 scripts/uninstall-sensor-proxy.sh(raw 下载地址)
status=$(curl --disable --fail --silent --show-error --proto '=https' \
--connect-timeout 5 --max-time 60 --output "$download_file" --write-out '%{http_code}' \
"$HELPER_URL") || curl_exit=$?
printf 'HTTP %s\n' "$status"
[ "$curl_exit" -eq 0 ] || exit "$curl_exit"
[ "$status" = 200 ] || exit 1
mv -n "$download_file" "$helper_file" || exit $?
[ ! -e "$download_file" ] || exit 1
printf 'Inspect the complete private helper at %s before running it.\n' "$helper_file"
)
注意其中的安全细节:curl 忽略本地配置文件、不跟随重定向、始终启用 TLS 校验。准备或下载失败就停止——一次临时响应并不是辅助脚本本身。同时要清楚:这是从仓库当前 main 分支的 HTTPS 下载,不是签名的发布资产。运行前必须检查保存下来的完整脚本,并自行选择清理范围。不要用 bash <(curl ...) 之类的方式把网页响应直接管道给特权 shell。
确认脚本完整后执行:
bash "$HOME/.config/pulse/sensor-proxy-uninstall.sh" \
--uninstall --purge --local-only
--local-only 完全跳过集群 SSH;每台承载过代理的 Proxmox 节点都要单独运行一次。若要一次完成集群级清理,省略 --local-only 即可。此时远程节点必须在 root 的常规 OpenSSH 用户/系统 known_hosts 文件中已有受信任的主机密钥,或通过 --ssh-known-hosts /path/to/known_hosts 提供单独配置的文件。辅助脚本从不接受或登记未知主机密钥;缺失或变更的主机密钥只会让远程部分在本地清理完成后失败。
如果还想在重新添加节点前一并移除旧的 pulse-monitor@pam API 用户与 token,追加 --remove-proxmox-access:
bash "$HOME/.config/pulse/sensor-proxy-uninstall.sh" \
--uninstall --purge --remove-proxmox-access --local-only
最后两点务必记住:
- 重新安装或升级 Pulse 容器不会移除主机上的传感器代理——两者是相互独立的安装;
- 如果跳过这次清理,selfheal 定时器会持续运行,并可能在 Proxmox 任务日志中反复产生
TASK ERROR条目。
数据解析与权威性:从原始 JSON 到界面读数
理解"什么算一个可用读数",对排查尤其关键。SSH wrapper 与 sensors -j 的原始 JSON 由 internal/sensors/parser.go(Agent 侧)与 internal/monitoring/temperature.go 中的 parseSensorsJSON(服务器侧)解析,核心规则一致:
- 温度单位归一化:解析
*_input字段时,若绝对值 ≥ 1000 则按毫摄氏度换算为摄氏度(如42000→42.0),常规度数(如45.0、+45.0°C)保持不变; - CPU 封装温度:优先取 Intel 的
Package id、AMD 的Tdie/Tctl;无封装温度时用 AMDTccd*chiplet 最高值,再退而求其次用树莓派/ARM 芯片的temp1; - 单核温度:形如
Core 0的条目进入逐核列表,并参与 CPU 最大值计算; - NVMe 温度:优先取
Composite传感器,回退到Sensor 1,并按芯片顺序归一化为nvme0、nvme1…; - GPU 温度:AMD 芯片按
edge、junction/hotspot、mem三类字段收集;nouveau 驱动下 NVIDIA GPU 的GPU core映射为 edge 温度; - 其他温度与风扇:主板/DDR5 等其余温度(0~150°C 合理性检查)与
fan*_input的 RPM 也会被保留,形成更完整的传感器视图。
服务器侧还会标记一个关键事实:某读数 Available 为真意味着 CPU、NVMe、GPU、SMART 中至少有一类数据存在。反过来,若 SensorSetupOutdated 标志为真(见 internal/unifiedresources/proxmox_sensor_setup.go),说明该节点的 SSH 温度设置是在 v6.0.0-rc.6 之前建立的、key 被锁定为裸 sensors -j:这类 payload 仍能解析出 CPU 与 NVMe 温度,但 SMART 磁盘温度永远无法到达,于是界面上的磁盘温度持续空白且没有任何报错。遇到"只有磁盘温度缺失"的情况,这就是优先怀疑对象。
小结:一条健康的温度采集链路应该长什么样
- Proxmox 主机优先部署统一 Agent(
--enable-proxmox),SSH 只作为非 Agent 主机的兜底; - 主机侧依赖受支持的驱动(
lm-sensors芯片、sysfs 热区、NVIDIA 驱动、Windows Storage 可靠性计数器、LibreHardwareMonitor 回环端点),Pulse 只读取、不探测; - 诊断永远在主机受信任的本地控制台进行,用有界、私有、不安装任何东西的检查脚本,超时即视为失败,绝不自动触发硬件探测;
- SSH 回退的 key 被
command=限制在/usr/local/sbin/pulse-sensors,容器化部署不挂载 root 密钥; - 升级自旧版时逐节点清理
pulse-sensor-proxy,并留意SensorSetupOutdated提示以解除旧 key 对 SMART 温度的限制。
按上述原则落地后,"温度读不到"与"硬件确实损坏"之间的边界会变得清晰可辨,Pulse 的智能告警与 AI patrol 也才能基于真实、权威的传感器数据工作。