Home Assistant 部署指南

概述

Home Assistant 支持多种部署方式，包括：

Docker：推荐方式，易于管理和更新
Home Assistant OS：专用操作系统，适合树莓派等设备
Python 虚拟环境：适合开发和测试
Supervised：在现有 Linux 系统上安装

Docker 部署（推荐）

1. 安装 Docker

确保你的系统已安装 Docker 和 Docker Compose。

                            # 检查 Docker 版本
docker --version
docker-compose --version
                        

如果未安装，请参考： Docker 官方安装文档

2. 创建配置目录

                            mkdir -p ~/homeassistant
cd ~/homeassistant
                        

3. 创建 docker-compose.yml

                            version: '3'
services:
  homeassistant:
    container_name: homeassistant
    image: "ghcr.io/home-assistant/home-assistant:stable"
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
    restart: unless-stopped
    privileged: true
    network_mode: host
                        

4. 启动 Home Assistant

docker-compose up -d

首次启动需要几分钟时间。启动后，访问 http://localhost:8123 完成初始设置。

初始配置

1. 创建管理员账户

首次访问时，系统会引导你创建管理员账户。按照提示完成设置。

2. 配置位置和时区

设置你的地理位置和时区，这有助于自动发现设备和正确显示时间。

3. 发现和添加设备

Home Assistant 会自动发现局域网内的智能设备。你也可以手动添加集成。

创建长期访问令牌

为了安全地访问 Home Assistant API，需要创建一个长期访问令牌。

登录 Home Assistant 管理界面
点击左下角你的用户名
滚动到底部，找到 "长期访问令牌" 部分
点击 "创建令牌"
输入令牌名称（如：Home Voice Box）
点击 "确定"，复制生成的令牌
重要：令牌只显示一次，请妥善保存

安全提示：长期访问令牌具有完全访问权限，请妥善保管，不要泄露给他人。

外部访问配置

如果你有公网 IP，可以配置端口转发。如果没有公网 IP，请参考 Cloudflare Tunnel 配置指南。

有公网 IP 的情况

在路由器中配置端口转发（8123 端口）
配置动态 DNS（可选，但推荐）
在 Home Assistant 中启用外部访问

无公网 IP 的情况

使用 Cloudflare Tunnel 可以安全地暴露 Home Assistant，无需公网 IP 和端口转发。详细步骤请查看 Cloudflare Tunnel 配置指南。