当前位置: 首页 > news >正文

手把手教你在 Docker 中部署 Home Assistant

🧰 准备工作

若你的系统尚未安装 Docker,请先一键安装:

Linux Docker & Docker Compose 一键安装

一键安装配置脚本(推荐方案):
该脚本支持多种 Linux 发行版,支持一键安装 Docker、Docker Compose 并自动配置轩辕镜像加速源。

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 使用轩辕镜像登录验证方式拉取

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

2.2 拉取后改名

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 使用免登录方式拉取(推荐)

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 官方直连方式

若网络环境良好,或已配置轩辕镜像加速器,可直接拉取:

docker pull homeassistant/home-assistant:stable

2.5 查看镜像是否拉取成功

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 快速部署(最简方式)

适合测试或临时使用,命令如下:

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 会存储大量配置文件(如自动化脚本、设备配置、日志等),必须挂载本地目录,保证重启后配置不会丢失。

第一步:创建宿主机目录

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 \                          # 允许访问硬件(USB/Zigbee网关)homeassistant/home-assistant:stable

目录映射说明

宿主机目录 容器内目录 用途
/data/homeassistant/config /config 存放 Home Assistant 配置文件
/etc/localtime /etc/localtime 保持时区一致

3.3 docker-compose 部署(适合企业/长期运行)

推荐使用 docker-compose 管理,便于一键启动/停止。

第一步:创建 docker-compose.yml 文件

version: '3'
services:homeassistant:image: homeassistant/home-assistant:stablecontainer_name: home-assistantrestart: unless-stoppedports:- "8123:8123"volumes:- ./config:/config- /etc/localtime:/etc/localtime:roprivileged: true

第二步:启动服务

docker compose up -d

补充说明

  • 修改配置文件:直接编辑 config 目录下的 YAML 文件
  • 停止服务:docker compose down
  • 查看状态:docker compose ps

4、结果验证

浏览器验证

访问 http://服务器IP:8123,应显示 Home Assistant 初始化界面。第一次启动会提示创建用户和设置语言。

查看容器状态

docker ps

若 STATUS 为 Up,说明运行正常。

查看容器日志

docker logs -f home-assistant

无报错信息即可正常使用。

5、常见问题(FAQ)

5.1 访问不到 Home Assistant?

排查方向:

  • 端口:确认 8123 已开放
    ufw allow 8123/tcp
    
    firewalld --add-port=8123/tcp --permanent && firewall-cmd --reload
    
  • 端口冲突:执行 netstat -tuln | grep 8123,检查是否被其他进程占用
  • 容器未启动:docker ps -a 检查状态

5.2 如何接入智能硬件(Zigbee、USB 设备等)?

  1. 确保启动参数中加了 --privileged--device=/dev/ttyUSB0
  2. 挂载宿主机的串口设备:
    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
    
  3. 在 Home Assistant 配置页面中添加对应的集成

5.3 配置文件在哪里?

所有配置文件都在 /data/homeassistant/config,常见文件:

  • configuration.yaml:核心配置文件
  • automations.yaml:自动化规则
  • scripts.yaml:脚本
  • home-assistant.log:日志

5.4 如何更新 Home Assistant?

docker pull homeassistant/home-assistant:stable
docker stop home-assistant
docker rm home-assistant
docker run -d ... (保持原有参数)

或使用 docker-compose:

docker compose pull
docker compose up -d

5.5 时区不正确?

容器启动时加上:

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

即可保持与宿主机一致。

结尾

至此,你已掌握基于 轩辕镜像 的 Home Assistant 镜像拉取与 Docker 部署全流程。

  • 初学者可从 快速部署 入手,体验智能家居平台功能
  • 实际项目建议使用 持久化挂载,避免配置丢失
  • 企业或长期运行建议选择 docker-compose 管理,方便维护升级

在此基础上,你还可以扩展 Home Assistant 的强大功能,例如:接入 Zigbee、MQTT、语音助手、自动化场景等,让智能家居真正服务于生活。

http://www.hskmm.com/?act=detail&tid=32125

相关文章:

  • Index of /download/windows/spice-guest-tools
  • 铁磁材料的磁化曲线和磁滞回线
  • 达芬奇杂志风格挂件字幕文字标题转场预设插件20组 MotionVFX – mRoutine DVR
  • uni-app实现瀑布流展示
  • localdateTime转date及localdatetime格式化日期格式转换为字符串
  • 元推理框架,人类文明的逻辑正果
  • 2025 年广州心理咨询机构最新推荐榜权威发布,详解品牌实力优势与选择指南广州青少年心理咨询/广州情感心理咨询/广州婚姻情感心理咨询/广州催眠心理咨询机构推荐
  • 大学本科及研究生职业专业题库数据集:112031条高质量中文职业教育题库数据,涵盖铁路交通市场营销会计管理等全领域,支持智能教育系统与机器学习算法训练的专业数据集
  • 嘉立创EDA使用技巧
  • 还在手动Code Review?给你的GitHub项目请一个免费的AI审查官吧!
  • 【光照】UnityURP[泛光Bloom]原理与实现
  • 学习Linux应该从哪里开始?
  • P9403 [POI 2020/2021 R3] Les Bitrables
  • Cartesian MST
  • P5609 [Ynoi2013] 对数据结构的爱
  • 剪映高级感口播动态文字字幕排版预设标题入场出场动画素材850款
  • JavaScript 中的安全编码:10 个关键实践
  • 2025 年最新推荐!国内优质球墨铸铁管厂家排行榜,涵盖市政 / 给水 / 水利工程适用产品
  • STM32 代码
  • 2025 年最新冷水机定制厂家排行榜:工业 / 防爆 / 低温 / 水冷 / 螺杆 / 超低温等多类型冷水机优质品牌推荐
  • 2025 年飞机票预定公司最新推荐排行榜:聚焦专业诚信,覆盖特殊旅客与企业服务的口碑榜单
  • 2025 年水质测定仪厂家最新推荐排行榜:解析科技等优质企业实力领衔,助您精准选品多参数/便携式/cod快速/台式水质测定仪厂家推荐
  • 2025 年电永磁吊具厂家最新推荐排行榜:涵盖多类型吊具优质厂家及专业选型参考大型电/全覆盖电/起重电永磁吊具厂家推荐
  • Redis布隆过滤器 Redisson 汇总
  • 2025 年电子散热器厂家推荐:镇江新区富利电子散热器厂,多领域适配与品质服务的可靠之选
  • 高级 RAG 实战:Neo4j 与 LangChain 构建知识图谱驱动的 AI 系统
  • 朴诚乳业携手纷享销客CRM6周实现项目全国推广(附9大核心能力)
  • 2025 年最新推荐 AI 健康管理公司榜单:覆盖多场景,为机构选品提供权威参考
  • 从playfield开源代码复制的opensl es初始化代码
  • 第九届电气、机械与计算机工程国际学术会议(ICEMCE 2025)