Flutter アプリの AI を VPS プロキシ経由にした理由と実装
Flutter アプリから AI API を直接呼ばず、VPS プロキシへ分ける構成。API キー、認証、ゲスト用の分離セッション。
Flutter アプリに AI 機能を追加するとき、最短の実装はクライアントから AI API を直接呼び出すことです。Angla ではその方法を採らず、VPS 上の Node.js / Express プロキシ経由で Gemini を呼ぶ構成にしています。
更新(2026-10-05): 2026年8月9日に本番の AI プロバイダーを Groq から Gemini へ移行しました。現在も Gemini を使っています。この記事では Gemini を組み込んだ経路を説明し、アプリから自前プロキシを経由させる境界は継続しています。
理由の中心は、API キーをアプリの配布物に含めないことです。クライアントで隠したつもりでも、アプリはユーザーの端末で動きます。難読化は解析の手間を上げることはあっても、そこに含まれる秘密をサーバーと同じようには守れません。
API キーはサーバーだけに置き、アプリは自前 API を呼ぶ。
クライアントへキーを置かない理由
モバイルアプリのバイナリや Web アプリの JavaScript は、利用者の端末に配信されます。キーをコードに直書きしたり、ビルド時の設定値として埋め込んだりすれば、配布物や通信を調べて値が取り出される可能性があります。キーが第三者に使われれば、想定しないリクエストや利用料金につながります。
もう一つは、利用制御を置く場所です。クライアントが AI プロバイダーを直接呼ぶと、モデルやプロンプトを変えるたびにアプリを更新する必要があり、利用回数や認証の扱いも各クライアントへ分散します。VPS のプロキシに寄せれば、プロバイダーとの接続情報をサーバー側に閉じ、アプリ向けの API を維持したまま実装を変更できます。
これは「プロキシを置けば安全」という意味ではありません。プロキシ自体の認証、レート制限、入力の扱い、ログへの記録、障害時の挙動を設計する必要があります。鍵をクライアントから移すのは、守る境界をサーバー側に作るための最初の一歩です。
Angla でのリクエストの流れ
大まかな流れは次の通りです。
- アプリが釣り場の天気など、アドバイスに使う情報を用意する
- アプリから Angla の VPS プロキシへリクエストを送る
- プロキシがリクエストを認証・制御して Gemini を呼ぶ
- プロキシが生成結果を受け取り、アプリへ返す
アプリが知る必要があるのは Angla の API の使い方です。Gemini の認証情報はサーバー環境に置き、リクエストで使う鍵をクライアントに返しません。外部プロバイダーとアプリの間に自分が管理する境界を置くことで、プロバイダーを変更するときにもアプリ側の責務を増やさずに済みます。
プロキシは、たとえば /api/fishing-advice のような目的別のエンドポイントとして用意しています。クライアントから汎用のプロンプトを何でも送れる形にするのではなく、アプリ機能に必要なリクエストをサーバー側で扱う方が、入力や利用条件を管理しやすくなります。
認証と利用回数をサーバーで扱う
API キーを隠しても、エンドポイントが誰でも無制限に使える状態なら、別の問題が残ります。Angla では Supabase のユーザー JWT をプロキシ側で検証し、呼び出し回数にも制限を設けています。上限の扱いは運用しながら調整しており、成功したリクエストだけ消費するなど、利用者が失敗を重ねたときの挙動も確認しています。
認証をクライアントだけで済ませるのではなく、サーバーが受け取ったトークンを検証してからプロバイダーを呼ぶことが重要です。クライアントの画面でボタンを隠しても、API リクエストは直接送れてしまうためです。
ゲスト利用では既存セッションを分離する
ログイン前に AI を少し試せるよう、ゲスト向けの経路も用意しました。ここで気をつけたのは、Angla の通常ログイン状態と匿名利用を混ぜないことです。お気に入り同期などで使うメインの Supabase クライアントを匿名サインインに流用すると、現在のセッションが予期せず切り替わる可能性があります。
そこで AI 用の Supabase クライアントを分け、匿名トークンの取得に限定して使います。そのトークンをプロキシへ送り、サーバーが認証した上で AI 呼び出しを処理します。ゲスト側は利用を抑えるため、回答形式や利用できる範囲にも制限を設けています。大切なのは匿名機能を足すことより、どの状態を変更し、どの権限を持たせるのかを狭く決めることでした。
プロバイダーを替えられることの意味
本番の AI プロバイダーは運用中に切り替えており、2026年8月9日に Groq から Gemini へ移行しました。2026年10月5日時点でも Gemini を使っています。プロバイダーを切り替える際、アプリが直接外部 API を呼んでいたら、配布アプリ側の変更とストア更新も必要になります。サーバー側のプロキシに呼び出しを集めていると、アプリとプロバイダーの結合を弱められます。今回の履歴が示すのは、切り替えが無条件に簡単ということではなく、アプリのクライアント契約を保ったままサーバー側を変更できたことです。
ただし、モデルを替えれば何もかも同じ結果になるわけではありません。応答形式、失敗時の扱い、待ち時間や利用条件は確かめる必要があります。境界を分ける設計は、差し替えを無条件に簡単にする魔法ではなく、変更の影響範囲をサーバー側に寄せる手段です。
公開時に守る運用ルール
- API キーやトークンの値はクライアントへ含めない
- 本番の認証情報はサーバー側の環境変数で管理し、リポジトリに入れない
- リクエスト本文や認証情報を不用意にログへ残さない
- エンドポイント側でも JWT 検証と利用制限を行う
- ゲスト利用は通常のログイン状態から分離する
プロキシは、クライアントへ秘密を配らないためだけの中継サーバーではありません。認証、利用制限、外部サービスの切り替え、障害の切り分けをまとめる境界です。Angla 全体の構成は公開までの全体像、日次ジョブの運用はGitHub Actions から VPS cron へ移した話にまとめています。
API が失敗したときの切り分け
AI 機能でエラーが出ても、原因がモデルだけとは限りません。アプリからプロキシへ届いているか、認証トークンが有効か、VPS から外部 API に接続できるか、返ってきた形式をアプリが扱えるかを順に分けます。プロキシのログへリクエスト本文やキーをそのまま残すと、調査ログが新たな漏えい経路になるため、必要な状態だけを記録する設計にします。
プロバイダー側の障害時には、利用者へ返すエラーも考えます。原因を特定する情報は運用者のログに残しつつ、アプリには過剰な内部情報を返しません。課金や回数制限に関わる処理は、リトライのたびに二重消費しないかも確認します。こうした運用の境界を持つことが、単に API キーを隠す以上にプロキシを置く理由になります。
プロキシを挟む分、アプリから外部 API への直接呼び出しより通信の段数は増えます。認証や利用制限のための処理時間も加わるため、ユーザーが待つ画面ではタイムアウトやローディング表示も確認します。応答が遅いときに、アプリから VPS までなのか、VPS からプロバイダーまでなのかを分けて調べられるよう、秘密を含めない範囲で処理段階を記録しておくと切り分けやすくなります。
プロキシは、新しいサーバーを保守するコストとの交換です。利用者がいない試作であれば、外部 API を呼ばないモックから始める方法もあります。一方、公開アプリに課金される API キーを配るなら、最初からサーバー側に境界を置く方が、後から全クライアントを更新して鍵を取り替えるより扱いやすいと判断しました。