home-assistant-Getting started（开始入门）

Getting started（开始入门）

Installation（安装）

Home Assistant Green （即插即用，现成的成品）
Home Assistant Yellow （基于树莓派计算模块）
Raspberry Pi （树莓派）
ODROID
Generic x86-64 （老台式机）
Linux 
macOS
Windows
Other systems 其他系统
Troubleshooting 故障排除

Install Home Assistant Operating System （安装Home Assistant 系统）

DOWNLOAD THE APPROPRIATE IMAGE(下载合适的镜像)

After downloading, decompress the image. If the image comes in a ZIP file, for example, unzip it.
下载之后，解压image，判断这个image是不是zip格式文件， 作为 例子 unzip 如果。

Follow this guide if you already are running a supported virtual machine hypervisor. 

如果你已经在一个运行受支持的虚拟管理程序，就请跟随本指南。


If you are not familiar with virtual machines,
如果你不熟悉这个虚拟机
，
install Home Assistant OS directly on a Home Assistant Yellow，a Raspberry Pi, or an ODROID.

在Home Assistant Yellow，树莓派或者ODROID，直接安装Home Assistant 。

CREATE THE VIRTUAL MACHINE（创建虚拟机）

Load the appliance image into your virtual machine hypervisor. 
把设备镜像加载到虚拟机管理程序里。

(Note: You are free to assign as much resources as you wish to the VM, please assign enough based on your add-on needs).
（注意：您可以自由地为虚拟机分配尽可能多的资源，请根据您的附加需求分配足够的资源）。


Minimum recommended assignments:
最低推荐分配：

2 GB RAM
32 GB Storage 
2vCPU
All these can be extended if your usage calls for more resources.
如果您的使用需要更多的资源，所有这些都可以扩展。

HYPERVISOR SPECIFIC CONFIGURATION （特定于Hypervisor的配置）

略。

START UP YOUR VIRTUAL MACHINE （启动虚拟机）

Install Home Assistant Container（使用容器安装 Home Assistant）

These below instructions are for an installation of Home Assistant Container running in your own container environment, which you manage yourself. Any OCI compatible runtime can be used, however this guide will focus on installing it with Docker.

下面的说明适用于在您自己管理的容器环境中运行Home Assistant Container的安装。任何OCI兼容的运行时都可以使用，但是本指南将重点介绍如何用Docker安装它。

Note-注意

This installation type does not have access to add-ons. If you want to use add-ons, you need to use another installation type. The recommended type is Home Assistant Operating System. Checkout the overview table of installation types to see the differences.


此安装类型没有访问附加组件的权限。如果要使用附加组件，则需要使用另一种安装类型。建议选择“家庭助理操作系统”。检查安装类型概述表以查看差异。

Important （重要的）

Prerequisites This guide assumes that you already have an operating system setup and a container runtime installed (like Docker).

If you are using Docker then you need to be on at least version 19.03.9, ideally an even higher version, and libseccomp 2.4.2 or newer. Docker Desktop will not work, you must use Docker Engine.

本指南假设您已经安装了操作系统和容器运行时（如Docker）。
如果您正在使用Docker，那么您需要至少使用版本19.03.9，最好是更高的版本，以及libseccomp 2.4.2或更新的版本。Docker桌面不能工作，你必须使用Docker引擎。

PLATFORM INSTALLATION 平台的安装

Installation with Docker is straightforward. Adjust the following command so that:

/PATH_TO_YOUR_CONFIG points at the folder where you want to store your configuration and run it. Make sure that you keep the :/config part.

MY_TIME_ZONE is a tz database name, like TZ=America/Los_Angeles.

D-Bus is optional but required if you plan to use the Bluetooth integration.

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


/PATH_TO_YOUR_CONFIG指向您希望存储配置并运行它的文件夹。确保您保留了：/config部分。
MY_TIME_ZONE是一个tz数据库名，如tz =America/ los - angeles。
D-Bus是可选的，但如果您计划使用蓝牙集成，则需要D-Bus。

Install

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

update

docker pull ghcr.io/home-assistant/home-assistant:stable

docker stop homeassistant

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

Once the Home Assistant Container is running Home Assistant should be accessible using http://<host>:8123 (replace with the hostname or IP of the system). You can continue with onboarding.


一旦Home Assistant容器运行，Home Assistant应该可以使用http://:8123（替换为系统的主机名或IP）访问。你可以继续入职了。

RESTART HOME ASSISTANT 重启家庭助理

If you change the configuration, you have to restart the server. To do that you have 3 options.

In your Home Assistant UI, go to the Settings > System and click the Restart button.
You can go to the Developer Tools > Actions, select homeassistant.restart and select Perform action.
Restart it from a terminal.

如果更改配置，则必须重新启动服务器。要做到这一点，你有三个选择。


在你的家庭助理界面，转到设置>系统，点击重启按钮。
你可以去开发人员工具>操作，选择homeassistant。重新启动并选择执行操作。
从终端重新启动它。

docker restart homeassistant

DOCKER COMPOSE

Tip

docker compose should already be installed on your system. If not, you can manually install it.

Docker组合应该已经安装在您的系统上。如果没有，可以手动安装。

As the Docker command becomes more complex, switching to docker compose can be preferable and support automatically restarting on failure or system restart. Create a compose.yaml file:
随着Docker命令变得越来越复杂，切换到Docker compose可能是更好的选择，并支持在故障或系统重启时自动重启。创建一个撰写。yaml文件:

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

Start it by running:

docker compose up -d

Once the Home Assistant Container is running, Home Assistant should be accessible using http://<host>:8123 (replace with the hostname or IP of the system). You can continue with onboarding.

一旦Home Assistant容器运行，应该可以使用http://:8123（替换为系统的主机名或IP）访问Home Assistant。你可以继续入职了。

EXPOSING DEVICES 暴露的设备

In order to use Zigbee or other integrations that require access to devices, you need to map the appropriate device into the container. Ensure the user that is running the container has the correct privileges to access the /dev/tty* file, then add the device mapping to your container instructions:

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

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

OPTIMIZATIONS 优化

The Home Assistant Container is using an alternative memory allocation library jemalloc for better memory management and Python runtime speedup.

As the jemalloc configuration used can cause issues on certain hardware featuring a page size larger than 4K (like some specific ARM64-based SoCs), it can be disabled by passing the environment variable DISABLE_JEMALLOC with any value, for example:

Home Assistant容器正在使用一个可选的内存分配库jemalloc，以实现更好的内存管理和Python运行时加速。


由于所使用的jemalloc配置可能会在某些页面大小大于4K的硬件上导致问题（例如某些特定的基于arm64的soc），因此可以通过传递带有任意值的环境变量DISABLE_JEMALLOC来禁用它，例如：

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

The error message <jemalloc>: Unsupported system page size is one known indicator.


错误消息：不支持的系统页面大小是一个已知的指示符。

Troubleshooting  故障排除
NO ACCESS TO THE FRONTEND 无法进入前端


Symptom: You cannot open the Home Assistant page in your browser. If you are not using Home Assistant Operating System, the cause may be an access restriction.

In newer Linux distributions, the access to a host is very limited. This means that you can’t access the Home Assistant frontend that is running on a host outside of the host machine.

To fix this, you will need to open your machine’s firewall for TCP traffic to port 8123. The method for doing this will vary depending on your operating system and the firewall you have installed. Below are some suggestions to try. Google is your friend here.

For UFW systems (for example, Debian):

现象：无法在浏览器中打开“家庭助理”页面。如果您没有使用家庭助理操作系统，原因可能是访问限制。


在较新的Linux发行版中，对主机的访问非常有限。这意味着您无法访问在主机之外的主机上运行的Home Assistant前端。


要解决这个问题，需要打开机器的防火墙，允许TCP通信到端口8123。执行此操作的方法取决于您的操作系统和所安装的防火墙。下面是一些可以尝试的建议。b谷歌是你的朋友。


对于UFW系统（例如Debian）：

 HELP US IMPROVE OUR DOCUMENTATION
Suggest an edit to this page, or provide/view feedback for this page.
帮助我们改进文档
建议对此页进行编辑，或提供/查看此页的反馈。

创建文件夹：/usr/local/docker/homeassistant/config

docker run -d   --name homeassistant   --privileged   --restart=unless-stopped   -v /usr/local/docker/homeassistant/config:/config   --network=host   ghcr.io/home-assistant/home-assistant:stable

新单词：

below 在..下面

example 例子

Follow 跟随

guide 指南

already 已经

supported 受支持的

virtual 虚拟的

machine 机器（普通工具都能用）

familiar 熟悉

virtual machines 虚拟机

directly 直接

appliance 计划

hypervisor 管理程序

Note 注意

free 自由

assign 分配

much 多

resources 资源

please 请

enough 足够的

based 基础

needs 需要

Minimum 最低

recommended 推荐的

assignments 分配

Storage 存储

Container 容器

instructions 指令