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

# ⚡ UPS Guard 用户使用说明

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

---



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




## 📚 目录

- [产品简介](#产品简介)
- [系统要求](#系统要求)
- [安装与部署](#安装与部署)
- [首次使用](#首次使用)
- [仪表盘（Dashboard）](#仪表盘dashboard)
- [历史记录（History）](#历史记录history)
- [事件日志（Events）](#事件日志events)
- [设置（Settings）](#设置settings)
- [关机保护流程](#关机保护流程)
- [来电自动唤醒（WOL）](#来电自动唤醒wol)
- [支持的 UPS 设备](#支持的-ups-设备)
- [主题与界面](#主题与界面)
- [配置导入导出](#配置导入导出)
- [API 参考](#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 设备并识别品牌和推荐驱动。

---

## 安装与部署

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

1. 从 [GitHub Releases](https://github.com/KingBoyAndGirl/ups-guard/releases) 下载最新 `.lpk` 文件
2. 进入懒猫微服控制面板 → 应用商店 → **本地安装**
3. 选择下载的 `.lpk` 文件，等待安装完成
4. 通过 USB 连接 UPS 到懒猫微服主机
5. 打开应用，系统将自动检测 UPS 设备

### 方式二：Docker Compose（通用）

```bash
# 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 连接"，请检查：

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

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

### 第 2 步：配置关机策略

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

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

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

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

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

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

进入 **设置 → 通知设置**：

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

### 第 5 步：测试（推荐）

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

1. 进入 **设置 → 系统配置 → 测试模式**
2. 选择 **演练模式（Dry-Run）**
3. 在仪表盘中点击"立即关机"
4. 观察关机流程是否正常（设备连接、通知发送等，但不会实际关机）
5. 确认无误后切换回 **生产模式（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 | 最稳定，兼容性好 |
| 事件驱动 |  ⚠️ **安全提示**：所有参数修改经过白名单验证、范围验证、二次确认，并记录到事件历史。

### 🛠️ 系统配置

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

### 📊 数据管理

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

### 📎 配置导入/导出

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

---

## 关机保护流程

### 完整流程图

```
市电中断
  │
  ▼
检测到 UPS 切换到电池供电 (OB)
  │
  ▼
发送「市电断电」通知
  │
  ▼
开始等待计时（默认 5 分钟）
  │
  ├──── 市电恢复 ───→ 取消关机 → 发送「市电恢复」通知
  │                                    │
  │                               启用 WOL？──→ 延迟后唤醒所有设备
  │
  ▼
等待时间到 / 电量  ⚠️ **安全警告**：
> - **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） | 两列网格 |
| 手机（ 💡 导入/导出功能也用于在不同设备间迁移配置，或在重装后恢复设置。

---

## API 参考

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

### 认证

```bash
# 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` 后，服务端会实时推送：

```json
{
  "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 状态显示"离线"

```bash
# 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  upsc -l localhost
docker exec  upsc @localhost
```

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

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

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

# 3. 测试网络连通
ping 
telnet  22
```

### Q3：通知未发送

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

### Q4：WOL 唤醒失败

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

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

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

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

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

# 3. 重启 UPS Guard 容器
docker restart 
```

### Q6：懒猫微服 gRPC 关机失败

```bash
# 检查 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 | 懒猫微服应用包格式 |

---

> 📞 **需要帮助？**
> - 📝 [用户指南](https://github.com/KingBoyAndGirl/ups-guard/blob/main/docs/zh/user-guide.md)
> - 🔔 [推送配置教程](https://github.com/KingBoyAndGirl/ups-guard/blob/main/docs/zh/push-setup.md)
> - ❓ [常见问题](https://github.com/KingBoyAndGirl/ups-guard/blob/main/docs/zh/faq.md)
> - 🐛 [问题反馈](https://github.com/KingBoyAndGirl/ups-guard/issues)
> - 💬 [参与讨论](https://github.com/KingBoyAndGirl/ups-guard/discussions)

---

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

*© 2026 王.W — 采用 AGPL-3.0 开源协议*