⚡ UPS Guard 用户使用说明

更新日期：2026-03-05 | 开发者：王.W

https://appstore.lazycat.cloud/#/shop/detail/cloud.lazycat.app.ups-guard

📚 目录

产品简介
系统要求
安装与部署
首次使用
仪表盘（Dashboard）
历史记录（History）
事件日志（Events）
设置（Settings）
关机保护流程
来电自动唤醒（WOL）
支持的 UPS 设备
主题与界面
配置导入导出
API 参考
故障排除
安全说明
附录：术语表

产品简介

UPS Guard 是一个功能完整、安全可靠、性能优异的 UPS 智能监控与管理解决方案。

它能做什么？

能力	说明
🔌 实时监控	WebSocket 实时推送 UPS 状态（电量、电压、负载、温度），无需刷新页面
🔋 智能关机	停电后自动倒计时关机，市电恢复自动取消；支持电量阈值和续航阈值双重触发
📱 多设备纳管	一台 UPS 管理多台设备：Windows、Linux、macOS、群晖、威联通、懒猫微服
⏻ 来电唤醒	市电恢复后自动发送 WOL 魔术包唤醒所有纳管设备
📈 数据可视化	ECharts 实时曲线图，历史趋势分析，电池健康评估
🔔 多渠道通知	Server酱、PushPlus、钉钉、Telegram、邮件、自定义 Webhook
🔧 硬件参数调节	直接修改 UPS 硬件参数（电压阈值、灵敏度、关机延迟）
🐳 一键部署	Docker Compose / 懒猫微服 lpk / 群晖 / 威联通，开箱即用

支持的部署平台

平台	部署方式	配置目录
懒猫微服	原生应用（lpk）	`deploy/lazycat/`
群晖 NAS	Container Manager	`deploy/synology/`
威联通 NAS	Container Station	`deploy/qnap/`
Linux / Windows / macOS	Docker Compose	`deploy/docker/`

系统要求

硬件要求

至少 512MB RAM（推荐 1GB）
至少 500MB 存储空间
USB 接口（连接 UPS 设备）

软件要求

Docker Engine 20.10+ 和 Docker Compose 2.0+
或懒猫微服 LZCOS 系统

支持的 UPS 品牌

品牌	USB Vendor ID	推荐驱动	测试状态
APC（施耐德）	051d	`usbhid-ups`	✅ 已验证
CyberPower	0665	`usbhid-ups`	✅ 已验证
瓦力方程（Wali）	04d8	`usbhid-ups`	✅ 已验证
山特（SANTAK）	0463	`blazer_usb`	🔄 社区反馈
伊顿（Eaton）	06da	`usbhid-ups`	🔄 社区反馈
华为	0764	`nutdrv_qx`	🔄 社区反馈

💡 UPS Guard 使用 NUT（Network UPS Tools）协议，理论上支持 NUT 兼容的所有 UPS 设备。应用启动时会自动扫描 USB 设备并识别品牌和推荐驱动。

安装与部署

方式一：懒猫微服（推荐）

从 GitHub Releases 下载最新 .lpk 文件
进入懒猫微服控制面板 → 应用商店 → 本地安装
选择下载的 .lpk 文件，等待安装完成
通过 USB 连接 UPS 到懒猫微服主机
打开应用，系统将自动检测 UPS 设备

方式二：Docker Compose（通用）

# 1. 克隆仓库
git clone https://github.com/KingBoyAndGirl/ups-guard.git
cd ups-guard/deploy/docker

# 2. 配置环境变量
cp .env.example .env
nano .env  # 按需修改

# 3. 启动服务
docker-compose up -d

# 4. 访问 Web 界面
# http://localhost:8080

方式三：群晖 / 威联通

参考 deploy/synology/README.md 或 deploy/qnap/README.md 中的详细说明。

首次使用

第 1 步：确认 UPS 连接

安装完成后，打开 Web 界面。如果一切正常，仪表盘会自动显示 UPS 状态。

如果显示"离线"或"无 UPS 连接"，请检查：

# 确认 USB 连接
lsusb  # 应能看到 UPS 设备

# 查看 NUT 日志
docker-compose logs nut-server  # 或在懒猫微服中查看应用日志

第 2 步：配置关机策略

进入设置页面，配置关机策略：

参数	推荐值	说明
断电等待时间	2-5 分钟	停电后等待多久开始关机流程
最低电量阈值	20%	电量低于此值立即触发关机
最终等待时间	30 秒	关机命令发出后，等待多久执行最终关机
续航阈值	3 分钟	预计续航低于此值触发关机

第 3 步：添加纳管设备（可选）

如果你需要 UPS Guard 在停电时自动关闭其他设备：

进入 设置 → 关机前置任务
点击 添加设备
选择设备类型（SSH / Windows / Synology / QNAP / HTTP API / 自定义脚本）
填写连接信息
点击 测试连接

第 4 步：配置通知（可选）

进入 设置 → 通知设置：

打开通知总开关
添加通知渠道（Server酱 / PushPlus / 钉钉 / Telegram / 邮件 / Webhook）
选择需要通知的事件类型
发送测试通知验证配置

第 5 步：测试（推荐）

首次使用时，建议使用 演练模式 测试完整流程：

进入 设置 → 系统配置 → 测试模式
选择 演练模式（Dry-Run）
在仪表盘中点击"立即关机"
观察关机流程是否正常（设备连接、通知发送等，但不会实际关机）
确认无误后切换回 生产模式（Production）

仪表盘（Dashboard）

仪表盘是 UPS Guard 的核心页面，提供所有关键信息的实时视图。

状态区域

页面顶部显示 UPS 当前状态：

状态	图标	含义
市电供电 (OL)	✅	UPS 由市电供电，一切正常
电池供电 (OB)	🔋	市电中断，UPS 切换到电池
低电量 (LB)	⚠️	电池电量不足
升压调节 (BOOST)	📈	输入电压偏低，UPS 升压补偿
降压调节 (TRIM)	📉	输入电压偏高，UPS 降压补偿
报警 (ALARM)	🚨	UPS 有报警信息
过载 (OVER)	🚨	UPS 负载超出容量
强制关机 (FSD)	🛑	UPS 即将强制关机

核心指标卡片

卡片	显示内容	交互功能
电池仪表盘	电量百分比、续航时间、电池电压、温度、低电量阈值、安装日期	点击设置电池安装日期
电压质量	当前输入电压、波动范围、安全区间、额定电压、切换原因、灵敏度	点击 ✏️ 编辑安全区间
负载与功率	负载百分比、额定功率、实际功率、效率	—
保护状态总览	输入灵敏度、自检结果、蜂鸣器状态	控制蜂鸣器开关/静音、启动电池测试
关机时间线	关机流程各阶段倒计时、关机规则、UPS 关机延迟	点击 ✏️ 编辑关机延迟；紧急关机/取消关机
纳管设备	设备在线/离线状态、最后检测时间	点击 ⏻ 唤醒离线设备
实时曲线图	电量、电压、负载的实时趋势	可选择不同时间范围
最近事件	最新的系统事件列表	点击查看详情
智能预测	续航预测、异常检测、电池评估（AI 分析）	—

DC UPS 适配（v1.0.71 新增）

对于 DC UPS（如瓦力方程 W120，输出 12V），系统会：

自动推断额定电压并标注 "(推断)"
正确显示 DC 电压范围（而非 AC 220V）
自动过滤已知固件误报（如 W120 的 No battery installed!）

快捷操作

操作	位置	说明
立即关机	关机时间线卡片	立即执行关机流程
取消关机	关机时间线卡片 / 状态栏	取消正在进行的关机倒计时
蜂鸣器控制	保护状态总览	启用/禁用/静音蜂鸣器
电池测试	保护状态总览	快速测试/深度测试/停止测试
WOL 唤醒	纳管设备卡片	唤醒离线的纳管设备
生成报告	右上角 📊	生成完整的 UPS 诊断报告

历史记录（History）

历史记录页面提供长期的数据趋势分析。

趋势图表

电池电量趋势：24 小时内电量变化曲线
输入电压趋势：检测电压波动
负载趋势：监控功耗变化
温度趋势：跟踪温度变化

时间范围选择

支持查看不同时间段的历史数据：

最近 1 小时 / 6 小时 / 12 小时 / 24 小时 / 7 天 / 30 天

数据降采样

当数据量较大时，系统自动进行降采样以保证图表流畅加载：

1 小时内：原始数据
6 小时内：每 2 分钟一个点
24 小时以上：自动智能降采样

事件日志（Events）

事件日志页面记录所有系统事件的完整历史。

事件类型

事件类型	图标	说明
服务启动	🚀	UPS Guard 服务启动
市电断电	⚡	检测到市电中断
市电恢复	✅	市电恢复供电
低电量	🔋	电池电量低于阈值
系统关机	🔌	执行关机命令
关机取消	↩️	关机流程被取消
NUT 断开	⚠️	NUT 服务器连接中断
NUT 连接	🔗	NUT 服务器连接恢复
参数修改	🔧	修改了 UPS 硬件参数
设备关机	🔌	纳管设备执行关机
WOL 唤醒	⏻	发送 WOL 唤醒包

筛选与搜索

按事件类型筛选
按时间范围筛选
支持关键词搜索

设置（Settings）

设置页面采用四列可拖拽卡片布局，可自由调整卡片位置。

🔧 关机策略

设置项	范围	默认值	说明
断电等待时间	1-60 分钟	5	停电后等待多久启动关机流程
最低电量	5-80%	20%	电量低于此值立即关机
最终等待时间	10-300 秒	30	关机倒计时最后的等待
续航阈值	1-30 分钟	3	预估续航低于此值触发关机

📡 监控参数

设置项	选项	推荐	说明
监控模式	轮询 / 事件驱动 / 混合	混合 ⭐	UPS 状态检测方式
NUT 轮询间隔	1-60 秒	5	轮询模式下的检查频率
采样间隔	10-600 秒	60	指标数据记录频率
数据保留	1-90 天	30	历史数据保留时长

监控模式详解

模式	响应延迟	日通信次数	说明
轮询	0-5 秒	~17,280	最稳定，兼容性好
事件驱动	< 100ms	< 100	最快，需 NUT 2.7.4+
混合 ⭐	< 100ms	~2,000	事件驱动为主 + 轮询备份

🔔 通知设置

渠道	配置项	获取方式
Server酱	SendKey	sct.ftqq.com
PushPlus	Token	pushplus.plus
钉钉	Webhook URL + Secret	钉钉群 → 群设置 → 机器人
Telegram	Bot Token + Chat ID	@BotFather
Email	SMTP 服务器信息	邮箱设置 → 开启 SMTP
Webhook	自定义 URL	自建服务

通知事件选择：

电源事件：市电断电 ⚡、恢复供电 ✅、低电量 🔋、系统关机 🔌、取消关机 ↩️
设备事件：设备关机 🔌、WOL 唤醒 ⏻、设备离线 📡
系统事件：NUT 断开 ⚠️、NUT 恢复 🔗、驱动错误 🚨

💻 关机前置任务（纳管设备）

支持的设备类型：

类型	协议	认证方式	关机命令示例
Linux/macOS	SSH	密码/密钥	`sudo shutdown -h now`
Windows	SSH	密码	`shutdown /s /t 0 /f`
Synology	SSH	密码	`sudo poweroff`
QNAP	SSH	密码	`poweroff`
HTTP API	HTTP	Token/Header	`POST /api/shutdown`
自定义脚本	Shell	—	任意脚本
懒猫微服	gRPC/SSH	—	内置 gRPC 关机

每个设备可配置：

优先级：数字越小越先关机，相同优先级并行执行
预关机命令：关机前执行的准备命令（如停止 Docker）
MAC 地址：用于来电后 WOL 唤醒
超时时间：关机命令执行超时

⚡ 来电自动唤醒（WOL）

设置项	默认值	说明
启用 WOL	关	是否在市电恢复后自动唤醒设备
WOL 延迟	60 秒	等待网络设备先启动后再发送唤醒包

⚙️ UPS 高级配置

直接修改 UPS 硬件参数（通过 NUT SET VAR 协��）：

参数	AC UPS 范围	DC UPS 范围	说明
高压切换阈值	220-300V	5-48V	超过此电压切换到电池
低压切换阈值	100-200V	1-30V	低于此电压切换到电池
输入灵敏度	低/中/高	低/中/高	对电压波动的敏感程度
关机延迟	0-600 秒	0-600 秒	UPS 收到关机命令后延迟
额定输出电压	—	5-48V	DC UPS 输出电压设置
额定输出电流	—	0.5-20A	DC UPS 输出电流设置

⚠️ 安全提示：所有参数修改经过白名单验证、范围验证、二次确认，并记录到事件历史。

🛠️ 系统配置

设置项	选项	说明
测试模式	生产 / 演练 / 模拟	见下方说明
关机方式	gRPC / SSH	懒猫微服推荐 gRPC
设备检测间隔	10-600 秒	纳管设备在线状态检测频率

📊 数据管理

查看数据库大小和记录数量
一键清理历史数据
配置数据清理间隔

📎 配置导入/导出

导出：将当前配置导出为 JSON 文件
导入：从 JSON 文件恢复配置
- 支持"覆盖"和"合并"两种导入模式
- 导入前显示配置预览和差异对比

关机保护流程

完整流程图

市电中断
  │
  ▼
检测到 UPS 切换到电池供电 (OB)
  │
  ▼
发送「市电断电」通知
  │
  ▼
开始等待计时（默认 5 分钟）
  │
  ├──── 市电恢复 ───→ 取消关机 → 发送「市电恢复」通知
  │                                    │
  │                               启用 WOL？──→ 延迟后唤醒所有设备
  │
  ▼
等待时间到 / 电量 < 阈值 / 续航 < 阈值
  │
  ▼
发送「系统关机」通知
  │
  ▼
执行关机前置任务（按优先级逐一关闭纳管设备）
  │
  ▼
最终等待（默认 30 秒）
  │
  ▼
执行本机关机

测试模式对比

模式	UPS 连接	发送通知	关闭纳管设备	本机关机	适用场景
生产	✅	✅	✅	✅	正式使用
演练	✅	✅	✅（模拟）	❌	测试流程
模拟	❌（Mock）	❌	❌	❌	开发调试

来电自动唤醒（WOL）

前提条件

UPS 配置：市电恢复后自动开机
BIOS 设置：启用 Wake On LAN / Power On By PCI-E
操作系统配置：
- Windows：设备管理器 → 网络适配器 → 属性 → 高级 → 启用"魔术包唤醒"
- Linux：sudo ethtool -s eth0 wol g
- macOS：系统偏好设置 → 节能 → 唤醒以供网络访问
获取 MAC 地址：ipconfig /all（Windows）或 ip link show（Linux）

UPS Guard 中配置

在每个纳管设备中填写 MAC 地址
设置 广播地址（同子网用 192.168.x.255，跨子网用 255.255.255.255）
进入设置 → 来电自动唤醒 → 启用 WOL
设置延迟时间（推荐 60 秒，等待路由器和交换机先启动）

手动唤醒

在仪表盘的纳管设备卡片中，离线设备会显示 "⏻ 唤醒" 按钮，点击即可手动发送 WOL 唤醒包。

电压稳定性检查（v1.0.71 新增）

自动唤醒前系统会检查输入电压是否稳定：

AC UPS：连续 3 次检查在 190V-250V 范围内
DC UPS（如瓦力 W120）：连续 3 次检查在 10V-30V 范围内
系统自动根据实际电压值判断 AC/DC 类型，无需手动配置

支持的 UPS 设备

AC UPS（交流 UPS）

适用于给服务器、NAS、台式机等 220V 设备供电。

品牌	测试型号	状态
APC（施耐德）	Back-UPS BK650M2-CH	✅
CyberPower	多型号	✅
伊顿（Eaton）	—	🔄
山特（SANTAK）	—	🔄

DC UPS（直流 UPS）（v1.0.71 新增支持）

适用于给路由器、光猫、摄像头等 12V/24V 设备供电。

品牌	型号	输出电压	电压可调	适配懒猫微服
瓦力方程	W120	固定 12V	❌	LC02 ✅ / LC03 ❌
瓦力方程	W150	可调	✅（小程序）	LC02 ✅ / LC03 ⚠️

⚠️ 安全警告：

W120 + LC03：不兼容！ W120 输出固定 12V，LC03 需要 19V，电压不匹配会导致设备供电不足。

W150 + LC03：必须先通过瓦力方程小程序将输出设置为 19V / ≥ 6.32A，确认正确后再接入。

已知问题与自动修复

问题	影响型号	状态
`No battery installed!` 误报	瓦力 W120	✅ 自动过滤
USB usbfs 死锁	所有 USB UPS	✅ 启动时自动清理
USB 设备权限不足	容器环境	✅ 启动时自动修复

主题与界面

主题模式

UPS Guard 支持三种主题模式：

☀️ 亮色模式：明亮的浅��界面
🌙 暗色模式：护眼的深色界面
🌓 跟随系统：自动匹配操作系统主题

点击导航栏右上角的主题切换按钮即可切换。

响应式布局

自动适配不同屏幕尺寸：

屏幕	布局
桌面（≥ 1200px）	三列/四列网格
平板（768px-1200px）	两列网格
手机（< 768px）	单列堆叠

卡片拖拽

设置页面的卡片支持拖拽调整位置：

拖动卡片左上角的 ⋮⋮ 图标
可在列之间自由移动
布局自动保存到浏览器本地存储
点击右下角 🔄 重置布局 恢复默认

配置导入导出

导出配置

进入 设置 → 配置管理
点击 📥 导出配置
保存生成的 JSON 文件

导入配置

点击 📤 导入配置
选择之前导出的 JSON 文件
查看配置预览和差异对比
选择导入模式：
- 覆盖模式：完全替换当前配置
- 合并模式：仅更新有变化的项
确认导入

💡 导入/导出功能也用于在不同设备间迁移配置，或在重装后恢复设置。

API 参考

所有 API 端点需要 Bearer Token 认证（/health 和 /ws 除外）。

认证

# Token 在首次启动时自动生成（查看日志获取）
# 或通过环境变量设置：API_TOKEN=your-token

curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8000/api/ups

常用端点

方法	端点	说明
GET	`/api/ups`	获取 UPS 当前状态
GET	`/api/config`	获取配置
PUT	`/api/config`	更新配置
POST	`/api/actions/shutdown`	立即关机
POST	`/api/actions/cancel-shutdown`	取消关机
GET	`/api/ups/writable-vars`	列出 UPS 可写参数
POST	`/api/ups/set-var`	修改 UPS 硬件参数
POST	`/api/ups/command`	执行 UPS 命令
POST	`/api/ups/beeper/{action}`	蜂鸣器控制
POST	`/api/ups/test-battery/{type}`	电池测试
GET	`/api/devices`	获取纳管设备列表
GET	`/api/devices/status`	获取设备状态
POST	`/api/devices/{index}/wake`	WOL 唤醒设备
POST	`/api/config/test-notify`	测试通知
GET	`/api/hooks/plugins`	列出可用 Hook 插件
WS	`/ws`	WebSocket 实时数据推送

WebSocket 数据推送

连接 ws://HOST:PORT/ws 后，服务端会实时推送：

{
  "type": "ups_data",
  "data": {
    "status": "OL",
    "battery_charge": 100,
    "battery_runtime": 3600,
    "input_voltage": 220.5,
    "output_voltage": 220.5,
    "ups_load": 25,
    "battery_temperature": 30
  }
}

故障排除

Q1：UPS 状态显示"离线"

# 1. 检查 USB 连接
lsusb | grep -i "ups\|apc\|cyber\|wali\|04d8\|051d\|0665"

# 2. 查看 NUT 日志
docker-compose logs nut-server  # 或 docker logs <容器名>

# 3. 手动测试 NUT
docker exec <nut容器> upsc -l localhost
docker exec <nut容器> upsc <UPS名称>@localhost

Q2：纳管设备连接测试失败

# 1. 手动测试 SSH
ssh user@host -p 22

# 2. 检查防火墙
sudo ufw status  # Ubuntu
sudo firewall-cmd --list-all  # CentOS

# 3. 测试网络连通
ping <设备IP>
telnet <设备IP> 22

Q3：通知未发送

检查通知总开关是否开启
使用"测试通知"功能验证配置
检查后端日志：docker logs <后端容器> | grep -i notif
确认 Token/Key 是否过期

Q4：WOL 唤醒失败

确认 BIOS 中 WOL 已启用
确认 MAC 地址正确
确认路由器"无线隔离"已关闭
尝试命令行测试：wakeonlan AA:BB:CC:DD:EE:FF
查看日志：docker logs <后端容器> | grep -i wol

Q5：USB 设备 "Entity not found" 错误

这通常是 USB 驱动残留 claim 导致。v1.0.71 已自动处理此问题。如果仍然遇到：

# 在宿主机上执行
# 1. 查看 USB 接口驱动绑定状态
ls -la /sys/bus/usb/devices/*/driver

# 2. 手动解绑残留
echo "<interface-id>" > /sys/bus/usb/drivers/usbfs/unbind

# 3. 重启 UPS Guard 容器
docker restart <容器名>

Q6：懒猫微服 gRPC 关机失败

# 检查 Socket 文件
ls -la /lzcapp/run/sys/lzc-apis.socket

# 切换到 SSH 关机方式
# 设置 → 系统配置 → 关机方式 → SSH

安全说明

认证机制

所有 API 端点通过 Bearer Token 认证保护
Token 可通过环境变量 API_TOKEN 设置
未设置时系统自动生成随机 Token（首次启动查看日志获取）
WebSocket 和健康检查端点无需认证

数据加密

敏感配置（SSH 密码、API Key 等）使用 Fernet 对称加密 存储
加密密钥通过 ENCRYPTION_KEY 环境变量设置
未设置时自动生成并持久化保存

UPS 参数修改安全

白名单机制：仅允许修改安全白名单内的 UPS 参数
范围验证：所有数值必须在合理范围内
二次确认：界面修改前显示确认对话框
审计日志：所有修改记录到事件历史，包含修改前后的值

网络安全

CORS 限制：默认仅允许同域访问
可通过 ALLOWED_ORIGINS 环境变量配置允许的来源
建议在生产环境中使用 HTTPS（通过反向代理配置）

附录：术语表

术语	全称	说明
UPS	Uninterruptible Power Supply	不间断电源
NUT	Network UPS Tools	UPS 通信协议和工具集
WOL	Wake On LAN	局域网唤醒，通过网络魔术包远程开机
OL	On Line	市电供电状态
OB	On Battery	电池供电状态
LB	Low Battery	低电量状态
FSD	Forced Shutdown	强制关机状态
gRPC	Google Remote Procedure Call	远程过程调用协议
DC UPS	Direct Current UPS	直流不间断电源（如 12V/24V）
AC UPS	Alternating Current UPS	交流不间断电源（如 220V）
lpk	LazyCAT Package	懒猫微服应用包格式

📞 需要帮助？

📝 用户指南

🔔 推送配置教程

❓ 常见问题

🐛 问题反馈

💬 参与讨论

本文档基于 UPS Guard v1.0.71 编写，最后更新：2026-03-05

⚡ UPS Guard V1.0.71 — 用户使用手册