bnhf/apcupsd

apcupsd-master-slave

镜像概述和主要用途

apcupsd-master-slave是一个基于Ubuntu的Docker容器，内置apcupsd工具，用于管理和监控一个或多个连接的UPS设备。它能够在长时间断电时优雅关闭主机和UPS本身，且无需对主机进行任何定制，无需主机上的 cron 任务或触发文件及脚本，所有操作均在容器内完成。

容器还集成了Postfix，支持通过Gmail的SMTP服务发送电源事件的邮件和SMS通知。同时支持自定义版本的WoLweb，可在供电恢复后唤醒断电期间关闭的系统。

核心功能和特性

• UPS监控与管理：实时监控UPS状态，支持USB连接的UPS设备
• 主从模式支持：可作为主节点（直接连接UPS）或从节点（监控主节点UPS状态）
• 自动关机机制：断电时按顺序关闭从机、主机及UPS，延长电池寿命
• 通知功能：通过Gmail SMTP发送断电、恢复等事件的邮件/SMS通知
• 唤醒功能：供电恢复后通过WoLweb发送魔术包唤醒已关闭的系统
• 健康检查：内置健康检查机制，可在Portainer中显示UPS在线状态
• 配置持久化：支持将配置目录绑定到主机或Docker卷，确保配置持久化

使用场景和适用范围

主要使用场景：

1. UPS直接连接Docker主机：当UPS通过USB线连接到Docker主机，且不想在物理主机OS上运行apcupsd时
2. 主从架构部署：在其他主机（从机）上运行容器，监控连接UPS的主机（主机）的电源状态，并在断电时优雅关闭非UPS连接的主机

支持的系统：

• Linux系统关闭
• Windows系统关闭
• Proxmox节点关闭

详细使用方法和配置说明

前提要求

• Docker和Docker Compose环境
• UPS通过USB连接到主节点主机（主节点）
• 网络可达性（主从节点之间、与SMTP服务器、WoLweb服务之间）

最小化Docker Compose配置（快速测试用）

yml
version: '3.7'
services:
  apcupsd:
    image: bnhf/apcupsd:latest
    container_name: apcupsd
    hostname: apcupsd_ups  # 每个apcupsd实例使用唯一主机名，将用于apcupsd-cgi和邮件通知
    devices:
      - /dev/usb/hiddev0  # 主节点需匹配APC UPS使用的USB设备，从节点注释此行
    ports:
      - 3551:3551
    environment:
      - UPSNAME=${UPSNAME}  # 设置UPS名称（1-8个字符），用于系统托盘通知、apcupsd-cgi和Grafana仪表板
    volumes:
      - /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket  # 支持从容器关闭主机
      - /data/apcupsd:/etc/apcupsd  # /etc/apcupsd可绑定到目录或Docker卷

完整带注释的Docker Compose配置（推荐使用Portainer-Stacks）

yml
version: '3.7'
services:
  apcupsd:
    image: bnhf/apcupsd:latest
    container_name: apcupsd
    hostname: apcupsd_ups  # 每个apcupsd实例使用唯一主机名，将用于apcupsd-cgi和邮件通知
    devices:
      - /dev/usb/hiddev0  # 主节点需匹配APC UPS使用的USB设备，从节点注释此行
    ports:
      - 3551:3551
    environment:
      - UPSNAME=${UPSNAME}  # 设置UPS名称（1-8个字符），用于系统托盘通知、apcupsd-cgi和Grafana仪表板
      
      # 非USB连接的环境变量（包括不直接连接UPS的从节点）：
#      - UPSCABLE=${UPSCABLE}  # 连接UPS的系统通常无需更改（默认=usb），从节点设置为ether
#      - UPSTYPE=${UPSTYPE}  # 连接UPS的系统通常无需更改（默认=usb），从节点设置为net
#      - DEVICE=${DEVICE}  # 仅从节点使用，设置主节点的主机名或IP地址及监听端口（:3551）

      # 监控和关闭UPS连接设备及UPS本身的环境变量：
#      - POLLTIME=${POLLTIME}  # apcupsd轮询UPS状态的间隔（秒）（默认=60）
#      - ONBATTERYDELAY=${ONBATTERYDELAY}  # 检测到断电后启动电池模式的延迟时间（秒）（默认=6）
#      - BATTERYLEVEL=${BATTERYLEVEL}  # 电池电量低于此百分比时发送关机信号（默认=5）
#      - MINUTES=${MINUTES}  # 剩余电量时间低于此时长时发送关机信号（分钟）（默认=5）
#      - TIMEOUT=${TIMEOUT}  # 电池供电时间超过此时长时发送关机信号（秒）（默认=0）
#      - KILLDELAY=${KILLDELAY}  # 发送关机请求后尝试关闭UPS的延迟时间（秒，非零值生效）（默认=0）

      # 定时UPS自检的环境变量：
#      - SELFTEST=${SELFTEST}  # 每隔x小时请求UPS执行自检（默认=336）

      # 列出与此主节点连接的从节点的两个环境变量：
#      - APCUPSD_HOSTS=${APCUPSD_HOSTS}  # 若为主节点，在此输入APCUPSD_HOSTS列表（含本系统，空格分隔）
#      - APCUPSD_NAMES=${APCUPSD_NAMES}  # 与APCUPSD_HOSTS列表一一对应（含本系统，空格分隔）

      # 设置本地时区（替代UTC）：
      - TZ=${TZ}
      
      # 更新apcupsd脚本和.conf文件的环境变量（即使绑定了持久化主机数据目录）
      # 通常脚本一旦保存在绑定目录就不会被覆盖，但脚本会定期更新，避免过时
      # 若未手动编辑脚本，可保持为true
      - UPDATE_SCRIPTS=${UPDATE_SCRIPTS}  # 设置为true将用最新版本覆盖所有apcupsd脚本和.conf文件
      
      # 通过Gmail SMTP接收电源故障事件或紧急UPS维护的邮件/SMS通知的环境变量
      # 无需使用个人Gmail账户，可创建新账户并启用2FA和"应用密码"
      # 仍可发送通知到个人账户或通过运营商的Email-to-SMS网关发送到手机
      - SMTP_GMAIL=${SMTP_GMAIL}  # 用于SMTP的Gmail账户（需启用2FA）
      - GMAIL_APP_PASSWD=${GMAIL_APP_PASSWD}  # apcupsd使用的Gmail账户应用密码
      - NOTIFICATION_EMAIL=${NOTIFICATION_EMAIL}  # 接收电池状态等通知的邮箱（任何有效邮箱均可）
      - POWER_RESTORED_EMAIL=${POWER_RESTORED_EMAIL}  # 供电恢复后是否发送邮件通知（设为true）
      
      # 断电期间关闭的系统恢复供电后唤醒相关环境变量（需配置bnhf/wolweb容器）：
      - WOLWEB_HOSTNAMES=${WOLWEB_HOSTNAMES}  # 启动时发送WoL魔术包的主机名列表（空格分隔）
      - WOLWEB_PATH_BASE=${WOLWEB_PATH_BASE}  # WoLweb路径（http://之后，/hostname之前，如raspberrypi6:8089/wolweb/wake）
      - WOLWEB_DELAY=${WOLWEB_DELAY}  # 发送WoL魔术包前的延迟时间（秒）
      
      # 关闭一个或多个Proxmox节点的环境变量（需先关闭所有VM和CT，可将其配置为apcupsd从节点）
      # 创建"shutdown" pve域用户，仅分配"shutdown"角色的Sys.PowerMgmt权限，然后创建API令牌
      # 可列出匹配数量的主机、节点和令牌，或通过同一主机和令牌列出多个节点：
      - PVE_SHUTDOWN_HOSTS=${PVE_SHUTDOWN_HOSTS}  # 用于API关闭的pve主机名（或IP）有序列表，与PVE_SHUTDOWN_NODES和PVE_SHUTDOWN_TOKENS匹配
      - PVE_SHUTDOWN_NODES=${PVE_SHUTDOWN_NODES}  # pve节点有序列表，与PVE_SHUTDOWN_HOSTS和PVE_SHUTDOWN_TOKENS匹配
      - PVE_SHUTDOWN_TOKENS=${PVE_SHUTDOWN_TOKENS}  # pve API令牌有序列表，格式为<username>@<node>!<api_token>=<api_secret>
    
    # 健康检查选项，在Portainer中显示UPS是否在线并与apcupsd通信（推荐）：
    healthcheck:
      test: ["CMD-SHELL", "apcaccess | grep -E 'ONLINE' >> /dev/null"]  # 健康检查命令
      interval: 30s  # 健康检查间隔
      timeout: 5s  # 检查超时时间
      retries: 3  # 重试次数
      start_period: 15s  # 启动等待时间
      
    # system_bus_socket绑定始终用于主机关闭，数据目录可按如下绑定或使用Docker卷
    volumes:
      - /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket  # 支持从容器关闭主机
      - /data/apcupsd:/etc/apcupsd  # /etc/apcupsd可绑定到目录或Docker卷
    restart: unless-stopped
    
# 若倾向使用Docker卷而非目录绑定，按需取消注释以下内容
# volumes:  # 仅用于卷绑定
#   config:  # 若卷不存在，堆栈名称将附加到卷名前
#     external: true  # 若提前创建了Docker卷，使用此指令

所有环境变量

可粘贴到Portainer-Stacks"高级"环境变量部分的完整环境变量列表。将${}部分替换为实际值，删除不使用的变量：

console
UPSNAME=${UPSNAME}
UPSCABLE=${UPSCABLE}
UPSTYPE=${UPSTYPE}
DEVICE=${DEVICE}
POLLTIME=${POLLTIME} 
ONBATTERYDELAY=${ONBATTERYDELAY}
BATTERYLEVEL=${BATTERYLEVEL}
MINUTES=${MINUTES}
TIMEOUT=${TIMEOUT}
KILLDELAY=${KILLDELAY}
SELFTEST=${SELFTEST} 
APCUPSD_HOSTS=${APCUPSD_HOSTS}
APCUPSD_NAMES=${APCUPSD_NAMES}
TZ=${TZ}
UPDATE_SCRIPTS=${UPDATE_SCRIPTS}
SMTP_GMAIL=${SMTP_GMAIL}
GMAIL_APP_PASSWD=${GMAIL_APP_PASSWD}
NOTIFICATION_EMAIL=${NOTIFICATION_EMAIL}
POWER_RESTORED_EMAIL=${POWER_RESTORED_EMAIL}
WOLWEB_HOSTNAMES=${WOLWEB_HOSTNAMES}
WOLWEB_PATH_BASE=${WOLWEB_PATH_BASE}
WOLWEB_DELAY=${WOLWEB_DELAY}
PVE_SHUTDOWN_HOSTS=${PVE_SHUTDOWN_HOSTS}
PVE_SHUTDOWN_NODES=${PVE_SHUTDOWN_NODES}
PVE_SHUTDOWN_TOKENS=${PVE_SHUTDOWN_TOKENS}

配套容器

apcupsd-cgi

!apcupsd-cgi界面

基于Debian 11（Bullseye）的Docker镜像，包含nginx-light作为Web服务器、fcgiwrap作为CGI服务器和apcupsd-cgi。apcupsd-cgi配置为通过标准端口3551连接主机上的apcupsd守护进程。Nginx配置为连接fcgiwrap（CGI服务器）并在端口80上直接提供multimon.cgi。容器暴露端口80，可按需重映射（建议使用3552）。

apcupsd-cgi的Docker Compose配置（推荐使用Portainer-Stacks）

yml
version: '3.7'
services:
  apcupsd-cgi:
    image: bnhf/apcupsd-cgi:latest
    container_name: apcupsd-cgi
    dns_search: localdomain  # 设置为局域网域名（通常为local或localdomain），有助于本地主机名DNS解析
    ports:
      - 3552:80
    environment:
      - UPSHOSTS=${UPSHOSTS}  # 连接APC UPS的计算机主机名或IP地址有序列表（空格分隔，无引号）
      - UPSNAMES=${UPSNAMES}  # 状态页面上显示的位置名称有序列表（与UPSHOSTS顺序匹配，空格分隔，无引号）
      - TZ=${TZ}  # 状态页面使用的时区，默认UTC
    volumes:
      - /data/apcupsd-cgi:/etc/apcupsd
    restart: unless-stopped

所需环境变量（或直接在compose中硬编码值）：

• UPSHOSTS：连接APC UPS的计算机主机名或IP地址列表（空格分隔，无引号）
• UPSNAMES：Web界面中显示的名称列表（顺序需与UPSHOSTS匹配，空格分隔，无引号）
• TZ：apcupsd-cgi显示UPS信息时使用的时区

TIG stack

!TIG stack监控界面

用于监控UPS设备的TIG（telegraf-InfluxDB-Grafana）堆栈，几乎无需配置。

Wake-on-LAN (WoLweb)

定制更新版WoLweb用于发送Wake-on-LAN魔术包。提供Web界面，用于输入断电恢复后需唤醒的以太网连接系统的主机名和MAC地址。也可通过Web界面或可收藏的URL用于一般唤醒目的：

!WoLweb界面

WoLweb的Docker Compose配置

yml
version: '3.7'
services:  
  wolweb:
    image: bnhf/wolweb:latest
    container_name: wolweb  
    environment:
      - WOLWEBPORT=${WOLWEBPORT}  # WoLweb使用的端口（推荐8089）
      - WOLWEBVDIR=${WOLWEBVDIR}  # WoLweb的虚拟目录（推荐/wolweb）
      - WOLWEBBCASTIP=${WOLWEBBCASTIP}  # 子网广播IP（含端口，通常为192.168.0.255:9或192.168.1.255:9）
    volumes:
      - /data/wolweb:/wolweb/data  # 将目录绑定到/wolweb/data以实现数据持久化
    network_mode: host  # 仅host网络模式支持WoL魔术包
    restart: unless-stopped

相关资源

完整说明文档可参考：[***]