sfudeus/apcupsd

apcupsd镜像文档

镜像概述

本镜像基于debian-slim精简系统构建，集成apcupsd服务。apcupsd是一款开源的UPS管理工具，专为APC（American Power Conversion）不间断电源设计，可实现UPS状态监控、电池健康管理、低电量自动保护等核心功能。基于debian-slim的特性，镜像具有体积小、资源占用低、运行高效的优势，适用于各类需要稳定供电保障的环境。

核心功能

UPS状态监控

• 实时监测UPS输入/输出电压、负载百分比、电池容量等关键参数
• 支持通过命令行工具（apcaccess）查询详细状态信息

电池管理

• 持续检测电池健康状态，提供剩余容量、预估续航时间等数据
• 记录电池充放电周期，辅助判断电池更换周期

自动保护机制

• 低电量阈值触发：当电池电量低于设定阈值时，自动执行安全关机流程
• 断电事件响应：检测到市电中断后，立即记录事件并启动保护逻辑
• 恢复供电通知：市电恢复后自动记录并可选触发通知机制

日志与事件记录

• 记录UPS状态变化、电池告警、断电/恢复等关键事件
• 支持日志持久化存储，便于问题排查与供电稳定性分析

使用场景

服务器机房环境

适用于中小型服务器集群，通过集中部署实现多台服务器的UPS协同保护，确保断电时按优先级有序关机。

家庭办公/小型工作室

为个人服务器、网络设备（如NAS、路由器）提供供电保护，避免突然断电导致的数据损坏或设备故障。

工业控制场景

对需要持续运行的工业自动化设备、监控系统等提供供电保障，降低停电带来的生产中断风险。

边缘计算节点

在网络边缘设备（如边缘服务器、IoT网关）中部署，保障数据采集与传输的连续性。

使用方法

基本运行命令

以下命令启动基础apcupsd服务（需根据实际UPS连接方式调整设备参数）：

bash
docker run -d \
  --name apcupsd \
  --device=/dev/ttyS0 \  # UPS设备路径（串口连接示例，USB可能为/dev/usb/hiddev0）
  -v /etc/localtime:/etc/localtime:ro \  # 同步主机时间
  --restart unless-stopped \
  apcupsd:latest

自定义配置

挂载配置文件

apcupsd的核心配置通过apcupsd.conf文件定义，可通过本地文件挂载实现自定义配置：

bash
docker run -d \
  --name apcupsd \
  --device=/dev/usb/hiddev0 \  # USB连接的UPS设备路径
  -v /path/to/local/apcupsd.conf:/etc/apcupsd/apcupsd.conf \  # 挂载本地配置文件
  -v /var/log/apcupsd:/var/log/apcupsd \  # 持久化存储日志（可选）
  --restart unless-stopped \
  apcupsd:latest

环境变量配置

支持通过环境变量调整基础配置（优先级低于挂载的配置文件）：

环境变量配置示例：

bash
docker run -d \
  --name apcupsd \
  --device=/dev/usb/hiddev0 \
  -e UPS_TYPE=usb \
  -e LOW_BATTERY_THRESHOLD=15 \
  -e SHUTDOWN_DELAY=180 \
  -v /path/to/logs:/var/log/apcupsd \
  apcupsd:latest

docker-compose配置示例

创建docker-compose.yml文件实现更便捷的部署与管理：

yaml
version: '3.8'
services:
  apcupsd:
    image: apcupsd:latest
    container_name: apcupsd
    devices:
      - /dev/usb/hiddev0:/dev/usb/hiddev0  # 根据UPS实际连接设备调整
    volumes:
      - ./apcupsd.conf:/etc/apcupsd/apcupsd.conf:ro  # 只读挂载配置文件
      - ./logs:/var/log/apcupsd  # 日志持久化
      - /etc/localtime:/etc/localtime:ro  # 时间同步
    environment:
      - UPS_TYPE=usb
      - LOW_BATTERY_THRESHOLD=12
      - UPS_PORT=3551
    restart: unless-stopped
    # 如需远程监控，可添加端口映射
    ports:
      - "3551:3551"

启动命令：docker-compose up -d

状态验证与管理

查看UPS状态

容器运行后，可通过以下命令查询UPS实时状态：

bash
docker exec -it apcupsd apcaccess status

典型输出示例：

APC      : 001,036,0893
DATE     : 2023-10-01 15:30:00 +0800
HOSTNAME : apcupsd-container
VERSION  : 3.14.14 (31 May 2016) debian
UPSNAME  : MyAPC
CABLE    : USB Cable
DRIVER   : USB UPS Driver
UPSMODE  : Stand Alone
STARTTIME: 2023-10-01 14:00:00 +0800
STATUS   : ONLINE
LINEV    : 220.0 Volts
LOADPCT  : 25.0 Percent
BCHARGE  : 100.0 Percent
TIMELEFT : 25.0 Minutes

日志查看

通过挂载的日志目录或容器内日志文件查看历史记录：

bash
# 查看挂载的本地日志
tail -f /path/to/logs/apcupsd.events

# 或直接查看容器内日志
docker exec -it apcupsd cat /var/log/apcupsd/apcupsd.events

注意事项

1. 设备权限：确保容器有权限访问UPS设备，USB连接需确认--device参数路径正确，串口连接需检查主机串口权限。
2. 配置匹配：不同型号APC UPS可能需要调整apcupsd.conf中的UPS_TYPE和DEVICE参数，建议参考apcupsd官方文档或UPS型号手册。
3. 网络安全：如需远程访问apcaccess服务，建议通过防火墙限制访问IP，并避免将3551端口直接暴露在公网。
4. 测试验证：首次部署后，建议通过断开市电的方式测试自动关机功能，确保配置生效。