⚡ UPS Guard V1.0.71 — 纳管设备优雅关机指南

# 🛡️ 纳管设备优雅关机指南 > **先保存数据 → 再退出应用 → 最后关机** — 完整配置教程 https://appstore.lazycat.cloud/#/shop/detail/cloud.lazycat.app.ups-guard --- ## 目录 1. [核心原理](#核心原理) 2. [预关机命令机制详解](#预关机命令机制详解) 3. [场景配置大全](#场景配置大全) - [懒猫微服](#场景-1纳管另一台懒猫微服) - [Linux 服务器（数据库+Web）](#场景-2linux-服务器跑数据库--web) - [Windows 工作站](#场景-3windows-工作站agent-方式) - [群晖 NAS（Docker 应用）](#场景-4群晖-nas-上跑了-docker-应用) - [开发环境多服务](#场景-5开发环境多服务编排) 4. [超时控制详解](#超时控制详解) 5. [紧急关机 vs 正常关机](#紧急关机-vs-正常关机) 6. [多设备优先级编排](#多设备优先级编排) 7. [完整实战案例](#完整实战案例) 8. [常见问题](#常见问题) 9. [检查清单](#检查清单) --- ## 核心原理 UPS Guard 的关机前置任务支持 **预关机命令**（Pre Commands），会在最终关机命令执行前 **逐行顺序执行**，每行等待上一行完成后再继续。这就是实现"保存 → 退出 → 关机"的关键。 ### 执行时序图 ``` SSH / Agent 连接到目标设备 │ ▼ ┌───────────────────────────────────────┐ │ 预关机命令（逐行顺序执行，每行等完成） │ │ │ │ 第 1 行: 保存数据（等待完成） ✅ │ │ ↓ │ │ 第 2 行: 停止应用（等待完成） ✅ │ │ ↓ │ │ 第 3 行: 清理资源（等待完成） ✅ │ │ ↓ │ │ 第 4 行: 同步磁盘（等待完成） ✅ │ └───────────────────────────────────────┘ │ ▼ ┌───────────────────────────────────────┐ │ 关机命令：poweroff │ │ （发出后不等待响应，连接会断开） │ └───────────────────────────────────────┘ ``` ### 源码验证 SSH 关机插件的核心逻辑： ```python # 逐行执行预关机命令，每条等待完成 if pre_commands_str: pre_commands = [cmd.strip() for cmd in pre_commands_str.split("\n") if cmd.strip()] for cmd in pre_commands: result = await conn.run(cmd, check=False, timeout=30) # 每条超时 30 秒 if result.exit_status != 0: logger.warning(f"Pre-command failed: {cmd}") # 全部预命令执行完毕后，才执行关机 await conn.run(shutdown_command, check=False) ``` **关键特性：** | 特性 | 说明 | |------|------| | ✅ 顺序执行 | 每行命令等上一行完成后再执行 | | ✅ 单行超时 | 每条预关机命令超时 30 秒（SSH）| | ✅ 失败容忍 | 某条命令失败不会阻塞后续命令 | | ✅ 先于关机 | 所有预命令完成后才发送 `poweroff` | | ⚠️ 紧急跳过 | Agent 方式在电量极低时会跳过预命令 | --- ## 预关机命令机制详解 ### SSH 方式 vs Agent 方式 | 对比项 | SSH 远程关机 | Agent 客户端关机 | |--------|-----------|---------------| | 连接方式 | 服务端 SSH → 目标设备 | 客户端主动反连服务端 | | 适用设备 | Linux / macOS / 懒猫微服 | Windows / Linux / macOS | | 需要开放端口 | ✅ 需要 SSH 22 端口 | ❌ 无需开放任何端口 | | 单行命令超时 | 30 秒（硬编码） | 无固定限制（由 Agent 控制） | | 紧急模式跳过 | ❌ 不跳过（整体超时保障） | ✅ 自动跳过预命令 | | 关机延迟 | 无（立即 `poweroff`） | 可配置（默认 60 秒，Windows 显示倒计时） | | 强制关闭应用 | 需手动 `kill` | 紧急模式自动 `/f` | ### 预关机命令的编写规则 ```bash # ✅ 正确：每行一条独立命令 redis-cli BGSAVE sleep 5 systemctl stop nginx systemctl stop postgresql sync # ❌ 错误：不要用 && 连接多条命令（只算一行，30 秒超时可能不够） redis-cli BGSAVE && sleep 5 && systemctl stop nginx && systemctl stop postgresql # ✅ 如果命令可能耗时较长，用后台 + sleep 控制 nohup /opt/backup.sh & sleep 20 # ✅ 忽略可能不存在的命令的错误 redis-cli BGSAVE 2>/dev/null || true docker stop myapp 2>/dev/null || true ``` --- ## 场景配置大全 ### 场景 1：纳管另一台懒猫微服 **背景**：UPS Guard 运行在主机 A，需要远程关闭另一台懒猫微服 B。 > ⚠️ 旧的 `lazycat_shutdown` 插件**已废弃**（只停 lzc-docker，遗漏 docker 和 pg-docker）。 > ✅ 推荐使用 **SSH 远程关机** + 预关机命令。 #### 界面配置 | 配置项 | 值 | 说明 | |--------|-----|------| | 插件类型 | SSH 远程关机 (Linux/macOS) | — | | 任务名称 | 懒猫微服-客厅 | 描述清楚是哪台 | | 主机地址 | 192.168.1.x | 目标懒猫微服 IP | | SSH 端口 | 22 | — | | 用户名 | root | 需要 root 权限停容器 | | 认证方式 | 密码 或 私钥 | 推荐私钥更安全 | | 优先级 | 5 | 根据实际需要 | | 超时时间 | 180 | 停容器 + 关机需要时间 | | 失败策略 | 继续 | 不影响其他设备 | | MAC 地址 | AA:BB:CC:DD:EE:FF | 用于来电唤醒 | #### 预关机命令 ```bash # ① 保存：通知核心容器做数据持久化 docker exec lzc-docker sync 2>/dev/null || true docker exec pg-docker su - postgres -c "pg_ctl checkpoint -D /var/lib/postgresql/data" 2>/dev/null || true # ② 退出：优雅停止懒猫的 3 个核心容器 docker stop lzc-docker pg-docker docker # ③ 同步磁盘缓存 sync ``` #### 关机命令 ```bash poweroff ``` --- ### 场景 2：Linux 服务器（跑数据库 + Web） **背景**：一台 Ubuntu 服务器上跑了 MySQL + Redis + Nginx。 #### 预关机命令 ```bash # ① 保存数据 # MySQL：刷新所有表并锁定（确保数据写入磁盘） mysql -u root -p'yourpass' -e "FLUSH TABLES WITH READ LOCK; SYSTEM sleep 3; UNLOCK TABLES;" 2>/dev/null || true # Redis：触发 RDB 快照 redis-cli BGSAVE 2>/dev/null || true # 等待 Redis 保存完成 sleep 5 # ② 退出应用 systemctl stop nginx systemctl stop mysql systemctl stop redis # ③ 同步磁盘 sync ``` #### 关机命令 ```bash sudo shutdown -h now ``` --- ### 场景 3：Windows 工作站（Agent 方式） **背景**：Windows 11 工作站，用户可能正在编辑文件。 > 💡 Windows 推荐使用 **Agent 客户端关机** 插件，无需开放 SSH 端口。 #### 界面配置 | 配置项 | 值 | 说明 | |--------|-----|------| | 插件类型 | Agent 客户端关机 | — | | Agent ID | windows-desk-01 | Agent 安装时生成 | | 关机延迟 | 120 秒 | 给用户 2 分钟手动保存 | | 关机提示消息 | UPS 电量不足，请立即保存工作，系统将在 2 分钟后关机 | Windows 系统弹窗提示 | | 超时时间 | 300 | 预命令 + 120 秒延迟 | #### 预关机命令 ```powershell # ① 保存：优雅关闭 Office（触发自动保存） powershell -Command "(Get-Process WINWORD -ErrorAction SilentlyContinue) | ForEach-Object { $_.CloseMainWindow() }" powershell -Command "(Get-Process EXCEL -ErrorAction SilentlyContinue) | ForEach-Object { $_.CloseMainWindow() }" powershell -Command "(Get-Process POWERPNT -ErrorAction SilentlyContinue) | ForEach-Object { $_.CloseMainWindow() }" # ② 等待 Office 保存（给 15 秒） powershell -Command "Start-Sleep -Seconds 15" # ③ 退出：停止数据库等服务 net stop "MySQL80" net stop "W3SVC" # ④ 刷新磁盘缓存 powershell -Command "Write-VolumeCache C" ``` #### 执行流程 ``` 预关机命令执行（约 30 秒） ↓ 关机命令下发，Windows 开始 120 秒倒计时 ↓ 屏幕弹窗：「UPS 电量不足，请立即保存工作，系统将在 2 分钟后关机」 ↓ 120 秒后执行 shutdown /s ``` > ⚠️ **超时设置**：`任务超时` ≥ 预关机命令耗时 + 关机延迟秒数。此例中：30 + 120 = 150 秒，设置 300 秒留出余量。 --- ### 场景 4：群晖 NAS 上跑了 Docker 应用 **背景**：群晖 NAS 上用 Docker 跑了 Jellyfin 和 Home Assistant，需要先停容器再关机。 > 群晖的 `synology_shutdown` 插件通过 API 关机，无法执行预关机命令。如果需要先停容器，改用 **SSH 远程关机**。 #### 预关机命令 ```bash # ① 保存：通知 Home Assistant 保存状态 docker exec homeassistant python -c "import requests; requests.post('http://localhost:8123/api/services/homeassistant/stop')" 2>/dev/null || true # ② 退出：优雅停止 Docker 容器 docker stop jellyfin homeassistant sleep 5 # ③ 停止 Docker 服务（可选，群晖会自动处理） # synoservicecfg --stop Docker 2>/dev/null || true # ④ 同步 sync ``` #### 关机命令 ```bash sudo poweroff ``` --- ### 场景 5：开发环境多服务编排 **背景**：一台 Linux 服务器跑了 Docker Compose 编排的微服务（API + 前端 + 数据库 + 缓存 + 消息队列）。 #### 预关机命令 ```bash # ① 保存：各服务数据持久化 docker exec redis redis-cli BGSAVE 2>/dev/null || true docker exec postgres pg_ctl checkpoint -D /var/lib/postgresql/data 2>/dev/null || true sleep 5 # ② 退出：按依赖关系反向停止（先停前端，后停数据库） cd /opt/myproject && docker compose stop frontend api worker sleep 3 cd /opt/myproject && docker compose stop redis rabbitmq postgres # ③ 确保所有容器停止 docker stop $(docker ps -q) 2>/dev/null || true # ④ 同步磁盘 sync ``` --- ## 超时控制详解 ### 三层超时体系 ``` ┌──────────────────────────────────────────────────┐ │ 第 1 层：单条预关机命令超时 │ │ SSH 方式：每条 30 秒 │ │ Agent 方式：无固定限制 │ ├──────────────────────────────────────────────────┤ │ 第 2 层：设备任务超时 │ │ 在设置页面为每个设备配置 │ │ 默认 120 秒，可设置 30-600 秒 │ │ 包含：所有预命令 + 关机命令 + 关机延迟 │ ├──────────────────────────────────────────────────┤ │ 第 3 层：全局关机前置任务超时 │ │ 由 HookExecutor 的 default_timeout 控制 │ │ 默认 120 秒（可被单设备超时覆盖） │ └──────────────────────────────────────────────────┘ ``` ### 超时计算公式 ``` 设备任务超时 ≥ (预关机命令行数 × 30s) + 关机延迟 + 安全余量 ``` | 场景 | 预命令行数 | 关机延迟 | 推荐超时 | |------|:---------:|:-------:|:-------:| | 简单 Linux（无预命令） | 0 | 0 | 60s | | Linux + 停容器 | 5 行 | 0 | 180s | | 懒猫微服 | 4 行 | 0 | 180s | | Windows Agent | 4 行 | 120s | 300s | | 大型数据库备份 | 3 行 + sleep | 0 | 600s | ### 单条命令超时应对策略 如果某个操作需要超过 30 秒（SSH 方式的单行硬编码超时）： ```bash # ❌ 错误：这条命令如果超过 30 秒会被 kill /opt/heavy-backup.sh # ✅ 正确：后台执行 + sleep 等待 nohup /opt/heavy-backup.sh & sleep 60 # ✅ 正确：用 timeout 命令控制 timeout 25 /opt/quick-save.sh || true ``` --- ## 紧急关机 vs 正常关机 系统会根据 UPS 剩余电量和续航时间自动判断关机模式： ### 对比表 | 对比项 | 正常关机 | 紧急关机 | |--------|:-------:|:-------:| | 触发条件 | 断电等待超时 / 电量 < 阈值 | 续航 < 3 分钟 | | 预关机命令 | ✅ 完整执行 | ⚠️ Agent 跳过 / SSH 受整体超时限制 | | 关机延迟 | 使用配置值（如 120s） | Agent 缩短到 10s | | 强制关闭应用 | ❌ 优雅关闭 | ✅ Agent 加 `/f` 强制 | | 通知用户 | ✅ 正常消息 | ✅ 紧急消息 | ### Agent 紧急关机行为 ```python # 紧急时的关机参数 params = { "delay": 10, # 缩短延迟到 10 秒（正常 60 秒） "force": True, # Windows 加 /f 强制关闭应用 "message": "..." # 紧急关机提示 } # 跳过预关机命令 if self.urgent and pre_commands_str: logger.warning("URGENT shutdown — skipping pre_commands") ``` ### 最佳实践 为了兼顾正常和紧急场景： 1. **预关机命令尽量精简**：只做必要的保存操作，不要包含耗时很长的任务 2. **超时设置合理**：不要设太大，紧急时系统没那么多时间等 3. **关键数据用服务自身保护**：如 MySQL 的 `innodb_flush_log_at_trx_commit=1`，Redis 的 AOF 持久化 --- ## 多设备优先级编排 ### 执行机制 ```python # 按优先级分组 → 同优先级并行 → 不同优先级串行 priority_groups = defaultdict(list) for hook in enabled_hooks: priority_groups[hook["priority"]].append(hook) for priority in sorted(priority_groups.keys()): # 同优先级并行执行（asyncio.gather） tasks = [execute(hook) for hook in priority_groups[priority]] await asyncio.gather(*tasks) ``` ### 编排原则：先保存后关机 ``` 优先级 1（最先执行）: 触发所有设备的数据保存 ├─ 数据库服务器：保存操作放在预关机命令里 └─ NAS：数据持久化 优先级 5（中间执行）: 关闭业务应用 ├─ Web 服务器 A ← 并行 └─ Web 服务器 B ← 并行 优先级 10（较晚执行）: 关闭基础设施 ├─ 懒猫微服 B ← 预命令先停容器 └─ 群晖 NAS ← 并行 优先级 20（最后执行）: 关闭非关键设备 ├─ Windows 工作站 1 ← 并行 ├─ Windows 工作站 2 ← 并行 └─ Windows 工作站 3 ← 并行 所有设备完成后 → 关闭宿主机 A（UPS Guard 所在主机） ``` ### 跨设备数据依赖 如果设备 B 的应用依赖设备 A 的数据库： ``` 优先级 1: 设备 B（先关闭应用，因为它依赖 A 的数据库） 预命令：停止 Web 应用 关机：poweroff 优先级 2: 设备 A（后关闭数据库） 预命令：MySQL checkpoint → 停止 MySQL 关机：poweroff ``` > ⚠️ 注意：先关**依赖方**（Web 应用），再关**被依赖方**（数据库）。 --- ## 完整实战案例 ### 家庭 + 小型办公环境 ``` 宿主机 A：懒猫微服（运行 UPS Guard + 日常应用） ├─ UPS: 瓦力方程 W120（12V DC UPS，给路由器/光猫供电） │ └─ 纳管设备： ├─ 懒猫微服 B（客厅 NAS，跑 Jellyfin + Photo） ├─ 群晖 DS923+（存储重要数据） ├─ Windows 工作站（日常办公） └─ Linux 服务器（开发用） ``` #### 配置方案 | 设备 | 插件类型 | 优先级 | 超时 | 失败策略 | 预关机命令 | |------|---------|:------:|:----:|:-------:|---------| | Linux 服务器 | SSH 关机 | 1 | 180s | 继续 | 保存 DB → 停服务 → sync | | 群晖 DS923+ | SSH 关机 | 3 | 300s | 终止 | 停 Docker → sync | | 懒猫微服 B | SSH 关机 | 5 | 180s | 继续 | 停 3 容器 → sync | | Windows 工作站 | Agent 关机 | 10 | 300s | 继续 | 关 Office → 停服务 | #### 执行时间轴 ``` 00:00 UPS 断电检测 ↓ 05:00 等待 5 分钟，市电未恢复 ↓ 05:01 开始执行关机前置任务 ↓ 05:01 [优先级 1] Linux 服务器 ├─ 预命令: redis-cli BGSAVE (3s) ├─ 预命令: sleep 5 (5s) ├─ 预命令: systemctl stop nginx mysql redis (10s) ├─ 预命令: sync (1s) └─ 关机命令: poweroff ✅ ↓ 05:21 [优先级 3] 群晖 NAS ├─ 预命令: docker stop jellyfin homeassistant (15s) ├─ 预命令: sync (1s) └─ 关机命令: poweroff ✅ ↓ 05:40 [优先级 5] 懒猫微服 B ├─ 预命令: docker stop lzc-docker pg-docker docker (20s) ├─ 预命令: sync (1s) └─ 关机命令: poweroff ✅ ↓ 06:02 [优先级 10] Windows 工作站 ├─ 预命令: 关闭 Office (5s) ├─ 预命令: sleep 15 (15s) ├─ 预命令: 停数据库服务 (5s) └─ 关机延迟 120 秒倒计时... ↓ 08:10 宿主机 A 执行关机 ✅ 总计用时：约 3 分钟（+ Windows 延迟 2 分钟） ``` --- ## 常见问题 ### Q1：预关机命令执行失败会怎样？ **不会阻塞关机流程。** 某条预命令失败后会打印警告日志，继续执行下一条命令，最终仍会执行关机命令。 ``` 预命令 1: redis-cli BGSAVE → ✅ 成功 预命令 2: systemctl stop nginx → ✅ 成功 预命令 3: 某个不存在的命令 → ⚠️ 失败（日志记录，继续） 预命令 4: sync → ✅ 成功 关机命令: poweroff → ✅ 执行 ``` ### Q2：预命令超过 30 秒怎么办？ SSH 方式每条命令硬编码 30 秒超时。对于耗时操作： ```bash # 方案一：后台执行 + sleep nohup /opt/long-task.sh & sleep 25 # 在 30 秒超时内 # 方案二：提前在系统层面保障 # 如设置 MySQL 事务自动刷盘，不依赖关机时的手动保存 ``` ### Q3：能否区分"保存失败就不关机"的场景？ 当前系统中，单条预命令失败不会阻止关机。如果你需要"保存失败则终止"的行为： ```bash # 把保存和验证写成一条命令，失败时主动 exit 阻塞后续 redis-cli BGSAVE && redis-cli LASTSAVE || exit 1 ``` 但即使预命令全部失败，**关机命令仍会执行**（这是安全设计：UPS 电量有限，必须关机）。 ### Q4：多台设备同时关机，SSH 连接会不会来不及？ 同优先级的设备 **并行执行**（`asyncio.gather`），每个设备独立 SSH 连接，互不影响。10 台工作站设为同一优先级可以同时关机，总时间 = 最慢的那台。 ### Q5：市电恢复了，正在执行的预关机命令会停吗？ **会。** 系统在每个优先级组执行前会检查取消标志。如果在执行过程中市电恢复且用户点击了"取消关机"，后续优先级的设备会被跳过。但已经 SSH 连上并正在执行的命令不会被中断（需要命令自然结束或超时）。 --- ## 检查清单 部署前逐项确认： ### 每台纳管设备 - [ ] SSH / Agent 连接测试通过 - [ ] 预关机命令在目标设备上手动测试过 - [ ] 关机命令在目标设备上手动测试过（注意：会真的关机！） - [ ] 超时设置 ≥ 预命令总耗时 + 关机延迟 - [ ] MAC 地址填写正确（用于来电唤醒） - [ ] 优先级设置合理（依赖方先关） ### 整体验证 - [ ] 使用 **演练模式（Dry-Run）** 测试完整流程 - [ ] 观察仪表盘的实时关机进度（每个设备状态：⏳→🔄→✅/❌） - [ ] 检查事件日志确认所有设备成功关闭 - [ ] 测试 WOL 唤醒所有设备 - [ ] 切换回 **生产模式** 后进行一次真实断电测试（选在非工作时间） ### 定期维护（每月） - [ ] 测试所有设备连接 - [ ] 确认 IP 地址未变更 - [ ] 更新过期密码/密钥 - [ ] 检查预关机命令是否仍然适用（应用变更后可能需要更新） - [ ] 验证 WOL 功能

UPS Guard V1.0.82 — Wake On LAN (WOL) 配置指南

# Wake On LAN (WOL) 配置指南 ## 概述 UPS Guard 支持通过 Wake On LAN (WOL) 协议来唤醒已关闭的纳管设备。本指南将详细说明如何配置支持 WOL 的设备。 https://appstore.lazycat.cloud/#/shop/detail/cloud.lazycat.app.ups-guard    ## 前置条件 ### 硬件要求 1. **网卡支持**: 设备网卡必须支持 Wake On LAN 功能 2. **主板支持**: BIOS/UEFI 需要启用 WOL 相关选项 3. **电源连接**: 设备需要保持电源连接（关机状态但插着电源） ### 软件要求 1. 设备需要配置静态 IP 或 DHCP 保留地址 2. 知道设备的 MAC 地址 ## 如何获取 MAC 地址 ### Windows ```cmd ipconfig /all ``` 查找 "物理地址" 或 "Physical Address" ### Linux/macOS ```bash ip link show # 或 ifconfig ``` 查找类似 `AA:BB:CC:DD:EE:FF` 格式的地址 ## 配置步骤 ### 步骤 1: 启用设备的 WOL 功能 #### BIOS/UEFI 设置 1. 重启设备，进入 BIOS/UEFI 2. 找到电源管理相关选项 3. 启用以下选项（名称可能不同）: - Wake On LAN - Wake On PCI-E - Power On by PCI-E - Resume by PCI-E Device #### 操作系统设置 **Windows:** 1. 设备管理器 → 网络适配器 2. 右键网卡 → 属性 3. 电源管理标签页: - ✅ 允许此设备唤醒计算机 - ✅ 只允许魔术数据包唤醒计算机 4. 高级标签页: - 启用 "Wake on Magic Packet" **Linux:** ```bash # 检查 WOL 状态 sudo ethtool eth0 | grep Wake-on # 启用 WOL sudo ethtool -s eth0 wol g # 永久启用（添加到 /etc/network/interfaces 或 NetworkManager） ``` ### 步骤 2: 在 UPS Guard 中配置设备 #### 支持 WOL 的设备类型 UPS Guard 所有设备类型都支持 Wake On LAN 功能，只需配置 MAC 地址即可： - ✅ **SSH 关机** (Linux/Unix 服务器) - ✅ **Windows 远程关机** (Windows 服务器) - ✅ **群晖 NAS 关机** (Synology NAS) - ✅ **QNAP NAS 关机** (QNAP NAS) - ✅ **懒猫微服关机** (LazyCAT 微服务) - ✅ **自定义脚本** (自定义设备) - ✅ **HTTP API** (通过 API 控制的设备) #### 方法 1: 通过设置页面添加 1. 打开 **设置** 页面 2. 在 **纳管设备配置** 部分点击 **➕ 添加设备** 3. 选择设备类型并填写信息 ##### 示例 1: Linux 服务器 (SSH 关机) ``` 设备名称: Linux 服务器 设备类型: SSH 关机 优先级: 1 配置参数: - 主机地址: 192.168.1.100 - MAC 地址: AA:BB:CC:DD:EE:FF ← 必填！ - 广播地址: 192.168.1.255 (可选) - 用户名: admin - 认证方式: 密码/密钥 ``` ##### 示例 2: Windows 服务器 ``` 设备名称: Windows 服务器 设备类型: Windows 远程关机 (SSH) 优先级: 2 配置参数: - 主机地址: 192.168.1.101 - SSH 端口: 22 - 用户名: Administrator - 密码: ******** - MAC 地址: BB:CC:DD:EE:FF:11 ← 必填！ - 广播地址: 255.255.255.255 (可选) - 关机命令: shutdown /s /t 60 /c "UPS power lost" ``` **注意**: Windows 需要先安装 OpenSSH Server ##### 示例 3: 群晖 NAS ``` 设备名称: Synology NAS 设备类型: 群晖 NAS 关机 优先级: 3 配置参数: - NAS 地址: 192.168.1.200 - 端口: 5001 - 用户名: admin - 密码: ******** - MAC 地址: CC:DD:EE:FF:11:22 ← 必填！ - 广播地址: 255.255.255.255 (可选) - 使用 HTTPS: 是 ``` 4. 点击 **保存** #### 方法 2: 通过配置文件 编辑 `config/config.yaml`: ```yaml pre_shutdown_hooks: # Linux 服务器 - name: "Linux 服务器" type: "ssh_shutdown" priority: 1 config: host: "192.168.1.100" port: 22 username: "admin" auth_method: "password" password: "your_password" mac_address: "AA:BB:CC:DD:EE:FF" # WOL 必需 broadcast_address: "192.168.1.255" # 可选 # Windows 服务器 - name: "Windows 服务器" type: "windows_shutdown" priority: 2 config: host: "192.168.1.101" port: 22 username: "Administrator" password: "windows_password" mac_address: "BB:CC:DD:EE:FF:11" # WOL 必需 broadcast_address: "255.255.255.255" # 可选 shutdown_command: "shutdown /s /t 60 /c \"UPS power lost\"" # 群晖 NAS - name: "Synology NAS" type: "synology_shutdown" priority: 3 config: host: "192.168.1.200" port: 5001 username: "admin" password: "nas_password" use_https: "true" mac_address: "CC:DD:EE:FF:11:22" # WOL 必需 broadcast_address: "192.168.1.255" # 可选 ``` ### 步骤 3: 测试 WOL 功能 #### 在设置页面测试 1. 设备配置中找到 **🧪 测试 WOL** 按钮 2. 点击测试，查看是否成功发送魔术包 #### 在首页测试 1. 关闭目标设备 2. 等待设备显示为离线状态（灰色） 3. 点击设备卡片上的 **⏻ 开机** 按钮 4. 观察设备是否成功启动 ## 首页电源管理功能 ### 当前支持的功能 #### 1. 单设备操作 **关机 (🔌 关机)** - 位置: 设备卡片右上角 - 条件: 设备在线时显示 - 功能: 关闭单个设备 **开机 (⏻ 开机)** - 位置: 设备卡片右上角 - 条件: 设备离线且配置了 MAC 地址 - 功能: 通过 WOL 唤醒设备 **测试 WOL (🧪 测试WOL)** - 位置: 设备卡片操作栏 - 条件: 设备在线且有 MAC 地址 - 功能: 测试 WOL 功能（无需关机） #### 2. 批量操作 **全部关机 (🔌 立即关机)** - 位置: 首页顶部 - 条件: UPS 电池供电 + 有设备在线 - 功能: 关闭所有在线设备 **全部开机 (⏻ 全部开机)** - 位置: 首页顶部 - 条件: 所有设备离线 - 功能: 唤醒所有配置了 MAC 地址的设备 ### 暂不支持的功能 以下功能需要额外开发: #### ❌ 休眠 (Hibernate) - **需求**: 将内存内容保存到硬盘，完全断电 - **实现难度**: 需要各操作系统特定命令 - **Windows**: `shutdown /h` - **Linux**: `systemctl hibernate` - **macOS**: `pmset sleepnow` (实际是睡眠) #### ❌ 睡眠 (Sleep) - **需求**: 保持内存供电，低功耗模式 - **实现难度**: 需要各操作系统特定命令 - **Windows**: `rundll32.exe powrprof.dll,SetSuspendState 0,1,0` - **Linux**: `systemctl suspend` - **macOS**: `pmset sleepnow` **注意**: - 休眠和睡眠后可能无法通过 WOL 唤醒（取决于硬件和配置） - 建议使用完全关机 + WOL 的方式 ## 常见问题 ### Q1: WOL 不工作？ **检查清单:** 1. ✅ BIOS 中启用了 WOL 2. ✅ 操作系统中启用了 WOL 3. ✅ MAC 地址配置正确 4. ✅ 设备在同一子网或正确配置了广播地址 5. ✅ 防火墙允许 UDP 9 端口（WOL 魔术包端口） 6. ✅ 设备电源已连接 ### Q2: 如何知道 WOL 包发送成功？ 查看以下地方: 1. **控制台日志**: 浏览器 F12 → Console 2. **通知**: 成功发送会显示 "✅ 成功发送 WOL 到 X 台设备" 3. **事件日志**: 设置页面 → 日志查看器 ### Q3: 广播地址如何填写？ **同一子网**: 使用子网广播地址 - 例如: 192.168.1.0/24 → 192.168.1.255 **不同子网**: 可能需要: 1. 路由器支持 WOL 转发 2. 使用定向广播 3. 或保持默认 255.255.255.255 ### Q4: 支持跨子网 WOL 吗？ **部分支持**, 需要: 1. 路由器/交换机支持定向广播 2. 正确配置广播地址 3. 网络设备允许 WOL 包转发 ### Q5: 可以通过互联网唤醒设备吗？ **不直接支持**, 但可以: 1. 使用 VPN 连接到内网 2. 在路由器上配置 WOL 转发（端口转发） 3. 使用专门的 WOL 网关设备 ## 最佳实践 ### 1. 设备命名 使用清晰的名称，便于识别: - ✅ "开发服务器-Ubuntu" - ✅ "文件服务器-Synology" - ❌ "设备1" ### 2. 优先级设置 按照重要性和依赖关系设置优先级: - 优先级 1: 最先关闭（如普通服务器） - 优先级 2-5: 依次关闭 - 优先级 10: 最后关闭（如 NAS、数据库服务器） ### 3. 测试流程 新设备配置后建议测试: 1. **关机测试**: 设备能否正常关闭 2. **WOL 测试**: 使用 "🧪 测试WOL" 按钮 3. **完整流程**: 关机 → 等待 → 开机 ### 4. MAC 地址管理 - 使用 DHCP 保留地址，避免 IP 变化 - 记录每个设备的 MAC 地址 - 定期检查设备配置的准确性 ## 技术细节 ### WOL 工作原理 1. UPS Guard 发送魔术包 (Magic Packet) 2. 魔术包格式: 6 字节 0xFF + 16 次目标 MAC 地址 3. 使用 UDP 协议，端口 9 或 7 4. 广播到局域网 5. 目标设备网卡接收到魔术包后唤醒主机 ### 代码实现位置 - **后端 WOL 发送**: `backend/src/api/wol.py` - **前端 WOL 按钮**: `frontend/src/components/DeviceCard.vue` - **批量唤醒**: `frontend/src/views/Dashboard.vue` ## 进阶配置 ### 自定义广播地址 某些网络环境需要指定特定的广播地址: ```yaml config: mac_address: "AA:BB:CC:DD:EE:FF" broadcast_address: "192.168.1.255" # 子网广播 # 或 broadcast_address: "192.168.255.255" # 大段广播 ``` ### 多网卡设备 如果设备有多个网卡，配置主网卡的 MAC 地址（通常是启用了 WOL 的那个）。 ### 虚拟机 WOL 虚拟机通常不支持 WOL，但可以: 1. 唤醒物理主机 2. 通过脚本自动启动虚拟机 ## 相关文档 - [设备配置指南](./device-configuration.md) - [关机前置任务](./shutdown-hooks.md) - [常见问题](./faq.md) ## 反馈与支持 如有问题或建议，请: 1. 查看项目 Issues 2. 提交新的 Issue 3. 参与项目讨论

⚡ 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 | 最稳定，兼容性好 | | 事件驱动 | < 100ms | < 100 | 最快，需 NUT 2.7.4+ | | **混合** ⭐ | < 100ms | ~2,000 | 事件驱动为主 + 轮询备份 | ### 🔔 通知设置 | 渠道 | 配置项 | 获取方式 | |------|--------|---------| | Server酱 | SendKey | [sct.ftqq.com](https://sct.ftqq.com/) | | PushPlus | Token | [pushplus.plus](http://www.pushplus.plus/) | | 钉钉 | Webhook URL + Secret | 钉钉群 → 群设置 → 机器人 | | Telegram | Bot Token + Chat ID | [@BotFather](https://t.me/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） ### 前提条件 1. **UPS 配置**：市电恢复后自动开机 2. **BIOS 设置**：启用 Wake On LAN / Power On By PCI-E 3. **操作系统配置**： - Windows：设备管理器 → 网络适配器 → 属性 → 高级 → 启用"魔术包唤醒" - Linux：`sudo ethtool -s eth0 wol g` - macOS：系统偏好设置 → 节能 → 唤醒以供网络访问 4. **获取 MAC 地址**：`ipconfig /all`（Windows）或 `ip link show`（Linux） ### UPS Guard 中配置 1. 在每个纳管设备中填写 **MAC 地址** 2. 设置 **广播地址**（同子网用 `192.168.x.255`，跨子网用 `255.255.255.255`） 3. 进入 设置 → 来电自动唤醒 → 启用 WOL 4. 设置延迟时间（推荐 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） | 单列堆叠 | ### 卡片拖拽 设置页面的卡片支持拖拽调整位置： - 拖动卡片左上角的 **⋮⋮** 图标 - 可在列之间自由移动 - 布局自动保存到浏览器本地存储 - 点击右下角 **🔄 重置布局** 恢复默认 --- ## 配置导入导出 ### 导出配置 1. 进入 **设置 → 配置管理** 2. 点击 **📥 导出配置** 3. 保存生成的 JSON 文件 ### 导入配置 1. 点击 **📤 导入配置** 2. 选择之前导出的 JSON 文件 3. 查看配置预览和差异对比 4. 选择导入模式： - **覆盖模式**：完全替换当前配置 - **合并模式**：仅更新有变化的项 5. 确认导入 > 💡 导入/导出功能也用于在不同设备间迁移配置，或在重装后恢复设置。 --- ## 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 <nut容器> upsc -l localhost docker exec <nut容器> upsc <UPS名称>@localhost ``` ### Q2：纳管设备连接测试失败 ```bash # 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：通知未发送 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 "<interface-id>" > /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 开源协议*