bsakuramiku/ugreen-ups-panel repository overview

⁠US3000 电力监控

为 UGREEN US3000 UPS + Linux NAS 提供直观的网页监控面板，查看供电状态、电芯电压、历史趋势和估算用电量。深绿色界面，适配桌面与手机。

GitHub 项目⁠ · 完整安装说明⁠ · English documentation⁠ · 版本记录⁠

⁠可以查看什么

• 实时供电：外部供电、充电与电池供电状态，电量、输入/输出电压及电池组读数。
• 电芯观察：四节电芯电压、压差趋势，以及连续待机后的电芯一致性参考。
• 历史趋势：1 小时至 1 年的时间范围、状态事件与 CSV 导出。
• 用电月历：今日和月份累计、完整记录日均；点击日期查看小时平均功率及记录覆盖率，按北京时间统计。
• 电池供电记录：起止时间、观测时长、估算放电量与相对容量参考。
• 校准与诊断：分步功率校准、组件版本、连接状态及脱敏诊断导出。

⁠工作方式

US3000 → NAS 原有 UPS 驱动 → 宿主机采集器 → Docker 网页面板

宿主机采集器通过 Linux usbmon 只读观察现有 UPS 驱动通信。容器读取采集快照，并将历史数据库和校准配置保存到数据目录。

首次安装需要先安装宿主机采集器，再启动容器。单独拉取镜像不会直接读取 USB。NAS 原有 UPS 服务继续负责断电保护与关机。

⁠安装与运行

宿主机需具备 systemd、Python 3.10+、usbmon、Docker 和 Compose v2，并由原有 UPS 驱动持续读取 US3000 私有报告。UGOS Pro 用户可直接按 三步安装教程⁠ 操作。

完成采集器安装后，在同一项目目录使用以下 Compose 配置：

services:
  panel:
    image: bsakuramiku/ugreen-ups-panel:latest
    user: "0:0" # 兼容部分 NAS 数据目录权限；非 root 方案见下方链接
    restart: unless-stopped
    ports:
      - "9086:8080"
    volumes:
      - /run/ugreen-ups-panel:/run/ugreen-ups-panel:ro
      - ./data:/data

docker compose up -d

访问 http://NAS_IP:9086。镜像自身默认用户为 10001:10001，上面的 root 覆盖用于兼容部分 NAS 数据目录权限，参见 非 root 运行方式⁠。无需开启 privileged，也无需映射 USB 设备或挂载 Docker socket。

请保留并备份 ./data，其中包含历史记录与校准配置。更新容器时继续使用原数据目录；已启用可选更新服务的部署还需沿用原有 Compose 附加配置。

⁠镜像与使用范围

• latest：最新稳定版；需要固定版本时可选择发行标签，例如 0.12.0。
• 支持 linux/amd64、linux/arm64。目前硬件实测覆盖一台 x86_64 NAS 与 US3000，ARM 已通过容器运行验证。
• 功率模型默认关闭（none）。功率和电量均为校准模型估算，缺采不补算；用电账本从启用后的有效记录开始，不回填旧日期。
• 相对容量参考表示相对于本次固定参考的变化，不是出厂 SOH 或电池健康鉴定。
• 页面和 API 没有内置认证，请在可信局域网使用。

本项目是社区监控工具，与 UGREEN 无隶属或认证关系。源代码采用 MIT 许可证⁠。问题反馈请前往 GitHub Issues⁠。

⁠界面预览

以下为 v0.12.0 DEMO 演示数据，用于展示界面。