夜雨聆风本文档基于飞牛 NAS + Docker 环境，从零开始通过 SSH 完成 Home Assistant 的部署，并解决 HACS 安装过程中遇到的所有常见问题。内容详实，适合新手及进阶用户参考。
第一部分：准备工作与环境确认
1.1 确保飞牛 NAS 已开启 SSH 服务
登录飞牛 NAS 的 Web 管理界面（通常地址为 https://你的NASIP:8000）进入 设置 → SSH 勾选 启用 SSH 服务 记录 端口号（默认为 22，若修改过如8888，后续连接需使用-p指定）记录 允许登录的用户（确保你的账号在列表中；若没有，可在“用户管理”中添加）
1.2 获取必要信息
NAS IP 地址：例如 192.168.1.2SSH 端口：例如 8888（若非默认）系统用户名：不是 Web 界面的“显示名称”，而是实际的系统账号，常见为 admin、root或你在“用户管理”中看到的名称密码：与 Web 登录密码相同
1.3 确认 Docker 已安装
飞牛 NAS 通常自带 Docker。可通过以下命令验证（连接 SSH 后执行）：
docker --version
若显示版本号（如 Docker version 27.3.1），则已安装。
第二部分：通过 SSH 连接飞牛 NAS
2.1 打开终端工具
Windows：使用 PowerShell 或 CMD（命令提示符） macOS / Linux：使用系统自带的终端
2.2 连接命令
ssh -p 端口号 用户名@NAS\_IP示例:端口 8888，用户 admin，IP 192.168.1.2：ssh -p 8888 admin@192.168.1.2
2.3 首次连接提示
The authenticity of host '...' can't be established. ... Are you sure you want to continue connecting (yes/no)?
输入 yes 并回车。
2.4 输入密码
admin@192.168.1.2's password:
注意：输入密码时屏幕不会有任何显示（不会出现 * 或光标移动），这是正常的安全特性。直接输入密码后按回车即可。
2.5 登录成功标志
看到类似如下提示符表示登录成功：
Welcome to ... Last login: ... admin@NAS_NAME:~$
第三部分：获取 Root 权限并准备部署
3.1 切换到 root 用户
sudo -i
再次输入密码（同样无回显），提示符变为：
root@NAS_NAME:~#
3.2 创建 Home Assistant 配置目录（可选，但推荐）
Docker 部署时需要挂载一个本地目录用于永久存储 HA 的配置。本例使用 /root/homeassistant/config：
mkdir -p /root/homeassistant/config
💡 你可以将路径改为任何你方便的位置，例如
/vol1/1000/docker/ha_config，但后续所有命令需同步修改。
第四部分：使用 Docker 部署 Home Assistant
4.1 执行部署命令（单行完整版）
强烈建议使用以下单行命令，避免多行复制时产生换行符错误：
docker run -d --name home-assistant --restart=unless-stopped --network=host -e TZ=Asia/Shanghai -v /root/homeassistant/config:/config homeassistant/home-assistant:stable
参数详解：
4.2 验证容器是否运行
docker ps | grep home-assistant
若看到 Up 状态，表示运行成功。
4.3 访问 Home Assistant 初始界面
打开浏览器，输入：
http://你的NAS\_IP:8123
例如：http://192.168.1.2:8123
你应该能看到 Home Assistant 的首次设置向导（创建用户、设置位置等）。
4.4 常见错误排查
❌ 错误：docker: 'docker run' requires at least 1 argument
原因：命令未完整粘贴，可能丢失了镜像名或参数之间有缺失。
解决：使用上面提供的单行完整命令重新执行。
❌ 错误：port is already allocated
原因：之前已经创建过同名容器。
解决：先删除旧容器再重新创建：
docker stop home-assistant docker rm home-assistant docker run ... （重新执行上面的命令）
第五部分：安装 HACS（Home Assistant Community Store）
HACS 是 HA 的第三方插件商店，必须通过它才能安装小米集成等非官方组件。
5.1 确认 HA 配置目录的真实位置
由于我们在 Docker 命令中使用了 -v /root/homeassistant/config:/config，宿主机上的配置目录为 /root/homeassistant/config。但有时因权限或路径混淆，需要再次确认：
docker inspect home-assistant | grep -A 5 Mounts
输出示例：
"Mounts": \[{"Type": "bind","Source": "/root/homeassistant/config","Destination": "/config", ... }\]
**Source**字段就是宿主机上的配置目录，例如 /root/homeassistant/config。
5.2 进入该目录并创建 custom_components 文件夹
cd /root/homeassistant/config mkdir -p custom\_components cd custom\_components
5.3 下载 HACS 压缩包
使用 wget 从 GitHub 下载最新版：
wget https://github.com/hacs/integration/releases/latest/download/hacs.zip
如果下载缓慢或失败，可使用国内镜像（例如 https://ghproxy.com/ 前缀），或直接用 get.hacs.vip 脚本（见下文）。
5.4 解压 hacs.zip
unzip hacs.zip
如果提示 unzip: command not found，先安装 unzip：
apt update && apt install unzip -y
然后重新解压。
5.5 ⚠️ 关键步骤：修正目录结构（90% 的问题源于此）
解压后，所有 HACS 文件会直接散落在 custom_components/ 目录下，而 Home Assistant 要求它们必须位于 custom_components/hacs/ 子目录中。
错误的结构：
/root/homeassistant/config/custom\_components/ ├── \_\_init\_\_.py ├── const.py ├── config\_flow.py ├── ...（其他文件） └── hacs\_frontend/
正确的结构：
/root/homeassistant/config/custom\_components/ └── hacs/ ├── \_\_init\_\_.py ├── const.py ├── config\_flow.py ├── ...（所有文件） └── hacs\_frontend/
如何修正：
cd /root/homeassistant/config/custom\_components mkdir hacs mv \* hacs/ __\# 将所有文件和文件夹移入 hacs 目录__
⚠️ 执行
mv * hacs/时可能会出现mv: cannot move 'hacs' to a subdirectory of itself警告，可忽略。若仍有文件遗漏，使用ls -la检查并手动移动。
5.6 重启 Home Assistant 容器
docker restart home-assistant
5.7 验证 HACS 是否可访问
等待 1~2 分钟，打开浏览器：
直接访问 http://你的NAS_IP:8123/hacs如果看到 HACS 的配置界面（需要授权 GitHub），则安装成功。或者在 HA 界面中：设置 → 设备与服务 → 添加集成，搜索 HACS，若能找到也说明成功。
5.8 完成 HACS 的 GitHub 授权
在 HACS 配置界面勾选所有选项（或按需选择），点击“提交” 弹出 GitHub 授权窗口，点击第一个链接 登录你的 GitHub 账号（免费注册） 输入屏幕显示的验证码 授权成功后，侧边栏会出现 HACS 的商店图标
第六部分：HACS 安装过程中遇到的典型问题及解决方案
问题 1：执行自动安装脚本时报错 ERROR: Could not find the directory for Home Assistant
现象：
ERROR: Could not find the directory for Home Assistant ERROR: 找不到 Home Assistant 根目录 Manually change the directory ...
原因：脚本无法自动定位 HA 配置目录（尤其在 Docker 自定义挂载时）。
解决：手动进入正确的目录后手动下载（见上文 5.2 ~ 5.5），或者使用带 --config 参数的脚本（不推荐）。最简单就是手动 wget + unzip + 修正目录结构。
问题 2：HACS 文件明明放好，却搜不到或访问 /hacs 返回 404
现象：
在“设备与服务”中搜索 HACS 无结果 访问 http://IP:8123/hacs显示 404 Not Found
根本原因：目录结构错误（见 5.5 节）。绝大多数情况都是因为 HACS 文件直接放在了 custom_components/ 下，缺少 hacs 子文件夹。
解决：执行 5.5 节的 mkdir hacs && mv * hacs/ 命令，然后重启 HA。
问题 3：解压时提示 unzip: command not found
解决：
apt update && apt install unzip -y
问题 4：重启后仍然 404
排查步骤：
再次确认目录结构：
ls -la /root/homeassistant/config/custom\_components/
应该只看到一个 `hacs` 目录。检查 hacs目录内是否有__init__.py等文件：
ls /root/homeassistant/config/custom\_components/hacs/
查看 HA 容器日志，寻找错误：
docker logs home-assistant --tail 50
清理浏览器缓存（ Ctrl+Shift+Delete）并使用无痕模式访问。强制重启 HA 容器（停止再启动）：
docker stop home-assistant sleep 5 docker start home-assistant
问题 5：HACS 安装后，小米集成（Xiaomi Home）登录时跳转到 homeassistant.local 无法访问
现象：小米授权页面返回“无法访问此网站”，地址栏显示 homeassistant.local:8123/...
原因：小米官方集成 OAuth 回调地址硬编码为 homeassistant.local，在 Docker 环境下无法解析。
解决：手动将浏览器地址栏中的 homeassistant.local 改为你的 NAS 真实 IP（如 192.168.31.235），其余路径不变，按回车即可继续授权。
第七部分：通过 HACS 安装小米集成（Xiaomi Home）
7.1 打开 HACS
在 HA 左侧边栏点击 HACS 图标（如未出现，请等待几分钟或重启 HA）。
7.2 搜索并安装 Xiaomi Home
进入 HACS → 集成（Integrations） 点击右下角 浏览并下载存储库（Explore & Download Repositories） 搜索 Xiaomi Home点击结果，再点击右下角 下载（Download） 下载完成后，HACS 会提示需要重启，执行：
docker restart home-assistant
7.3 配置小米账号
HA 重启后，进入 设置 → 设备与服务 → 添加集成 搜索 Xiaomi Home，点击选择国家/地区（中国） 点击 请点击此处进行登录 如遇到 homeassistant.local无法访问，按 6.5 节的方法修改 URL登录小米账号，勾选要接入的设备，点击完成
7.4 验证
在 设备与服务 中应看到已添加的米家设备。你可以在仪表盘中添加卡片来控制它们。
第八部分：附录 — 常用命令速查
第九部分：总结
通过本教程，你应该能够：
使用 SSH 安全连接到飞牛 NAS 通过 Docker 命令行成功部署 Home Assistant 正确安装 HACS 并解决最常见的目录结构错误 接入小米设备，实现跨品牌智能家居控制
关键经验：
SSH 连接时端口和用户名一定要准确 Docker 部署时使用 --network=host避免设备发现问题HACS 安装的核心是确保文件位于 custom_components/hacs/下遇到小米授权跳转问题，手动修改 URL 中的域名为 IP 即可
如果遇到本文未覆盖的问题，请检查 HA 容器日志或访问 Home Assistant 官方社区寻求帮助。
文档版本：1.0
适用环境：飞牛 NAS + Docker + Home Assistant 2025.5
