企业官网建设流程全解析

Home Assistant 部署指南：5 条路径在本地跑起你的智能家居中枢

【免费下载链接】core:house_with_garden: Open source home automation that puts local control and privacy first.项目地址: https://gitcode.com/GitHub_Trending/co/core

你的树莓派跑满 20 个设备就开始卡顿？生产环境的依赖和系统环境搅在一起？自动化逻辑改了想立刻看到效果？Home Assistant 是一个开源智能家居中枢，核心功能是本地控制与隐私优先，设备数据不经过云端。这篇部署指南给出 3 条完整部署路径：pip 秒级跑通、Docker 容器常驻、源码开发环境，每条路径都带成功验证命令。

选型决策

先看这棵决策树，3 步收敛到部署路径：

后文三个 H3 与上表一一对应，直接跳转即可。

环境前置

依赖安装命令（uv 是虚拟环境管理器，比 pip 快）：

# 安装 uv 虚拟环境管理器 pip install uv # 在仓库目录创建 .venv 虚拟环境 uv venv .venv # 自检：确认 Python 版本达标 .venv/bin/python --version

自检命令预期输出Python 3.14.x。失败说明版本低于 3.14.2，跳转文末故障速查第 2 条。

部署路径

临时调试：3 条命令跑通

定位：验证自动化逻辑或体验界面，代价是依赖装在独立虚拟环境，不污染系统。

执行以下命令：

# 第一步：创建并激活隔离的虚拟环境 python3 -m venv ha-env && source ha-env/bin/activate # 第二步：安装稳定版 Home Assistant（约 200 MB） pip install homeassistant # 第三步：启动服务，默认监听 8123 端口 hass --open-ui

验证方式：

# 检查 API 是否响应 curl -sI http://localhost:8123/api/ | head -1 # 预期输出：HTTP/1.1 201 UNAUTHORIZED（201 表示服务存活，未带令牌属正常）

⚠️ 最易踩的坑：启动报ModuleNotFoundError，多为激活了错误的虚拟环境。修复：deactivate && source ha-env/bin/activate && which hass。

启动后打开 http://localhost:8123 ，按向导完成初始化即可获得上图这类状态界面。

家庭服务器：容器常驻部署

定位：升级、回滚、卸载互不牵连，代价是多一层容器学习成本。

执行以下命令：

# 拉取官方镜像，Apple Silicon 与 Raspberry Pi 均可运行 docker pull homeassistant/home-assistant:stable # 创建配置数据目录 mkdir -p ~/ha-docker/config # 启动容器：--restart 保证开机自启 docker run -d \ --name ha \ --restart=unless-stopped \ -e TZ=Asia/Shanghai \ -v ~/ha-docker/config:/config \ -p 8123:8123 \ homeassistant/home-assistant:stable

验证方式：

# 容器应输出 Up docker ps --filter name=ha --format "{{.Status}}" # API 存活检查 curl -sI http://localhost:8123/api/ | head -1

⚠️ 最易踩的坑：首次启动约 1 分钟，期间 curl 返回 000 是正常冷启动，别急着重启容器。等待后重试：sleep 60 && curl -sI http://localhost:8123/api/ | head -1。

深度定制：源码开发模式

定位：可修改任意一行代码，代价是依赖体积大、安装耗时。

执行以下命令（准备阶段）：

# 克隆仓库 git clone https://gitcode.com/GitHub_Trending/co/core ha-core cd ha-core # 用 uv 创建开发虚拟环境 uv venv .venv source .venv/bin/activate # 安装仓库与集成依赖（可复用仓库自带脚本 script/bootstrap） uv pip install -e . -r requirements_all.txt -r requirements_test.txt

执行以下命令（初始化阶段）：

# 生成初始配置文件 hass --script ensure_config -c config

执行以下命令（启动阶段）：

# 用自定义配置目录启动 hass -c config --open-ui

验证方式：

# 校验配置文件语法 hass -c config --script check_config # 预期输出：YAML is valid

⚠️ 最易踩的坑：configuration.yaml缩进错误导致校验失败。修复：执行hass -c config --script check_config，按输出中的行号修正 配置文件校验脚本。

运行手册

运维命令速查表：

单行资源监控命令：

# 查看 Home Assistant 进程 CPU 与内存占用 ps aux | grep -v grep | grep homeassistant | awk '{print $2, $3"% CPU", $4"% MEM"}'

故障速查

高频故障一：端口被旧实例占用。

现象：新实例启动即退出，日志出现Address already in use。诊断：lsof -i :8123。修复：kill -9 <上一步输出的 PID>后重新执行启动命令。

高频故障二：Python 版本不达标。

现象：安装直接报错Requires-Python >=3.14.2。诊断：python3 --version。修复：pyenv install 3.14.2 && pyenv local 3.14.2，再重跑安装命令。

高频故障三：依赖版本冲突。

现象：启动时ImportError或版本冲突提示。诊断：pip check。修复：pip install --upgrade pip setuptools && pip install -r requirements_all.txt。

下一步

• 校验当前配置无误：hass -c config --script check_config
• 打开演示集成体验完整界面：演示组件
• 接入真实设备：在configuration.yaml添加mqtt:配置块并重启
• 跑一遍测试套件确认环境健康：pytest tests/test_core.py

收藏本篇，部署系列下一篇见。

【免费下载链接】core:house_with_garden: Open source home automation that puts local control and privacy first.项目地址: https://gitcode.com/GitHub_Trending/co/core