haos-https-tunnel

Cloudflare Tunnel 経由で HAOS に HTTPS を設定する

HAOS のボックスに、ルーターのポートを開放したり、クライアントデバイスに何かをインストールしたりせずに、どこからでも使える公開 https://ha.<domain> を設定します。Raspberry Pi 4（HAOS 18.1、Core 2026.6.4）と brenner-tobias/cloudflared アドオン v7.0.9 で 2026-07-10 に実機検証済みです。§4 の ≥ 2026.8 UI の手順は、公式の http 統合ページに従っています。以下の落とし穴はすべて実際に遭遇したものです。⚠️ は特に注意してください。

0. この方法を選ぶ理由（および却下した方法）

トンネルでは、RPi が Cloudflare へのアウトバウンドの長時間接続を確立します。DNS は cfargotunnel.com への CNAME であり、自宅の IP アドレスを公開することはありません。インバウンドポートは不要で、動的 IP アドレスも問題にならず、TLS はトンネルトークンを使って 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 に従った HAOS ボックスへの SSH アクセス（⚠️ 非対話型の ha CLI 呼び出しには ssh ha 'bash -lc "…"' が必要です。そうしないと unauthorized になります）。
• ha = Advanced SSH & Web Terminal アドオンへの SSH エイリアス。Protection モードはオフにします。
• ⚠️ あなた（エージェント）は、以下のうちユーザーが行う手順以外をすべて実行できます。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 で確認してください。
• インストールされたアドオンのスラッグは <repo-slug>_cloudflared です。例：9074a9fa_cloudflared。

3. アドオンを設定する

必要なオプションは公開ホスト名 1 つだけです。

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 のログインフローでトンネルを作成します。…/addons/9074a9fa_cloudflared/info に対してプレーンな GET を実行した場合と同じ curl で external_hostname が設定されていることを確認できれば完了です（haos-addon-deploy §4）。

4. プロキシを信頼する（初回起動前）

トンネルのトラフィックはリバースプロキシ経由のリクエストとして HA に届きます。プロキシのサブネットが信頼されていないと、HA はリクエストを拒否するか、すべてのアクセスについてプロキシの IP を記録します（IP ban が機能しなくなります）。設定場所は 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。新規インストールを含め、Core ≥ 2026.8 のすべての環境では UI を使用してください。ドキュメントで説明されている YAML のインポートは、一度限りのアップグレード手順としてのみ使用します。ユーザーが4つの値を保存し、再起動後に HA が復帰したことを確認したら完了です。

• ⚠️ 2026.8 をまたいでアップグレードした環境では、初回起動時に古い http: ブロックが .storage/http にインポートされ、それ以降 YAML は無視されます（修正方法：「移行後は HTTP YAML 設定が無視される」）。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 ban とログイン試行回数のしきい値（§4）は第2の防御策であり、2FA の代わりにはなりません。
• コンパニオンアプリ：外部 URL → https://ha.<domain>、内部 URL → LAN アドレス。こちらは引き続き使用できます（http://<lan-ip>:8123）。
• 今すぐ HA の完全バックアップを作成し（設定を変更したばかりです）、環境外に取り出してください。Web からダウンロードするより scp ha:/backup/<file>.tar をおすすめします。ユーザーが /config をバージョン管理する場合は、.storage/（認証トークン）と secrets.yaml を除外してください。