apcupsd Docker镜像文档

镜像概述和主要用途

本镜像基于Ubuntu系统，内置apcupsd服务，用于管理和监控USB连接的UPS设备。它能够在长时间停电时优雅地关闭主机，无需对主机进行任何自定义配置，不需要在主机上设置cron任务或触发文件和脚本，所有操作都在容器内部完成。

核心功能和特性

• 容器化APC UPS监控守护进程，与主机系统分离
• 通过USB连接监控UPS设备状态
• 在UPS电池电量严重不足时自动关闭主机
• 无需以privileged模式运行（主机关闭功能除外）
• 通过--device指令仅附加特定USB设备到容器
• 暴露3551端口，允许网络访问apcupsd监控数据
• 支持配置文件持久化存储

使用场景和适用范围

主要适用场景

• UPS通过USB电缆连接到Docker主机，且不想在物理主机操作系统上运行apcupsd
• 在其他主机上运行此容器，监控连接到UPS的主机的电源状态，并在需要时优雅关闭未直接连接UPS的主机

不适用场景

• 本镜像不直接将监控数据导出到Grafana或Prometheus，但可以通过3551端口让其他容器捕获监控数据以集成到监控解决方案中

详细的使用方法和配置说明

前提条件

• Docker环境已安装并运行
• 了解UPS设备在主机上的USB设备路径（如/dev/usb/hiddev1）

持久化卷创建

建议先创建一个卷来持久化配置文件，以便在容器重建和更新时保留配置：

docker volume create apcupsd_config

卷为空时，容器创建时会自动填充apcupsd的默认配置文件和脚本。这些文件不会在容器删除和重新创建时被覆盖，因此可以在此处进行自定义配置。

Docker Run部署

docker run -d --privileged \
  --name=apcupsd  \
  -e TZ=Europe/London \
  --device=/dev/usb/hiddev1 \
  --restart unless-stopped \
  -p=3551:3551 \
  -v /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket \
  -v apcupsd_config:/etc/apcupsd \
  gregewing/apcupsd:latest

Docker Compose部署

version: '3.7'
services:
  apcupsd:
    image: gregewing/apcupsd:latest
    container_name: apcupsd-stack
    devices:
      - /dev/usb/hiddev0
    ports:
      - 3551:3551
    environment: # 删除或注释掉不需要更改的环境变量
      - UPSNAME=${UPSNAME} # 将显示在apcupsd-cgi详情中
      - UPSCABLE=${UPSCABLE} # 默认值：usb
      - UPSTYPE=${UPSTYPE} # 默认值：usb
      - DEVICE=${DEVICE} # 默认值：空
      - NETSERVER=${NETSERVER} # 默认值：on
      - NISIP=${NISIP} # 默认值：0.0.0.0
      - TZ=${TZ} # 默认值：Europe/London
    volumes:
      - /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket
      - /etc/apcupsd
    restart: unless-stopped

参数说明

必要参数

可选参数

环境变量

配置文件自定义

配置文件位于卷apcupsd_config中，路径为/etc/apcupsd/apcupsd.conf。可以通过以下方式修改：

1. 进入容器内部修改：

   docker exec -it apcupsd /bin/bash
   vi /etc/apcupsd/apcupsd.conf
   

2. 从主机修改（需知道卷在主机上的实际路径）

修改后需重启容器使配置生效：

docker restart apcupsd

注意事项

USB设备识别

1. 在物理主机上运行usb-devices命令识别UPS设备类型
2. 通常UPS会被识别为usbhid设备
3. 设备路径通常在/dev/usb/目录下，如/dev/usb/hiddev0或/dev/usb/hiddev1
4. 如果将USB电缆插入不同端口，设备路径可能会改变

功能测试

可以通过在容器内运行apcaccess命令测试UPS连接状态：

docker exec -it apcupsd apcaccess

成功连接时输出会包含详细的UPS状态信息，与连接失败时有明显区别。

主机关闭功能测试

可以通过以下命令测试主机关闭功能：

docker exec -it apcupsd /etc/apcupsd/apccontrol doshutdown

此命令应能使主机优雅关闭。该功能已在Ubuntu 16.04和18.04主机上测试通过。

远程监控配置

apcupsd软件采用网络信息服务器(NIS)模型在主机之间共享信息。未直接连接UPS的远程主机可以定期轮询直接连接UPS的apcupsd实例。建议将未直接连接UPS的主机的关闭阈值设置得比直接连接UPS的主机稍高，以便远程主机能够在UPS连接主机不可用之前关闭。

更多信息

有关apcupsd的更多信息，请参阅***手册：APC UPS Daemon User Manual