llmgateway を自ホストする前に読む、AGPLv3 と ee ディレクトリの境界線

プロバイダごとに散らばるキーと利用量を 1 つの入口にまとめる

LLM を使うアプリケーションが増えると、プロバイダごとに API キーが増え、どのモデルにいくら使ったかが請求書を突き合わせないと分からなくなる。llmgateway はこの中間に立つミドルウェアで、README は役割として「Route requests to multiple LLM providers」「Manage API keys for different providers in one place」「Track token usage and costs」の 3 点を挙げている。対象は OpenAI、Anthropic、Google Vertex AI など複数のプロバイダを併用している開発チームで、アプリ側のコードをプロバイダごとに書き分けたくない場合に効く。提供形態はホスト版と自ホスト版の 2 通りがあり、データと設定を自分の管理下に置きたいなら後者を選ぶことになる。

OpenAI 互換の入口と、apps/ 配下に分かれた実行単位

利用側から見た仕組みは単純で、OpenAI の chat completions と同じ形のリクエストをゲートウェイに投げ、ゲートウェイが実際のプロバイダへ転送する。README の例では `https://api.llmgateway.io/v1/chat/completions` に `model` と `messages` を渡し、`Authorization: Bearer $LLM_GATEWAY_API_KEY` で認証する。既存コードの base URL を差し替えるだけで移行できる、というのが「Compatible with the OpenAI API format」の意味である。リポジトリ側の構成はモノレポで、`apps/gateway` が LLM リクエストのルーティングを担い、`apps/api` が Hono のバックエンド、`apps/ui` が Next.js のダッシュボード、`packages/db` が Drizzle ORM のスキーマとマイグレーション、`packages/models` がモデルとプロバイダの定義を持つ。つまりルーティング、管理画面、永続化が別プロセスに分かれており、Docker の公開ポートも 3002 から 4002 まで複数用意されているのはこのためだ。

自ホストは named volume で立ち上げる

最短の手順は同梱スクリプトで、README は 2 つのシークレットを生成してから実行する形を示している。`export LLM_GATEWAY_SECRET="$(openssl rand -base64 32 | tr -d '\n')"` と `export GATEWAY_API_KEY_HASH_SECRET="$(openssl rand -base64 32 | tr -d '\n')"` を設定し、`./scripts/run-unified-container.sh` を叩く。docker run を直接使う場合は、`llmgateway_postgres` と `llmgateway_redis` という named volume を作り、`-v llmgateway_postgres:/var/lib/postgresql/data` と `-v llmgateway_redis:/var/lib/redis` でマウントする。イメージは `ghcr.io/theopenco/llmgateway-unified:latest`、環境変数は `AUTH_SECRET` と `GATEWAY_API_KEY_HASH_SECRET` に渡す。ここで README が明示的に警告しているのが、`/var/lib/postgresql/data` にホストディレクトリを bind-mount してはいけないという点である。コンテナ内の PostgreSQL が初期化時にそのディレクトリのパーミッションを設定する必要があり、ホストのファイルシステムと所有権によっては失敗する。開発用のセットアップは別系統で、`pnpm i && pnpm run setup` が依存の導入、Docker サービスの起動、DB スキーマの同期、初期データの投入までを行う。WSL2 では Docker Desktop の WSL 統合を有効にしておく必要がある。

30 日という保持期間と、ee/ に線引きされた機能

ライセンスは二重構造になっている。コア機能は AGPLv3、`ee/` ディレクトリの商用機能はエンタープライズライセンスで、複数組織の管理にはホワイトラベルライセンスが要ると README は説明する。エンタープライズ側に列挙されているのは、高度な課金とサブスクリプション管理、保持期間の延長（無制限か 30 日か）、カスタムプロバイダキー設定、チームと組織の管理、優先サポートなどである。実務上いちばん効くのは保持期間の差だろう。30 日を超えてリクエスト履歴を残したい、あるいは組織をまたいだ管理をしたいなら、AGPLv3 のままでは足りない可能性が高い。逆に単一組織で直近の利用量とコストを見るだけなら、コアの範囲で目的は満たせる。ライセンスの解釈は用途によって変わるため、導入前に LICENSE と ee/LICENSE の原文を確認し、必要なら法務に相談する形が安全である。なお、リポジトリのライセンス表記は NOASSERTION と検出されており、自動判定だけでは二重ライセンスの内容までは分からない。

向かないケースと、LiteLLM という対抗軸

ゲートウェイを挟むという判断自体がコストになる。プロバイダが 1 つだけで、キー管理もコスト集計もそのプロバイダのダッシュボードで足りるなら、llmgateway を自ホストする理由は薄い。PostgreSQL と Redis を抱え、複数ポートを公開し、アップグレードのたびにスキーマのマイグレーションを追うことになる。また、レイテンシに敏感な経路でプロバイダを 1 つしか使わない場合、間に 1 ホップ増える分の遅延は純粋な追加コストになる。代替としては LiteLLM が挙げられる。Python で書かれた同種のプロキシで、YAML の設定ファイルにモデルとプロバイダを列挙して `litellm --config config.yaml` のように起動する構成をとる。llmgateway が TypeScript のモノレポとして Next.js のダッシュボードや組織管理まで自前で持つのに対し、LiteLLM は設定ファイル中心でルーティングとフォールバックに寄っている。既に Python の運用基盤があり、管理画面よりも設定の宣言性を重視するなら LiteLLM、Node/TypeScript のスタックに揃えたいなら llmgateway という分け方が素直だ。

アップグレードと運用で見ておく場所

リリースは v1.14.0、v1.15.0、v1.16.0 とほぼ週次の間隔で並んでおり、更新の頻度は高い。`packages/db` が Drizzle ORM のスキーマとマイグレーションを管理しているため、イメージを更新するときは DB のマイグレーションが同時に走る前提で考える必要がある。`pnpm run setup` がスキーマ同期とシードを行うのは開発環境の話で、本番の更新手順が README に書かれているわけではない。ここは記述が薄い部分で、実際に運用するならリリースノートとマイグレーションの内容を追う作業が発生すると考えておいたほうがよい。監視の観点では、`apps/gateway` がルーティング、`apps/api` が管理系という分離を踏まえ、どちらのポートが落ちているのかを切り分けられるようにしておくと復旧が早い。AGPLv3 である以上、改変したものをネットワーク越しに提供する場合はソースの開示義務が生じる点も、社内利用か外部提供かで判断が変わる。

編集部の結論

OpenAI 互換のエンドポイントを維持したまま複数プロバイダのキーと利用量を 1 か所に集約したいチームには候補になる。ただし ee/ 配下の機能と複数組織の管理は商用ライセンスの対象なので、必要な機能が AGPLv3 側にあるかを先に確かめたい。最初に確認するのは LICENSE と ee/LICENSE の記述、そして自ホスト時に /var/lib/postgresql/data をホストディレクトリに bind-mount していないか、この 2 点である。

公式情報源

1. Issues
2. Project website
3. README
4. Releases
5. theopenco/llmgateway on GitHub