高级树莓派安装

虽然我们推荐使用 Home Assistant OS，但也有其他方式安装 Home Assistant。在您继续之前，请注意与 Home Assistant OS 相比的限制和差异。您可以在 安装页面 中找到更多信息。值得注意的是， 附加组件 仅在 Home Assistant Operating System中可用。

安装 Home Assistant Container

以下说明适用于在您自己管理的容器环境中安装 Home Assistant ContainerHome Assistant Container 是 Home Assistant Core 的独立容器化安装。任何 OCI 兼容的运行时都可以使用，但文档重点是 Docker。 [Learn more]。可以使用任何 OCI 兼容的运行时，但本指南将重点介绍使用 Docker 进行安装。

平台安装

使用 Docker 安装非常简单。调整以下命令，使：

• /PATH_TO_YOUR_CONFIG 指向您要存储配置并运行它的文件夹。请确保保留 :/config 部分。

• MY_TIME_ZONE 是 tz 数据库名称，例如 TZ=America/Los_Angeles。

• D-Bus 是可选的，但如果您计划使用 Bluetooth 集成则是必需的。

  Install

  Update

  docker run -d \
    --name homeassistant \
    --privileged \
    --restart=unless-stopped \
    -e TZ=MY_TIME_ZONE \
    -v /PATH_TO_YOUR_CONFIG:/config \
    -v /run/dbus:/run/dbus:ro \
    --network=host \
    ghcr.io/home-assistant/home-assistant:stable
  

  # if this returns "Image is up to date" then you can stop here
  docker pull ghcr.io/home-assistant/home-assistant:stable
  

  # stop the running container
  docker stop homeassistant
  

  # remove it from Docker's list of containers
  docker rm homeassistant
  

  # finally, start a new one
  docker run -d \
    --name homeassistant \
    --restart=unless-stopped \
    --privileged \
    -e TZ=MY_TIME_ZONE \
    -v /PATH_TO_YOUR_CONFIG:/config \
    -v /run/dbus:/run/dbus:ro \
    --network=host \
    ghcr.io/home-assistant/home-assistant:stable
  

  一旦 Home Assistant Container 运行，您应该可以使用 http://<host>:8123 访问 Home Assistant（将 替换为系统的主机名或 IP）。您可以继续 onboarding。

    Onboarding

  重启 Home Assistant

  如果您更改了配置，则必须重启服务器。为此，您有 3 个选项。

  1. 在 Home Assistant UI 中，转到 设置 > 系统 并点击 重启 按钮。
  2. 您可以转到 开发者工具 > 操作，选择 homeassistant.restart 并选择 执行操作。
  3. 从终端重启。
  Docker CLI

  Docker Compose

  docker restart homeassistant
  

  docker compose restart
  

  Docker compose

  Tip

  docker compose 应该已经安装在您的系统上。如果没有，您可以手动安装它。

  随着 Docker 命令变得越来越复杂，切换到 docker compose 可能更可取，并支持在失败或系统重启时自动重启。创建一个 compose.yml 文件：

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

  通过以下命令启动:

  docker compose up -d
  

  一旦 Home Assistant Container 运行，您应该可以使用 http://<host>:8123 访问 Home Assistant（将 替换为系统的主机名或 IP）。您可以继续 onboarding。

    Onboarding

  暴露设备

  为了使用 Zigbee 或其他需要访问设备的集成，您需要将适当的设备映射到容器中。确保运行容器的用户具有访问 /dev/tty* 文件的正确权限，然后将设备映射添加到您的容器指令中：

  Docker CLI

  Docker Compose

  docker run ... --device /dev/ttyUSB0:/dev/ttyUSB0 ...
  

  services:
    homeassistant:
      ...
      devices:
        - /dev/ttyUSB0:/dev/ttyUSB0
  

  优化

  Home Assistant Container 使用替代的内存分配库 jemalloc 来实现更好的内存管理和 Python 运行时加速。

  由于使用的 jemalloc 配置可能会在某些具有大于 4K 页面大小的硬件（如某些特定的 ARM64 架构 SoC）上导致问题，可以通过传递环境变量 DISABLE_JEMALLOC 来禁用它，例如：

  Docker CLI

  Docker Compose

  docker run ... -e "DISABLE_JEMALLOC=true" ...
  

  services:
    homeassistant:
    ...
      environment:
        DISABLE_JEMALLOC: true
  

  错误信息 <jemalloc>: Unsupported system page size 是一个已知的指示器。

  安装 Home Assistant Core

  Caution

  这是一个高级安装过程，某些步骤可能因系统而异。考虑到这种安装类型的性质，我们假设您可以处理本文档与您使用的系统配置之间的细微差异。如有疑问，请考虑使用 其他安装方法，因为它们可能更适合您。

  先决条件

  本指南假设您已经设置好操作系统并安装了 Python 3.13（包括 python3-dev 包）或更新版本。

  安装依赖项

  在开始之前，请确保您的系统已完全更新，本指南中的所有软件包都使用 apt 安装，如果您的操作系统没有 apt，请寻找替代方案。

  sudo apt-get update
  sudo apt-get upgrade -y
  

  安装依赖:

  sudo apt-get install -y python3 python3-dev python3-venv python3-pip bluez libffi-dev libssl-dev libjpeg-dev zlib1g-dev autoconf build-essential libopenjp2-7 libtiff6 libturbojpeg0-dev tzdata ffmpeg liblapack3 liblapack-dev libatlas-base-dev
  

  上述列出的依赖项可能会有所不同或缺失，具体取决于您的系统或个人使用 Home Assistant 的情况。

  创建账户

  为 Home Assistant Core 添加一个名为 homeassistant 的账户。 由于此账户仅用于运行 Home Assistant Core，因此添加了额外的参数 -rm 来创建一个系统账户并创建主目录。

  sudo useradd -rm homeassistant
  

  创建虚拟环境

  首先，我们将为 Home Assistant Core 的安装创建一个目录，并将所有者更改为 homeassistant 账户。

  sudo mkdir /srv/homeassistant
  sudo chown homeassistant:homeassistant /srv/homeassistant
  

  接下来是为 Home Assistant Core 创建并切换到虚拟环境。这将使用 homeassistant 账户来完成。

  sudo -u homeassistant -H -s
  cd /srv/homeassistant
  python3 -m venv .
  source bin/activate
  

  激活虚拟环境后（注意提示符会变为 (homeassistant) homeassistant@raspberrypi:/srv/homeassistant $），您需要运行以下命令来安装所需的 Python 包。

  python3 -m pip install wheel
  

  安装完所需的 Python 包后，现在可以安装 Home Assistant Core 了！

  pip3 install homeassistant==2025.3.4
  

  故障排除：如果您在环境中没有看到上述版本的 Home Assistant 包，请确保您已安装正确的 Python 版本，如先决条件中所述。

  首次启动 Home Assistant Core。这将为您完成安装，自动在 /home/homeassistant 目录中创建 .homeassistant 配置目录，并安装任何基本依赖项。

  hass
  

  您现在可以通过 Web 界面访问您的安装，地址为 http://homeassistant.local:8123。

  如果此地址无法访问，您也可以尝试 http://localhost:8123 或 http://X.X.X.X:8123（将 X.X.X.X 替换为您机器的 IP 地址）。

  Note

  当您第一次运行 hass 命令时，它将下载、安装并缓存必要的库/依赖项。此过程可能需要 5 到 10 分钟。在此期间，当您访问 Web 界面时，可能会遇到 无法访问此网站 的错误。这种情况只会发生在第一次。后续的重启会快得多。

  帮助我们改进翻译

  建议编辑此页面，或提供/查看此页面的反馈。

  编辑 提供反馈 查看已提交的反馈