本文詳細介紹在Docker中部署Home Assistant的全流程，含從軒轅鏡像查看詳情、多種方式拉取鏡像，提供快速部署、持久化掛載（推薦）、docker-compose部署三種方案，還包含結果驗證方法與常見問題解決辦法。

?? 準備工作

若你的系統尚未安裝 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:stable
    container_name: home-assistant
    restart: unless-stopped
    ports:
      - "8123:8123"
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
    privileged: 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、語音助手、自動化場景等，讓智能家居真正服務于生活。