Ivan's Blog
项目实践

Tavily Hikari

Tavily Hikari 是 Rust + Axum proxy，用于 Tavily MCP endpoint：它复用多 API key、匿名化上游请求、把完整 audit logs 写入 SQLite，并附带 React + Vite web console 做实时可视化。README.md 与 README.zh-CN.md 说明这个项目同时服务英文/中文维护入口。

  • README content contract
  • Worktree bootstrap

目录

技术栈

运行与交付

CI 工作流
  • ci.yml
能力标记
  • cargo_toml
  • docker_compose
  • dockerfile
  • github_actions
  • package_json
  • package_lock
JSON

Purpose

Tavily Hikari 是 Rust + Axum proxy，用于 Tavily MCP endpoint：它复用多 API key、匿名化上游请求、把完整 audit logs 写入 SQLite，并附带 React + Vite web console 做实时可视化。README.md 与 README.zh-CN.md 说明这个项目同时服务英文/中文维护入口。

Taxonomy

  • Tags: README content contract, Worktree bootstrap

Repository map

  • Cargo.toml 是 Axum/MCP proxy 服务 manifest。
  • src/ 保存 key pool、routing、audit、admin API 等 Rust 逻辑。
  • web/ 是 React/Vite 控制台，作为 embedded admin UI 随服务发布。
  • Dockerfile 与 docker-compose.yml 提供 container deployment，compose 默认 PROXY_PORT=8787、PROXY_DB_PATH=<runtime-data>/tavily_proxy.db。

Runtime and delivery

本地/部署都围绕 Rust service + SQLite。docker-compose.yml 暴露 8787:8787 并挂载 tavily-hikari-data；根 package.json 仅提供辅助测试脚本 test:tavily-http。环境变量 PROXY_BIND、PROXY_PORT、PROXY_DB_PATH、WEB_STATIC_DIR 是部署 contract。linked worktree 的入口由 scripts/install-hooks.sh 和 shared post-checkout 负责，首次 checkout 会 copy-missing root env、安装 root / web / docs-site 依赖并执行 cargo fetch --locked；需要严格修复时统一走 scripts/worktree-setup.sh，而不是拼接启动脚本。

Architecture notes

核心是 high-anonymity MCP forwarding：只转发 /mcp，敏感 headers 被剥离或重写；SQLite 维护 key affinity、last-used、exhausted 状态和 audit log；admin UI/API 负责 key 管理与可视化。MCP server Topic 是主语义，React UI 只是运营面。

Workflow and quality gates

.github/workflows/ci.yml 是当前 CI 入口。Dockerfile 使用 Rust builder + slim runtime，Compose 提供持久化卷。相比 label-driven release 项目，这里 release 机制更轻；验证重点应放在 Rust tests、HTTP/MCP proxy smoke、Docker compose 和 SQLite migration。

Reusable decisions

  • 把 audit log 放 SQLite，适合单节点 key pool 代理。
  • 高匿名 forwarding 要在 docs 中明确，不要让 admin UI 泄露上游 secret。
  • Compose 的 env/volume 是部署记忆，Topic 中要保留。
  • README 顶部的 Release、CI Pipeline、Rust badges 分别链接 GitHub Releases、ci.yml 的 main workflow 和 rust-toolchain.toml；Badge 是可验证状态的紧凑入口，不替代产品说明或真实质量门禁（README.md、README.zh-CN.md、skills/style-playbook/references/data/projects/tavily-hikari.json）。
  • 运行态恢复应拆成自动 best-effort 与手动 strict repair：自动路径不阻断 checkout，手动入口才聚合失败；.env 只 copy-missing，不覆盖 linked worktree 已有本地状态（docs/specs/worktree-bootstrap-contract/SPEC.md）。

Risks and open questions

  • Tavily status code/limit 语义变更会影响 exhausted key 规则。
  • MCP forwarding 安全边界不能被通用 proxy refactor 破坏。
  • Docker Compose 端口 8787 是默认，不应在本地预览时不经租约直接占用。

Evidence index

  • README.md
  • README.zh-CN.md
  • Cargo.toml
  • Dockerfile
  • docker-compose.yml
  • docs/high-anonymity-proxy.md
  • package.json
  • web/package.json
  • .github/workflows/ci.yml
  • docs/specs/worktree-bootstrap-contract/SPEC.md
  • docs/specs/worktree-bootstrap-contract/IMPLEMENTATION.md
  • scripts/install-hooks.sh
  • scripts/worktree-bootstrap.sh
  • scripts/worktree-setup.sh
  • scripts/test-worktree-bootstrap.sh

相关内容