Caddy を前に置いて HTTPS 化する 完成

このガイドで作るもの

Caddy をリバースプロキシとして MAESTRO の前に置き、Cloudflare の DNS を使って Let's Encrypt からワイルドカード証明書を取ります。証明書の取得も 60 日ごとの更新も Caddy が自分でやるので、 運用中に手を入れる作業は残りません。

前提

• Docker Compose で MAESTRO を動かしていること。Compose は v2.24 以上（docker compose version で確認）。
• 使いたいドメインの DNS を Cloudflare が管理していること（ネームサーバーが Cloudflare を向いている）。
• そのドメインの名前が公開 DNS から引けること。手元の DNS サーバーだけで解決している名前では発行できません。

証明書はドメイン単位で取ります。手元の機械が外から見えている必要はありません。 maestro.example.com の A レコードを 10.0.0.10 のような内側のアドレスに向ける使い方で問題ありません。

ステップ 1 — Cloudflare の API トークンを作る

Cloudflare のダッシュボードで My Profile → API Tokens → Create Token を開き、 Custom token を選んで次のとおり作ります。

ステップ 2 — DNS レコードを置く

Cloudflare の DNS 設定に、MAESTRO を出したいホスト名の A レコードを追加します。

ステップ 3 — 設定ファイルを用意する

リポジトリのルートで見本をコピーし、値を埋めます。

cp .env.caddy.example .env.caddy

ワイルドカードが覆うのは 1 階層分だけです。maestro.home.example.com を使いたいなら MAESTRO_BASE_DOMAIN=home.example.com（証明書は *.home.example.com）にします。

ステップ 4 — config.yaml をホスト側に置く（起動より先）

次のステップで config.yaml を書き換えます。その前に、設定ファイルがホスト側に残る形にしておく必要があります。 Docker の既定では config.yaml はイメージの中にあり、どのボリュームにも入っていません。 重ねがけを始めた最初の起動で MAESTRO のコンテナが作り直されるので、コンテナの中で書いた設定はそこで消えます。

4-1. 上書きファイル側の指定（確認だけ・作業なし）

docker-compose.caddy.yml には、設定ファイルをホストに置くための指定がすでに入っています。書き足す作業はありません。

services:
  maestro:
    volumes:
      - ./config.yaml:/app/config.yaml

リポジトリのルートの config.yaml がコンテナの中の設定ファイルになります。 以降は設定画面からの保存も、手で書いた変更も、コンテナを作り直しても残ります。 :ro は付けないでください（設定画面からの保存が書き込むため）。

4-2. ホスト側の config.yaml を用意する

すでに MAESTRO を動かしている場合 — 重ねる前に、動いているコンテナから取り出します。

docker cp maestro:/app/config.yaml ./config.yaml

これから始める場合 — イメージが同梱する初期状態と同じ 1 行だけのファイルを作ります。

printf 'config_version: 2\n' > ./config.yaml

持ち主と書き込み権限 — コンテナの中の MAESTRO は root ではなく node（UID 1000）で動くので、 ホスト側のファイルはその UID から書ける状態にしておきます。上の 2 通りはどちらも、 実行した人の持ち物になります。ホストの利用者が UID 1000 でないなら、所有者を合わせてください。

sudo chown 1000:1000 ./config.yaml

食い違ったままだと、すでに動いている環境では設定画面からの保存が静かに失敗します（起動は通るので気づきにくい）。 新規インストールでは起動を拒否し、書き込めない旨を名指しするメッセージが出ます。

配布用のドキュメントとの食い違いについて — 配布版の docs/docker.md（この repo では oss/overlay/docs/docker.md）には cp config.yaml.example config.yaml で作る案内がありますが、そちらは完成済みの見本なので、 インストール済みと判定されてセットアップウィザードが出ません（さらに、動いていない localhost の LLM を指した状態になります）。 イメージが同梱する初期状態は 1 行だけのファイルなので、ここに書いたほうに従ってください。

どちらの場合も、この先の編集はすべてこの、ホスト側の config.yaml に対して行います。 コンテナの中に入って書く必要はありません。

ステップ 5 — MAESTRO 側の設定を 2 か所直す

ステップ4で用意したホスト側の config.yaml を編集します。 この 2 つを外すと、動かないか、危ない状態になります。

5-1. MAESTRO 自身の TLS は切る

Caddy が TLS を終端するので、MAESTRO 側でも終端すると二重になって噛み合いません。 config.yaml の server.tls ブロックを書かないか、enabled: false にします。

# config.yaml — プロキシ構成では server ブロックごと省くのが確実
# server:
#   tls:
#     enabled: false

Docker のイメージが同梱する初期 config.yaml には server ブロックが入っていないため、 Docker で始めた環境は既定で TLS が切れています。自分で有効にした覚えがなければ、この項目の作業は不要です。

5-2. 安全なクッキーを有効にする

auth.secure_cookie: true にします。効き目は 2 つです。

auth:
  secure_cookie: true

この締め出しは、メールとパスワードでログインする構成のときに起きます（OAuth だけの環境には、この制限そのものがありません）。 なお この設定が無くても HTTPS 越しのログイン自体は通ります。プロトコルによって行き先が変わるリダイレクトは MAESTRO のコードにありません。 「入れないと繋がらない」ではなく「入れないと、全員が道連れで締め出される」と考えてください。

ステップ 6 — 起動する

6-1. 2 つのファイルを既定にする（推奨）

先に .env（.env.caddy ではありません）に次の 1 行を足してください。 以降は docker compose のどのコマンドでも 2 つのファイルが読まれます。

COMPOSE_FILE=docker-compose.yml:docker-compose.caddy.yml

COMPOSE_FILE は .env に書いて構いません。ステップ3で「トークンは .env に書くな」と書いたのは、 .env が MAESTRO のコンテナの環境変数として読み込まれ、エージェントから読めてしまうからです。 COMPOSE_FILE は秘密ではなく、Compose 自身がどのファイルを読むかの指定なので、読まれても実害がありません。
（COMPOSE_FILE は Compose の実行時に解釈されるため、.env に置く必要があります。.env.caddy に書いても効きません。）

6-2. 起動する

docker compose -f docker-compose.yml -f docker-compose.caddy.yml up -d --build

（6-1 を設定済みなら docker compose up -d --build だけで同じです。）

初回は Caddy のイメージをビルドします。公式の配布物には Cloudflare の DNS 対応が入っていないため、 xcaddy で組み込んだものを作ります（deploy/caddy/Dockerfile）。数分かかりますが、初回だけです。

ログで発行を確認します。

docker compose -f docker-compose.yml -f docker-compose.caddy.yml logs -f caddy

certificate obtained successfully が出れば取れています。 あとは https://maestro.example.com を開くだけです。

何が変わったか

ポートを閉じているのは docker-compose.caddy.yml の ports: !reset [] という 1 行です。 Compose の profiles ではこれができません。ports は {ip, target, published, protocol} を一意キーとして追記されるだけで、 元のファイルが書いた公開を取り消す手段が無いためです。 重ねたファイルから元の値を消すには !reset を使います（!override [] と書いても同じ結果になります）。

ゲートウェイ（AAO Gateway）も HTTPS で出す場合

ゲートウェイを使っていないなら、この節は読み飛ばして構いません。

ゲートウェイ（この MAESTRO 自身を OpenAI 互換の中継口として公開する仕組み）は、 MAESTRO 本体とは別のポートで待ち受けます。同じプロセスで動かしていても口は別です（既定 4000）。 プロキシを通すなら、そちら向けの設定も要ります。

1. Cloudflare に gateway の A レコードを追加する（ステップ2と同じ要領。同じアドレスでよい）。
2. .env.caddy の GATEWAY_HOSTNAME のコメントを外して値を入れる。コメントを外したら必ず値を書くこと（等号だけの空の行は、Caddy を起動しなくします）。
3. config.yaml の gateway.listen_port を既定（4000）から変えている場合だけ、GATEWAY_UPSTREAM_PORT のコメントを外して同じ値を書く。既定のままならコメントアウトのままにする（外して空にすると、黙って 80 番へ中継されます）。
4. 再起動する（up -d をもう一度）。

証明書は本体と同じワイルドカード 1 枚で覆われるので、追加の発行はありません。

よくある詰まり

手動で組む場合（Docker を使わない）

Docker を使わず、ホストに直接 Caddy を入れる場合も考え方は同じです。違いは 2 点だけです。

1. Caddy を自分でビルドする。公式の配布物には Cloudflare 対応が入っていません。 xcaddy build --with github.com/caddy-dns/cloudflare で作るか、 公式のダウンロードページで caddy-dns/cloudflare を選んで取得します。
2. 中継先をコンテナ名からホストの口に変える。deploy/caddy/Caddyfile の reverse_proxy maestro:9876 を reverse_proxy 127.0.0.1:9876 にします。 合わせて MAESTRO 側は HOST=127.0.0.1 で起動し、外から直接届かないようにします。

環境変数（CLOUDFLARE_API_TOKEN など）は、systemd で動かすなら systemctl edit caddy で Environment= として渡します。Caddyfile に直接書かないでください。 ステップ5 の MAESTRO 側の設定（TLS を切る・安全なクッキー）は Docker の場合と同じです。 ステップ4（config.yaml をホスト側に置く）は不要です。Docker を使わない構成では設定ファイルは最初からホストにあり、消えません。

関連ファイル