nathanvaughn/powerpanel-business

CyberPower PowerPanel Business Docker镜像

镜像概述和主要用途

本镜像为CyberPower PowerPanel Business提供Docker化部署，支持通过HTTP或HTTPS访问。可独立运行或置于CloudFlare、Traefik等反向代理之后，用于管理UPS（不间断电源）设备，实现UPS状态监控、事件响应、关机调度等功能。

核心功能和特性

• 支持HTTP（3052端口）和HTTPS（53568/tcp端口）访问
• 提供本地直连（local）、远程监控（remote）和混合模式（both）三种部署类型
• 支持USB设备映射，实现本地UPS连接
• 数据持久化卷挂载，保存配置和运行数据
• 多 registry 支持，可从Docker Hub、GitHub Container Registry等获取
• 可配置日志记录，保留PowerPanel守护进程（ppbd、ppbwd）输出

使用场景和适用范围

• 服务器机房或数据中心的UPS集中管理
• 需要本地监控和控制直连UPS的场景
• 远程服务器需响应其他UPS事件进行关机/重启的场景
• 多UPS环境下的混合管理需求
• 需通过反向代理实现安全访问的企业环境

使用方法和配置说明

快速启动

可直接参考项目提供的https://github.com/NathanVaughn/powerpanel-business-docker/blob/master/docker-compose.yml%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6%E5%90%AF%E5%8A%A8%E3%80%82%E9%BB%98%E8%AE%A4%E7%94%A8%E6%88%B7%E5%90%8D%E5%92%8C%E5%AF%86%E7%A0%81%E5%9D%87%E4%B8%BA%60admin%60%E3%80%82

如需保留PowerPanel守护进程（ppbd和ppbwd）的标准输出和错误日志，可设置环境变量ENABLE_LOGGING=true。注意：日志文件会持续增长（每小时约4 MiB，每天约90 MiB），需定期清理。

USB设备访问

若使用local或both标签，容器需访问UPS的USB设备，有两种配置方式：

方式一：共享整个USB总线

通过共享/dev/usb（部分发行版可能还需/dev/bus/usb）让容器访问整个USB总线。docker run命令示例：

bash
docker run --device=/dev/usb:/dev/usb --device=/dev/bus/usb:/dev/bus/usb ...

docker-compose配置示例：

yaml
devices:
  - "/dev/usb:/dev/usb"
  - "/dev/bus/usb:/dev/bus/usb"

方式二：共享特定USB设备

需先获取UPS对应的设备路径，可通过以下命令（适用于大多数Linux系统）：

bash
ups_type="Cyber Power"
ups_dev_type="hiddev"
dev_bus_usb_name=$(lsusb | grep "$ups_type" | sed -E -e "s/^Bus ([0-9][0-9][0-9]) Device ([0-9][0-9][0-9]):.+$/\/dev\/bus\/usb\/\1\/\2/")
usb_product_name=$(sudo lsusb -D "$dev_bus_usb_name" 2>/dev/null | grep "iProduct" | sed -E -e "s/\s*iProduct\s*[0-9]*\s*//")
dev_usb_name=$(sudo dmesg | grep "$usb_product_name" | grep "$ups_dev_type" | tail -n 1 | sed -E -e "s/.*$ups_dev_type([0-9]+).*/\/dev\/usb\/$ups_dev_type\1/")
echo "$dev_usb_name"

假设输出为/dev/usb/hiddev0，docker-compose配置示例：

yaml
devices:
  - "/dev/usb/hiddev0:/dev/usb/hiddev0"

注意：设备路径可能因USB端口变化、系统重启、内核更新等原因改变。

卷挂载

镜像将/usr/local/PPB/目录作为卷挂载，包含所有PowerPanel程序和数据。必须使用卷挂载，绑定挂载会覆盖容器内文件导致运行异常。docker-compose配置示例：

yaml
volumes:
  - ppb_data:/usr/local/PPB/

volumes:
  ppb_data:

网络配置

镜像暴露以下端口：

• 2003（PowerPanel Watchdog进程使用）
• 3052（HTTP访问）
• 53566/udp（用途未知）
• 53568/tcp（HTTPS访问）
• 161/udp（SNMP）
• 162/udp（SNMP）

建议至少暴露HTTP/HTTPS端口，启用SNMP可提供更多监控功能。docker-compose端口映射示例：

yaml
ports:
  - "3052:3052"
  - "53568:53568"
  - "161:161/udp"
  - "162:162/udp"

镜像标签

提供三种类型标签，对应不同部署模式（详见用户手册）：

• local：适用于UPS直连容器所在主机的场景，支持自定义事件脚本、关机调度、功率监控和UPS配置
• remote：适用于需响应其他UPS事件进行关机/重启的远程主机
• both：适用于多UPS环境，需管理本地直连UPS并响应其他UPS事件

特定版本

可通过标签指定PowerPanel版本（格式：{类型}-{版本号}），例如：

yaml
image: ghcr.io/nathanvaughn/powerpanel-business:local-490

安全提示：截至2022年5月，仅481、486、490版本修复了log4j漏洞（CVE-2021-44228），建议使用这些版本。

最新版本

使用{类型}-latest获取最新版本：

yaml
image: ghcr.io/nathanvaughn/powerpanel-business:remote-latest

⚠️ 警告：latest标签版本稳定性未经验证，建议使用特定版本标签。

镜像仓库

可从以下仓库获取镜像：

• https://hub.docker.com/r/nathanvaughn/powerpanel-business
• https://github.com/users/nathanvaughn/packages/container/package/powerpanel-business
• cr.nathanv.app/library/powerpanel-business（实验性）

ESXi配置

要启用ESXi关机功能（替代本地关机选项），需在/usr/local/PPB/etc/config.properties中添加：

bash
isVirtualAppliance = true

详见https://github.com/NathanVaughn/powerpanel-business-docker/issues/18%E3%80%82

已知问题

• 卷内容问题：/usr/local/PPB/卷包含所有PowerPanel可执行文件（包括完整Java运行时），导致软件更新、迁移和备份困难。
• 数据迁移：迁移容器或PPB版本时需手动备份恢复用户数据，/usr/local/PPB/目录内容说明：

• SNMP功能：当前SNMP功能可能无法正常工作，需进一步配置。
• 端口用途：端口2003和53566用途不明确，但2003端口需暴露。
• 日志文件命名：ENABLE_LOGGING生成的日志文件名称基于容器启动时间，手动重启守护进程会覆盖旧日志。
• 反向代理配置：450及以上版本需反向代理设置Origin头为空，Nginx示例：

  nginx
  location / {
          proxy_pass http://ip:3052;
          proxy_set_header 'Origin' '';
  }
  

• local版本问题：最新版本中local标签可能存在问题，可使用both标签替代。