UPS 无法识别问题报告
1. 问题摘要
飞牛系统设置中的 UPS 页面长期显示未插入 UPS，但底层 USB 和 NUT 实际可以识别该 UPS。
最终确认原因是 /etc/nut/ups.conf 中 UPS 的 serial 字段被写坏：
serial = """
正确值应为：
serial = "9B2425A18306"
该错误会导致 NUT 的 usbhid-ups 驱动无法按配置匹配到实际 USB UPS，从而导致飞牛 UI 认为没有可用 UPS。
2. 系统环境
设备系统：fnOS / 飞牛
当前 trim 版本：1.1.3107
NUT 版本：2.8.0-7
UPower 版本：0.99.20-2
内核：Linux 6.18.18-trim
UPS 型号：APC Back-UPS BK650M2-CH
UPS 厂商：American Power Conversion
UPS 序列号：9B2425A18306
3. 用户侧现象
系统设置路径：
系统设置 -> 硬件和电源 -> UPS
现象：
选择 USB UPS 时，设备列表为空
页面提示类似：请接入 USB UPS 设备
但底层扫描可以识别 UPS。
4. 底层识别正常的证据
执行：
sudo nut-scanner -U
可以识别到 UPS：
[nutdev1]
driver = "usbhid-ups"
port = "auto"
vendorid = "051D"
productid = "0002"
product = "Back-UPS BK650M2-CH FW:294803G -292804G"
serial = "9B2425A18306"
vendor = "American Power Conversion"
bus = "003"
执行：
upsc 2030091@localhost
可以读到：
device.mfr: American Power Conversion
device.model: Back-UPS BK650M2-CH
device.serial: 9B2425A18306
ups.mfr: American Power Conversion
ups.model: Back-UPS BK650M2-CH
ups.serial: 9B2425A18306
说明 UPS 本体、USB 连接、NUT 扫描能力都正常。
5. 异常配置
故障时 /etc/nut/ups.conf 中的 UPS 配置为：
[2030091]
driver = "usbhid-ups"
port = "auto"
vendorid = "051D"
vendor = "American Power Conversion"
productid = "0002"
product = "Back-UPS BK650M2-CH FW:294803G -292804G"
serial = """
bus = "003"
override.x.additional.lowbatt = "15"
override.x.additional.devicetype = "USB"
问题字段：
serial = """
这个值不是合法序列号。
6. 正确配置
修复后的 /etc/nut/ups.conf：
[2030091]
driver = "usbhid-ups"
port = "auto"
vendorid = "051D"
vendor = "American Power Conversion"
productid = "0002"
product = "Back-UPS BK650M2-CH FW:294803G -292804G"
serial = "9B2425A18306"
bus = "003"
override.x.additional.lowbatt = "15"
override.x.additional.devicetype = "USB"
飞牛自己的 UPS 元数据文件 /etc/nut/device.conf 当前正确内容包括：
enable = true
last-device.name = 2030091
last-device.driver = usbhid-ups
last-device.port = auto
last-device.vendorid = 051D
last-device.productid = 0002
last-device.product = Back-UPS BK650M2-CH FW:294803G -292804G
last-device.serial = 9B2425A18306
last-device.vendor = American Power Conversion
last-device.bus = 003
power-policy.type = LOWBATT
power-policy.value = 15
x.additional.devicetype = USB
7. 时间线证据
故障配置备份文件：
/etc/nut/ups.conf.codex-20260611_045941.bak
该文件修改时间：
2026-05-13 16:15:52 +0800
其中已经存在错误配置：
serial = """
同一天 dpkg 日志显示：
2026-05-13 16:09:57 - trim 从 1.1.30 升级到 1.1.3102
2026-05-13 16:10:23 - trim 1.1.3102 安装完成
坏配置写入时间大约在该次升级完成后 5 分钟左右。
8. 原因分析
NUT 的 usbhid-ups 驱动会根据这些字段匹配实际 USB UPS：
vendorid
productid
serial
bus
当配置中写成：
serial = """
时，驱动会尝试寻找序列号为异常值的 UPS。
实际 UPS 的序列号是：
9B2425A18306
两者不匹配，所以结果是：
USB 层能看到 UPS
nut-scanner 能扫描到 UPS
但 NUT 配置无法绑定到这台 UPS
飞牛 UI 最终显示未插入 UPS
这不是 UPS 硬件问题，也不是 USB 接口问题，更像是飞牛在 UPS 绑定、配置迁移、自动恢复或升级流程中错误生成了 serial 字段。
9. 当前手动修复方式
已手动将：
serial = """
修正为：
serial = "9B2425A18306"
并确认以下服务正常：
systemctl is-active nut-driver@2030091.service
systemctl is-active nut-server.service
systemctl is-active nut-monitor.service
systemctl is-active trim_sac.service
结果均为：
active
10. 建议飞牛修复方向
10.1 写入配置前校验 serial
在 trim_sac 或 UPS 绑定逻辑写入 /etc/nut/ups.conf 前，应校验：
serial 不应为空
serial 不应为单独的 "
serial 不应为 """
serial 不应包含未转义的异常引号
serial 应与 nut-scanner 或 upsc 获取到的实际值一致
建议拒绝写入以下值：
serial = ""
serial = """
serial = "\""
10.2 配置损坏时自动自愈
如果当前 /etc/nut/ups.conf 中配置的 vendorid/productid/bus 能匹配到设备，但 serial 不匹配，应自动尝试：
nut-scanner -U
然后用扫描结果修复：
serial = "实际扫描到的 serial"
或者至少在 UI 中提示：
检测到 UPS，但配置中的序列号不匹配，请重新绑定或修复配置。
而不是只显示：
请接入 USB UPS 设备
10.3 升级迁移时检查旧配置
系统升级时应检查：
/etc/nut/ups.conf
/etc/nut/device.conf
/etc/nut/upsmon.conf
重点检查：
last-device.serial
driver.parameter.serial
serial
如果发现非法值，应触发迁移修复或提示用户重新绑定。
10.4 UI 错误提示需要区分原因
当前 UI 把多种失败都表现成“未插入 UPS”，不利于定位。
建议区分：
1. USB 没有扫描到 UPS
2. USB 扫描到了 UPS，但 NUT 配置匹配失败
3. NUT 服务未启动
4. upsmon 监控配置缺失
5. serial/vendorid/productid 不匹配
10.5 增加回归测试
建议增加以下测试用例：
serial = ""
serial = """
serial 缺失
serial 与 nut-scanner 返回值不一致
vendorid/productid 相同但 serial 不同
升级前已有旧 UPS 配置
升级后重新生成 NUT 配置
期望行为：
系统不应写入非法 serial
系统应能提示配置损坏
系统应允许用户重新绑定并覆盖坏配置
系统升级不应保留明显非法的 UPS 配置
11. 结论
该问题不是 UPS 硬件故障，也不是 USB 连接问题。
更可能是飞牛系统在某次 trim 升级、UPS 绑定迁移、或配置自动恢复过程中，将 UPS 的 serial 字段错误写成了：
serial = """
后续系统更新保留了该坏配置，导致 UPS 长期无法在 UI 中识别。
建议飞牛重点检查 trim_sac 的 UPS 配置生成、迁移和校验逻辑。
