thinkfan 风扇控制故障排查清单：从传感器找不到到hwmon索引漂移的10个常见问题与解决办法

thinkfan 风扇控制故障排查清单从传感器找不到到hwmon索引漂移的10个常见问题与解决办法【免费下载链接】thinkfanThe minimalist fan control program项目地址: https://gitcode.com/gh_mirrors/th/thinkfanthinkfan 是一个极简的 Linux 风扇控制程序它读取温度传感器hwmon、LM-sensors、thinkpad_acpi、NVML 等按你配置的档位自动调节风扇转速。配置稍有不慎就会报错退出。本文整理 thinkfan 故障排查中最常见的 10 类问题与解决办法帮你快速定位传感器找不到、hwmon 索引漂移、权限不足等报错的根源。 先花 30 秒做自检排查前先跑通这三步80% 的问题在这里就露出马脚# 1. 前台 详细日志运行直接看报错 sudo thinkfan -n -v -c /etc/thinkfan.conf # 2. 确认内核到底暴露了哪些 hwmon 设备 ls /sys/class/hwmon/ cat /sys/class/hwmon/*/name # 3. 用 lm-sensors 交叉验证温度读数 sensors提示thinkfan 守护进程支持SIGHUP热重载配置、SIGUSR1打印当前温度出错时的日志可通过journalctl -u thinkfan查看。1️⃣ hwmon 索引漂移hwmon0 这次开机变成了 hwmon3现象Cant find hwmon file: /sys/class/hwmon/hwmon0/temp1_input或者今天好好的重启后又报错了。原因hwmon0、hwmon1这类编号取决于驱动模块的加载顺序每次开机可能不同。直接写死hwmonN路径是不稳定做法。解决办法改用名字搜索或稳定的设备路径示例见examples/thinkfan.yamlsensors: # 方式一按驱动名搜索最稳妥 - hwmon: /sys/class/hwmon name: k10temp indices: [1] # 方式二走不随加载顺序变化的 PCI 设备路径 - hwmon: /sys/devices/pci0000:00/0000:00:03.1/0000:27:00.0/hwmon indices: [1, 2]风扇端同理把fans:下的hwmon: /sys/class/hwmon/hwmon0/pwm1换成name搜索写法即可。2️⃣ 找不到 hwmon 名字或发现了多个同名 hwmon现象Could not find a hwmon with this name: k10tempFound multiple hwmons with this name: /sys/... /sys/...原因name字段要和/sys/class/hwmon/*/name文件的内容完全一致而多个驱动可能上报同一个名字例如多个显卡。解决办法先执行cat /sys/class/hwmon/*/name拿到真实名字逐字符核对区分大小写名字对应的驱动还没加载运行sensors-detect或检查lsmod出现多个同名时把搜索的hwmon:基路径收窄到具体设备目录如某块 GPU 的 PCI 路径下让搜索结果唯一。搜索逻辑见src/hwmon.cpp。3️⃣ 配置里没有传感器或传感器数量对不上现象No sensors in config file.Lower limit [...] must have the length N (one entry for each configured sensor)Your config requires at least X temperatures, but only Y temperatures were found.原因sensors:段为空或详细模式detailed mode下每档upper_limit/lower_limit数组长度必须等于传感器总数且顺序必须与sensors:声明顺序一致。解决办法数一数配置了多少个温度输入一个indices: [1, 2]算 2 个把每档的上下限数组补齐到相同长度如果多个传感器温标接近也可以改用简单模式单值上下限。4️⃣ 权限不足Thinkfan needs to be run as root!现象No permission to write to /sys/class/hwmon/hwmon0/pwm1. Thinkfan needs to be run as root!原因读取温度普通用户即可但写 PWM/档位文件需要 root 权限。解决办法以 root 运行或交给 init 系统。thinkfan 编译安装时会按系统自动安装 systemdthinkfan.service或 OpenRC/etc/init.d/thinkfan服务文件开机自启即可无需手动sudo。5️⃣ PID 文件残留already exists现象PID_FILE already exists. Either thinkfan is already running, or it was killed by SIGKILL.原因thinkfan 用 PID 文件防止双开如果上一次是被SIGKILL强杀的PID 文件不会自动清理。解决办法先ps aux | grep thinkfan确认没有活进程确认没有后手动删除那个 PID 文件再启动。6️⃣ 风扇档位顺序错误现象均为配置校验期直接拒绝启动Fan levels are not ordered correctlyYour LOWER limit is not lesser than your UPPER limit. That doesnt make sense.LOWER limit doesnt overlap with previous UPPER limit原因档位必须升序排列每档内部 lower upper相邻两档的 upper 与下一档 lower 之间不能出现空档。解决办法逐档检查levels:数值比如- [0, 0, 50]、- [100, 45, 65]、- [255, 60]这类单调递增、无缝衔接的写法完整示例见examples/thinkfan.yaml。7️⃣ 缺少 lower/upper limit或修正值长度不对现象You must specify a lower limit on all but the first fan levelYou must specify an upper limit on all but the last fan levelSensor ... has N temperatures, but you have M correction values for it.原因只有第一档可以省略 lower只有最后一档可以省略 uppercorrection:数组长度必须与该传感器的温度数量一致。解决办法补全档位上下限给correction:补 0 或对齐个数再重新启动或kill -HUP pid热重载验证。8️⃣ PWM 风扇最高档太低现象Youre using a PWM fan, but your highest fan level is only N.原因PWM 控制范围是 0–255如果最高档配得低于 128thinkfan 认为你可能永远无法把风扇拉满出于安全拒绝启动。解决办法把最高档设为 255如果确认自己永远不需要拉满风扇可用-D危险模式绕过——但请三思。9️⃣ ThinkPad 上 fan_control 未启用现象Kernel module thinkpad_acpi: Fan_control seems disabled原因thinkpad_acpi内核模块默认可能禁用风扇控制接口/proc/acpi/ibm/fan。解决办法创建模块参数文件并重启echo options thinkpad_acpi fan_control1 | sudo tee /etc/modprobe.d/99-thinkfan.conf 休眠唤醒后A sensor has vanished!现象合盖/休眠一段时间后日志报A sensor has vanished! Exiting since theres no safe way of handling this.风扇停止受控。原因S3 休眠会重置 PCIe 链路部分显卡/主板的 hwmon 节点唤醒后需要时间重新出现非可选optional传感器读不到时 thinkfan 选择安全退出。解决办法可插拔硬件外置硬盘等在传感器上加optional: true使用仓库自带的 systemd 休眠/唤醒服务thinkfan-sleep.service、thinkfan-wakeup.service见rcscripts/systemd/自动重启 thinkfanthinkfan 收到SIGPWR后会容忍 4 个循环的读数错误唤醒瞬间的短暂丢失可以扛过去。 附YAML 解析失败的隐藏坑如果日志出现Config file ... could not be parsed as YAML并提示 Attempting to parse with legacy syntax多半是文件内容是新格式 YAML但文件名不以.yaml结尾——thinkfan 会据此决定是否回退到旧语法解析器。保持扩展名与格式一致即可。此外若编译时未启用USE_NVML/USE_ATASMART配置里写- nvml:或- atasmart:会直接报not compiled in需重新编译或换用 hwmon 接口。 10 个问题速查表#关键报错一句话解决1Cant find hwmon file改用name搜索或 PCI 稳定路径2Could not find a hwmon with this name核对/sys/class/hwmon/*/name收窄搜索路径3No sensors / limit 长度不匹配上下限数组补到与传感器数一致4needs to be run as root用 systemd/OpenRC 服务方式运行5already exists确认无残留进程后删 PID 文件6levels not ordered / LOWER ≥ UPPER档位升序、无缝衔接7missing lower/upper limit补全档位边界与 correction 长度8highest fan level is only N最高档设 255或-D自担风险9Fan_control seems disabledthinkpad_acpi fan_control110A sensor has vanishedoptional: true 休眠/唤醒服务如果报错带有堆栈回溯Backtrace并提示这可能是 bug记得附上完整日志和examples/thinkfan.yaml格式的配置文件去项目 Issue 区求助能大幅提高排障效率。【免费下载链接】thinkfanThe minimalist fan control program项目地址: https://gitcode.com/gh_mirrors/th/thinkfan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考