HomeAssistant SSL 连接问题排查与解决方案

问题背景

在使用 HomeAssistant (HA) 时，许多用户会遇到 SSL 证书配置问题，特别是在通过反向代理访问 HA 实例时。本文将以一个典型场景为例，详细分析 SSL 连接失败的原因，并提供完整的解决方案。

典型错误现象

用户配置了 HA 的 SSL 证书并启用强制 HTTPS 后，发现后端服务与 HA 之间的通信出现以下两种错误：

1. 证书验证失败错误
   HTTPSConnectionPool(host='hass.xxx.ltd', port=8123): Max retries exceeded with url: /api/conversation/process (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: certificate has expired (_ssl.c:1007)'))

2. 连接被拒绝错误
   HTTPSConnectionPool(host='hass.xxx.ltd', port=38123): Max retries exceeded with url: /api/conversation/process (Caused by NewConnectionError('<urllib3.connection.HTTPSConnection object at 0x7f28f6075fc0>: Failed to establish a new connection: [Errno 111] Connection refused'))

问题分析

1. 证书过期问题

第一种错误明确提示证书已过期。虽然用户在浏览器中访问正常，但后端服务可能使用了不同的证书验证机制。需要检查：

• 确保证书链完整
• 检查证书有效期
• 验证证书是否被正确加载

2. 反向代理配置问题

第二种错误表明连接被拒绝，这通常与反向代理配置有关。HA 默认会阻止未经授权的反向代理访问，需要在配置文件中明确允许。

完整解决方案

1. 正确配置 HTTP 模块

在 HA 的 configuration.yaml 文件中添加以下配置：

http:
  use_x_forwarded_for: true  # 允许反向代理
  trusted_proxies:
    - 127.0.0.1              # 可信代理地址，根据实际情况修改
    - 192.168.1.0/24         # 可添加局域网段
  ssl_certificate: /ssl/fullchain.pem  # 证书路径
  ssl_key: /ssl/privkey.pem           # 私钥路径
  ip_ban_enabled: true       # 增强安全性
  login_attempts_threshold: 5 # 登录尝试限制

2. 证书管理注意事项

• 确保证书文件路径正确
• 检查文件权限（HA 用户需要有读取权限）
• 推荐使用 Let's Encrypt 等自动续期服务
• 定期检查证书有效期

3. 反向代理配置要点

如果使用 Nginx 作为反向代理，确保配置中包含：

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Host $host;

4. 端口与防火墙检查

• 确认 HA 监听的端口（默认 8123）
• 检查防火墙规则是否允许该端口通信
• 验证端口转发是否正确配置

验证步骤

1. 修改配置后，通过 HA 开发者工具中的"检查配置"功能验证语法
2. 重新加载所有 YAML 配置
3. 测试从内网和外网访问
4. 检查 HA 日志是否有相关错误

常见误区

1. 浏览器访问正常不等于配置正确
   浏览器可能会忽略某些证书错误，而程序调用会严格验证。

2. 仅配置反向代理不够
   HA 需要明确知道哪些代理是可信的。

3. 证书路径问题
   Docker 容器内路径可能与宿主机不同，需要特别注意。

总结

解决 HomeAssistant 的 SSL 连接问题需要系统性地检查证书、反向代理配置和 HA 本身的 HTTP 模块设置。通过本文提供的解决方案，用户可以建立安全的 HTTPS 连接，同时确保反向代理正常工作。定期检查证书有效期和访问日志，可以预防类似问题的再次发生。