使用 APCUPSD 让 PVE 接入 UPS 获得断电保护

前言

最近一直想整台 UPS 给 PVE 玩玩，正巧又看见了玩转PVE：连接施耐德UPS实现自动关机 - 知乎这篇文章，折腾属性大发，当即买了台 APC 的 UPS 回来玩。

本文内容参考上述文章并扩充一些内容。本文作记录分享/教学用均可。

环境介绍

以下是本文环境：

PVE 9.1.1
UPS：APC BK650M2-CH

概念科普

APCUPSD

apcupsd 是一款开源、跨平台的软件，全称是 APC UPS Daemon。它的核心功能是监控和管理美国电力转换公司（APC，现属于施耐德电气）的不同断电源（UPS）设备，确保在停电或电力异常时，受保护的计算机或服务器能够安全、自动地关机，从而防止数据丢失或硬件损坏。

守护进程：apcupsd 作为一个后台服务（daemon）运行。
通信：通过USB/串口等与UPS硬件保持通信，定期查询状态。
事件触发：当检测到预设的“危险”条件（如市电断电且电池电量低于某个阈值）时，触发关机序列。
执行关机：按照配置，在电池耗尽前预留足够时间，向系统发送关机命令。

正式开始

一、安装 APCUPSD 服务

SSH 或通过其他方式连接到 PVE 主机的 SHELL。然后执行：

apt-get install apcupsd -y

执行后将安装 APCUPSD

二、编辑 APCUPSD 服务配置文件

我们编辑 /etc/apcupsd/apcupsd.conf，编辑器挑一个顺手即可，这里以 nano 为例：

nano /etc/apcupsd/apcupsd.conf

二【附】、配置项解释

忽略掉注释行文字，剩下的就是配置项了：

UPSCABLE usb

此项配置 UPS 与 PVE 的连接线材类型。一般使用 USB 连接，这里默认即可。

UPSTYPE usb

UPS 与 PVE 连接方式。默认无需修改。

DEVICE /dev/ttyS0

指定的设备路径。若使用 USB 连接，请务必将此行注释掉。（特别提醒：注释后遇到问题可以翻阅本文第六章即常见问题解决方案）

我们再向下翻，可以看见一些如下配置项。这些配置项是电力故障时的设置。

#
# ======== Configuration parameters used during power failures ==========
#

# The ONBATTERYDELAY is the time in seconds from when a power failure
#   is detected until we react to it with an onbattery event.
#
#   This means that, apccontrol will be called with the powerout argument
#   immediately when a power failure is detected.  However, the
#   onbattery argument is passed to apccontrol only after the
#   ONBATTERYDELAY time.  If you don't want to be annoyed by short
#   powerfailures, make sure that apccontrol powerout does nothing
#   i.e. comment out the wall.
ONBATTERYDELAY 6

#
# Note: BATTERYLEVEL, MINUTES, and TIMEOUT work in conjunction, so
# the first that occurs will cause the initation of a shutdown.
#

# If during a power failure, the remaining battery percentage
# (as reported by the UPS) is below or equal to BATTERYLEVEL,
# apcupsd will initiate a system shutdown.
BATTERYLEVEL 5

# If during a power failure, the remaining runtime in minutes
# (as calculated internally by the UPS) is below or equal to MINUTES,
# apcupsd, will initiate a system shutdown.
MINUTES 3

# If during a power failure, the UPS has run on batteries for TIMEOUT
# many seconds or longer, apcupsd will initiate a system shutdown.
# A value of 0 disables this timer.
#
#  Note, if you have a Smart UPS, you will most likely want to disable
#    this timer by setting it to zero. That way, you UPS will continue
#    on batteries until either the % charge remaing drops to or below BATTERYLEVEL,
#    or the remaining battery runtime drops to or below MINUTES.  Of course,
#    if you are testing, setting this to 60 causes a quick system shutdown
#    if you pull the power plug.
#  If you have an older dumb UPS, you will want to set this to less than
#    the time you know you can run on batteries.
TIMEOUT 0

对其中配置项解释如下：

【名称】	【含义】	【单位】
ONBATTERYDELAY	断电多少时间后才识别为正在使用电池，防止短时间断电导致错误	秒/s
BATTERYLEVEL	电池电量低于多少时关闭主机，建议修改为95	百分比/%
MINUTES	当电池剩余后备时间为多少时关闭主机	分钟/min
TIMEOUT	断电时间（默认 0 即关闭）	分钟/min

注：若 BATTERYLEVEL、MINUTES、TIMEOUT 三个配置均被设置，则满足默认其中一个条件时便触发关机。

编辑完成后，按下键盘上的 ctrl+o 保存文件，随后按下 ctrl+x 退出编辑器。

三、启动服务并设置开机自启

启动 apcupsd 服务：

systemctl start apcupsd.service

设置服务开机自启动：

systemctl enable apcupsd.service

查看服务运行状态：

systemctl status apcupsd.service

四、查看 UPS 状态

执行：

apcaccess

打印类似如下内容：

root@pve:~# apcaccess
APC      : 001,035,0824
DATE     : 2025-12-06 13:50:00 +0800
HOSTNAME : pve
VERSION  : 3.14.14 (31 May 2016) debian
UPSNAME  : pve
CABLE    : USB Cable
DRIVER   : USB UPS Driver
UPSMODE  : Stand Alone
STARTTIME: 2025-12-06 13:49:58 +0800
MODEL    : Back-UPS BK650M2_CH
STATUS   : ONLINE
LINEV    : 220.0 Volts
LOADPCT  : 15.0 Percent
BCHARGE  : 99.0 Percent
TIMELEFT : 39.6 Minutes
MBATTCHG : 25 Percent
MINTIMEL : 3 Minutes
MAXTIME  : 0 Seconds
SENSE    : Low
LOTRANS  : 160.0 Volts
HITRANS  : 278.0 Volts
ALARMDEL : 30 Seconds
BATTV    : 13.5 Volts
LASTXFER : No transfers since turnon
NUMXFERS : 0
TONBATT  : 0 Seconds
CUMONBATT: 0 Seconds
XOFFBATT : N/A
SELFTEST : OK
STATFLAG : 0x05000008
SERIALNO : 9B2536A51882
BATTDATE : 2001-01-01
NOMINV   : 220 Volts
NOMBATTV : 12.0 Volts
NOMPOWER : 390 Watts
END APC  : 2025-12-06 13:50:04 +0800

STATUS : ONLINE 说明 UPS 已被成功连接至 PVE。若该栏显示为 COMMLOST 则表示通信丢失，可以移步至本文六、常见问题排查一章。

五、模拟电力故障测试

执行 systemctl status apcupsd.service，然后拔掉 UPS 与市电连接的电源，status变成了ONBATT。

六、常见问题

Q：我执行 apcaccess 后看见 STATUS : COMMLOST？

A：如果你根据本文进行操作并遇到这个问题（我实操时也遇到了），大概率是配置文件的缘故。我们前面不是该过一个 DEVICE /dev/ttyS0 吗？当时说是要注释掉，但实际上我发现这样会造成 COMMLOST 状态。尝试将这行取消注释而直接留空后恢复正常。由于参考文章中表示要注释且我并未做详细对照试验，所以保留了这一或许是错误的内容。