コンテンツにスキップ

AIアプリケーションの認証と転送をRubyで制御する。

ngx_mrubyはnginxの処理をRubyで拡張するモジュールです。AIアプリケーションとモデルAPIの間に置き、利用者キーをRubyで確認し、モデル別の転送先と上流の認証情報を選ぶAIゲートウェイを構成できます。

ここでのAIアプリケーションは、チャットの画面からエージェントやMCPのホストまで、モデルAPIやMCPサーバーを呼び出すソフトウェア全般です。

下のv3開発版の例では、リクエストされたモデルに応じた振り分けを手元ですぐに試せます。MCPゲートウェイなどへの拡張は、後半のユースケースで設計状況とともに説明しています。

ユースケースを見る

  • nextでのtestの結果
  • nextでのnginx-testsの結果
  • masterとnextを毎晩valgrindの下で試すvalgrind-nightlyの結果
  • nextでのCodeQLの結果
  • nextでのzizmorの結果
  • OpenSSF Best Practices
  • MITライセンス

リクエストされたモデルで、転送先を変える

たとえば、チャットと文書要約で別のモデルを使う構成。アプリには共通のURLと利用者キーだけを設定し、リクエストで指定されたモデルから接続先を選びます。API用のキーを各アプリに配る必要はありません。下のボタンで、送信から応答までの違いを確かめられます。

通信しない表示例です。同じモックを下の手順で実行できます。キーはすべてデモ用です。
  1. アプリから送る

    チャットや要約のアプリは、モデルを変えても同じプロキシURLと利用者キーで送ります。

    POST http://localhost:8080/v1/responsesAuthorization: Bearer local-client{"model":"mock-model-a"}
  2. nginx内のRubyで選ぶ

    利用者キーを確認し、モデルから転送先とそのAPI用のキーを選びます。対応表は各アプリではなく、プロキシ側で一か所にまとめます。

    route.rb
    routes = {
    "mock-model-a" => ["local_api_a", "Bearer local-upstream-a"],
    "mock-model-b" => ["local_api_b", "Bearer local-upstream-b"]
    }
  3. API Aの応答を返す

    nginxがAPI用のキーで転送し、応答をアプリへ中継します。下のモックは転送先とキーの置換結果を返します。モデルの生成結果ではありません。

    local_api_aAuthorization: Bearer local-upstream-a
    200 · アプリに届く応答
    {
    "upstream":"a",
    "model":"mock-model-a",
    "credential_replaced":true
    }

利用者キーが不明なら401、対応表にないモデルなら403として、APIへ送る前に拒否します。API形式の変換はしません。アプリは接続するAPIに合ったパスと本文を送ります。Messages APIとResponses APIの中継や同時実行制限は、別の結合テストが確かめます。

認証・同時実行制限・ストリーム中継の詳細
別の結合テスト:同時実行制限とストリーム中継
Rubyハンドラagent_proxy_route.rb
r = Nginx::Request.new
v = Nginx::Var.new
routes = {
"mock-model-a" => ["agent_proxy_llm_a", "Bearer upstream-test-key-a"],
"mock-model-b" => ["agent_proxy_llm_b", "Bearer upstream-test-key-b"]
}
route = routes[JSON.parse(r.body)["model"]]
if route
v.agent_proxy_backend = route[0]
v.agent_proxy_upstream_auth = route[1]
Nginx.return Nginx::DECLINED
else
Nginx.return Nginx::HTTP_FORBIDDEN
end
検証結果を開く(mock)
test/html/agent_proxy_route.expected:ケースが比べる値
# What test/t/cases/agent_proxy.rb compares for routing by model: status,
# port of the upstream, Authorization and x-api-key at the upstream, and
# whether the upstream got the client's body unchanged.
model_a=200 12372 Bearer upstream-test-key-a none true
model_b=200 12373 Bearer upstream-test-key-b none true
unknown_model=403
nginx.confを開く
test/conf/conf.d/60-agent-proxy.conf
upstream agent_proxy_llm_a {
server 127.0.0.1:12372;
}
upstream agent_proxy_llm_b {
server 127.0.0.1:12373;
}
# Concurrent requests per client key: agent_proxy_auth.rb sets the key.
limit_conn_zone $agent_proxy_stream_key zone=agent_proxy_streams:1m;
server {
listen 18132;
# Declares the variables that the hooks assign; never requested.
location = /.agent-proxy-vars {
internal;
set $agent_proxy_key_id "";
set $agent_proxy_stream_key "";
set $agent_proxy_backend "";
set $agent_proxy_upstream_auth "";
return 404;
}
# Most variables stay unset on most requests (a rejected key, a
# request that no hook routed).
uninitialized_variable_warn off;
# The client key, checked for every request of this server before a
# location is chosen. A request without a known key gets 401, and the
# server-level error_page gives it a JSON body.
mruby_server_rewrite_handler build/nginx/html/agent_proxy_auth.rb;
error_page 401 @agent_proxy_401;
# The upstream gets the credential that agent_proxy_route.rb picked and
# never the client's.
proxy_http_version 1.1;
proxy_set_header Connection close;
proxy_set_header Authorization $agent_proxy_upstream_auth;
proxy_set_header x-api-key "";
proxy_buffering off;
# The Anthropic Messages API, and the OpenAI Responses API below with
# the same recipes.
location = /v1/messages {
# One request at a time per client key; a second one gets 429 from
# @agent_proxy_too_many. limit_conn_status is a status that no
# upstream sends, so that an upstream's own 429 passes unchanged.
limit_conn agent_proxy_streams 1;
limit_conn_status 460;
limit_conn_log_level notice;
error_page 460 = @agent_proxy_too_many;
# Picks the upstream block and the credential by the model of the
# JSON body.
mruby_enable_read_request_body on;
mruby_access_handler build/nginx/html/agent_proxy_route.rb;
# Logs $upstream_status after the response.
mruby_log_handler build/nginx/html/agent_proxy_log.rb;
proxy_pass http://$agent_proxy_backend/v1/messages;
}
# The zone of limit_conn is per client key, so a stream of a key on
# either location holds the slot of that key on both.
location = /v1/responses {
limit_conn agent_proxy_streams 1;
limit_conn_status 460;
limit_conn_log_level notice;
error_page 460 = @agent_proxy_too_many;
mruby_enable_read_request_body on;
mruby_access_handler build/nginx/html/agent_proxy_route.rb;
mruby_log_handler build/nginx/html/agent_proxy_log.rb;
proxy_pass http://$agent_proxy_backend/v1/responses;
}
# The proxy's own error bodies, in the error format of the API that the
# client asked for: a named location keeps the request's $uri.
location @agent_proxy_401 {
default_type application/json;
if ($uri = /v1/responses) {
return 401 '{"error":{"message":"invalid API key","type":"invalid_request_error","param":null,"code":null}}';
}
return 401 '{"type":"error","error":{"type":"authentication_error","message":"invalid API key"}}';
}
location @agent_proxy_too_many {
default_type application/json;
add_header retry-after 1 always;
if ($uri = /v1/responses) {
return 429 '{"error":{"message":"too many concurrent requests","type":"rate_limit_error","param":null,"code":null}}';
}
return 429 '{"type":"error","error":{"type":"rate_limit_error","message":"too many concurrent requests"}}';
}
}

CIが動くたびに、ケースのtest/t/cases/agent_proxy.rbがクライアントでリクエストを送り、クライアントが出力する値を、ここに載せた値と比べます。4個のファイルを最後に変えたのは、2026-10-29のコミット300e251cです。

APIキーなしで、手元で試す

Docker Compose、git、curlがあれば、図と同じnginxと2つのモックAPIを起動できます。プロバイダーのアカウントは不要です。初回はソースのダウンロードとビルドが必要で、テキスト生成は行いません。

ローカルで起動
git clone --branch next https://github.com/matsumotory/ngx_mruby.git
cd ngx_mruby/examples/start
docker compose up --build --wait

起動が完了したら、同じディレクトリでリクエストを送ります。

起動後にリクエストを送る
curl -K client.conf -d '{"model": "mock-model-a"}'
期待する応答
{
"upstream":"a",
"model":"mock-model-a",
"credential_replaced":true
}

応答から、API Aへの転送と上流の認証情報への置換を確認できます。

route.rbの対応表を編集すれば、同じリクエストの転送先を変えられます。編集から再確認、終了までの手順は、実行例で説明します。

実行と編集の手順へ

アプリに組み込む

アプリは、AIゲートウェイのうちモデルAPIを中継するプロキシへ、HTTPリクエストを送ります。プロキシではnginx.confに転送先とHTTPの設定を、route.rbに利用者キーの確認とモデルの対応表を書きます。Rubyが選んだ転送先とキーをnginxの変数に渡し、proxy_passとproxy_set_headerで中継します。

実際のAPIへ接続する際は、そのAPIのパス、認証方式、TLSなどの接続設定を合わせて検証します。このローカル例だけで実プロバイダーとの互換性を確認したことにはなりません。公開サービスでは別途、認証情報と運用設定を用意してください。

実装済みの構成と制約を読む

HTTPとTCPの判断も、Rubyで書く

リクエストヘッダで転送先を選ぶ

リクエストヘッダと対応表から転送先を選び、サービスごとの振り分けを実装します。

HTTPの設定と実行例

接続元を確認しTCPを中継する

接続元のアドレスを許可表と照合し、バックエンドへ接続する前に許可・拒否を決めます。

TCPの設定と実行例

今後のユースケースと設計状況

モデル振り分けの実行例は手元で動かせます。以下は、MCPの認可、モデルAPIの切替、サイトへのアクセス制御に向けた設計です。次に何を検索し、どこを読み取るかをモデルが選ぶAIアプリケーションを、ここではエージェントと呼びます。

「設計中」は実行例と検証条件を示し、「構想」は用途の方向性を示します。どちらも、用途全体を動かすテストはまだありません。必要な機能と制約の詳細は、各項目の設計文書で確認できます。

MCPツールの呼び出し権限を確認する

設計中

ユーザーごとにMCPツールと引数を制限する設計です。Rubyで認証済みユーザーの権限とtools/callの内容を照合し、許可した呼び出しをMCPサーバーへ転送します。

個々のデータへのアクセス権限は、転送先のMCPサーバーでも検証する方針です。

設計と必要な機能を読む

MCP呼び出しの集中を制限する

構想

AIアプリケーションによる短時間の呼び出しや、多数のストリームで生じる負荷を制限する構想です。Rubyでユーザーと呼び出しの種類を識別し、nginxのlimit_reqとlimit_connで上限を適用します。

必要な読み直しは許可します。制限を受けたアプリには、再試行できる条件を返す方針です。

設計と必要な機能を読む

AIアプリケーション別にMCPツールを出す

設計中

異なるツール構成を必要とするAIアプリケーションから、同じMCPサービスを利用する設計です。接続プロファイルに応じて、MCPゲートウェイが転送先のMCPサーバーを選びます。

ツールの一覧と呼び出し方の違いは、バージョンを付けた転送先で扱います。検索や取得の処理は、アプリ間で共用する方針です。

設計と必要な機能を読む

文書を必要な範囲から取得する

設計中

エージェントが長い文書の必要な箇所をMCPツールで取得し、足りなければ読み足せるようにする設計です。MCPゲートウェイは取得方式と処理量の上限を選びます。

文書の位置、バージョン、続きの取得はバックエンドが管理します。JSONやストリームを切り詰めず、範囲指定に対応する取得機能を使う構成を検討しています。

設計と必要な機能を読む

検索結果がない場合の次の手順を伝える

構想

検索結果がない場合や取得に失敗した場合に、理由と次の手順をエージェントへ返す構想です。MCPゲートウェイは該当なし、権限不足、取得先の障害を区別して中継します。

検索対象に固有の手掛かりはMCPサービスが提供します。文書中の指示を実行の指示として扱わず、検索を続けるか条件を変えるかはエージェントが判断する方針です。

設計と必要な機能を読む

MCPツールの呼び出し順序を観測する

構想

MCPサービスの運用者が、検索、文書取得、再検索の順序と結果を調べる構想です。相関IDで呼び出しを関連付け、ツール名、成否、所要時間を記録します。

検索語や文書本文は標準では収集せず、保存期間と収集量に上限を設けます。調査を続けるかはエージェントが判断します。

設計と必要な機能を読む

モデルAPIのエラーで転送先を変える

設計中

モデルAPIの切替をAIゲートウェイで管理する設計です。上流の429などの再送対象エラーに応じ、Rubyが互換性のある転送先と認証情報を選び、nginxが再送します。

再送は安全に再実行できるリクエストに限り、回数と時間を制限します。応答を送り始めた後は、別の生成結果につなぎ替えない構成を検討しています。

設計と必要な機能を読む

AIクローラーとエージェントの頻度を絞る

構想

WebサイトやAPIへのアクセス規則をRubyで選ぶ構想です。AIクローラーの巡回とユーザーの指示によるアクセスを区別し、頻度と同時接続数を制限します。

User-Agentの自己申告だけを身元の証明とせず、署名などの検証方法と、識別できない相手の扱いを定める方針です。

設計と必要な機能を読む

外部のセマンティックキャッシュを参照する

構想

似たリクエストに保存済みの回答を再利用し、アプリの処理を変えずにモデルAPIへの問い合わせを減らす構想です。AIゲートウェイがアクセス範囲やモデルの条件を渡し、外部サービスが再利用の可否を判断します。

一致がない場合、判断が曖昧な場合、タイムアウト時は元のモデルAPIへ転送します。回答をキャッシュに保存する方式は未設計です。

設計と必要な機能を読む

log handlerで記録した値を外部へ送る

構想

サービスの運用者が、ステータス、応答時間、転送先を外部の集計基盤で確認する構想です。現在のlog handlerはネットワーク応答を待てないため、上限付きのワーカーキューとタイマーで送信する処理を計画しています。

収集先の遅延で応答を止めないよう、ノンブロッキングな通信を使います。キューの満杯時や送信失敗時の扱いも定めます。

設計と必要な機能を読む

実装と設計のドキュメント