SearchHub

SearchHub

English README · npm · Issues

AI エージェント向けのセルフホスト可能な検索フェイルオーバーゲートウェイ

1 つのプロトコル。複数の検索プロバイダー。API キーの自動ローテーションとフェイルオーバー。

SearchHub は Serper、Tavily、Exa、AnySearch などの検索 API を 1 つのプロトコルに統合し、API キーのローテーション、レート制限、クォータ、プロバイダーのフェイルオーバー、サーキットブレーカーを一元的に処理します。

安定したインターネット検索機能を必要とする MCP クライアント、AI エージェント、RAG アプリケーション、社内自動化サービスに適しています。

SearchHub を使う理由

単一の検索プロバイダーに問題が起きても、エージェントが検索不能になるべきではありません。

• 1 つのキーが無効になったり、レート制限に達したりした場合：次のキーに自動で切り替えます
• 1 つのプロバイダーに障害やタイムアウトが発生した場合：別のプロバイダーに自動で切り替えます
• 連続して失敗した場合：サーキットブレーカーを作動させ、冷却後に半開状態で探査します
• 各キーに QPS、日次／月次／総クォータを個別に設定できます
• HTTP API、CLI、MCP、管理画面から統一して利用できます
• セルフホスト可能で、キーと呼び出しログを自分のマシンに保持できます

画面プレビュー

概要 —— プロバイダーごとのカードに、サーキットブレーカーの状態、利用可能なキー数、冷却／隔離中の数、機能タグ、グローバルデフォルトのクォータが表示されます。

検索デバッグ —— 実際の呼び出しを 1 回実行します。最初の Exa キーがクォータ超過（keyQuotaExhausted）を返すと、システムは 2 つ目のキーに自動で切り替え、検索結果を正常に返します。呼び出し経路には 2 回の試行がすべて記録され、どのプロバイダーとキーが選ばれたか、フォールバックが発生したかを一目で確認できます。

プロバイダー設定 —— 重み（優先度）の順に並べ替えられます。グローバル QPS と 3 段階のクォータをフォールバック値として設定でき、キーでフィールドを空欄にすると自動的に継承されます。タイムアウト、プロバイダーごとの最大キー切り替え回数、サーキットブレーカーのしきい値、冷却時間も調整できます。

使用状況統計 —— 試行回数に基づく統計で、過去 24 時間と 14 日間の傾向、プロバイダー別・キー別の成功率、平均処理時間、直近のエラーが表示されます。

API リファレンス —— 認証方式、リクエスト形式、ページネーションに関する各プロバイダーの機能差を記載したインターフェースドキュメントを内蔵しています。

30 秒で起動

npm でグローバルインストール

Node.js >= 22 が必要です（24 推奨、Active LTS）。

npm install -g searchhub
searchhub start

http://localhost:8787 を開き、起動ログに記載された管理者パスワードで管理画面にログインします。

本番環境では、管理者パスワードと暗号化キーを必ず固定してください。以下の 2 つのコマンドで、強力なランダム値を生成できます。

export SEARCHHUB_SECRET=$(openssl rand -hex 32)
export SEARCHHUB_ADMIN_PASSWORD=$(openssl rand -base64 18)
searchhub start

この 2 つは、上流プロバイダーのキーと管理画面へのログインを保護します。例にある change-me はあくまでプレースホルダーです。そのまま使うと、キーの暗号化が実質的に無効になります。 また、SEARCHHUB_SECRET は設定後に変更しないでください。これはキーの復号用マスターキーであり、変更すると、ディスクに保存済みのプロバイダーキーを復号できなくなります。

npx で試す

npx searchhub start

Docker Compose

curl -O https://raw.githubusercontent.com/woodcoal/SearchHub/main/docker-compose.yml

cat > .env <<EOF
SEARCHHUB_SECRET=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
SEARCHHUB_ADMIN_PASSWORD=$(node -e "console.log(require('crypto').randomBytes(12).toString('base64url'))")
# 可选：启动时自动加入供应商密钥
# SERPER_KEYS=...
# TAVILY_KEYS=...
# EXA_KEYS=...
# ANYSEARCH_KEYS=...
EOF

docker compose up -d --build

http://localhost:8787 を開きます。データとログは Docker の名前付きボリューム searchhub-data に保存されます。

ヒアドキュメントでは <<'EOF' ではなく <<EOF（引用符なし）を使用してください。これにより、$(...) がシェルによって展開されます。Node を使って値を生成するのは、Node が本プロジェクトの実行要件であり、プラットフォーム間で一貫して動作するためです。 生成した値はご自身で安全に保管してください。SEARCHHUB_SECRET はプロバイダーキーの復号用マスターキーであり、設定後は変更しないでください。変更すると、ディスクに保存済みのキーを復号できなくなります。

.env を Git にコミットしないでください。本番環境では、SEARCHHUB_ADMIN_PASSWORD、SEARCHHUB_SECRET、プロバイダーキーを安全なシークレット管理システムに保管してください。

初回設定

1. 管理画面にログインします。
2. 「プロバイダー」または「キー管理」に移動し、Serper／Tavily／Exa／AnySearch の API キーを追加します。
3. 「API 認証」に移動し、呼び出し元用の API キーを作成します。
4. デバッグコンソールまたは CLI から最初の検索を実行します。

searchhub keys add serper '<provider-key>' --label primary --qps 2
searchhub keys add tavily '<provider-key>' --label backup --monthly-quota 1000
searchhub apikey create my-agent
searchhub search "latest MCP servers" --size 5

プロバイダーキーと SearchHub 呼び出し元 API キーは別々の認証情報です。前者は上流の検索サービスへのアクセスに、後者は SearchHub インターフェースの保護に使用します。

MCP 接続

ローカル stdio

Claude Desktop、Cursor、Cline など、ローカル MCP に対応するクライアント向けです。

{
  "mcpServers": {
    "searchhub": {
      "command": "searchhub",
      "args": ["mcp"]
    }
  }
}

CLI は現在のディレクトリにある .env と環境変数から設定を読み込みます。データディレクトリを指定することもできます。

{
  "mcpServers": {
    "searchhub": {
      "command": "searchhub",
      "args": ["mcp", "--home", "/path/to/searchhub-data"]
    }
  }
}

Streamable HTTP

メインサービスの起動後、デフォルトで /mcp が提供されます。

{
  "mcpServers": {
    "searchhub": {
      "url": "http://your-host:8787/mcp",
      "headers": {
        "x-api-key": "sh_xxxxxxxxxx"
      }
    }
  }
}

MCP HTTP サービスのみを起動することもできます。

searchhub mcp --http --port 8788

内蔵ツール：

ツール	用途
searchhub_search	統合検索を実行
searchhub_status	プロバイダーの健全性、サーキットブレーカーの状態、キー数を確認
searchhub_providers	プロバイダーとその機能を確認

HTTP API

ヘルスチェックには認証が不要です。

curl http://localhost:8787/api/health

検索インターフェースでは、管理画面の「API 認証」で生成したキー、または SEARCHHUB_API_TOKEN を使用します。

curl -X POST http://localhost:8787/api/search \
  -H 'content-type: application/json' \
  -H 'x-api-key: sh_xxxxxxxxxx' \
  -d '{"q":"MCP server","pageSize":10,"timeRange":"week","site":"github.com"}'

返される結果は次の形式に統一されています。

{
  "query": { "q": "MCP server", "pageSize": 10 },
  "results": [
    { "title": "...", "url": "https://...", "snippet": "...", "provider": "serper" }
  ],
  "meta": {
    "provider": "serper",
    "tookMs": 842,
    "degraded": false,
    "ignoredParams": [],
    "attempts": [{ "provider": "serper", "ok": true, "tookMs": 842 }]
  }
}

meta.attempts には、このリクエストで試行したキーとプロバイダーが記録されるため、トラブルシューティングやフォールバックの確認に役立ちます。

インターフェースの概要：

インターフェース	認証	説明
GET /api/health	なし	ヘルスチェックとプロバイダーの健全性
GET/POST /api/search	API Key	統合検索
POST /api/admin/login	管理者パスワード	管理画面にログイン
/api/admin/*	管理セッション	キー、プロバイダー、ログ、使用状況、API キーの管理
POST /mcp	API Key	Streamable HTTP MCP

内蔵プロバイダー

ID	特徴	主な機能
serper	Google SERP の生の結果	ページネーション、期間、サイト内検索、地域、言語
tavily	エージェント向けのリアルタイム検索	期間、サイト内検索、地域、言語、セーフサーチ
exa	セマンティック検索	期間、サイト内検索
anysearch	統合リアルタイム検索	言語、地域、匿名フォールバックに対応

SearchHub は、各プロバイダーで異なるレスポンス構造とエラーコードを正規化します。プロバイダーを追加するには、アダプターとエラー分類を実装し、src/providers/index.ts に登録するだけです。

容灾与配额

故障	处理
Key 无效（401/403）	隔离该 Key，切换下一个 Key
Key 限流（429）	按 Retry-After 冷却，切换下一个 Key
配额耗尽	冷却到下一重置周期，切换下一个 Key
供应商故障（5xx/超时）	不惩罚 Key，累计熔断计数并切换供应商
参数错误（400）	不重复请求当前供应商，直接返回或换下一家

每个供应商和每把 Key 都可以设置：

• QPS
• 日配额
• 月配额
• 总配额
• 优先级和超时
• 单供应商最大换 Key 次数
• 熔断阈值和冷却时长

内置默认配额（按各家免费额度预设）、供应商级继承规则与三级配额的完整说明见 docs/quotas.md； 故障分类的完整判定表与熔断状态机见 docs/providers.md。

CLI

searchhub start                         # 启动 API 和管理后台
searchhub search "openai" --size 5     # 直接搜索
searchhub status                        # 查看健康度
searchhub keys list                     # 列出密钥状态
searchhub keys test serper primary      # 测试某把 Key
searchhub usage --json                  # 查看用量
searchhub logs --prune                  # 清理过期日志
searchhub apikey create my-agent        # 创建调用方 API Key
searchhub mcp                           # 启动 stdio MCP
searchhub mcp --http --port 8788        # 启动 HTTP MCP

数据、日志与安全

默认目录：

~/.search-hub/
├── settings.json
├── store.json
└── log/
    ├── searchhub-YYYY-MM-DD.log
    └── calls.jsonl

• 供应商密钥使用 SEARCHHUB_SECRET 进行 AES-256-GCM 加密存储；未配置时会告警。
• 管理密码只保存 scrypt 哈希。
• API Key 只保存 SHA-256 哈希，明文只在创建时显示一次。
• 日志中的 API Key、管理令牌和密钥原文会脱敏。
• SEARCHHUB_LOG_RETENTION_DAYS 默认保留 14 天，设为 0 表示永久保留。
• 运行时冷却状态、统计和用量在内存中，重启会清零；多实例部署需要 Redis 化改造。

完整环境变量见 .env.example。 目录结构、后台密码优先级与找回、数据目录迁移、认证体系细节见 docs/data-and-settings.md； 日志切分与保留策略、调用日志、用量统计口径见 docs/logging.md。

从源码开发

npm install
npm run typecheck
npm run build
npm start

前端开发服务器：

npm run dev       # 后端
npm run dev:web   # Vite 前端，默认 http://localhost:5173

Docker 部署

项目提供多阶段 Dockerfile 和 docker-compose.yml：

docker build -t searchhub:local .

docker run --rm -p 8787:8787 \
  -e SEARCHHUB_SECRET="$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")" \
  -e SEARCHHUB_ADMIN_PASSWORD="$(node -e "console.log(require('crypto').randomBytes(12).toString('base64url'))")" \
  -v searchhub-data:/data \
  searchhub:local

容器内默认：

• 基于 Node.js 24（Active LTS）
• 监听 0.0.0.0:8787
• SEARCHHUB_HOME=/data
• 使用非 root 用户 searchhub（uid 10001）
• GET /api/health 作为 Docker healthcheck
• /data 保存配置、密钥密文和日志

文档

文档	内容
docs/quotas.md	三级配额、QPS 令牌桶、内置默认配额表、供应商级继承规则
docs/logging.md	日志按天切分与保留策略、调用日志、用量统计口径
docs/data-and-settings.md	数据目录、系统设置、后台密码优先级与找回、数据迁移
docs/providers.md	供应商能力矩阵、故障分类与熔断、如何扩展新供应商
docs/limitations.md	已知限制与适用边界——部署前请先读这一篇

许可

MIT License。第三方搜索服务的使用仍需遵守各自的服务条款和计费规则。

Copyright (c) 2026 木炭 [email protected]