分类: Docker,Home Assistant | 标签: home-assistant,docker,部署教程 | 发布时间: 2025-10-03 07:50:22
本文详细介绍在Docker中部署Home Assistant的全流程，含从轩辕镜像查看详情、多种方式拉取镜像，提供快速部署、持久化挂载（推荐）、docker-compose部署三种方案，还包含结果验证方法与常见问题解决办法。
本文详细介绍在Docker中部署Home Assistant的全流程，含从轩辕镜像查看详情、多种方式拉取镜像，提供测试级、家庭长期级、企业级三种部署方案，兼顾易用性与安全性，同时包含结果验证方法、常见问题解决办法及生产级优化建议。
若你的系统尚未安装 Docker，请先一键安装：
一键安装配置脚本（推荐方案）：该脚本支持多种 Linux 发行版，支持一键安装 Docker、Docker Compose 并自动配置轩辕镜像访问支持源。
bash <(wget -qO- https://xuanyuan.cloud/docker.sh)你可以在 轩辕镜像 中找到 Home Assistant 镜像页面： 👉 https://xuanyuan.cloud/r/homeassistant/home-assistant
在镜像页面中，你会看到多种拉取方式，下面我们逐一说明如何部署。
以下拉取方式根据网络环境与账号状态任选其一即可，无需全部执行。
docker pull docker.xuanyuan.run/homeassistant/home-assistant:stabledocker 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：删除临时镜像标签，避免冗余占用空间
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若网络环境良好，或已配置轩辕镜像访问支持器，可直接拉取：
docker pull homeassistant/home-assistant:stableTag风险提示：stable标签为滚动更新版本，每次拉取可能获取最新稳定版，适合大多数家庭用户；关键生产环境建议固定具体版本Tag（如2025.11.3），避免自动更新导致配置兼容问题。
Home Assistant 更新频率较高，且集成功能的破坏性变更（breaking change）较为常见，stable标签虽为稳定版，但滚动更新特性仍可能导致生产环境配置失效。
生产环境务必固定具体版本号部署，示例如下：
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版本更新需先在测试环境验证兼容性，再同步至生产环境，降低配置故障风险。
查看镜像是否拉取成功：
docker images若输出类似以下内容，说明镜像下载成功：
REPOSITORY TAG IMAGE ID CREATED SIZE
homeassistant/home-assistant stable 123abc456def 1 week ago 2.1GB
以下使用已下载的 homeassistant/home-assistant:stable 镜像，提供三种部署方案，可根据使用场景选择：
部署方式选择建议：
- 3.1 快速部署：仅用于临时测试、功能体验，不保留配置
- 3.2 持久化部署：家庭内网长期运行，兼顾易用性与数据安全
- 3.3 docker-compose部署：企业环境、复杂场景长期运行，便于管理与扩展
适合测试或临时使用，容器删除后配置全部丢失，命令如下：
# 容器名称：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 初始化页面。
Home Assistant 会存储大量配置文件（如自动化脚本、设备配置、日志等），挂载本地目录可保证重启后配置不丢失，同时适配硬件设备访问需求。
第一步：创建宿主机目录
mkdir -p /data/homeassistant/config第二步：启动容器并挂载目录（分场景配置）
# 与宿主机保持一致的时区
# 配置文件持久化目录
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参数精确映射设备。
# 与宿主机保持一致的时区
# 配置文件持久化目录
# 精确映射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 | 保持与宿主机时区一致，避免日志、定时任务时间偏差 |
使用 docker-compose 管理容器，便于一键启动/停止、配置修改与扩展，适合企业环境或长期运行场景。
第一步：创建 docker-compose.yml 文件（生产级配置）
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 环境不会强制执行，此处不再展开。
第二步：启动服务
# 进入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
关键提醒：Home Assistant 并非为裸公网暴露设计，不同部署场景需搭配对应的安全措施，避免被扫描攻击。
特点：仅在家庭内网访问，无需暴露公网，安全性较高。
优化建议：绑定内网 IP，避免端口暴露到外网，修改启动命令中的端口映射为：
-p 192.168.1.100:8123:8123 # 替换为宿主机内网IP-p 8123:8123，并通过防火墙限制访问来源，保障内网安全。
network_mode: host 取舍说明：使用 host 网络模式对 mDNS、SSDP 等本地发现协议更友好，适合家庭内网需自动发现智能设备的场景；但云服务器、企业安全环境中，优先选择 bridge 模式配合反向代理，网络访问更可控，降低暴露面。
风险：云服务器IP为公网地址，直接暴露8123端口极易被扫描、暴力破解。
必做防护：
- 禁止直接暴露8123端口到公网，仅允许内网访问（搭配VPN）
- 通过反向代理（Nginx/Traefik）提供HTTPS访问与身份鉴权
- 启用服务器防火墙，限制仅信任IP访问
核心要求：反向代理+HTTPS+强鉴权+最小权限原则。
推荐架构：用户 → VPN/反向代理（鉴权+HTTPS） → 内网Home Assistant容器。
重启策略补充：企业环境若已接入 systemd、Kubernetes 或其他外部调度系统，需避免 --restart unless-stopped 与外部重启策略叠加，防止容器异常循环重启，建议统一由外部调度系统管理生命周期。
注：Home Assistant 强依赖本地硬件与状态存储，不推荐直接运行在 Kubernetes 集群中。核心原因在于 USB/串口设备调度不可预测、Pod 漂移会导致设备绑定失效，且 Stateful 负载与本地硬件结合并非 K8s 友好型场景，除非对设备透传、持久化和调度行为有完整掌控能力。
注：本文假设 Home Assistant 作为业务辅助系统运行，不建议将其纳入核心生产控制链路（如工业控制、安防主控等），相关场景需额外风险评估。
通过Nginx实现HTTPS访问与身份鉴权，避免直接暴露8123端口：
⚠️ 关键说明：WebSocket 连接是 Home Assistant 实时交互的必需项，以下配置中proxy_http_version 1.1及 Upgrade 相关参数已适配，不可省略。
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";
}
}访问对应地址（内网：http://内网IP:8123；反向代理：https://自定义域名），应显示 Home Assistant 初始化界面。第一次启动会提示创建用户、设置语言与家庭信息。
docker ps若 STATUS 为 Up，说明容器运行正常。
docker logs -f home-assistant无报错信息，且显示 Startup complete 即可正常使用。
重要提醒：Home Assistant 配置文件较多，定期备份可避免因容器故障、系统升级导致配置丢失，建议每周备份一次。
# 压缩备份配置目录，文件名含日期
tar czvf ha-backup-$(date +%F).tar.gz /data/homeassistant/config生产环境建议配合 cron 定时任务实现自动备份，或采用宿主机级备份方案（如 rsync、restic），禁止在容器内执行备份操作，避免容器故障导致备份失效。
# 停止并删除现有容器
docker stop home-assistant && docker rm home-assistant
# 解压备份文件到配置目录
tar xzvf ha-backup-2025-12-01.tar.gz -C /
# 重新启动容器（使用原有部署命令）排查方向：
- 端口问题：确认 8123 端口已开放（家庭内网可跳过，云服务器需配置防火墙）
# 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状态，查看日志排查原因 - 网络问题：云服务器需确认安全组已开放对应端口，家庭环境需确保设备在同一内网
- 确认宿主机已识别设备：执行
ls /dev/ttyUSB*查看设备路径（如/dev/ttyUSB0） - 生产环境使用
--device参数精确映射（禁止用--privileged）：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），选择映射后的设备路径即可
所有配置文件均存储在持久化目录中，路径为 /data/homeassistant/config（宿主机），核心文件：
configuration.yaml：核心配置文件，管理集成、设备、自动化基础设置automations.yaml：自动化规则配置文件scripts.yaml：自定义脚本配置文件home-assistant.log：运行日志文件，用于排查故障
# 拉取最新镜像
docker pull homeassistant/home-assistant:stable
# 停止并删除旧容器
docker stop home-assistant && docker rm home-assistant
# 用原有参数启动新容器（需保留持久化、设备映射等参数）
docker run -d ... （复制原有部署命令）cd /path/to/compose-dir
docker compose pull
docker compose up -d更新前建议先备份配置文件，避免新版本与旧配置不兼容。
容器启动时添加以下参数，即可保持与宿主机时区一致：
-v /etc/localtime:/etc/localtime:ro若已启动容器，需停止并删除容器后，重新执行带时区参数的启动命令。
┌──────────────┐
│ 浏览器 │
└──────┬───────┘
│ 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 环境下的部署方式与安全边界，覆盖测试、家庭与企业三类典型场景。文中所有示例均以可维护性、最小权限原则和长期稳定运行为前提，适合作为生产环境部署参考。