Proxmox VE 接入UPS 山特SANTAK TG-BOX 850 UPS USB直连NUT部署方案

Proxmox VE 9.2.2 山特SANTAK TG-BOX 850 UPS USB直连NUT完整部署最终定稿方案

文档基础信息

1. 宿主机节点：homelab，内核 7.0.2-6-pve，PVE管理器版本 pve-manager/9.2.2
2. UPS硬件：山特TG-BOX 850（MGE协议USB UPS）
   • USB识别ID：0463:ffff
   • 系统HID设备路径：/dev/usb/hiddev0
3. 虚拟机清单：150(ubuntu)、151(ubuntu-dev)、152(iStoreOS)、155(fnas飞牛)、160(win11)
4. 方案核心优化：废弃自定义shell关机脚本，改用PVE官方原生stopallAPI批量关机，无脚本维护、自带锁机制、兼容KVM+LXC，规避D-Bus锁冲突报错；不安装nut-cgi，最小化维护成本；原生PVE节点UPS面板可视化；断电自动有序关闭全部虚拟机+宿主机
5. 解决全流程历史故障：PVE面板ups@localhost 查询失败、Driver not connected、pve-shutdown文件不存在、手动测试锁超时/D-Bus关闭报错、防火墙命令报错、systemd服务启用冲突

一、前置硬件识别校验（确认UPS被系统识别）

1. 查看全部USB设备，定位UPS硬件

lsusb

本机标准输出参考

Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 8087:8000 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 002: ID 214b:7250 Huasheng Electronics USB2.0 HUB
Bus 002 Device 003: ID 214b:7250 Huasheng Electronics USB2.0 HUB
Bus 002 Device 004: ID 214b:7250 Huasheng Electronics USB2.0 HUB
Bus 002 Device 005: ID 1b3f:2008 Generalplus Technology Inc. USB Audio Device
# 目标UPS设备行
Bus 002 Device 006: ID 0463:ffff MGE UPS Systems UPS
Bus 003 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub

提取关键参数

厂商ID：0463，设备ID：ffff

2. 查看UPS对应的HID硬件设备

ls /dev/usb/hiddev*

本机输出

/dev/usb/hiddev0

注意：本机UPS经过USB HUB转接，长期使用存在通信丢包风险，推荐将UPS数据线直插主板后置原生USB2.0接口

二、安装NUT核心服务包（剔除nut-cgi，减少维护负担）

执行安装命令

apt update && apt install nut nut-server nut-client nut-monitor -y

组件功能说明

1. nut-server：UPS硬件数据采集服务，内置upsd监听进程，负责对外提供UPS数据
2. nut-monitor：断电检测核心程序，触发PVE原生批量关机接口
3. nut-client：提供upsc查询工具，PVE节点「UPS信息」面板底层依赖此工具读取数据

本方案不安装nut-cgi，舍弃独立Web面板，仅使用PVE原生节点UPS状态展示，无Apache额外服务占用资源

三、分步修改NUT全套核心配置文件

步骤1：配置UPS硬件定义 /etc/nut/ups.conf（修复面板查询失败核心文件）

编辑文件

vi /etc/nut/ups.conf

清空原有内容，写入山特TG-BOX850专属绑定配置

[ups]
    driver = usbhid-ups
    port = auto
    desc = "homelab 山特SANTAK TG-BOX 850 USB UPS (0463:ffff)"
    vendorid = 0463
    productid = ffff
    pollfreq = 30
    offdelay = 20

配置关键解释

1. [ups]：设备名强制固定，匹配PVE面板默认查询地址ups@localhost，改名会直接报查询失败
2. usbhid-ups：通用USB HID驱动，原生兼容MGE协议山特UPS
3. vendorid=0463 / productid=ffff：精准锁定本机UPS，避免其他USB设备干扰驱动扫描
4. pollfreq=30：30秒轮询一次硬件，适配TG-BOX850通信速率
5. offdelay=20：市电丢失后延迟20秒再开始检测低电量，避免瞬间闪断误关机

步骤2：设置NUT全局运行模式 /etc/nut/nut.conf

编辑文件

vi /etc/nut/nut.conf

修改MODE参数

MODE=netserver

参数说明

netserver模式：同时支持本地回环访问、局域网其他设备读取UPS状态

步骤3：配置NUT访问权限账号 /etc/nut/upsd.users

编辑文件

vi /etc/nut/upsd.users

写入两组账号（监控账号用于断电关机，管理员用于手动调试）

[admin]
    password = Admin@123
    actions = SET
    instcmds = ALL

[monitor]
    password = Monitor@456
    upsmon master

账号说明

1. admin：管理员账号，可读写UPS参数、手动下发控制指令
2. monitor：主监控账号，upsmon服务使用此账号读取UPS、触发关机逻辑，密码后续upsmon.conf必须完全一致

步骤4：配置断电自动关机逻辑 /etc/nut/upsmon.conf（核心关机规则文件，采用PVE原生stopall接口）

编辑文件

vi /etc/nut/upsmon.conf

完整替换全部内容（废弃自定义shell脚本，使用官方原生批量关机接口）

# 匹配PVE面板默认读取地址 ups@localhost
MONITOR ups@localhost 1 monitor Monitor@456 master

MINSUPPLIES 1
# 【核心优化】使用PVE官方原生stopall API，批量关闭所有KVM虚拟机+LXC容器，无自定义脚本
SHUTDOWNCMD "/usr/bin/pvesh --nooutput create /nodes/localhost/stopall && sleep 30 && systemctl poweroff"

NOTIFYCMD /usr/sbin/upssched
POLLFREQ 5
POLLFREQALERT 1
HOSTSYNC 30
DEADTIME 30
POWERDOWNFLAG /etc/killpower

# 告警文字自定义
NOTIFYMSG ONLINE    "UPS %s 市电正常在线供电"
NOTIFYMSG ONBATT    "UPS %s 市电断开，切换电池供电"
NOTIFYMSG LOWBATT   "UPS %s 电池电量过低，即将执行关机流程"
NOTIFYMSG FSD       "UPS %s 强制断电保护，开始关闭设备"

# 告警输出渠道：系统日志+终端弹窗
NOTIFYFLAG ONLINE    SYSLOG
NOTIFYFLAG ONBATT    SYSLOG+WALL
NOTIFYFLAG LOWBATT   SYSLOG+WALL
NOTIFYFLAG FSD       SYSLOG+WALL

关键参数说明

1. MONITOR ups@localhost 1 monitor Monitor@456 master：监控本地UPS，账号密码与upsd.users内monitor账号严格匹配
2. SHUTDOWNCMD 执行逻辑：
   • /usr/bin/pvesh --nooutput create /nodes/localhost/stopall：调用PVE内置API，自动遍历所有运行VM/CT，下发ACPI优雅关机，自带锁、超时、异常容错，规避手动脚本D-Bus/锁冲突报错
   • sleep 30：延长关机等待时间，适配FNAS大容量存储磁盘卸载需求
   • systemctl poweroff：全部虚拟机关闭完成后，宿主机整机断电
3. HOSTSYNC 30：底层监控等待时长，与脚本休眠时长对齐

步骤5：配置NUT服务监听地址 /etc/nut/upsd.conf（解决本地回环连接拒绝）

编辑文件

vi /etc/nut/upsd.conf

写入监听规则，开放本地回环与全网段

LISTEN 127.0.0.1 3493
LISTEN 0.0.0.0 3493

说明

127.0.0.1 3493是PVE节点面板读取UPS数据必需监听地址，缺失会出现连接拒绝报错

四、防火墙端口放行（修正原错误pve-firewall命令，使用iptables永久放行）

原错误命令（废弃，PVE9.x无pve-firewall rules add子命令）

# 废弃，执行会报unknown command
pve-firewall rules add --type in --dport 3493 --action ACCEPT --source 127.0.0.1/32

正确放行端口命令（系统iptables永久生效）

# 放行本地回环127.0.0.1，供PVE后台读取UPS数据
iptables -A INPUT -s 127.0.0.1/32 -p tcp --dport 3493 -j ACCEPT
# 放行局域网网段192.168.1.0/24，其他内网设备可读取UPS状态
iptables -A INPUT -s 192.168.1.0/24 -p tcp --dport 3493 -j ACCEPT

验证端口监听状态

ss -tulpn | grep 3493

正常输出参考

tcp   LISTEN 0      16         127.0.0.1:3493      0.0.0.0:*    users:(("upsd",pid=xxxx,fd=4))

五、永久修复USB设备权限（解决Driver not connected驱动断开问题）

问题根源

临时执行chmod 666 /dev/usb/hiddev0重启系统/重新插拔USB后权限重置，驱动无法读取硬件，出现Driver not connected报错，通过udev规则永久赋权。

步骤1：创建udev规则文件

vi /etc/udev/rules.d/50-mge-box850-ups.rules

写入专属规则（匹配山特TG-BOX850 ID 0463:ffff）

# 山特SANTAK TG-BOX 850 UPS USB设备永久读写权限
SUBSYSTEM=="usb", ATTRS{idVendor}=="0463", ATTRS{idProduct}=="ffff", MODE="0666", GROUP="nut", TAG+="systemd"

步骤2：重载udev规则生效

udevadm control --reload-rules
udevadm trigger --subsystem-match=usb

临时权限应急命令（仅调试使用，重启失效）

chmod 666 /dev/usb/hiddev0

六、NUT服务启用与重启（修正原upsd服务冲突报错）

原错误启用命令（废弃，upsd是nut-server软链接，单独启用会冲突）

# 废弃，执行会报Failed to enable unit: Refusing to operate on linked unit file upsd.service
systemctl enable --now nut-server nut-monitor upsd

正确服务启用命令（仅启用nut-server、nut-monitor，upsd随nut-server自动启动）

# 设置开机自启并立即启动
systemctl enable --now nut-server nut-monitor
# 重启全套NUT服务
systemctl restart nut-server nut-monitor

查看服务运行状态

1. 查看采集服务nut-server

systemctl status nut-server

正常状态：active (running)，主进程为upsd

2. 查看断电监控服务nut-monitor

systemctl status nut-monitor

正常状态：active (running)，进程为upsmon

实时查看UPS驱动日志（排查连接失败）

journalctl -u nut-server -f

正常成功日志标识

Connected to UPS [ups]: usbhid-ups-ups

临时启动日志（无需处理，属于正常时序报错）

Can't connect to UPS [ups] (usbhid-ups-ups): No such file or directory

该报错仅出现在服务重启瞬间，驱动扫描完成后会自动重连成功，不影响长期运行

七、核心连通性校验（模拟PVE面板读取逻辑）

执行查询UPS完整数据命令

upsc ups@localhost

成功输出判定标准（本机完整输出节选）

battery.charge: 100
battery.runtime: 2280
device.model: SANTAK TG-BOX 850 
ups.load: 14
ups.status: OL
output.voltage: 230.0
ups.power.nominal: 850
ups.realpower: 95

1. 输出包含device.model: SANTAK TG-BOX 850代表驱动完全识别UPS；
2. ups.status: OL = 市电在线供电；OL代表正常在线；
3. 执行成功后，刷新PVE节点「概要」页面，ups@localhost 查询失败报错消失，面板正常展示UPS全部实时参数。

关机流程安全测试（优先关闭全部业务虚拟机）

# 原生官方关机指令，模拟断电执行逻辑
/usr/bin/pvesh --nooutput create /nodes/localhost/stopall && sleep 30 && systemctl poweroff

八、市电断电完整保护执行流程（基于PVE原生stopall关机）

1. 市电断开 → 山特TG-BOX850 UPS自动切换电池供电；
2. NUT每5秒轮询检测到ONBATT电池模式，系统日志+终端弹窗推送断电告警；
3. UPS电池放电至硬件内置20%低电量阈值，NUT触发FSD强制关机指令；
4. 执行SHUTDOWNCMD内置原生接口：
   1. pvesh stopall 批量有序关闭全部KVM虚拟机+LXC容器：150 ubuntu → 151 ubuntu-dev → 152 iStoreOS → 155 fnnas飞牛 → 160 win11
   2. 休眠30秒，等待存储虚拟机完成磁盘阵列卸载、数据落盘
   3. systemctl poweroff 宿主机整机系统断电
5. UPS检测无负载输出，自动切断供电；
6. 市电恢复来电（配套来电自启配置见第九节）：
   • UPS等待30秒（ups.delay.start=30）后输出电源；
   • 主板BIOS来电自启，宿主机自动开机；
   • PVE按预设开机自启顺序自动启动所有虚拟机。

九、来电自动开机完整配置（硬件+虚拟机双层配置）

9.1 宿主机主板来电自启（底层硬件，必须配置）

1. 重启宿主机，开机按Del/F2进入BIOS电源管理页面；
2. 找到选项 AC Power Recovery / After Power Loss；
3. 设置为 Power On / Always On（来电自动开机），不要选择Stay Off；
4. 保存BIOS退出。

9.2 虚拟机开机自启（宿主机开机后自动启动VM）

图形界面单台配置

1. 虚拟机 → 选项 → 开机自启动：勾选启用；
2. 调整启动序号：FNAS飞牛设置更大数字，延后启动，等待磁盘就绪。

批量命令一键开启所有虚拟机自启

for vid in $(qm list | awk 'NR>1 {print $1}'); do qm set $vid --onboot 1; done

--onboot 1=开机自启；--onboot 0=关闭自启

十、各虚拟机ACPI关机兼容性说明

1. 150/151 Ubuntu（Linux虚拟机）
   原生支持ACPI电源关机，stopall接口下发关机信号自动保存进程、卸载磁盘。
2. 152 iStoreOS
   内置电源管理模块，收到关机指令自动断开网络、卸载存储介质。
3. 155 FNAS飞牛（存储核心）
   存储系统优先卸载硬盘阵列，SHUTDOWNCMD内置sleep 30延长磁盘卸载等待时间，规避文件损坏风险。
4. 160 Win11 虚拟机
   机型q35默认开启ACPI，虚拟机「选项」中勾选「启用关机代理」，提升Windows优雅关机稳定性。

十一、全流程故障排查清单（对应部署过程遇到的所有报错）

故障1：执行pve-firewall rules add提示unknown command

• 原因：PVE9.x版本pve-firewall无rules add子命令
• 解决：改用iptables命令放行3493端口，见第四节防火墙配置

故障2：systemctl enable --now nut-server nut-monitor upsd 报链接单元冲突

• 原因：upsd.service是nut-server内置软链接，不能单独启用
• 解决：删除命令中upsd，仅启用nut-server nut-monitor

故障3：upsc ups@localhost 报错Error: Driver not connected

1. 排查udev永久权限规则是否创建并重载；
2. 检查UPS USB线直插主板后置USB2.0，移除多级HUB；
3. 核对ups.conf内vendorid=0463 productid=ffff与硬件匹配；
4. 重启nut-server服务：systemctl restart nut-server。

故障4：PVE节点面板提示ups@localhost 查询失败，请检查 NUT 配置或设备名

1. 确认ups.conf设备名为[ups]，不可自定义其他名称；
2. upsd.conf包含LISTEN 127.0.0.1 3493本地回环监听；
3. iptables放行127.0.0.1 3493端口；
4. 执行upsc ups@localhost验证底层连通，刷新浏览器页面。

故障5：手动执行关机脚本出现D-Bus锁超时报错

• 根源：手动shell循环qm stop无内置锁机制，测试环境会话冲突
• 解决：全程使用本方案pvesh stopall原生接口，官方自带锁与异常容错，规避此类报错

故障6：服务启动日志短暂打印Can't connect to UPS

• 说明：服务启动时序问题，驱动扫描完成后自动重连，无需任何修复操作，不影响长期稳定运行。

故障7：市电来电后宿主机不开机

• 根源：BIOS电源选项未设置来电自启
• 解决：进入BIOS修改AC Power Recovery为Power On

十二、最终验收标准（部署完成全部达标项）

1. PVE节点「概要」页面UPS信息正常展示：型号SANTAK TG-BOX 850、电量100%、负载、剩余续航、输出电压，无查询失败报错；
2. upsc ups@localhost可完整读取UPS全部硬件参数；
3. systemctl status nut-server、systemctl status nut-monitor均为active (running)；
4. 断电场景可通过PVE原生stopall接口自动有序关闭全部虚拟机，最后关闭宿主机；
5. 系统重启后无需重新配置USB权限，驱动持续稳定连接UPS；
6. 市电恢复后，宿主机自动开机，虚拟机按预设顺序自启动；
7. 无自定义shell关机脚本，减少维护点，底层依赖PVE官方持续维护API，稳定性拉满。

十三、效果