Vane：把AI搜索主权还给你的本地引擎

嘿，各位老铁，我是周小码——一个被Spring Boot的自动配置绕晕过三次、被Nacos心跳包背叛过两次、还曾对着ThreadLocal内存泄漏日志凌晨三点发呆的Java老兵。

今天不聊JVM调优，也不扯分布式事务。咱来拆解一个刚杀上GitHub Trending榜首、3.3万星的TypeScript新贵：Vane。

痛点不是“找不到答案”，而是“答案不该离开你的硬盘”

你有没有过这种体验？在内部知识库搜“Feign重试机制”，结果跳转到某云厂商的LLM API控制台，日志里赫然写着POST https://api.xxx.ai/v1/chat/completions；上传的PDF文档被悄悄切片发往境外服务器；搜索关键词K8s initContainer timeout，返回的答案页脚印着“Powered by Llama-3-70B (cloud-hosted)”。

这不是懒，是失控。当AI成为基础设施，你连它的输入输出路径都看不见，谈何工程可控？

Vane的出现，就是对这种失控的硬核反击。

它不是又一个Next.js壳，而是一台可拧螺丝的AI实体机

第一眼看到README里那句“AI-powered answering engine”，我下意识摸了摸MacBook散热口——又一个API封装套壳？但往下读三行，我就把咖啡杯放正了：

All search, document parsing, and model inference happen locally by default.

所有搜索、文档解析、模型推理，默认就在你自己的机器上跑。

这感觉就像，别人在云上开直播卖货，Vane却给你送了一整套带加密地下室的实体书店，连书架螺丝都是你亲手拧的。

技术上，它玩的是「分层解耦」的乐高哲学：

• 前端层：Next.js + TypeScript，只管交互渲染，UI干净得像白纸；
• 调度层：tRPC（从代码结构推断）+ Zod Schema校验，负责路由分发、策略选择（Speed/Balanced/Quality）、模型路由（Ollama vs Groq vs OpenAI）；
• 引擎层：完全插件化设计，每个模型接入都是独立Adapter模块——Ollama走http://host.docker.internal:11434/api/chat，Groq走https://api.groq.com/openai/v1/chat/completions，甚至预留了Lemonade自定义服务入口；
• 搜索底座：SearxNG不是简单调用，而是直接打包进Docker镜像（见docker-compose.yml），连Wolfram Alpha后端都预置好JSON格式开关——这不是集成，是亲手造底盘。

核心代码解析：三行命令背后的硬核契约

Vane拒绝抽象陷阱，API直给HTTP，没有SDK，只有契约。来看几个真实可用的代码片段：

## 【推荐】Docker一键部署（生产就绪）
docker run -d -p 3000:3000 \
  -v vane-data:/home/vane/data \  # 持久化用户数据、索引、缓存
  --name vane \
  itzcrazykns1337/vane:latest

注意这个volume挂载点 /home/vane/data ——它不只是存配置，更是全文索引、PDF解析缓存、SearxNG查询历史的落盘位置。Vane没用Elasticsearch，而是用轻量级SQLite+本地向量DB（推测为@xenova/transformers + chroma-client轻量适配），这对NAS或低配MacBook极其友好。

## 【开发调试】非Docker方式启动
git clone https://github.com/ItzCrazyKns/Vane.git
cd Vane
npm i
npm run build  # 构建Next.js SSR + tRPC服务端
npm run start  # 启动全栈服务（含tRPC dev server）

关键在于tRPC的类型安全穿透：前端调用trpc.search.query({ query: "...", mode: "Quality" })，类型定义从server/router/search.ts一路透传到client/app/hooks/useSearch.ts，连mode枚举值都是TS编译期校验，不是字符串魔法。

## 【高级定制】连接自建SearxNG实例（绕过内置副本）
docker run -d -p 3000:3000 \
  -e SEARXNG_API_URL=http://your-searxng-url:8080 \
  -e OLLAMA_HOST=http://your-ollama-host:11434 \
  -v vane-data:/home/vane/data \
  --name vane itzcrazykns1337/vane:slim-latest

这里暴露了Vane真正的架构清醒：环境变量驱动一切。SEARXNG_API_URL覆盖默认搜索后端，OLLAMA_HOST切换Ollama地址——Windows/macOS/Linux下host.docker.internal兼容性问题？它早就在src/server/lib/ollama.ts里写了fallback逻辑：

// src/server/lib/ollama.ts
export const getOllamaHost = () => {
  const host = process.env.OLLAMA_HOST || 'http://host.docker.internal:11434';
  // Windows Docker Desktop fallback
  if (process.platform === 'win32') return 'http://10.0.2.2:11434';
  // Linux without docker-in-docker
  if (!host.includes('host.docker.internal')) return host;
  return host.replace('host.docker.internal', '172.17.0.1');
};

这才是真·工程细节，不是README里一句“请自行配置”。

实战演示：3秒查清Spring Cloud Alibaba的异步重试真相

假设你正在排查Feign Client异步重试失败问题，传统方式：翻17个GitHub Issue + 5篇博客 + Spring官方文档跳转3次。用Vane：

curl -X POST http://localhost:3000/api/search \
  -H "Content-Type: application/json" \
  -d '{
        "query": "如何让Feign支持异步重试？",
        "mode": "Quality",
        "sources": ["docs.spring.io", "github.com/alibaba/spring-cloud-alibaba"]
      }'

返回JSON里不仅有答案摘要，还有精确引用来源：

{
  "answer": "需配合Resilience4j异步装饰器，Feign原生不支持CompletableFuture重试...",
  "references": [
    {
      "url": "https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html/#resilience4j",
      "title": "Resilience4j Integration",
      "page_number": 42
    }
  ]
}

这就是Vane的「结果可溯源」能力——不是幻觉拼凑，而是基于SearxNG精准抓取+LLM多跳推理+引用锚点提取的闭环。

踩坑指南：别让防火墙和JSON格式毁掉你的第一次搜索

• ❌ Linux下Ollama无法访问？检查防火墙：sudo ufw allow 11434；
• ❌ SearxNG返回空结果？确认它启用了json输出格式（settings.yml中result_proxy设为true）且Wolfram Alpha后端已启用；
• ❌ Windows下Docker报host.docker.internal: unknown host？手动改C:\Windows\System32\drivers\etc\hosts，加一行192.168.99.100 host.docker.internal；
• ❌ PDF上传后无响应？确认vane-data卷有写权限，且PDF未加密（Vane用pdf-parse，不支持密码保护PDF）。

这些不是bug，是Vane把“部署即运维”的理念刻进了骨子里。

我的真实评价：它不是工具，是范式演进的观察窗口

Vane的硬伤很真实：没Auth、没CI/CD文档、Lemonade组件像幽灵。但它把AI工程化最棘手的三个问题——私有化部署、多模型调度、结果可溯源——用一套轻量、透明、可审计的方式解了出来。

没有黑箱，只有清晰的管道：请求进来 → SearxNG抓取 → 文档切片 → 向量嵌入 → LLM推理 → 引用标注 → HTTP返回。

如果你是个Java老兵，会欣赏它用TypeScript避开GIL和callback hell；如果你是前端工程师，会爱上tRPC的类型穿透；如果你是SRE，会感激它把SearxNG和Ollama打包成单一容器。

最后说句掏心窝的：别光盯着3.3万star看。真正厉害的，是它让每个普通开发者，第一次真切感觉到——原来AI引擎的控制权，真的可以握在自己手里，而不是飘在某个API Key的云端。