Sub2API導入ガイド：AI APIプロキシサーバーを構築する

公開日：2026-05-08

Sub2APIをサーバーへ導入し、初期設定を行い、利用者向けのベースURLとAPIキーを発行する手順です。

ショートバージョン

独自の使用可能な APIプロキシを実行したい場合は、多くの場合、Sub2API などのオープンソースプロジェクトで十分です。中心的なフローは単純です。Linux サーバーを準備し、サービスをデプロイし、データベースと管理者アカウントを初期化し、ユーザーに外部 Base URL と API Key を付与します。

最適なユースケース

Sub2API は、次のことを行う人に適しています。

複数の上流アカウントを 1 か所で管理
チームメンバーに統一APIキーを発行する
トップアップ、権限、転送ルール自体を制御する
より複雑なプラットフォームにコミットする前に、使用可能なプライベートプロキシを実行する

インターフェイスを一時的にテストするだけの場合は、デモ環境を使用してフローを理解できます。実際に使用する場合は、やはり自己展開の方が良い選択です。

導入前

まず次の 3 つを準備します。

Linux クラウドサーバー (できれば AMD64 または ARM64)
PostgreSQL と Redis、または両方を含む Docker Compose セットアップ
サーバーに解決されるドメイン。証明書を追加して管理パネルに簡単にアクセスできます。

Nginx 経由でリバースプロキシを計画している場合は、http ブロックで underscores_in_headers on; を有効にします。そうしないと、ヘッダーがドロップされるため、一部のマルチアカウントシナリオが失敗する可能性があります。

推奨される導入方法

Sub2API ドキュメントでは通常、次の 2 つのデプロイメントパスが示されています。

ワンクリックインストールスクリプト: すぐにオンラインに接続するのに適しています。スクリプトはバイナリをダウンロードし、サービスを作成し、ディレクトリ構造を初期化します。
Docker Compose: データディレクトリ、移行、バックアップをより明確に制御したい場合に適しています。

最初のデプロイメントでは、通常、Docker を選択する方が簡単です。運用スタイルの systemd 管理を希望する場合は、インストールスクリプトも便利です。

オプション 1: Docker のデプロイメント

大まかな流れは次のとおりです。

mkdir -p sub2api-deploy && cd sub2api-deploy
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash
docker compose up -d

通常、スクリプトは以下を準備します。

docker-compose.local.yml
.env
セキュリティキー
ローカルデータディレクトリ

また、セットアップ全体をまとめてパッケージ化できるため、将来のサーバー移行も容易になります。

実行時ログを検査するには:

docker compose logs -f sub2api

オプション 2: スクリプトをインストールする

直接の systemd サービスを希望する場合は、公式のワンクリックインストールスクリプトを使用してください。プログラムをサーバーにインストールし、サービスを作成し、初期化ウィザードを開始します。

curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bash

インストール後、通常、http://server-ip:8080 で初期化ページが利用可能になります。続けて、データベース、Redis、および管理者アカウントを構成します。

初期化時に確認すること

セットアップパネルで、次のことを確認します。

データベース接続は機能します
Redis は正常です
管理者アカウントが作成されました
ポートは外部に開いています
ドメインとリバースプロキシはすでに接続されています

他の人がサービスを使用する場合は、初期化時に管理者ユーザーと一般ユーザーの境界を定義します。後でこれを再設計するのははるかに面倒です。

ユーザーにアクセスを許可する

パネルが実行されると、通常、ユーザーには次の 2 つの値が必要になります。

Base URL
API Key

ユーザーは、これらの値を Claude Code、Codex、Cursor、または互換性のあるツールに入力できます。リクエストは最初にプロキシに送られ、次にプロキシがリクエストをアップストリームサービスに転送します。

この種のプロキシとは実際には何ですか

中間層と考えてください。

ユーザーはプロキシにリクエストを送信します。その後、プロキシは、設定した上流のアカウント、モデル、ルールに従ってそれらのリクエストを転送します。これにより、アカウント、権限、請求、配布を 1 か所で管理できます。

よくある落とし穴

Nginx はヘッダーを削除します: リバースプロキシを使用する場合は、アンダースコアヘッダーを保持します。
データベースまたは Redis がダウンしています: 初期化パネルが開いても、すべてのバックエンドの依存関係が正常であることを意味するわけではありません。
ドメインが不完全です: パネルにアクセスできても、外部 API アドレスが機能することは保証されません。
アカウント認証が失敗します: まずブラウザセッション、プロキシ設定、コールバック URL、およびアップストリームアカウントのステータスを確認してください。