📚 课程目录第3章安装部署

3、安装部署：通过命令行、Docker、Home Assistant OS等不同方式安装Home Assistant，并完成初始配置与目录结构解析

Home Assistant（以下简称HA）的安装方式直接决定了后续的运维复杂度、扩展能力与稳定性。很多初学者在第一次接触HA时，往往被“HassOS、Supervised、Container、Core、Python venv”这些名词搞得一头雾水。实际上，这些名称对应的是HA官方定义的四种主要安装类型，它们在系统层级、更新方式、附加组件（Add-on）支持以及硬件要求上有着本质区别。本章将深入剖析这四种安装方式的底层逻辑，重点讲解命令行（Python虚拟环境）、Docker容器以及Home Assistant OS（HassOS）三种主流路径的完整部署流程，并详细拆解安装完成后的目录结构，帮助你建立从“装起来”到“管起来”的系统认知。

在开始安装之前，必须明确一个核心概念：Home Assistant Core 是HA的Python引擎本体，而 Supervisor 是一个负责管理Core、Add-ons以及系统更新的守护进程。HassOS和Supervised安装方式包含了Supervisor，因此支持通过UI安装各种附加组件（如Node-RED、ESPHome、Zigbee2MQTT）；而Docker和Python venv方式仅运行Core，需要手动配置所有外部依赖。理解这一差异，是选择安装路径的第一步。

3.1 核心原理：四种安装方式的架构层级

HA官方将安装方式划分为四个层级，从底层硬件的控制权来看，它们依次是：HassOS（专用操作系统）、Supervised（在通用Linux上安装Supervisor）、Container（Docker容器）、Core（Python虚拟环境）。HassOS是一个经过深度定制的Linux系统，它内置了Docker引擎和Supervisor，将HA Core、Add-ons以及操作系统本身打包成一个不可分割的整体，升级时只需点击一个按钮即可完成系统级更新。Supervised方式则是在Debian等通用系统上手动安装Supervisor，虽然也能获得与HassOS几乎一致的体验，但对宿主系统的依赖较深，升级时可能出现兼容性问题。Docker方式只运行Core容器，用户需要自行管理Docker网络、卷映射和容器重启策略，灵活性最高但运维成本也最高。Python venv方式则直接面向开发者，它允许在任意Linux发行版上通过Python包管理器安装HA，但升级和依赖管理完全依赖手动操作，不适合生产环境。

  关键判断标准：如果你希望HA像“智能家居网关”一样即插即用，且不打算折腾底层系统，首选HassOS；如果你已经有一台长期运行的NAS或服务器，且熟悉Docker命令，那么Container方式是最佳平衡点；如果你是开发者，需要频繁修改HA源码或调试集成，Python venv方式能提供最大的代码自由度。

3.2 操作流程：三种安装方式实战

3.2.1 方式一：Home Assistant OS（推荐新手）

HassOS的安装过程最为简单，本质上是将官方镜像写入SD卡或SSD。首先访问 HA官方下载页面，根据硬件架构（树莓派4/5、x86_64 NUC、Odroid等）下载对应的 .img.xz 镜像文件。使用 Balena Etcher 或 Raspberry Pi Imager 将镜像写入存储介质。写入完成后，将存储介质插入设备并通电启动。首次启动大约需要3-5分钟，设备会通过DHCP自动获取IP地址。在浏览器中访问 http://homeassistant.local:8123 或直接访问设备的IP地址加端口8123，即可进入初始化页面。初始化过程包括创建管理员账户、设置住宅名称与位置（用于天气和日出日落计算）、以及选择是否匿名分享统计数据。整个过程无需任何命令行操作，非常适合硬件专用场景。

# 在树莓派上使用Raspberry Pi Imager烧录HassOS镜像（命令行方式）
# 1. 下载镜像
wget https://github.com/home-assistant/operating-system/releases/download/13.2/haos_rpi5-64-13.2.img.xz
# 2. 解压并写入SD卡（假设SD卡设备为/dev/sdb）
xz -dk haos_rpi5-64-13.2.img.xz
sudo dd if=haos_rpi5-64-13.2.img of=/dev/sdb bs=4M status=progress conv=fsync
# 3. 插入SD卡启动，等待约5分钟，访问 http://homeassistant.local:8123

3.2.2 方式二：Docker Container（适合已有Linux服务器）

Docker方式的核心在于一条 docker run 命令，但生产环境强烈建议使用 docker-compose.yml 文件来管理。首先确保宿主机已安装Docker Engine和Docker Compose插件。创建一个专用目录，例如 /opt/homeassistant，并在其中创建 docker-compose.yml 文件。关键配置项包括：image: ghcr.io/home-assistant/home-assistant:stable（使用稳定版镜像）、network_mode: host（使用主机网络模式，以便发现局域网内的设备）、volumes 映射（将容器内的 /config 目录映射到宿主机的 ./config 目录）、以及 restart: unless-stopped 保证开机自启。执行 docker compose up -d 后，HA容器将在后台运行。这种方式下，HA的配置目录完全由宿主机管理，备份和迁移只需复制整个 config 文件夹即可。

# docker-compose.yml 示例
version: '3.8'
services:
  homeassistant:
    container_name: ha
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
    network_mode: host
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai

3.2.3 方式三：命令行 Python 虚拟环境（适合开发调试）

这种方式要求宿主机具备Python 3.11或更高版本。首先创建系统用户 homeassistant，并切换到该用户。使用 python3 -m venv ha_venv 创建虚拟环境，激活后通过 pip install homeassistant 安装HA核心。安装完成后，执行 hass 命令即可启动。首次启动会在当前用户目录下生成 .homeassistant 文件夹（即配置目录）。这种方式最大的痛点是依赖管理——HA的依赖包更新频繁，手动升级时容易遇到版本冲突。因此，除非你明确需要修改HA源码，否则不建议在生产环境使用此方式。

# 创建专用用户并安装
sudo useradd -rm homeassistant
sudo mkdir -p /srv/homeassistant
sudo chown homeassistant:homeassistant /srv/homeassistant
sudo -u homeassistant -H -s
cd /srv/homeassistant
python3 -m venv ha_venv
source ha_venv/bin/activate
pip install --upgrade pip
pip install homeassistant
# 启动HA（首次启动会创建配置目录）
hass

3.3 案例拆解：从Docker迁移到HassOS的实战复盘

某智能家居爱好者最初在群晖NAS上通过Docker运行HA，使用约半年后遇到了两个棘手问题：一是群晖系统每次大版本更新后，Docker网络桥接模式偶尔会导致HA无法发现局域网内的Sonoff设备；二是由于NAS还承担了文件存储和媒体服务功能，HA的频繁日志写入与NAS的硬盘休眠策略产生冲突，导致硬盘频繁唤醒。经过评估，他决定将HA迁移到一台专用的树莓派4B上，采用HassOS方式部署。

迁移过程的关键步骤：

备份旧配置：在旧Docker容器中，通过HA的“创建备份”功能生成一个 .tar 备份文件，下载到本地电脑。
部署HassOS：烧录HassOS镜像到树莓派，完成初始化并创建管理员账户。
恢复备份：在HassOS的“备份”页面中，上传之前下载的 .tar 文件，点击“恢复”。系统会自动安装备份中包含的附加组件和自定义集成。
网络调整：由于HassOS默认使用主机网络，之前Docker桥接网络导致的设备发现问题自然消失。

结果对比：迁移后，HA的响应速度明显提升（树莓派4B的CPU性能优于NAS虚拟机分配的CPU），且不再受NAS硬盘休眠影响。更重要的是，HassOS支持一键系统更新，无需再手动维护Docker镜像版本。但代价是失去了NAS的大容量存储，对于需要存储监控视频的集成（如Frigate），需要额外配置网络存储（NFS/Samba）。

风险提示：从Docker迁移到HassOS时，务必注意附加组件的兼容性。某些在Docker中通过自定义方式安装的第三方插件（如手动编译的Zigbee协调器驱动），在HassOS中可能无法直接运行，因为HassOS的Supervisor对附加组件的权限控制更为严格。

3.4 目录结构深度解析与常见误区

无论采用哪种安装方式，HA的配置目录（通常为 config）内部结构是高度一致的。理解这些目录和文件的用途，是进行自动化配置和排障的基础。

路径/文件	作用说明	运维要点
`configuration.yaml`	主配置文件，定义自动化、场景、设备接入等核心逻辑。	修改后需重启HA或使用“开发者工具→YAML→重新加载”生效。
`secrets.yaml`	存储密码、等敏感信息，通过 `!secret` 引用。	切勿将此文件提交到公共Git仓库。
`custom_components/`	存放第三方自定义集成（如HACS下载的插件）。	升级HA前需检查自定义组件兼容性。
`.storage/`	以JSON格式存储UI配置、设备注册、历史统计等内部状态。	不建议手动编辑，损坏时可能导致HA无法启动。
`home-assistant.log`	运行日志，记录错误、警告和调试信息。	排障第一入口，可通过 `logger` 集成调整日志级别。
`deps/`	Python依赖库目录（仅Python venv方式存在）。	Docker/HassOS方式此目录在容器内部，无需关注。

常见误区一：很多新手误以为 configuration.yaml 是唯一需要编辑的文件，实际上HA的UI配置（如添加设备、创建自动化）会自动写入 .storage 目录，导致YAML文件与UI配置并存。建议在 configuration.yaml 中通过 homeassistant: 下的 customize: 或 automation: !include_dir_merge_list automations/ 来组织配置，避免单文件过于臃肿。

常见误区二：关于备份，只备份 configuration.yaml 是远远不够的。完整的备份应包含 .storage 目录（保存了UI配置和实体注册信息）、custom_components 目录（第三方插件）、以及 .cloud 目录（如果使用了云服务）。HassOS和Supervised方式提供了内置的“备份”功能，可以一键打包所有内容；而Docker方式则需要手动执行 tar 命令备份整个 config 目录。

经验总结：对于Docker用户，建议在 docker-compose.yml 中额外挂载一个 ./backups:/backups 卷，并定期通过HA的“备份”功能将备份文件输出到该目录，实现备份与宿主机文件系统的隔离。对于HassOS用户，建议插入一个USB存储设备，并在“系统→存储”中将其配置为备份目标，避免因SD卡损坏导致备份丢失。

最后，无论选择哪种安装方式，安装完成后的第一件事都应该是：检查 configuration.yaml 中的 default_config: 指令。这一行代码会加载HA的默认组件集（包括历史记录、日志、天气、发现等），是系统正常运行的基础。如果出于精简目的删除了它，务必手动添加所需的组件，否则HA将失去大部分基础功能。