bnhf/apcupsd-cgi

apcupsd 与 apcupsd-cgi Docker镜像

镜像概述和主要用途

本镜像提供APC UPS电源管理守护进程(apcupsd)及Web界面(apcupsd-cgi)，基于Debian 11 (Bullseye)，集成nginx-light作为Web服务器、fcgiwrap作为CGI服务器。用于监控和管理APC UPS设备，支持通过USB或网络连接的UPS，提供状态监控、自动关机、事件通知等功能，并可通过Web界面直观查看UPS状态。

核心功能和特性

• UPS状态监控：实时监测UPS运行状态、电池电量、剩余运行时间等关键指标
• 自动关机管理：当UPS电池电量低或断电时间达到阈值时，自动触发主机或Proxmox节点关机
• 多UPS支持：支持主从架构，可监控多台UPS设备
• 事件通知：通过Gmail SMTP发送断电、恢复等事件的邮件通知
• 远程唤醒：配合bnhf/wolweb容器，支持断电恢复后远程唤醒设备
• 数据可视化：可与TIG (InfluxDB、Telegraf、Grafana) 栈集成，实现UPS数据的图表化展示
• 灵活配置：通过环境变量自定义UPS参数、通知设置、时区等

使用场景和适用范围

• 家庭实验室或小型数据中心的UPS管理
• 需要远程监控UPS状态的环境
• 多UPS设备的集中管理场景
• 需实现自动安全关机的服务器环境
• 希望通过Web界面或Grafana仪表盘监控UPS状态的用户

使用方法和配置说明

前置要求

• 需拥有支持监控的APC UPS设备（通过USB线缆或网络连接）
• 如需使用容器化apcupsd，需在每台连接UPS的主机上部署apcupsd容器或直接安装apcupsd守护进程

apcupsd 部署

Docker Compose (Portainer Stacks) 配置

yml
version: '3.9'
services:
  apcupsd:
    image: bnhf/apcupsd:latest
    container_name: apcupsd
    hostname: apcupsd_ups  # 每个apcupsd实例使用唯一主机名，将用于通知和Web界面
    devices:
      - /dev/usb/hiddev0  # APC UPS的USB设备路径，从节点无需此配置
    ports:
      - 3551:3551
    environment:
      - UPSNAME=${UPSNAME}  # UPS名称（1-8字符），用于通知和仪表盘
      
      # 非USB连接或从节点配置（从节点需取消注释）
#      - UPSCABLE=${UPSCABLE}  # 线缆类型，从节点设为ether（默认：usb）
#      - UPSTYPE=${UPSTYPE}  # 连接类型，从节点设为net（默认：usb）
#      - DEVICE=${DEVICE}  # 从节点连接的主节点主机名或IP:端口（如192.168.1.100:3551）

      # 监控和关机参数（可选）
#      - POLLTIME=${POLLTIME}  # 状态轮询间隔（秒，默认：60）
#      - ONBATTERYDELAY=${ONBATTERYDELAY}  # 断电检测延迟（秒，默认：6）
#      - BATTERYLEVEL=${BATTERYLEVEL}  # 低电量关机阈值（%，默认：5）
#      - MINUTES=${MINUTES}  # 剩余时间关机阈值（分钟，默认：5）
#      - TIMEOUT=${TIMEOUT}  # 断电持续时间关机阈值（秒，默认：0）
#      - KILLDELAY=${KILLDELAY}  # 关机后UPS断电延迟（秒，默认：0）

      # 自检配置（可选）
#      - SELFTEST=${SELFTEST}  # 自动自检间隔（小时，默认：336）

      # 主节点从机列表（可选）
#      - APCUPSD_HOSTS=${APCUPSD_HOSTS}  # 主节点管理的从机列表（空格分隔，含本机）
#      - APCUPSD_NAMES=${APCUPSD_NAMES}  # 从机名称列表（与APCUPSD_HOSTS顺序对应）

      # 时区设置
      - TZ=${TZ}
      
      # 配置更新（可选）
      - UPDATE_SCRIPTS=${UPDATE_SCRIPTS}  # 是否覆盖更新配置文件（true/false，默认：true）
      
      # 邮件通知配置（可选）
      - SMTP_GMAIL=${SMTP_GMAIL}  # Gmail SMTP账号（需启用2FA）
      - GMAIL_APP_PASSWD=${GMAIL_APP_PASSWD}  # Gmail应用密码
      - NOTIFICATION_EMAIL=${NOTIFICATION_EMAIL}  # 接收通知的邮箱
      - POWER_RESTORED_EMAIL=${POWER_RESTORED_EMAIL}  # 恢复供电通知（true/false）
      
      # 远程唤醒配置（需bnhf/wolweb容器，可选）
      - WOLWEB_HOSTNAMES=${WOLWEB_HOSTNAMES}  # 需唤醒的主机名列表（空格分隔）
      - WOLWEB_PATH_BASE=${WOLWEB_PATH_BASE}  # WoL服务路径（如raspberrypi6:8089/wolweb/wake）
      - WOLWEB_DELAY=${WOLWEB_DELAY}  # 唤醒延迟（秒）
      
      # Proxmox节点关机配置（可选）
      - PVE_SHUTDOWN_HOSTS=${PVE_SHUTDOWN_HOSTS}  # Proxmox主机列表（IP或主机名）
      - PVE_SHUTDOWN_NODES=${PVE_SHUTDOWN_NODES}  # Proxmox节点列表
      - PVE_SHUTDOWN_TOKENS=${PVE_SHUTDOWN_TOKENS}  # Proxmox API令牌列表（格式：<用户>@<节点>!<令牌>=<密钥>）
    
    # 健康检查（推荐）
    healthcheck:
      test: ["CMD-SHELL", "apcaccess | grep -E 'ONLINE' >> /dev/null"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 15s
      
    volumes:
      - /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket  # 用于主机关机
      - /data/apcupsd:/etc/apcupsd  # 配置文件持久化（目录或Docker卷）
    restart: unless-stopped

环境变量说明

所有环境变量均为可选，建议至少配置UPSNAME和TZ：

apcupsd-cgi 部署

apcupsd-cgi提供Web界面，用于查看UPS状态，基于nginx和fcgiwrap。

Docker Compose (Portainer Stacks) 配置

yml
version: '3.9'
services:
  apcupsd-cgi:
    image: bnhf/apcupsd-cgi:latest
    container_name: apcupsd-cgi
    dns_search: localdomain  # 局域网域名（通常为local或localdomain）
    ports:
      - 3552:80  # Web界面端口（可自定义映射）
    environment:
      - UPSHOSTS=${UPSHOSTS}  # UPS主机列表（空格分隔的IP或主机名）
      - UPSNAMES=${UPSNAMES}  # UPS显示名称列表（与UPSHOSTS顺序对应，空格分隔）
      - TZ=${TZ}  # 时区（默认UTC）
      - DASHBOARD_PROVISION=${DASHBOARD_PROVISION}  # 是否预配置Grafana仪表盘（true/false）
    volumes:
      - /data/apcupsd-cgi:/etc/apcupsd  # 配置文件持久化
      - /data/telegraf:/etc/telegraf  # 仅Grafana集成时需要
      - /data/grafana/provisioning:/etc/grafana/provisioning  # 仅Grafana集成时需要
    restart: unless-stopped

环境变量说明（必填）

Web界面访问

部署后通过 http://<主机IP>:3552 访问Web界面，可查看所有UPS的状态概览及详细信息。

Grafana仪表盘集成（TIG栈）

通过InfluxDB、Telegraf、Grafana（TIG栈）实现UPS数据可视化。

Docker Compose (Portainer Stacks) 配置

yml
version: '3.9'
services:
  influxdb2:
    image: influxdb:latest
    container_name: influxdb2
    ports:
      - 8086:8086
    volumes:
      - /data/influxdb2/data:/var/lib/influxdb2
      - /data/influxdb2/config:/etc/influxdb2
    environment:
      - DOCKER_INFLUXDB_INIT_MODE=${MODE}  # 初始化模式（通常为setup）
      - DOCKER_INFLUXDB_INIT_USERNAME=${USERNAME}  # 管理员用户名（Grafana也使用此用户）
      - DOCKER_INFLUXDB_INIT_PASSWORD=${PASSWORD}  # 密码
      - DOCKER_INFLUXDB_INIT_ORG=${ORG}  # 组织名称
      - DOCKER_INFLUXDB_INIT_BUCKET=${BUCKET}  # 数据桶名称（通常为telegraf）
      - DOCKER_INFLUXDB_INIT_RETENTION=${RETENTION}  # 数据保留时间（通常为1w）
      - DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=${ADMIN_TOKEN}  # 管理员令牌
    restart: unless-stopped
    
  telegraf:
    image: telegraf:latest
    container_name: telegraf
    pid: 'host'
    ports:
      - 8092:8092
      - 8094:8094
      - 8125:8125
    environment:
      - HOST_PROC=/host/proc
      - HOST_SYS=/host/sys
      - HOST_ETC=/host/etc
      - DOCKER_INFLUXDB_INIT_ORG=${ORG}
      - DOCKER_INFLUXDB_INIT_BUCKET=${BUCKET}
      - DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=${ADMIN_TOKEN}
      - UPS1=${UPS1}  # UPS1地址:端口（如192.168.1.100:3551）
      - UPS2=${UPS2}  # 可选，更多UPS
      - UPS3=${UPS3}  # 可选
      # ... 最多支持UPS8
    volumes:
      - /data/telegraf/telegraf.conf:/etc/telegraf/telegraf.conf:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /sys:/host/sys:ro
      - /proc:/host/proc:ro
      - /etc:/host/etc:ro
    restart: unless-stopped
    
  grafana8:
    image: grafana/grafana:latest
    container_name: grafana8
    ports:
      - 3000:3000
    user: '0:0'
    environment:
      - GF_SECURITY_ADMIN_USER=${USERNAME}  # Grafana管理员用户名
      - GF_SECURITY_ADMIN_PASSWORD=${PASSWORD}  # Grafana管理员密码
      - GF_SECURITY_ALLOW_EMBEDDING=true  # 允许嵌入（如Organizr）
      - DOCKER_INFLUXDB_INIT_ORG=${ORG}
      - DOCKER_INFLUXDB_INIT_BUCKET=${BUCKET}
      - DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=${ADMIN_TOKEN}
    volumes:
      - /data/grafana:/var/lib/grafana
      - /data/grafana/provisioning:/etc/grafana/provisioning
    restart: unless-stopped

环境变量说明（必填）

console
MODE=setup
USERNAME=admin  # InfluxDB和Grafana管理员用户名
PASSWORD=your_secure_password  # 密码
ORG=your_org  # 组织名称
BUCKET=telegraf  # 数据桶名称
RETENTION=1w  # 数据保留时间
ADMIN_TOKEN=your_generated_token  # 管理员令牌（可使用随机密钥生成器）
UPS1=192.168.1.100:3551  # 第一台UPS的地址:端口
UPS2=192.168.1.101:3551  # 可选，第二台UPS
# ... 最多支持UPS8

部署后通过 http://<主机IP>:3000 访问Grafana，可查看预配置的UPS监控仪表盘。