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 步收敛到部署路径使用场景部署路径上手耗时隔离等级临时调试自动化路径 Apip 虚拟环境10 分钟中家庭服务器常驻路径 BDocker 容器30 分钟高定制开发路径 C源码开发环境1 小时低后文三个 H3 与上表一一对应直接跳转即可。环境前置组件最低版本推荐值Python3.14.2源码与新版 pip 包硬性要求3.14.x操作系统Linux 发行版 / macOS 12任意 64 位系统磁盘空间10 GB 可用20 GB SSD内存4 GB8 GBDocker24.0仅路径 B 需要27.x依赖安装命令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 UNAUTHORIZED201 表示服务存活未带令牌属正常⚠️ 最易踩的坑启动报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 \ --restartunless-stopped \ -e TZAsia/Shanghai \ -v ~/ha-docker/config:/config \ -p 8123:8123 \ homeassistant/home-assistant:stable验证方式# 容器应输出 Up docker ps --filter nameha --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按输出中的行号修正 配置文件校验脚本。运行手册运维命令速查表操作命令说明启动源码路径hass -c config --open-ui打开浏览器访问界面校验配置hass -c config --script check_config改动 yaml 后必跑查看日志源码tail -f config/home-assistant.log实时跟踪容器查看日志docker logs -f ha跟踪容器输出容器状态docker ps --filter nameha确认 Up 状态停止容器docker stop ha优雅停止升级镜像docker pull homeassistant/home-assistant:stable docker restart ha先拉新镜像再重启单行资源监控命令# 查看 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考