mcpField
H
haos-https-tunnel

haos-https-tunnel

github.com/caanio云与 DevOps038 次安装1 天前更新
代码仓库

关于 haos-https-tunnel

haos-https-tunnel 是为 Home Assistant OS 配置 Cloudflare Tunnel 的操作指南，面向希望从外网通过 HTTPS 访问 HAOS 的用户。它说明了安装、代理信任、授权和验证步骤，无需开放路由器入站端口。

主要功能

  1. 01安装并配置 cloudflared 插件
  2. 02通过 Cloudflare 授权创建 Tunnel
  3. 03设置 Home Assistant 可信代理
  4. 04检查连接日志与 HTTPS 响应
  5. 05提供用户授权和界面设置交接

适用场景

  1. 01从外网安全访问 HAOS
  2. 02在不开放路由器端口时发布 HTTPS 地址
  3. 03配置反向代理的可信来源
  4. 04排查 Tunnel 连接及访问问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/caanio/agent-skills --skill haos-https-tunnel

安装后在 Claude Code 中输入/haos-https-tunnel确认已加载。

详细介绍

通过 Cloudflare Tunnel 为 HAOS 启用 HTTPS

为 HAOS 设备配置公开的 https://ha.<domain>，让你随时随地都能访问，无需开放路由器端口，也无需在客户端设备上安装任何东西。已于 2026-07-10 在 Raspberry Pi 4（HAOS 18.1、Core 2026.6.4）上使用 brenner-tobias/cloudflared 插件 v7.0.9 实测验证；§4 中适用于 ≥ 2026.8 的 UI 操作步骤遵循官方 http 集成页面。以下每个陷阱都是真实遇到的；⚠️ 表示陷阱。

0. 为什么选择这种方案（以及排除了哪些方案）

Tunnel = RPi 与 Cloudflare 建立一条出站的长连接；DNS 是指向 cfargotunnel.com 的 CNAME，永远不会指向你的家庭 IP。无需开放入站端口，动态 IP 也完全不是问题，TLS 使用 Tunnel 令牌在 Cloudflare 处终止。

已排除的替代方案（只有出现新情况时才重新建议）：

  • HA 原生 SSL（http: ssl_certificate）：会强制全局使用 HTTPS — 本地的 http://<ip>:8123 将无法使用，而且所有操作都会变慢。实际使用后很后悔。
  • DuckDNS + 端口转发 443：会将家庭 IP 和一个入站端口暴露给互联网。
  • Nabu Casa：可用，但需要按月付费。
  • Tailscale：每台客户端设备都需要安装应用。

1. 前提条件

  • 一个在用户 Cloudflare 账户中作为区域添加的域名。通过 Cloudflare Registrar 购买 → 区域会自动创建。从任何地方验证： dig +short NS <domain> → 应返回 *.ns.cloudflare.com 域名。
  • 按照 haos-addon-deploy §0/§8 通过 SSH 访问 HAOS 设备（⚠️ 非交互式的 ha CLI 调用需要使用 ssh ha 'bash -lc "…"'，否则会出现 unauthorized）。
  • ha = 指向 Advanced SSH & Web Terminal 插件的 SSH 别名，Protection 模式已关闭。
  • ⚠️ 你（Agent）可以完成以下所有操作，用户需要执行的步骤除外：Cloudflare 登录授权（§5），以及 Core ≥ 2026.8 时在 UI 中设置代理（§4）——请安排好交接。

2. 安装 cloudflared 插件

ssh ha 'bash -lc "ha store add https://github.com/brenner-tobias/ha-addons && ha store reload"'
ssh ha 'bash -lc "ha store repositories | grep -B2 -A4 -i brenner"'   # repo slug: 9074a9fa
ssh ha 'bash -lc "ha apps install 9074a9fa_cloudflared"'
  • ⚠️ 子命令是**ha store add <url>**。没有 add-repository；使用错误的 子命令不会报错，而是输出整个商店列表并以状态码 0 退出，因此请验证仓库是否 实际添加成功（ha store repositories），不要只看退出码。
  • 已安装插件的 slug 是 <repo-slug>_cloudflared，例如 9074a9fa_cloudflared。

3. 配置插件

只需设置一个选项 — 公开主机名：

echo '{"options":{"external_hostname":"ha.<domain>","additional_hosts":[]}}' \
  | ssh ha 'bash -lc "curl -sS -X POST -H \"Authorization: Bearer \$SUPERVISOR_TOKEN\" \
            -H \"Content-Type: application/json\" -d @- \
            http://supervisor/addons/9074a9fa_cloudflared/options"'

（或者在 HA UI 中使用插件的 Configuration 标签页。）保持 tunnel_token 未设置：§5 中的登录流程会创建 Tunnel。完成后，使用相同的 curl 命令，以普通 GET 请求 …/addons/9074a9fa_cloudflared/info，应能看到已设置的 external_hostname （haos-addon-deploy §4）。

4. 信任代理（首次启动前）

隧道流量会以反向代理请求的形式到达 HA；除非信任代理子网，否则 HA 会拒绝这些请求（或将所有请求都记录为代理的 IP，从而导致 IP 封禁失效）。设置位置取决于 Core 版本（ssh ha 'bash -lc "ha core info"'）：

Core ≥ 2026.8 — UI，由用户操作。 HTTP 服务器在 设置 → 系统 → 网络 中配置；保存后会重启 HA。请让用户设置： Trust X-Forwarded-For 开启；Trusted proxies 172.30.33.0/24（Supervisor docker 子网，加载项所在位置）；Enable IP banning 开启（现在有了公共端点——保持开启）；Login attempts before ban 3。所有 ≥ 2026.8 的设备（包括全新安装）都使用 UI——文档中提到的 YAML 导入仅是一次性升级步骤。用户确认四项设置已保存，且 HA 重启后恢复运行，即表示完成。

  • ⚠️ 跨版本升级到 2026.8 的设备会在首次启动时将旧的 http: 块导入 .storage/http，此后会忽略 YAML（修复方法：“HTTP YAML configuration is ignored after migration”）。编辑 configuration.yaml 不会产生任何效果；实际生效的值由 UI 管理。观察于 2026-08-15，Core 2026.8.1。

Core < 2026.8 — configuration.yaml。

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 172.30.33.0/24   # Supervisor docker subnet, where add-ons live
  ip_ban_enabled: true          # public endpoint now — keep this on
  login_attempts_threshold: 3
  • SSH 加载项中的文件位置：/config/configuration.yaml （/homeassistant/... 是同一卷的别名挂载）。
  • ⚠️ /config 由 root 拥有——在 SSH 加载项中使用 cp/sed 时需要 sudo。
  • 高风险配置编辑：先备份（sudo cp configuration.yaml configuration.yaml.bak-YYYYMMDD），再编辑，然后在执行 ha core restart 前运行 ha core check。不要跳过检查——损坏的 YAML 会导致 HA 无法启动。

5. 启动并授权（由用户操作）

ssh ha 'bash -lc "ha apps start 9074a9fa_cloudflared"'
ssh ha 'bash -lc "ha apps logs 9074a9fa_cloudflared"'

首次启动时不要设置 tunnel_token：日志会输出 Please open the following URL and log in with your Cloudflare account:，后面跟着 一个 https://dash.cloudflare.com/argotunnel?... 链接。将此 URL 交给用户——用户登录、选择区域并授权。随后 cloudflared 会下载证书、创建隧道，并自行创建 DNS CNAME。用户报告已完成授权，即表示此步骤完成；§6 会进行确认。

6. 验证

ssh ha 'bash -lc "ha apps logs 9074a9fa_cloudflared"' | grep -iE "registered|route|error"
# want: "Added CNAME ha.<domain> …" + 4× "Registered tunnel connection"
curl -s -o /dev/null -w "%{http_code} %{time_total}s\n" https://ha.<domain>/
# want: 200
  • ⚠️ 预检信息 UDP Connectivity … QUIC connection failed / degraded transport, will proceed using 'http2' 没有问题——有些网络会阻止出站 UDP 7844； http2 回退可正常工作。只有硬性失败才需要处理。
  • “Registered tunnel connection” 行中显示附近的边缘位置（例如 <iata>01） = 延迟良好；无需配置。

7. 设置完成后（告知用户）

  • 为 HA 账户启用 2FA——登录页面现在已暴露在公共互联网上。 IP 封禁和登录尝试阈值（§4）只是第二道防线，不能替代 2FA。
  • 配套应用：外部 URL → https://ha.<domain>；内部 URL → LAN 地址，仍可正常使用（http://<lan-ip>:8123）。
  • 立即进行完整的 HA 备份（配置刚刚更改过），并将备份从设备中取出—— scp ha:/backup/<file>.tar 比网页下载更好。如果用户对 /config 进行版本管理， 请排除 .storage/（身份验证令牌）和 secrets.yaml。

评论

支持 Markdown