よくある質問

インストールできない§

ポートが使用中

デフォルトのポートは3001です。.envのPORTを変更してください。サブスクリプションアカウントはコールバック用に1455、54545、51121も使用し、これらはアップストリームで固定され、変更できない。

1 台のホストで同時にローカルコールバック認可を使えるデフォルト Compose インスタンスは 1 つだけです。既存の OAuth JSON を持つアカウントはインポートでき、Grok はデバイス認可を使えます。

HOST を変更したがコンテナ内で反映されない

コンテナ内のHOSTとDATA_DIRは固定されています。

Compose のメインサービスでは公開先ホストアドレスに BIND_ADDRESS が優先され、未設定時のみ HOST にフォールバックします。いずれもコンテナ内のリッスンアドレスは変更しません。

起動時に権限エラーが報告される

管理対象のデータディレクトリは所有者だけがアクセスできます。所有者やリンク種別を確認できない場合、プログラムはチェックを弱めず、起動を拒否します。権限が不明な場所へ認証情報を書き込まないための意図的な動作です。DATA_DIRの所有者を確認してください。

接続できません§

クライアントは接続に失敗したと報告します

まず curl を使ってクライアント設定の問題を排除：

curl --fail http://127.0.0.1:3001/health

これが成功すればサービスは正常で、問題はクライアント設定です。URL末尾の/v1が余分または不足しているケースが多く、クライアント接続を参照してください。

未認可 / 401 を示す

AUTH_KEYやアップストリームプロバイダーのキーではなく、AccessKeyを使っていることを確認してください。3つは用途が異なります。

リモートアクセスできない

サービスは127.0.0.1だけをリッスンする。意図した安全なデフォルトです。SSHポート転送またはリバースプロキシを使い、直接 0.0.0.0 に変更して公開ネットワークにさらさないでください。管理画面が漏洩するとすべての認証情報が漏洩するため、セキュリティと本番運用を参照してください。

モデル関連§

モデルが存在しないことを示す

ルート検査が最短です。問題が AccessKey、Group、認証情報のどこにあるか示します。ルート検査の理由コードを参照して設定を変更し、もう一度検査してください。

クライアントに別のモデル名を使わせたい

モデルエイリアスを使います。クライアントはAをリクエストし、ゲートウェイが転送時にアップストリームのBへ置き換えます。プロバイダー変更でもコードは不要です。モデル管理を参照してください。

リクエスト失敗§

ときどき失敗するが、再試行で直る

多くはアップストリームのレート制限です。ゲートウェイは認証情報をクールダウンさせて別のものへ切り替えます。追加の認証情報を加えるのが最も直接的な緩和策です。頻発する場合は健全性ページで利用可能な認証情報数を確認します。

認証情報がブラックリストに入った

連続失敗がしきい値を超えると認証情報は自動でブラックリストに入ります。API キー Group は検証間隔に従って自動プローブされ、成功すると復帰します。サブスクリプション認証情報はこの自動復帰経路を使わないため、再認可または手動対応が必要です。しきい値は実行時設定で調整できます。

推論モデルが常にタイムアウトする

この種のモデルは出力開始前に長く推論することがあります。最初のバイトのタイムアウトを延長してください（リクエストタイムアウトではありません）。3種類のタイムアウトは実行時設定を参照してください。

ストリーミング出力が途中で切断される

ストリームアイドルタイムアウトを延長します。前段にリバースプロキシがある場合はストリーミング応答をバッファしないことを確認し、Nginxではproxy_buffering offを設定します。

サブスクリプションアカウント§

リモートデプロイで OAuth 認可を完了できない

ブラウザーのlocalhostはサーバーではなく自分のコンピューターを指すため、リダイレクトに失敗します。リダイレクト失敗後のアドレスバーにある完全なコールバック URL を管理画面に貼り付けるか SSH ポート転送を使ってください。サブスクリプションアカウントを参照してください。

アカウントに再認可が必要と表示される

アカウントカードのその他メニューから「認証情報を更新」を試し、失敗が続く場合はアカウントを再接続またはインポートしてください。「結果不明」も同様に対処できます。「クォータを更新」では認可は回復しません。4つの認可状態の意味はサブスクリプションアカウントのページを参照してください。

クォータが残っているのにアカウントが切り替わる理由

クォータ情報は表示専用で、スケジューリング判断には使われません。実際の切り替えはアップストリームのレート制限応答で発生します。制限されると表示クォータに関係なく直ちにクールダウンし、別のアカウントへ切り替えます。

使用量とコスト§

コストとプロバイダー請求額が一致しない

これは想定どおりです。コストは上流のトークン使用量、モデル価格、グループとアクセスキーの価格倍率から算出する運用分析用の見積もりであり、請求額とは異なります。上流が使用量を返さないリクエストや価格未設定のモデルは計上されず、価格変更で過去のコストは再計算されません。

コスト見積もりが明らかに低い

監視ページのデータ完全性を確認してください。「未価格設定」が多い場合は、モデルの価格を追加します。「使用量欠落」が多い場合は、上流が使用量データを返しているか確認してください。監視とトラブルシューティングを参照してください。

運用保守§

複数インスタンスを実行できますか？

1.x からアップグレードできますか？

2.0はインプレース更新できず、データインポートツールもありません。2.0は完全な書き直しです。並行デプロイして検証後にトラフィックを切り替えます。1.xからの移行を参照してください。

何をバックアップすべきか

データベースとencryption.keyを一緒にバックアップしてください。データベースだけをバックアップすると、復元後の認証情報は復号できません。このリリースはマスターキーの変更に対応していません。データベースとバックアップを参照してください。

ログがディスクを使いすぎる

リクエストログの保存日数を短くします（デフォルトは7日）。リクエスト量が多い場合はディスク使用量への影響が大きく、SQLiteでは特に注意が必要です。