Ubuntu 下 apcupsd 使用指南
前言
对于需要 7×24 小时运行的 Linux 服务器或 NAS 设备来说，意外断电不仅是数据灾难的源头，更可能损坏文件系统甚至硬件。虽然 APC（美国电力转换公司）的 UPS 在使用 USB 连接到电脑时就能提供基础的浪涌保护，但要让系统在断电时自动、优雅地关机，还是需要专门的守护进程来管理。
apcupsd 正是一个开源的 UPS 管理守护进程，专门用于监控和控制 APC 品牌的 UPS。它负责检测市电中断、电池电量变化，并在合适时机执行安全关机，最大程度保护你的数据和硬件。
本文将详细介绍在 Ubuntu 系统下从安装、配置到使用 apcupsd 的完整流程。
1. 什么是 apcupsd？
apcupsd（APC UPS Daemon）是 APC 旗下不同型号 UPS 的电源管理守护进程。它提供了三大核心功能：
| 功能 | 说明 |
|---|---|
| 实时监控 | 通过 USB/串口/SNMP 与 UPS 通信，持续获取电压、负载、电池状态、剩余时间等信息 |
| 自动关机 | 市电中断且电池电量低于阈值时，自动执行系统安全关机 |
| 事件告警 | 断电、恢复、电池低电量等事件发生时，可通过邮件等方式通知管理员 |
apcupsd 附带以下主要工具：
apcaccess— 命令行下查询 UPS 实时状态apctest— 测试和修改 UPS 的 EEPROM 参数（需先停止 apcupsd 服务）apcupsd-cgi— Web 界面，方便浏览器远程监控
2. 安装 apcupsd
Ubuntu 官方仓库中已经包含了 apcupsd，一行命令即可安装：
sudo apt update
sudo apt install -y apcupsd
如果希望使用 Web 监控界面，再额外安装 CGI 包：
sudo apt install -y apcupsd-cgi
安装完成后，主要文件分布在以下位置：
| 路径 | 说明 |
|---|---|
/etc/apcupsd/apcupsd.conf |
主配置文件 |
/etc/apcupsd/apccontrol |
事件处理脚本（不建议直接修改） |
/etc/default/apcupsd |
Debian/Ubuntu 特有的服务开关配置 |
/var/log/apcupsd.events |
事件日志文件 |
3. 基本配置
3.1 备份原始配置
在修改之前，先备份原文件：
sudo cp /etc/apcupsd/apcupsd.conf /etc/apcupsd/apcupsd.conf.bak
sudo cp /etc/default/apcupsd /etc/default/apcupsd.bak
3.2 编辑主配置文件
使用编辑器打开 /etc/apcupsd/apcupsd.conf：
sudo nano /etc/apcupsd/apcupsd.conf
① 设置连接方式
对于大多数通过 USB 连接的家用 / 小型 UPS（如 Back-UPS、Smart-UPS 系列），配置如下：
UPSCABLE usb
UPSTYPE usb
# DEVICE /dev/ttyS0 ← 注释掉，USB 模式下不需要
如果你的 UPS 通过串口连接，则配置为：
UPSCABLE smart
UPSTYPE smartups
DEVICE /dev/ttyS0
如果是通过网络管理的 UPS（APC 网络管理卡），则配置为：
UPSCABLE ether
UPSTYPE net
DEVICE 192.168.1.100:3551
② 设置 UPS 名称（可选）
UPSNAME my_ups
名称可以自定义，方便在多台设备监控时区分。
③ 设置自动关机触发条件
以下三个参数配合工作，只要满足其一就会触发关机：
# 电池电量 ≤ 此百分比时触发关机
BATTERYLEVEL 30
# 剩余续航 ≤ 此分钟数时触发关机
MINUTES 10
# 市电中断后最多等待此秒数（0 表示禁用时间限制）
TIMEOUT 0
常见推荐配置：
- 家庭服务器 / NAS：
BATTERYLEVEL 30、MINUTES 5 - 对数据安全要求极高的场景：
BATTERYLEVEL 50、MINUTES 10
④ 其他可选参数
# 轮询间隔（秒），默认 60
POLLTIME 60
# 电池电量低于此百分比时发出警报
BATTERYLEVEL 30
# 电池耗尽告警延迟（秒）
ALARMDEL 30
完整的配置完成后，保存文件退出。
3.3 启用 apcupsd 服务
编辑 /etc/default/apcupsd：
sudo nano /etc/default/apcupsd
确保以下内容存在且未被注释：
ISCONFIGURED=yes
这一步非常关键——如果缺少这个设置，apcupsd 会拒绝启动。
3.4 启动服务并设置开机自启
sudo systemctl enable apcupsd
sudo systemctl restart apcupsd
检查服务状态：
sudo systemctl status apcupsd
输出应显示 active (running)，说明服务正常运行。
4. 查看 UPS 状态 —— `apcaccess`
apcaccess 是 apcupsd 最重要的监控命令，它从守护进程获取实时数据并格式化输出：
apcaccess
典型输出如下：
APC : 001,036,0875
DATE : 2026-07-24 16:30:15 +0800
HOSTNAME : myserver
VERSION : 3.14.14 (31 May 2016) debian
UPSNAME : my_ups
CABLE : USB Cable
DRIVER : USB UPS Driver
UPSMODE : Stand Alone
STARTTIME: 2026-07-24 08:00:12 +0800
MODEL : Back-UPS RS 1500G
STATUS : ONLINE
LINEV : 224.0 Volts
LOADPCT : 12.0 Percent
BCHARGE : 100.0 Percent
TIMELEFT : 55.3 Minutes
MBATTCHG : 30 Percent
MINTIMEL : 5 Minutes
MAXTIME : 0 Seconds
SENSE : Medium
LOTRANS : 176.0 Volts
HITRANS : 294.0 Volts
ALARMDEL : 30 Seconds
BATTV : 27.2 Volts
LASTXFER : Unacceptable line voltage changes
NUMXFERS : 0
TONBATT : 0 Seconds
CUMONBATT: 0 Seconds
XOFFBATT : N/A
SELFTEST : NO
STATFLAG : 0x05000008
SERIALNO : 3Q1106X37131
BATTDATE : 2024-07-05
NOMINV : 230 Volts
NOMBATTV : 24.0 Volts
NOMPOWER : 865 Watts
FIRMWARE : 878.L4 .I USB FW:L4
END APC : 2026-07-24 16:30:18 +0800
其中重要的字段含义：
| 字段 | 含义 | 正常范围 |
|---|---|---|
STATUS |
UPS 当前状态 | ONLINE（正常）/ ONBATT（电池供电） |
LINEV |
市电输入电压 | 依地区不同，~220V / ~110V |
LOADPCT |
负载百分比 | 越低越好，建议 < 50% |
BCHARGE |
电池剩余电量百分比 | 正常应接近 100% |
TIMELEFT |
当前负载下剩余续航时间 | 分钟数 |
TONBATT |
本次断电已使用电池供电的秒数 | 断电时累加 |
NUMXFERS |
切换到电池供电的次数 | 数值越大说明市电越不稳定 |
5. 事件日志查看
apcupsd 将所有事件记录在 /var/log/apcupsd.events，你可以随时查看：
# 查看最近的日志
tail -f /var/log/apcupsd.events
# 查看所有日志
cat /var/log/apcupsd.events
典型事件输出示例：
2026-07-20 14:32:10 +0800 Power failure.
2026-07-20 14:32:15 +0800 Running on UPS batteries.
2026-07-20 14:37:40 +0800 Power is back. UPS running on mains.
2026-07-20 14:37:40 +0800 Mains reapparent. Shutting down UPS.
6. 自定义事件处理脚本
apcupsd 的事件处理机制非常灵活。它默认使用 /etc/apcupsd/apccontrol 脚本处理以下事件：
| 事件名称 | 触发条件 |
|---|---|
onbattery |
切换到电池供电 |
offbattery |
市电恢复 |
doshutdown |
即将执行关机 |
commfailure |
与 UPS 通信中断 |
commok |
与 UPS 通信恢复 |
changeme |
需要更换电池 |
emergencyshutdown |
紧急关机触发 |
mainsback |
市电恢复（UPS 切回市电） |
killpower |
切断 UPS 输出电源 |
startupscript |
apcupsd 启动时 |
stayson |
系统将继续运行，无需关机 |
要自定义某个事件的处理行为，不要修改 apccontrol 本身，而是在 /etc/apcupsd/ 下创建以事件命名的自定义脚本。自定义脚本会在系统默认处理之前被执行。
示例：断电时发送桌面通知（需要 notify-send）：
sudo tee /etc/apcupsd/onbattery << 'EOF'
#!/bin/bash
DISPLAY=:0.0 /usr/bin/notify-send -u critical "UPS 断电告警" "市电已中断，正在使用电池供电！"
EOF
sudo chmod +x /etc/apcupsd/onbattery
示例：断电时发送 HTTP 请求（如 Webhook 通知）：
sudo tee /etc/apcupsd/onbattery << 'EOF'
#!/bin/bash
curl -s -o /dev/null -X POST \
-H "Content-Type: application/json" \
-d '{"text":"⚠️ 市电中断，UPS 切换到电池供电！"}' \
https://hooks.example.com/webhook
EOF
sudo chmod +x /etc/apcupsd/onbattery
注意：自定义脚本必须设置可执行权限（
chmod +x），否则不会被调用。
7. 设置邮件告警
apcupsd 默认使用系统邮件向 root 用户发送告警。要实现真正的邮件通知，需要安装 MTA（邮件传输代理）：
sudo apt install -y exim4
sudo dpkg-reconfigure exim4-config
配置完成后，还需要将 root 邮件转发到你的真实邮箱。编辑 /etc/aliases：
root: your-email@example.com
然后执行：
sudo newaliases
之后在断电、恢复、低电量等事件发生时，apcupsd 会自动发送邮件通知。
8. Web 监控界面
使用 apcupsd-cgi 配合 Apache 即可通过浏览器远程监控 UPS 状态。
8.1 安装 Web 服务器和 CGI 模块
sudo apt install -y apache2 apcupsd-cgi
# 确保 Apache 启用了 CGI 模块
sudo a2enmod cgi
sudo systemctl restart apache2
8.2 访问 Web 界面
浏览器打开：
http://your-server-ip/cgi-bin/apcupsd/multimon.cgi
Web 界面直观显示：
- UPS 状态（绿色表示正常，红色告警）
- 实时数据（输入电压、负载百分比、剩余电池电量、续航时间）
- 历史事件记录
你还可以通过配置 /etc/apcupsd/multimon.conf 自定义界面中显示的参数。
9. 测试 UPS 功能 —— `apctest`
apctest 工具可以让你对 UPS 进行诊断测试和参数修改。注意：运行前必须先停止 apcupsd 服务，否则会报锁文件冲突。
sudo systemctl stop apcupsd
sudo apctest
成功进入后，你将看到交互菜单：
1) Test kill UPS power 2) Perform self-test
3) Read last self-test result 4) View/Change battery date
5) View manufacturing date 6) View/Change alarm behavior
7) View/Change sensitivity 8) View/Change low transfer voltage
9) View/Change high transfer voltage
10) Perform battery calibration
11) Test alarm 12) View/Change self-test interval
Q) Quit
常用选项说明：
| 选项 | 用途 | 建议 |
|---|---|---|
| 2 | 执行自检 | 定期检查电池健康状况 |
| 3 | 查看上次自检结果 | 排查电池问题 |
| 6 | 设置蜂鸣器行为 | 夜间建议关闭蜂鸣 |
| 12 | 设置自检间隔（天） | 默认 7 天一次即可 |
测试完成后记得重启服务：
sudo systemctl start apcupsd
10. NIS 网络模式（多台设备共享一台 UPS）
如果你有多台服务器共用一台 UPS，可以用 NIS（Network Information Server）模式实现联动关机。步骤如下：
主服务器（连接 UPS 的机器）
在 /etc/apcupsd/apcupsd.conf 中：
NETSERVER on
NISIP 0.0.0.0
NISPORT 3551
从属服务器
安装 apcupsd 后，配置为 NIS 客户端模式：
UPSCABLE ether
UPSTYPE net
DEVICE 192.168.1.10:3551
这样当主服务器因断电触发关机时，它会通知从属服务器一同安全关机。
11. 常见问题排查
Q1: apcupsd 启动失败
检查日志：
journalctl -u apcupsd -n 50 --no-pager
常见原因：
/etc/default/apcupsd中ISCONFIGURED未设为yes- USB 设备权限问题（确认
/dev/usb/hiddev*或/dev/hidraw*可读） apcupsd.conf中语法错误
Q2: `apcaccess` 显示 `COMMLOST`
表示 apcupsd 与 UPS 通信失败。尝试：
# 检查 USB 设备是否被识别
lsusb | grep -i apc
# 重启 apcupsd
sudo systemctl restart apcupsd
# 检查是否有其他程序占用了 USB 设备（如 nut）
Q3: 关机后 UPS 不断电
默认情况下，USB 连接的 UPS 在系统关机后 60 秒才会切断输出电源。这是 UPS 硬件设计决定的，确保系统有足够时间完成写盘操作。如果希望强制立即断电，可以在 /etc/apcupsd/apccontrol 的 doshutdown 事件中添加 killpower 调用。
Q4: `apctest` 报错 "Unable to create UPS lock file"
说明 apcupsd 仍在运行。先停止服务：
sudo systemctl stop apcupsd
然后再运行 sudo apctest。
结语
apcupsd 虽然诞生于 90 年代末，但它依然是 Linux 生态下最成熟、最可靠的 APC UPS 管理方案之一。从简单的 USB 连接到复杂的 NIS 多机联动，从日志监控到自定义脚本告警，它都能出色胜任。
配置完成后，建议定期用 apcaccess 查看电池健康状况，并结合 apctest 的自检功能检查 UPS 状态。毕竟，UPS 本身也是有寿命的——电池一般 3~5 年需要更换，提前发现异常远比断电时手忙脚乱要好得多。
希望这篇教程能帮你顺利搭建起自己的 UPS 管理方案，让你的服务器和数据在断电时也能安然无恙 😊
参考资源：