Home Assistant HTTPS 配置指南 – wiki基地

Home Assistant HTTPS 配置指南

导言

Home Assistant 是一个功能强大的开源家庭自动化平台，它让您能够全面控制智能家居设备，并创建复杂的自动化场景。然而，默认情况下，Home Assistant 实例通常通过 HTTP 连接，这意味着您的数据在传输过程中是未加密的。当您从家庭网络外部访问 Home Assistant 时，这会带来严重的安全风险。

通过配置 HTTPS（HTTP Secure），您可以为 Home Assistant 实例提供加密连接。HTTPS 使用 SSL/TLS 协议来加密客户端（您的浏览器或 Home Assistant 应用程序）与服务器（您的 Home Assistant 实例）之间传输的所有数据。这不仅可以保护您的凭据、敏感数据和设备状态不被窃听和篡改，还能在公共网络上提供安全的远程访问。

本指南将详细介绍如何为您的 Home Assistant 实例配置 HTTPS，主要关注使用 Let’s Encrypt 提供的免费 SSL/TLS 证书。我们将涵盖从准备工作到具体配置步骤，以及常见的故障排除方法，确保您的智能家居系统既强大又安全。

前提条件

在开始配置 Home Assistant 的 HTTPS 之前，请确保您满足以下条件：

1. 静态内部 IP 地址:
   • 您的 Home Assistant 实例应该有一个固定的内部 IP 地址（例如 192.168.1.100）。这可以通过在路由器中为 Home Assistant 设备分配静态 IP 地址或设置 DHCP 保留来实现。
2. 动态 DNS (DDNS) 服务或固定外部 IP 地址:
   • 如果您没有固定的外部（公共）IP 地址（大多数家庭用户都是这种情况），您需要使用一个动态 DNS (DDNS) 服务。DDNS 服务会将一个易于记忆的域名（例如 yourname.duckdns.org）映射到您不断变化的家庭外部 IP 地址。常见的 DDNS 服务有 DuckDNS, No-IP, FreeDNS 等。
   • 如果您有固定外部 IP 地址，则不需要 DDNS 服务，可以直接使用您的域名解析到该 IP。
3. 注册的域名 (可选但强烈推荐):
   • 虽然某些 DDNS 服务会为您提供一个子域名（例如 yourname.duckdns.org），但拥有一个自己的顶级域名（例如 yourdomain.com）并将其配置为指向您的 DDNS 服务或固定 IP 地址，将提供更大的灵活性和专业性。Let’s Encrypt 证书通常与域名绑定。
4. 路由器端口转发:
   • 您需要访问您的路由器设置，将外部端口 443（HTTPS 的标准端口）转发到您的 Home Assistant 实例的内部 IP 地址上的端口 8123（Home Assistant 的默认端口）。
   • 重要提示: 某些 ISP 可能会阻止或限制端口 80 和 443。如果您遇到困难，可能需要联系您的 ISP。
5. Home Assistant 正在运行:
   • 确保您的 Home Assistant 实例已正确安装并可以通过本地网络访问。
6. Samba 共享 (可选但方便):
   • 如果您需要手动编辑配置文件，安装 Samba 插件（在 Home Assistant Add-on Store 中）可以方便您通过网络共享访问 Home Assistant 的配置文件夹。
7. 备份:
   • 在进行任何重大配置更改之前，请务必备份您的 Home Assistant 配置。

满足这些前提条件将为您的 HTTPS 配置打下坚实的基础。

获取 SSL/TLS 证书

为了启用 HTTPS，您需要一个有效的 SSL/TLS 证书。本指南将重点介绍最常用且免费的 Let’s Encrypt 证书。

方案一：使用 Let’s Encrypt (推荐)

Let’s Encrypt 提供免费、自动化和开放的证书，是为 Home Assistant 配置 HTTPS 的首选方法。获取 Let’s Encrypt 证书通常需要一个域名，并能通过端口 80 或 443 验证该域名的所有权。

1. 使用 DuckDNS 插件和 Let’s Encrypt 插件 (Home Assistant OS/Supervisor)

这是 Home Assistant OS 或 Home Assistant Supervised 安装中最简单、最推荐的方法。

• 安装 DuckDNS 插件:
  1. 在 Home Assistant 中，导航到 设置 (Settings) -> 附加组件 (Add-ons) -> 附加组件商店 (Add-on Store)。
  2. 搜索并安装 DuckDNS 附加组件。
  3. 配置 DuckDNS 插件：
     • 在 DuckDNS 网站 (duckdns.org) 上注册一个免费账号，并创建一个子域名（例如 yourname.duckdns.org）。
     • 复制您的 DuckDNS token。
     • 在 Home Assistant 的 DuckDNS 附加组件配置中，将 domains 字段设置为您的 DuckDNS 域名，token 字段设置为您的 DuckDNS token。
     • 将 accept_terms 设置为 true。
     • 重要: 将 aliases 和 certfile, keyfile 字段留空，因为 Let’s Encrypt 插件会处理证书。
     • 如果您只用 DuckDNS 更新 IP，而证书由其他方式提供，才需要将 lets_encrypt 设置为 false。在本方案中，我们将使用 Let’s Encrypt 插件来处理证书。
     • 保存配置并启动 DuckDNS 插件。检查日志，确保它成功更新了您的 IP 地址。
• 安装 Let’s Encrypt 插件:
  1. 在 Home Assistant 附加组件商店中，搜索并安装 Let’s Encrypt 附加组件。
  2. 配置 Let’s Encrypt 插件：
     • 将 email 字段设置为您的电子邮件地址，用于接收证书续订通知。
     • 将 domains 字段设置为您的 DuckDNS 域名（或您自己的域名）。
     • 将 certfile 设置为 fullchain.pem。
     • 将 keyfile 设置为 privkey.pem。
     • seconds 字段可以保持默认（300）。
     • 重要: 确保您的路由器已将外部端口 80 (HTTP) 转发到运行 Home Assistant 的设备内部 IP 地址的端口 8123。Let’s Encrypt 通常通过端口 80 进行域名所有权验证。如果您无法转发 80 端口，请考虑使用 DNS 验证方式（更复杂，通常通过 Nginx Proxy Manager 等实现）。
     • 保存配置并启动 Let’s Encrypt 插件。首次启动可能需要一些时间。检查日志，确保证书已成功生成。

2. 使用 Nginx Proxy Manager 插件 (Home Assistant OS/Supervisor)

Nginx Proxy Manager (NPM) 是一个功能强大的反向代理，它不仅可以处理 Let’s Encrypt 证书，还可以让您通过一个公共端口访问多个内部服务。

• 安装 Nginx Proxy Manager 插件:
  1. 在 Home Assistant 附加组件商店中，搜索并安装 Nginx Proxy Manager 附加组件。
  2. 启动插件。在日志中找到其 Web 界面的访问地址和初始凭据。
  3. 通过浏览器访问 NPM 的 Web UI，使用初始凭据登录并更改密码。
• 配置 NPM 代理主机并获取证书:
  1. 在 NPM 界面中，导航到 Hosts -> Proxy Hosts -> Add Proxy Host。
  2. 在 Details 选项卡中：
     • Domain Names: 输入您的域名（例如 yourname.duckdns.org）。
     • Scheme: http
     • Forward Hostname / IP: 输入您的 Home Assistant 实例的内部 IP 地址（例如 192.168.1.100）。
     • Forward Port: 8123
     • 启用 Cache Assets, Block Common Exploits, Websockets Support。
  3. 在 SSL 选项卡中：
     • SSL Certificate: 选择 Request a new SSL Certificate。
     • Force SSL: 启用。
     • Email Address for Let’s Encrypt: 输入您的电子邮件地址。
     • I Agree to the Let’s Encrypt Terms of Service: 启用。
     • 如果您无法转发 80 端口，或者想使用 DNS 验证，可以在这里配置。否则，HTTP Challenge 是默认且推荐的验证方式。
  4. 保存配置。NPM 将尝试获取 Let’s Encrypt 证书。检查 NPM 日志以确保过程顺利。
• 路由器端口转发:
  • 确保您的路由器已将外部端口 80 和 443 转发到运行 Nginx Proxy Manager 的 Home Assistant 设备的内部 IP 地址。NPM 将监听这些端口并处理所有传入请求。

方案二：手动获取证书 (不推荐初学者)

对于高级用户或在特定场景下，您可能需要手动获取 SSL/TLS 证书。这通常涉及使用 Certbot 等工具在服务器上生成证书，然后将证书文件（fullchain.pem 和 privkey.pem）复制到 Home Assistant 配置目录中的 ssl 文件夹。

Home Assistant 配置

一旦您获取了 SSL/TLS 证书，就需要配置 Home Assistant 来使用它。

方案一：直接在 configuration.yaml 中配置 HTTPS (当证书文件可用时)

如果您通过 DuckDNS 附加组件生成了证书，或者手动将 fullchain.pem 和 privkey.pem 文件放置在 Home Assistant 配置目录的 ssl 文件夹中，那么您可以在 configuration.yaml 文件中直接启用 HTTPS。

1. 编辑 configuration.yaml:

   • 使用文件编辑器（例如 Home Assistant 的 File editor 附加组件或 Samba 共享）打开 Home Assistant 配置目录中的 configuration.yaml 文件。
   • 添加或修改 http: 部分，如下所示：

   yaml
http:
ssl_certificate: /ssl/fullchain.pem
ssl_key: /ssl/privkey.pem
# 如果您希望只能通过 HTTPS 访问，并且将所有 HTTP 请求重定向到 HTTPS，请取消注释以下行
# base_url: https://yourname.duckdns.org:8123 # 将 yourname.duckdns.org 替换为您的域名
# trusted_proxies:
# - 127.0.0.1 # Home Assistant 运行在同一主机上的代理，如果使用 Nginx Proxy Manager 则可能需要添加NPM的内部IP
# - ::1
# ip_filter: # 可选：限制允许访问的 IP 地址
# - 192.168.1.0/24

   • ssl_certificate: 指定您的 Let’s Encrypt 证书文件的完整路径。通常，如果您的证书在配置目录的 ssl 文件夹中，则路径为 /ssl/fullchain.pem。
   • ssl_key: 指定您的 Let’s Encrypt 私钥文件的完整路径。通常为 /ssl/privkey.pem。
   • base_url (可选，推荐远程访问时使用): 当您从外部网络访问 Home Assistant 时，设置此项可以确保生成的所有链接都使用正确的 HTTPS URL。请确保域名和端口与您通过路由器转发的外部访问方式一致。
   • trusted_proxies (如果您使用反向代理如 Nginx Proxy Manager): 如果您在 Home Assistant 前面使用了反向代理，您需要在此处列出代理的 IP 地址，以便 Home Assistant 能够正确识别客户端的真实 IP 地址。Nginx Proxy Manager 通常会在 Docker 容器中运行，您需要找到其内部 IP。
   • ip_filter (可选): 仅允许特定 IP 范围访问 Home Assistant。

2. 保存并重启 Home Assistant:

   • 保存 configuration.yaml 文件。
   • 导航到 设置 (Settings) -> 系统 (System) -> 重启 (Restart)。
   • 选择 完全重启 Home Assistant (Restart Home Assistant Core)。

方案二：通过反向代理 (如 Nginx Proxy Manager) 访问 Home Assistant

如果您使用了 Nginx Proxy Manager 附加组件来处理证书和 HTTPS 连接，那么 Home Assistant 本身不需要直接处理 SSL。在这种情况下，Home Assistant 仍然通过 HTTP (端口 8123) 运行在内部网络中，而 NPM 负责所有外部 HTTPS 请求的加密和转发。

1. Home Assistant configuration.yaml 配置:

   • 在这种情况下，不要在 http: 部分配置 ssl_certificate 和 ssl_key。Home Assistant 将保持 HTTP 连接。
   • 您可能需要配置 trusted_proxies，让 Home Assistant 知道 NPM 是一个受信任的代理。NPM 的 IP 地址通常是 Home Assistant 所在宿主机的内部 IP 或 Docker 网络的 IP 地址。

   yaml
http:
use_x_forwarded_for: true # 告诉 Home Assistant 使用 X-Forwarded-For 头来获取客户端的真实 IP
trusted_proxies:
- 172.30.33.0/24 # 示例：Nginx Proxy Manager 附加组件的 Docker 内部网络范围，可能需要根据您的环境调整
# - 192.168.1.10 # 如果 NPM 在单独的机器上运行，这是其内部 IP
# base_url: https://yourname.duckdns.org # 如果您希望所有链接都使用 HTTPS

   • trusted_proxies: 关键在于让 Home Assistant 知道 Nginx Proxy Manager 的内部 IP 地址或 IP 范围。对于 Home Assistant OS/Supervised，通常 NPM 运行在 Docker 容器中，其内部 IP 可能在 172.30.33.0/24 这样的 Docker 桥接网络中。您可以在 NPM 附加组件的日志中找到其 IP 地址，或者在 Home Assistant OS 的终端中使用 docker inspect addon_a0d7b954_nginxproxymanager | grep -i "ipaddress" (替换 addon ID) 来查看。
   • use_x_forwarded_for: 启用此选项以确保 Home Assistant 能够正确获取通过代理连接的客户端的真实 IP 地址。

2. 重启 Home Assistant:

   • 保存 configuration.yaml 文件。
   • 导航到 设置 (Settings) -> 系统 (System) -> 重启 (Restart)。
   • 选择 完全重启 Home Assistant (Restart Home Assistant Core)。

通过 NPM 访问 Home Assistant 的最终 URL 将是 https://yourname.duckdns.org (不带端口 8123)，因为 NPM 会在 443 端口监听并将其转发到 Home Assistant 的 8123 端口。

路由器端口转发

端口转发是实现从外部网络安全访问 Home Assistant 的关键一步。它告诉您的路由器将来自特定外部端口的传入请求发送到您本地网络中特定设备的特定端口。

重要提示： 路由器的界面和术语因制造商和型号而异。以下是一般步骤和常见设置。请查阅您路由器的用户手册或在线支持文档以获取具体说明。

步骤：

1. 访问路由器管理界面:
   • 在您的浏览器中输入路由器的 IP 地址（通常是 192.168.0.1, 192.168.1.1, 或 192.168.1.254）。
   • 输入您的路由器用户名和密码登录。
2. 找到端口转发 (Port Forwarding) 或虚拟服务器 (Virtual Server) 设置:
   • 这些设置通常位于 WAN, NAT, 安全 (Security) 或 高级设置 (Advanced Settings) 部分。

3. 创建端口转发规则:

   • 您需要创建至少一个（通常是两个）规则，具体取决于您的 HTTPS 配置方法。
   • 对于直接 Home Assistant HTTPS (configuration.yaml 或 DuckDNS 附加组件):
     • 服务名称 (Service Name): 例如 Home Assistant HTTPS
     • 协议 (Protocol): TCP
     • 外部端口 (External Port) / 广域网端口 (WAN Port) / 远程端口 (Remote Port):
       • 起始端口: 443
       • 结束端口: 443
     • 内部端口 (Internal Port) / 局域网端口 (LAN Port) / 本地端口 (Local Port):
       • 起始端口: 8123
       • 结束端口: 8123
     • 内部 IP 地址 (Internal IP Address) / 服务器 IP 地址 (Server IP Address): 输入您的 Home Assistant 设备的静态内部 IP 地址（例如 192.168.1.100）。
   • 如果您使用 Nginx Proxy Manager (NPM):
     • NPM 需要监听外部的 80 端口来完成 Let’s Encrypt 的 HTTP 验证，并监听 443 端口来处理 HTTPS 请求。
     • 规则 1 (HTTP 验证):
       • 服务名称: 例如 NPM HTTP
       • 协议: TCP
       • 外部端口: 80 到 80
       • 内部端口: 80 到 80 (NPM 在内部监听 80 端口)
       • 内部 IP 地址: 您的 Home Assistant 设备（运行 NPM）的静态内部 IP 地址。
     • 规则 2 (HTTPS):
       • 服务名称: 例如 NPM HTTPS
       • 协议: TCP
       • 外部端口: 443 到 443
       • 内部端口: 443 到 443 (NPM 在内部监听 443 端口)
       • 内部 IP 地址: 您的 Home Assistant 设备（运行 NPM）的静态内部 IP 地址。

4. 保存并应用设置:

   • 保存您的端口转发规则，并确保更改已应用。路由器可能需要重启。

重要注意事项:

• 端口冲突: 确保您的路由器或网络中的其他设备没有使用相同的外部端口 (例如 80 或 443)。
• UPnP (通用即插即用): 某些 Home Assistant 附加组件（如 DuckDNS）可能尝试使用 UPnP 自动配置端口转发。虽然这很方便，但出于安全原因，手动配置端口转发并禁用路由器的 UPnP 功能通常是更安全的选择。
• 双重 NAT: 如果您的网络处于双重 NAT 环境中（例如，您的路由器连接到另一个路由器的网络），端口转发会变得更加复杂。您可能需要配置两个路由器上的端口转发，或将一个路由器设置为桥接模式。
• ISP 限制: 如前所述，一些 ISP 会阻止或限制 80 和 443 端口。如果遇到问题，请联系您的 ISP。

完成端口转发后，您应该能够尝试通过您的域名 (例如 https://yourname.duckdns.org 或 https://yourname.duckdns.org:8123) 从外部网络访问您的 Home Assistant 实例。

常见问题与故障排除

在配置 Home Assistant 的 HTTPS 过程中，可能会遇到一些问题。以下是一些常见的故障排除步骤和建议：

1. 无法通过 HTTPS 访问 (连接超时或拒绝):

   • 检查端口转发: 确认路由器上的端口 443 (以及如果您使用 NPM 的话 80 端口) 已正确转发到 Home Assistant (或 NPM) 的内部 IP 地址。
   • 防火墙: 确保您的路由器防火墙或操作系统防火墙 (如果 Home Assistant 运行在通用操作系统上) 没有阻止 443 (和 80) 端口的传入连接。
   • ISP 限制: 某些 ISP 会阻止或限制 80 和 443 端口。尝试联系您的 ISP 确认是否存在此限制。
   • DDNS 服务: 确认您的 DDNS 服务正在正确更新您的公共 IP 地址，并且您的域名解析到的 IP 是正确的。您可以尝试使用在线工具（例如 ping yourname.duckdns.org 或 nslookup yourname.duckdns.org）来检查。
   • 内部 IP: 确认 Home Assistant 设备的内部 IP 地址是静态的，并且您在端口转发中使用了正确的 IP。

2. “不安全”或“证书无效”警告:

   • 证书过期: Let’s Encrypt 证书有效期为 90 天，需要定期续订。检查您的证书是否已过期。DuckDNS 或 Nginx Proxy Manager 附加组件通常会自动处理续订。
   • 域名不匹配: 确保您访问的域名与证书上注册的域名完全匹配。例如，如果您访问 https://192.168.1.100，即使证书有效，浏览器也会发出警告，因为它不是您域名的 IP 地址。
   • 未安装完整链: 确保您使用的是 fullchain.pem（包含完整证书链）而不是 cert.pem。
   • 证书文件路径错误: 仔细检查 configuration.yaml 中 ssl_certificate 和 ssl_key 的路径是否正确。
   • 时间不同步: 确保您的 Home Assistant 主机时间与当前时间同步。时间不同步可能导致 SSL/TLS 握手失败。

3. Home Assistant 重启失败或配置检查错误:

   • configuration.yaml 语法错误: 使用 Home Assistant 的 开发者工具 (Developer Tools) -> YAML -> 检查配置 (Check Configuration) 功能来验证您的 configuration.yaml 文件是否存在语法错误。
   • 文件权限: 确保 Home Assistant 用户对 ssl 文件夹及其中的证书文件具有读取权限。
   • 证书损坏: 尝试重新生成证书。

4. 使用 Nginx Proxy Manager (NPM) 时的问题:

   • NPM 附加组件未启动: 检查 NPM 附加组件的日志，确保它已成功启动且没有错误。
   • NPM 配置错误: 检查 NPM 中的代理主机设置，确保转发地址和端口正确，并且 SSL 证书已成功获取。
   • trusted_proxies 未配置或配置错误: 如果您通过 NPM 访问时 Home Assistant 行为异常（例如，无法显示客户端 IP），请检查 configuration.yaml 中的 trusted_proxies 设置。

5. Let’s Encrypt 证书无法获取:

   • 80 端口验证失败: Let’s Encrypt 默认通过 80 端口进行 HTTP-01 验证。确保 80 端口已从外部转发到 Home Assistant (或 NPM) 设备的内部 80 端口 (如果使用 NPM) 或 Home Assistant 的 8123 端口 (如果直接获取证书)。
   • DNS 记录未传播: 如果您刚更改了 DNS 记录，可能需要一些时间才能在全球范围内传播。
   • DDNS 服务更新失败: 检查 DuckDNS 附加组件的日志，确保它成功更新了您的 IP。
   • Let’s Encrypt 请求限制: 如果您尝试获取证书过于频繁，可能会遇到 Let’s Encrypt 的速率限制。请等待一段时间再重试。

调试技巧:

• 查看日志: 始终检查 Home Assistant (设置 -> 系统 -> 日志) 以及任何相关附加组件（如 DuckDNS, Let’s Encrypt, Nginx Proxy Manager）的日志。日志是诊断问题的最佳起点。
• 尝试本地访问: 在所有外部访问尝试失败之前，请确保您可以通过内部 IP 地址和端口 (http://192.168.1.100:8123) 正常访问 Home Assistant。
• 使用命令行工具:
  • ping yourname.duckdns.org: 检查域名是否解析到正确的公共 IP。
  • curl -v https://yourname.duckdns.org: 查看连接过程中的详细信息，有助于诊断 SSL 握手问题。
  • telnet your.public.ip 443: 检查 443 端口是否从外部开放。
• 分步测试: 每次只更改一处设置，然后进行测试，这样可以更容易地找出问题所在。

耐心和细致是成功的关键。通过以上故障排除步骤，您应该能够解决大多数 Home Assistant HTTPS 配置中遇到的问题。

结论

通过本指南，您应该已经成功为您的 Home Assistant 实例配置了 HTTPS，并能够从本地网络和外部网络安全地访问它。启用 HTTPS 不仅是提高数据安全性的关键一步，也为您的智能家居系统提供了专业级的远程访问能力。

无论是通过 DuckDNS 附加组件直接处理证书，还是通过 Nginx Proxy Manager 这样的反向代理来管理复杂的网络流量，HTTPS 都确保了您与 Home Assistant 之间通信的加密和数据完整性。请记住，Let’s Encrypt 证书需要定期续订，但大多数情况下，通过 Home Assistant 附加组件的自动化功能，您无需手动干预。

一个安全、可靠的智能家居系统是家庭自动化体验的基础。定期检查您的配置，关注 Home Assistant 和相关附加组件的更新，并持续关注网络安全最佳实践，将帮助您保持智能家居环境的稳定与安全。

祝您的智能家居体验更加安全、便捷！