Home Assistant Docker 部署规范：多场景架构设计与安全边界实践

本文详细介绍在Docker中部署Home Assistant的全流程，含从轩辕镜像查看详情、多种方式拉取镜像，提供测试级、家庭长期级、企业级三种部署方案，兼顾易用性与安全性，同时包含结果验证方法、常见问题解决办法及生产级优化建议。

🧰 准备工作

若你的系统尚未安装 Docker，请先一键安装：

Linux Docker & Docker Compose 一键安装

一键安装配置脚本（推荐方案）：该脚本支持多种 Linux 发行版，支持一键安装 Docker、Docker Compose 并自动配置轩辕镜像访问支持源。

bash
bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

1、查看 Home Assistant 镜像详情

你可以在轩辕镜像中找到 Home Assistant 镜像页面： 👉 https://xuanyuan.cloud/r/homeassistant/home-assistant

在镜像页面中，你会看到多种拉取方式，下面我们逐一说明如何部署。

2、下载 Home Assistant 镜像

以下拉取方式根据网络环境与账号状态任选其一即可，无需全部执行。

2.1 使用轩辕镜像登录验证方式拉取

bash
docker pull docker.xuanyuan.run/homeassistant/home-assistant:stable

2.2 拉取后改名

bash
docker pull docker.xuanyuan.run/homeassistant/home-assistant:stable \
&& docker tag docker.xuanyuan.run/homeassistant/home-assistant:stable homeassistant/home-assistant:stable \
&& docker rmi docker.xuanyuan.run/homeassistant/home-assistant:stable

说明：

docker pull：从轩辕镜像拉取 Home Assistant 镜像，加速下载
docker tag：将镜像重命名为官方标准名称，便于后续操作
docker rmi：删除临时镜像标签，避免冗余占用空间

2.3 使用免登录方式拉取（推荐）

bash
docker pull xxx.xuanyuan.run/homeassistant/home-assistant:stable \
&& docker tag xxx.xuanyuan.run/homeassistant/home-assistant:stable homeassistant/home-assistant:stable \
&& docker rmi xxx.xuanyuan.run/homeassistant/home-assistant:stable

2.4 官方直连方式

若网络环境良好，或已配置轩辕镜像访问支持器，可直接拉取：

bash
docker pull homeassistant/home-assistant:stable

2.5 镜像Tag说明与风险提示

Tag风险提示：stable标签为滚动更新版本，每次拉取可能获取最新稳定版，适合大多数家庭用户；关键生产环境建议固定具体版本Tag（如2025.11.3），避免自动更新导致配置兼容问题。

2.6 生产环境强制建议：固定版本号

Home Assistant 更新频率较高，且集成功能的破坏性变更（breaking change）较为常见，stable标签虽为稳定版，但滚动更新特性仍可能导致生产环境配置失效。

生产环境务必固定具体版本号部署，示例如下：

bash
docker pull homeassistant/home-assistant:2025.11.3
# 部署时也需指定固定版本，避免意外更新
docker run -d --name home-assistant \
  --restart unless-stopped \
  -p 8123:8123 \
  -v /data/homeassistant/config:/config \
  homeassistant/home-assistant:2025.11.3

版本更新需先在测试环境验证兼容性，再同步至生产环境，降低配置故障风险。

查看镜像是否拉取成功：

bash
docker images

若输出类似以下内容，说明镜像下载成功：

REPOSITORY                   TAG       IMAGE ID       CREATED         SIZE
homeassistant/home-assistant stable    123abc456def   1 week ago      2.1GB

3、部署 Home Assistant

以下使用已下载的 homeassistant/home-assistant:stable 镜像，提供三种部署方案，可根据使用场景选择：

部署方式选择建议：

3.1 快速部署：仅用于临时测试、功能体验，不保留配置
3.2 持久化部署：家庭内网长期运行，兼顾易用性与数据安全
3.3 docker-compose部署：企业环境、复杂场景长期运行，便于管理与扩展

3.1 快速部署（最简测试方式）

适合测试或临时使用，容器删除后配置全部丢失，命令如下：

bash
# 容器名称：home-assistant（便于管理）
# 重启策略：意外退出时自动重启
# 端口映射：宿主机8123端口映射容器8123端口
docker run -d --name home-assistant \
  --restart unless-stopped \
  -p 8123:8123 \
  homeassistant/home-assistant:stable

核心参数说明：

--name home-assistant：容器名称，便于管理
--restart unless-stopped：保证容器意外退出时自动重启
-p 8123:8123：映射宿主机 8123 端口，Home Assistant 默认端口

验证方式：浏览器访问 http://服务器IP:8123，应显示 Home Assistant 初始化页面。

3.2 持久化挂载目录（家庭长期运行推荐）

Home Assistant 会存储大量配置文件（如自动化脚本、设备配置、日志等），挂载本地目录可保证重启后配置不丢失，同时适配硬件设备访问需求。

第一步：创建宿主机目录

bash
mkdir -p /data/homeassistant/config

第二步：启动容器并挂载目录（分场景配置）

家庭/测试环境（需访问USB/Zigbee设备）

bash
# 与宿主机保持一致的时区
# 配置文件持久化目录
docker run -d --name home-assistant \
  --restart unless-stopped \
  -p 8123:8123 \
  -v /etc/localtime:/etc/localtime:ro \
  -v /data/homeassistant/config:/config \
  --privileged \
  homeassistant/home-assistant:stable

安全提示：--privileged 会赋予容器完整宿主机root权限，存在安全风险，仅建议在家庭内网或测试环境使用。生产环境禁止使用，需用--device参数精确映射设备。

生产环境（精确设备映射，无特权）

bash
# 与宿主机保持一致的时区
# 配置文件持久化目录
# 精确映射USB/Zigbee设备（按需添加）
docker run -d --name home-assistant \
  --restart unless-stopped \
  -p 8123:8123 \
  -v /etc/localtime:/etc/localtime:ro \
  -v /data/homeassistant/config:/config \
  --device /dev/ttyUSB0:/dev/ttyUSB0 \
  homeassistant/home-assistant:stable

目录映射说明：

宿主机目录	容器内目录	用途
/data/homeassistant/config	/config	存放 Home Assistant 配置文件，持久化核心数据
/etc/localtime	/etc/localtime	保持与宿主机时区一致，避免日志、定时任务时间偏差

3.3 docker-compose 部署（企业/长期运行推荐）

使用 docker-compose 管理容器，便于一键启动/停止、配置修改与扩展，适合企业环境或长期运行场景。

第一步：创建 docker-compose.yml 文件（生产级配置）

yaml
version: "3.9"  # 兼容Compose v2，提升生产环境兼容性
services:
  homeassistant:
    image: homeassistant/home-assistant:stable
    container_name: home-assistant
    restart: unless-stopped
    ports:
      - "8123:8123"
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
    # 生产环境用精确设备映射替代privileged
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0  # 按需添加USB/Zigbee设备
    # 强制资源限制（非Swarm环境推荐）
    cpus: 2.0
    mem_limit: 2g

资源限制说明：Home Assistant 集成设备或自动化规则较多时，CPU/内存占用会上升，建议按需调整以下参数（Docker Engine 原生支持，强制生效）。

注：deploy.resources 仅在 Swarm 环境生效，Compose 非 Swarm 环境不会强制执行，此处不再展开。

第二步：启动服务

bash
# 进入docker-compose.yml所在目录
cd /path/to/compose-dir
# 后台启动服务
docker compose up -d

补充说明：

修改配置文件：直接编辑当前目录下 config 文件夹中的 YAML 文件
停止服务：docker compose down
查看状态：docker compose ps
查看日志：docker compose logs -f homeassistant

4、部署场景说明与安全防护

关键提醒：Home Assistant 并非为裸公网暴露设计，不同部署场景需搭配对应的安全措施，避免被扫描攻击。

4.1 家庭内网部署（最常见场景）

特点：仅在家庭内网访问，无需暴露公网，安全性较高。

优化建议：绑定内网 IP，避免端口暴露到外网，修改启动命令中的端口映射为：

bash
-p 192.168.1.100:8123:8123  # 替换为宿主机内网IP

⚠️ 适配提示：并非所有 Docker 版本、网络模式都支持绑定指定 IP。若绑定失败或宿主机仅有一个内网 IP，可退化为 -p 8123:8123，并通过防火墙限制访问来源，保障内网安全。

network_mode: host 取舍说明：使用 host 网络模式对 mDNS、SSDP 等本地发现协议更友好，适合家庭内网需自动发现智能设备的场景；但云服务器、企业安全环境中，优先选择 bridge 模式配合反向代理，网络访问更可控，降低暴露面。

4.2 云服务器部署（需额外安全措施）

风险：云服务器IP为公网地址，直接暴露8123端口极易被扫描、暴力破解。

必做防护：

禁止直接暴露8123端口到公网，仅允许内网访问（搭配VPN）
通过反向代理（Nginx/Traefik）提供HTTPS访问与身份鉴权
启用服务器防火墙，限制仅信任IP访问

4.3 企业环境部署（合规与安全强化）

核心要求：反向代理+HTTPS+强鉴权+最小权限原则。

推荐架构：用户 → VPN/反向代理（鉴权+HTTPS） → 内网Home Assistant容器。

重启策略补充：企业环境若已接入 systemd、Kubernetes 或其他外部调度系统，需避免 --restart unless-stopped 与外部重启策略叠加，防止容器异常循环重启，建议统一由外部调度系统管理生命周期。

注：Home Assistant 强依赖本地硬件与状态存储，不推荐直接运行在 Kubernetes 集群中。核心原因在于 USB/串口设备调度不可预测、Pod 漂移会导致设备绑定失效，且 Stateful 负载与本地硬件结合并非 K8s 友好型场景，除非对设备透传、持久化和调度行为有完整掌控能力。

注：本文假设 Home Assistant 作为业务辅助系统运行，不建议将其纳入核心生产控制链路（如工业控制、安防主控等），相关场景需额外风险评估。

4.4 反向代理示例（Nginx）

通过Nginx实现HTTPS访问与身份鉴权，避免直接暴露8123端口：

⚠️ 关键说明：WebSocket 连接是 Home Assistant 实时交互的必需项，以下配置中 proxy_http_version 1.1 及 Upgrade 相关参数已适配，不可省略。

nginx
server {
    listen 443 ssl;
    server_name ha.example.com;  # 自定义域名

    ssl_certificate /etc/nginx/ssl/ha.crt;  # 证书文件
    ssl_certificate_key /etc/nginx/ssl/ha.key;  # 密钥文件

    # 身份鉴权（基础认证，企业可替换为OAuth2）
    auth_basic "Home Assistant Access";
    auth_basic_user_file /etc/nginx/htpasswd;

    location / {
        proxy_pass http://127.0.0.1:8123;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

5、结果验证

5.1 浏览器验证

访问对应地址（内网：http://内网IP:8123；反向代理：https://自定义域名），应显示 Home Assistant 初始化界面。第一次启动会提示创建用户、设置语言与家庭信息。

5.2 容器状态验证

bash
docker ps

若 STATUS 为 Up，说明容器运行正常。

5.3 日志验证

bash
docker logs -f home-assistant

无报错信息，且显示 Startup complete 即可正常使用。

6、数据备份（关键操作，避免配置丢失）

重要提醒：Home Assistant 配置文件较多，定期备份可避免因容器故障、系统升级导致配置丢失，建议每周备份一次。

6.1 手动备份

bash
# 压缩备份配置目录，文件名含日期
tar czvf ha-backup-$(date +%F).tar.gz /data/homeassistant/config

生产环境建议配合 cron 定时任务实现自动备份，或采用宿主机级备份方案（如 rsync、restic），禁止在容器内执行备份操作，避免容器故障导致备份失效。

6.2 恢复备份

bash
# 停止并删除现有容器
docker stop home-assistant && docker rm home-assistant
# 解压备份文件到配置目录
tar xzvf ha-backup-2025-12-01.tar.gz -C /
# 重新启动容器（使用原有部署命令）

7、常见问题（FAQ）

7.1 访问不到 Home Assistant？

排查方向：

端口问题：确认 8123 端口已开放（家庭内网可跳过，云服务器需配置防火墙）

bash
# UFW防火墙（Ubuntu/Debian）
ufw allow 8123/tcp

# Firewalld防火墙（CentOS/RHEL，修正命令）
firewall-cmd --add-port=8123/tcp --permanent
firewall-cmd --reload

端口冲突：执行 netstat -tuln | grep 8123，检查端口是否被其他进程占用，若冲突可修改宿主机端口（如 -p 8124:8123）
容器状态：执行 docker ps -a 检查容器是否启动，若为 Exited 状态，查看日志排查原因
网络问题：云服务器需确认安全组已开放对应端口，家庭环境需确保设备在同一内网

7.2 如何接入智能硬件（Zigbee、USB 设备等）？

确认宿主机已识别设备：执行 ls /dev/ttyUSB* 查看设备路径（如 /dev/ttyUSB0）

生产环境使用 --device 参数精确映射（禁止用--privileged）：

bash
docker run -d --name home-assistant \
--restart unless-stopped \
-p 8123:8123 \
-v /data/homeassistant/config:/config \
--device /dev/ttyUSB0:/dev/ttyUSB0 \  # 映射对应设备
homeassistant/home-assistant:stable

在 Home Assistant 配置页面添加对应集成（如 Zigbee2MQTT），选择映射后的设备路径即可

7.3 配置文件在哪里？

所有配置文件均存储在持久化目录中，路径为 /data/homeassistant/config（宿主机），核心文件：

configuration.yaml：核心配置文件，管理集成、设备、自动化基础设置
automations.yaml：自动化规则配置文件
scripts.yaml：自定义脚本配置文件
home-assistant.log：运行日志文件，用于排查故障

7.4 如何更新 Home Assistant？

普通部署方式

bash
# 拉取最新镜像
docker pull homeassistant/home-assistant:stable
# 停止并删除旧容器
docker stop home-assistant && docker rm home-assistant
# 用原有参数启动新容器（需保留持久化、设备映射等参数）
docker run -d ... （复制原有部署命令）

docker-compose 部署方式

bash
cd /path/to/compose-dir
docker compose pull
docker compose up -d

更新前建议先备份配置文件，避免新版本与旧配置不兼容。

7.5 时区不正确？

容器启动时添加以下参数，即可保持与宿主机时区一致：

bash
-v /etc/localtime:/etc/localtime:ro

若已启动容器，需停止并删除容器后，重新执行带时区参数的启动命令。

8、部署架构图

🧪 测试 / 快速部署（单容器，无持久化）

┌──────────────┐
│   浏览器     │
└──────┬───────┘
       │ HTTP :8123
┌──────▼───────┐
│ Home Assistant│
│  Docker容器  │
│ 无持久化     │
└──────────────┘

特点：无数据持久化，容器删除即丢失配置，适合快速体验功能。

🏠 家庭 / 长期运行（持久化+内网访问）

┌──────────────┐
│ 浏览器 / App │
└──────┬───────┘
       │ HTTP :8123（内网）
┌──────▼────────────────┐
│ Home Assistant 容器    │
│  - /config 挂载        │
│  - /etc/localtime:ro   │
│  - USB / Zigbee 设备   │
└──────┬────────────────┘
       │
┌──────▼───────┐
│ 宿主机目录   │
│ /data/...    │
│ 配置持久化   │
└──────────────┘

特点：配置持久化，支持硬件设备，仅内网访问，安全性较高。

🏢 生产 / 企业环境（安全强化架构）

┌──────────────┐
│ 用户 / App   │
└──────┬───────┘
       │ HTTPS（鉴权）
┌──────▼───────┐
│ Nginx / VPN  │
│ 鉴权 / 加密  │
└──────┬───────┘
       │ 内网通信
┌──────▼─────────────┐
│ Home Assistant     │
│ docker-compose     │
│ 无 privileged      │
│ 精确 device 映射   │
└────────────────────┘

特点：多层防护，最小权限原则，适配企业合规要求，支持长期稳定运行。

结尾

本文从实际生产视角出发，系统梳理了 Home Assistant 在 Docker 环境下的部署方式与安全边界，覆盖测试、家庭与企业三类典型场景。文中所有示例均以可维护性、最小权限原则和长期稳定运行为前提，适合作为生产环境部署参考。