Home Assistant HTTPS 配置指南 – wiki基地

作者： /

Home Assistant HTTPS 配置指南

为您的 Home Assistant 实例配置 HTTPS (Hypertext Transfer Protocol Secure) 至关重要，因为它能加密您浏览器与 Home Assistant 服务器之间的通信，保护您的数据免受窃听和篡改。这对于远程访问尤其重要，即使在本地网络中，HTTPS 也能提供额外的安全层，并启用某些需要安全连接的功能（例如 Z-Wave JS UI 的 Smart Start 功能和浏览器中的麦克风支持）。

先决条件

在开始配置之前，请确保满足以下条件：

  1. 域名 (Domain Name)：您需要一个注册的域名（例如 yourdomain.com）或一个动态 DNS 服务提供的域名（例如 DuckDNS）。Let’s Encrypt 证书需要一个公共可解析的域名。
  2. 端口转发 (Port Forwarding)：
    • 将外部端口 80 转发到您的 Home Assistant 实例（或反向代理）的内部端口 80。Let’s Encrypt 在颁发或续订证书时需要此端口进行验证。
    • 将外部端口 443 转发到您的 Home Assistant 实例（或反向代理）的内部端口 443。这是 HTTPS 的标准端口。
  3. 动态 DNS (Dynamic DNS)：如果您的家庭网络拥有动态 IP 地址（ISP 会定期更改），建议使用动态 DNS 服务（如 DuckDNS），以便您的域名始终指向正确的 IP 地址。

方法一：使用 Let’s Encrypt 插件 (推荐用于 Home Assistant OS/Supervised)

这是 Home Assistant OS 或 Supervised 安装最简单直接的方法。

1. 安装 Let’s Encrypt 插件

  • 登录您的 Home Assistant Web 界面。
  • 导航到 设置 (Settings) > 插件 (Add-ons)。
  • 点击右下角的 插件商店 (Add-on Store)。
  • 搜索并选择 Let’s Encrypt 插件。
  • 点击 安装 (Install)。

2. 配置 Let’s Encrypt 插件

  • 安装完成后，进入 Let’s Encrypt 插件的 配置 (Configuration) 选项卡。

  • 您需要编辑 YAML 配置。通常，您会看到类似以下内容的配置：

    yaml
    domains:
    - your_domain.duckdns.org # 替换为您的域名，例如 yourname.duckdns.org
    email: [email protected] # 替换为您的电子邮件地址
    certfile: fullchain.pem
    keyfile: privkey.pem
    challenge: http

  • 将 your_domain.duckdns.org 替换为您的实际域名。

  • 将 [email protected] 替换为您的电子邮件地址。Let’s Encrypt 会使用此地址发送证书到期提醒。
  • 如果您的 Home Assistant 实例在本地网络中，并且您希望避免浏览器警告，可以考虑添加一个通配符域名（例如 *.your_domain.duckdns.org）或同时列出子域名和根域名。
  • 保存配置。

3. 启动插件并检查日志

  • 返回插件的 信息 (Info) 选项卡。
  • 确保 启动时启动 (Start on boot) 已启用。
  • 点击 启动 (Start)。
  • 检查 日志 (Log) 选项卡，确保证书已成功颁发。寻找“Congratulations! Your certificate and chain have been saved…”之类的消息。

4. 更新 Home Assistant 配置

  • 安装 文件编辑器 (File Editor) 插件（如果尚未安装）。
  • 打开 configuration.yaml 文件。

  • 在文件末尾添加或修改 http 部分，如下所示：

    yaml
    http:
    ssl_certificate: /ssl/fullchain.pem
    ssl_key: /ssl/privkey.pem
    # 如果您使用反向代理，请取消注释以下两行并按需配置
    # use_x_forwarded_for: true
    # trusted_proxies:
    # - 172.30.33.0/24 # 替换为您的反向代理网络或IP

  • ssl_certificate 和 ssl_key 路径指向 Let’s Encrypt 插件生成的证书文件。

  • 保存 configuration.yaml 文件。

5. 重启 Home Assistant

  • 导航到 设置 (Settings) > 系统 (System) > 重启 (Restart)。
  • 选择 重启 Home Assistant (Restart Home Assistant)。

6. 证书自动续订

  • Let’s Encrypt 证书通常有效期为 90 天。Let’s Encrypt 插件会自动尝试续订。
  • 为了确保续订，您可以创建一个 Home Assistant 自动化，定期（例如每周）启动 Let’s Encrypt 插件。简单地打开插件就会触发续订检查。

方法二：使用反向代理 (Nginx/Caddy)

反向代理提供更大的灵活性，例如可以同时托管多个服务、处理 SSL 卸载、提供额外的安全层或在同一端口上处理 HTTP 和 HTTPS 请求。

1. 何时使用反向代理

  • 您希望在同一服务器上运行多个 Web 服务，并使用单个 IP 地址和端口进行访问。
  • 您需要更高级的负载均衡、缓存或安全功能。
  • 您希望将 SSL 证书管理与 Home Assistant 本身分离。

2. 安装反向代理

  • 在您的服务器上安装 Nginx 或 Caddy。这通常通过操作系统的包管理器完成（例如 sudo apt install nginx）。
  • 对于 Home Assistant OS/Supervised 用户，可以使用 Nginx Proxy Manager 插件，它提供了一个图形界面来管理反向代理和 Let’s Encrypt 证书，简化了配置过程。

3. 获取 SSL 证书 (通过 Certbot)

  • 如果您手动安装 Nginx/Caddy，可以使用 Certbot 工具为您的域名获取 Let’s Encrypt 证书。
  • 例如，对于 Nginx：sudo certbot --nginx -d your_domain.com。

4. 配置反向代理 (Nginx 示例)

  • 创建一个 Nginx 配置文件（例如 /etc/nginx/sites-available/homeassistant），并添加以下内容：

    “`nginx
    server {
    listen 80;
    server_name your_domain.com; # 替换为您的域名
    return 301 https://$host$request_uri;
    }

    server {
    listen 443 ssl;
    server_name your_domain.com; # 替换为您的域名

    ssl_certificate /etc/letsencrypt/live/your_domain.com/fullchain.pem; # 替换为您的证书路径
ssl_certificate_key /etc/letsencrypt/live/your_domain.com/privkey.pem; # 替换为您的私钥路径
# ssl_trusted_certificate /etc/letsencrypt/live/your_domain.com/chain.pem; # 可选，取决于您的证书链

# 强化的 SSL/TLS 设置 (可选但推荐)
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers 'TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384';
ssl_prefer_server_ciphers off;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;
ssl_session_tickets off;
ssl_stapling on;
ssl_stapling_verify on;
resolver 8.8.8.8 8.8.4.4 valid=300s;
resolver_timeout 5s;
add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload";
add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;

location / {
    proxy_pass http://127.0.0.1:8123; # 替换为您的 Home Assistant 内部 IP 和端口
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade"; # 启用 WebSocket 支持
}

    }
    “`

  • 将 your_domain.com 替换为您的域名。

  • 将 proxy_pass 中的 IP 地址和端口替换为您的 Home Assistant 实例的实际地址。
  • 将 ssl_certificate 和 ssl_certificate_key 路径替换为您的 Let’s Encrypt 证书文件路径。
  • 创建符号链接以启用配置：sudo ln -s /etc/nginx/sites-available/homeassistant /etc/nginx/sites-enabled/
  • 测试 Nginx 配置：sudo nginx -t
  • 重启 Nginx：sudo systemctl restart nginx

5. 更新 Home Assistant 配置 (配合反向代理)

  • 打开 Home Assistant 的 configuration.yaml 文件。

  • 在 http 部分添加或修改以下内容，以告知 Home Assistant 信任反向代理：

    yaml
    http:
    use_x_forwarded_for: true
    trusted_proxies:
    - 127.0.0.1 # 如果 Nginx 在同一台机器上
    - 192.168.1.0/24 # 替换为您的反向代理的 IP 地址或子网
    # 如果您通过反向代理处理 SSL，则不需要以下两行
    # ssl_certificate: /ssl/fullchain.pem
    # ssl_key: /ssl/privkey.pem

  • trusted_proxies 列表应包含您的反向代理服务器的 IP 地址或 IP 范围。

  • 保存 configuration.yaml 文件并重启 Home Assistant。

访问 Home Assistant

配置完成后，您应该能够通过 https://your_domain.com (或 https://your_domain.com:port 如果您使用了非标准端口) 访问您的 Home Assistant 实例。

常见问题

  • 浏览器警告：如果您的证书未正确配置或域名与证书不匹配，浏览器可能会显示安全警告。确保您访问的 URL 与证书上的域名完全一致。
  • 证书过期：Let’s Encrypt 证书有效期为 90 天。请确保您的续订机制（插件自动续订或 Certbot cron job）正常工作。
  • 内部访问：在某些情况下，您可能需要在本地 DNS 服务器中配置您的域名，使其解析到 Home Assistant 的本地 IP 地址，以便在内部网络中也能通过域名访问。
  • 移动应用：Home Assistant 移动应用可能需要手动输入完整的 HTTPS 地址才能连接。

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部