linuxserver/homeassistant

LinuxServer.io Docker Home Assistant 容器介绍

LinuxServer.io 团队简介

LinuxServer.io 团队致力于提供高质量 Docker 容器，其发布的容器具有以下特点：

• 应用定期及时更新
• 简单的用户权限映射（通过 PGID、PUID 配置）
• 基于 s6 overlay 的自定义基础镜像
• 每周更新基础操作系统，通过跨生态共享通用层减少存储空间占用、 downtime 和带宽消耗
• 定期安全更新

社区与支持渠道

• 博客：容器使用指南、教程及技术观点
• ***：实时社区支持与团队交流
• Discourse：社区论坛，可发布问题与讨论
• GitHub：所有仓库源代码
• Open Collective：支持我们的***或预算贡献平台

LinuxServer/HomeAssistant 容器

该容器基于 Home Assistant Core 构建。Home Assistant 是一款开源家庭自动化工具，强调本地控制与隐私保护，适合运行在树莓派或本地服务器上，由全球爱好者社区支持。

支持的架构

容器通过 Docker manifest 实现多平台支持，拉取 lscr.io/linuxserver/homeassistant:latest 即可自动匹配对应架构。也可通过标签指定特定架构：

应用设置

容器基于 Home Assistant Core 构建，Web 界面地址为 `[***]

网络模式：Host 与 Bridge

Home Assistant 依赖 zeroconf/mDNS 和 UPnP 协议自动发现网络设备，需使用 --net=host 模式才能确保设备发现功能正常。

蓝牙设备访问

若需让 Home Assistant 访问主机蓝牙设备，需：

1. 在主机安装 BlueZ；
2. 为容器添加 NET_ADMIN 和 NET_RAW 权限；
3. 映射 dbus 卷。

示例配置：

• Docker CLI：
  CODE_TOKEN_0
• Docker Compose：
  CODE_TOKEN_1
  若主机 dbus 路径不同（如 /var/run/dbus），可映射为 -v /var/run/dbus:/run/dbus:ro。

Ping 集成

使用 Ping 集成 需为容器添加 NET_RAW 权限（配置同上）。

使用方法

可通过 Docker Compose（推荐）或 Docker CLI 启动容器。除标记为“可选”的参数外，其余均为必填项。

Docker Compose

CODE_TOKEN_2

Docker CLI

CODE_TOKEN_3

参数说明

环境变量与文件（Docker Secrets）

可通过 FILE__ 前缀从文件加载环境变量，例如：
CODE_TOKEN_4

Umask 设置

通过 -e UMASK=022 可覆盖容器内服务的默认 umask（权限掩码）。umask 用于限制新文件权限，具体规则参考 umask 说明。

用户/组 ID

使用卷（-v）时，需确保主机目录所有者与容器内 PUID/PGID 一致，避免权限问题。通过 id 用户名 可查看当前用户的 UID/GID：
CODE_TOKEN_5

Docker Mods

可通过 Docker Mods 扩展容器功能。访问以下链接查看可用 Mods：

• Home Assistant 专用 Mods
• 通用 Mods

支持信息

• 容器内 shell 访问：
  CODE_TOKEN_6

• 实时查看日志：
  CODE_TOKEN_7

• 查看容器版本：
  CODE_TOKEN_8

• 查看镜像版本：
  CODE_TOKEN_9

更新方法

容器需通过更新镜像并重建来升级应用。

Docker Compose 更新

• 更新镜像：
  CODE_TOKEN_10

• 重启容器：
  CODE_TOKEN_11

• 清理旧镜像：
  CODE_TOKEN_12

Docker CLI 更新

• 拉取新镜像：
  CODE_TOKEN_13

• 停止并删除旧容器：
  CODE_TOKEN_14

• 用原参数重建容器（配置文件在 /config 中，不会丢失）：
  CODE_TOKEN_15

• 清理旧镜像：
  CODE_TOKEN_16

镜像更新通知

推荐使用 Diun 接收更新通知，不建议使用自动更新工具。

本地构建

如需自定义容器，可本地构建：

CODE_TOKEN_17

跨架构构建：需先注册 qemu-static：
CODE_TOKEN_18
然后指定架构 Dockerfile，例如 -f Dockerfile.aarch64。

版本历史

• 02.10.25：基于 Alpine 3.22 重建，依赖基础镜像服务修复 USB 设备权限。
• 19.09.25：添加必要权限，允许非特权用户访问蓝牙栈。
• 03.01.25：基于 Alpine 3.21 重建。
• 07.11.24：添加 go2rtc 二进制文件。
• 07.10.24：使用 uv 替代 pip 管理 Python 包。
• 13.02.24：基于 Alpine 3.19 重建，升级 Python 3.12，调整 Python 包结构。
• 05.07.23：不再支持 armhf 架构。
• 30.01.21：初始发布。