Tavily Hikari

Tavily Hikari 是一个面向 MCP (Model Context Protocol) 的 Tavily 代理层，基于 Rust + Axum 构建，具备多密钥轮询、匿名透传与细粒度审计能力。后端通过 SQLite 维护密钥状态与请求日志，前端使用 React + Vite 提供实时的可视化运维界面，可直接查看 Key 健康、告警与历史流量。

文档站与 Storybook

• 公开文档站：ivanli-cn.github.io/tavily-hikari
• Storybook：ivanli-cn.github.io/tavily-hikari/storybook.html
• 本地 docs-site：cd docs-site && bun install --frozen-lockfile && bun run dev
• 本地 Storybook：cd web && bun install --frozen-lockfile && bun run storybook

功能亮点

• 多密钥轮询 + 亲和：SQLite 记录每个 Key 的最近使用时间，并为访问令牌（access token）维护一个短期“亲和”关系——在一段时间窗口内，同一 token 会优先命中同一把 Tavily API key；亲和关系失效或 Key 状态变化（耗尽/禁用）时，再通过全局“最久未使用”策略在健康 Key 间重新分配，以尽量均衡磨损。
• 短 ID 与密钥密级隔离：每个 Tavily Key 会生成 4 位 nanoid，对外只暴露短 ID；真实 Key 仅管理员 API/Web 控制台可读取。
• 健康巡检：一旦收到 Tavily 432（额度耗尽）会把 Key 标记为 exhausted，并在下一个 UTC 月初或管理员恢复后重新上阵。
• 高匿透传：仅透传 /mcp 与静态资源，自动清洗 X-Forwarded-* 等敏感头并重写 Origin/Referer，细节见 docs/high-anonymity-proxy.md。
• 可视化运维：web/ 单页应用展示实时统计、请求日志、管理员操作入口，支持复制真实 Key、软删除/恢复等动作。
• 管理路由升级：管理端采用 URL Path 路由（如 /admin/dashboard、/admin/tokens/:id、/admin/keys/:id），不再使用旧 hash 子路由。
• 用户控制台 Path 路由：用户控制台现使用 /console、/console/dashboard、/console/tokens 与 /console/tokens/:id；首页 token 引导仍刻意保留 /#<token> / /#<token-id> hash 兼容，避免把完整 token 带入 path/query 日志面。
• 完整审计：request_logs 表保留 method/path/query、状态码、错误信息、透传/丢弃头部等字段，方便回溯配额损耗与异常请求。
• 生产级 CI/CD：GitHub Actions 对代码格式、lint、单元测试把关；发版由 PR intent label 驱动（打 tag + GitHub Release + 推送 ghcr.io 镜像）。

组件与数据流

Client → Tavily Hikari (Axum) ──┬─> Tavily upstream (/mcp)
                                ├─> SQLite (api_keys, request_logs)
                                └─> Web SPA (React/Vite, served via /)

• 后端：Rust 2024 edition、Axum、SQLx、Tokio；负责 CLI、Key 生命周期、请求透传/审计、静态资源托管。
• 数据层：SQLite 单文件库，包含 api_keys（状态、短 ID、配额字段）与 request_logs（请求/响应/错误）。
• 前端：React 18 + TanStack Router + Tailwind CSS + shadcn/ui（Radix）+ Vite 5；构建后输出 web/dist，由后端静态挂载或通过 Vite Dev Server 代理到 http://127.0.0.1:58087。

快速开始

本地运行

# 1. 启动代理（示例绑定高位端口，本地开发显式放开管理员接口）
DEV_OPEN_ADMIN=true cargo run -- --bind 127.0.0.1 --port 58087

# 2. （可选）启动前端 Dev Server
cd web && bun install --frozen-lockfile && bun run --bun dev -- --host 127.0.0.1 --port 55173

# 3. 通过管理员接口注册 Tavily key（仅本地开发模式）
curl -X POST http://127.0.0.1:58087/api/keys \
  -H "Content-Type: application/json" \
  -d '{"api_key":"key_a"}'

服务启动后可访问 http://127.0.0.1:58087/health 验证状态，或在浏览器打开 http://127.0.0.1:55173 使用控制台。所有 Tavily key 建议通过管理员 API 或 Web 控制台录入，避免把敏感密钥写入环境变量。

Docker 部署

CI 在发布时会产出 ghcr.io/ivanli-cn/tavily-hikari:<tag> 镜像，可直接运行：

docker run --rm \
  -p 8787:8787 \
  -v $(pwd)/data:/srv/app/data \
  ghcr.io/ivanli-cn/tavily-hikari:latest

镜像已包含 web/dist，默认监听 0.0.0.0:8787 并把 SQLite 数据写入 /srv/app/data/tavily_proxy.db（可通过挂载卷持久化）。容器启动后同样需通过管理员接口或前端控制台为代理注册 Tavily key。

二进制发布

GitHub Release 现在会附带 Linux tar.gz 二进制包，分别覆盖 linux/amd64 与 linux/arm64，并同步提供 SHA256 校验文件。该二进制把 Web 界面一并内嵌进程序里，运行时不再需要单独的 web/dist 目录。

Docker Compose

仓库内提供了一个最小化的 docker-compose.yml，用于长期运行或一次性 POC：

docker compose up -d

# 以管理员身份注入首批 Tavily key
curl -X POST http://127.0.0.1:8787/api/keys \
  -H "X-Forwarded-User: admin@example.com" \
  -H "X-Forwarded-Admin: true" \
  -H "Content-Type: application/json" \
  -d '{"api_key":"key_a"}'

• 服务会自动使用 ghcr.io/ivanli-cn/tavily-hikari:latest，将 8787 端口暴露到宿主机。
• 通过 tavily-hikari-data 卷持久化 /srv/app/data/tavily_proxy.db，容器重启不会丢数据。
• 其他 CLI 参数可通过 compose 文件的 environment 字段覆写（例如自定义 upstream 或端口）。

若需要运行自定义镜像，可在 compose 文件里将 image 替换为 build: . 并在本地构建 web/dist 后执行 docker compose up --build。

CLI / 环境变量

首次运行会自动建表。若在 CLI/环境变量里显式传入 --keys 或 TAVILY_API_KEYS，会同步 api_keys 表：在列表中的 Key 会被新增或恢复为 active；不在列表中的 Key 会被标记为 deleted。默认推荐通过管理员 API/前端控制台维护 Key 集合。

• TAVILY_UPSTREAM 按完整的 MCP 端点解释；如果反代保留了 path prefix，配置值里需要包含最终的 /mcp 路径。
• TAVILY_USAGE_BASE 可以带 path prefix；Hikari 会在这个 prefix 后继续追加 /search、/extract、/crawl、/map、/research、/research/{id} 与 /usage。

HTTP API 速览

管理员身份由 Passkey、内置管理员会话、显式启用的旧版 ForwardAuth 或本地 DEV_OPEN_ADMIN 判断；控制台仅在管理员会话下显示“复制原始 Key”按钮。

Cherry Studio 接入示例

Tavily Hikari 通过 /api/tavily/search 为 Tavily HTTP API 提供代理与密钥池能力，Cherry Studio 这类直接调用 Tavily HTTP