epitaxy/compact-hass

compact-hass

镜像概述

compact-hass 是一个基于 Alpine Linux 构建的轻量级 Home Assistant (HASS) Docker 镜像。该镜像在保持完整家庭自动化功能的前提下，将体积压缩至 400MB 以内，非常适合资源受限的硬件环境。

核心功能与特性

• 极致轻量：镜像体积小于 400MB，启动速度快，系统资源占用低。
• 运行环境：基于 Python 3.8 环境构建，保障核心组件的稳定运行。
• 系统与网络监控：预装 nmap 和 psutil 库，原生支持网络扫描与系统资源状态监控。
• 广泛的设备支持：已测试并支持 WEMO、Philips Hue、小米智能设备、Plex 媒体服务器以及 Pushbullet 推送服务。

使用场景与适用范围

• 硬件平台：已在 Synology NAS（群晖）、X86 架构系统以及 Raspberry Pi（树莓派）上完成测试，跨平台兼容性良好。
• 适用场景：适用于需要部署 Home Assistant，但硬件存储空间或内存有限的通用家庭自动化和智能家居控制环境。

使用方法与配置说明

网络配置要求

重要提示：为了让 Home Assistant 能够自动发现并访问局域网内的智能设备和网络资源，运行容器时必须使用 --net=host（主机网络模式）选项。

快速启动 (Docker CLI)

拉取镜像并启动容器：

bash
# 拉取镜像
docker pull epitaxy/compact-hass

# 启动容器（基础运行）
docker run -d --net=host epitaxy/compact-hass

推荐配置（包含数据持久化）： 为了防止容器重启或更新后配置丢失，建议挂载配置目录并设置重启策略：

bash
docker run -d \
  --name=homeassistant \
  --net=host \
  -v /path/to/your/config:/config \
  --restart=unless-stopped \
  epitaxy/compact-hass

(注：请将 /path/to/your/config 替换为宿主机上的实际配置存储路径)

Docker Compose 部署示例

如果您使用 Docker Compose 进行容器编排，可以参考以下 docker-compose.yml 配置文件：

yaml
version: '3.8'

services:
  homeassistant:
    image: epitaxy/compact-hass
    container_name: homeassistant
    network_mode: host
    volumes:
      - ./hass_config:/config
    restart: unless-stopped

配置完成后，在文件所在目录执行以下命令启动服务：

bash
docker-compose up -d

注意事项

1. 端口冲突：由于使用了 host 网络模式，容器将直接使用宿主机的网络栈。请确保宿主机的 8123 端口（Home Assistant 默认 Web 端口）未被其他服务占用。
2. 硬件透传：若需接入 USB 形式的智能家居网关（如 Zigbee 协调器），请在运行命令中追加 --device /dev/ttyUSB0（根据实际设备路径调整）参数以映射硬件设备。