# https://github.com/ItzCrazyKns/Vane 项目说明书
生成时间：2026-06-22 13:05:55 UTC
## 目录
- [Vane 项目概览与系统架构](#page-1)
- [AI 模型与 Provider 集成](#page-2)
- [搜索流水线、Researcher 与 Widget 系统](#page-3)
- [部署、安装、配置与常见故障排查](#page-4)
## Vane 项目概览与系统架构
### 相关页面
相关主题：[AI 模型与 Provider 集成](#page-2), [搜索流水线、Researcher 与 Widget 系统](#page-3), [部署、安装、配置与常见故障排查](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/ItzCrazyKns/Vane/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/ItzCrazyKns/Vane/blob/main/CONTRIBUTING.md)
- [src/lib/agents/search/types.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/types.ts#L1-L50)
- [src/lib/agents/search/researcher/actions/plan.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/researcher/actions/plan.ts#L1-L50)
- [src/lib/agents/search/researcher/actions/search/webSearch.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/researcher/actions/search/webSearch.ts#L1-L60)
- [src/lib/agents/search/researcher/actions/search/socialSearch.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/researcher/actions/search/socialSearch.ts#L1-L40)
- [src/lib/agents/search/researcher/actions/search/academicSearch.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/researcher/actions/search/academicSearch.ts#L1-L40)
- [src/lib/prompts/search/classifier.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/prompts/search/classifier.ts#L1-L80)
- [src/lib/prompts/search/writer.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/prompts/search/writer.ts#L1-L60)
- [src/lib/agents/suggestions/index.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/suggestions/index.ts#L1-L50)
- [src/lib/models/providers/ollama/ollamaLLM.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/providers/ollama/ollamaLLM.ts#L1-L45)
- [src/lib/config/index.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/config/index.ts#L1-L60)
# Vane 项目概览与系统架构
## 项目定位与核心能力
Vane 是从 Perplexica 派生的开源 AI 搜索引擎，主打"自托管 + 隐私优先"，用户可完全掌控数据 [README.md](https://github.com/ItzCrazyKns/Vane/blob/main/README.md)。项目在 v1.12.0 起移除了 Langchain，改用自研的轻量抽象以获得对流式输出与工具调用的更细粒度控制（[v1.12.0 release notes](https://github.com/ItzCrazyKns/Vane/releases/tag/v1.12.0)）。其核心能力包括：
- **多 LLM 提供方**：支持 Ollama、OpenAI 兼容接口与 LM Studio，并在配置中允许自定义系统提示词 [src/lib/config/index.ts:1-60](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/config/index.ts#L1-L60)
- **多源检索**：以 SearxNG 为后端，区分 `web` / `discussions` / `academic` 三类来源 [src/lib/agents/search/types.ts:1-15](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/types.ts#L1-L15)
- **小部件（Widgets）**：天气、股票、计算等 UI 卡片可在分类阶段被激活 [src/lib/prompts/search/classifier.ts:1-30](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/prompts/search/classifier.ts#L1-L30)
- **文件上传与图片/视频搜索**，以及搜索历史本地化保存 [README.md](https://github.com/ItzCrazyKns/Vane/blob/main/README.md)
- **后置建议生成**：根据聊天历史输出下一轮可能的问题 [src/lib/agents/suggestions/index.ts:1-50](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/suggestions/index.ts#L1-L50)
## 系统架构总览
代码组织遵循"前端 + 后端 Agent + 模型提供方"的分层结构 [CONTRIBUTING.md:1-30](https://github.com/ItzCrazyKns/Vane/blob/main/CONTRIBUTING.md#L1-L30)。前端基于 Next.js（`src/app`，主路由含 `/`、`/c`、`/discover`、`/library`），后端核心位于 `src/lib/agents/search`，模型层抽象为 `BaseLLM` / `BaseEmbedding` 供具体实现复用 [src/lib/agents/search/types.ts:15-50](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/types.ts#L15-L50)。
```mermaid
flowchart TB
UI[Next.js 路由
src/app] --> API[API 路由
src/app/api]
API --> SA[Search Agent
src/lib/agents/search]
SA --> CL[Classifier]
SA --> RS[Researcher
工具循环]
SA --> WG[Widgets]
SA --> WR[Writer]
RS --> WS[webSearch]
RS --> DS[socialSearch]
RS --> AS[academicSearch]
SA --> MP[Model Providers]
MP --> OL[Ollama]
MP --> OA[OpenAI 兼容]
MP --> LM[LM Studio]
RS --> SX[SearXNG]
SA --> CFG[配置系统
config/index.ts]
```
Search Agent 按"**分类 → 研究 → 部件 → 写作**"四阶段推进。研究阶段是显式的工具循环：每轮先调用 `__reasoning_preamble` 输出自然语言计划，再决定是否执行 `web_search` / `socialSearch` / `academicSearch` [src/lib/agents/search/researcher/actions/plan.ts:1-50](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/researcher/actions/plan.ts#L1-L50)（[src/lib/prompts/search/researcher.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/prompts/search/researcher.ts)）。
## 搜索流水线详解
**1. 分类阶段** —— [src/lib/prompts/search/classifier.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/prompts/search/classifier.ts) 通过 LLM 判定是否需要联网（`skipSearch`）、启用 `academicSearch` / `discussionSearch` / `personalSearch`，并激活 `showWeatherWidget` / `showStockWidget` / `showCalculationWidget` 等小部件；最终输出脱离上下文的 `standaloneFollowUp`。
**2. 研究阶段** —— Researcher 是带工具调用的循环体。`webSearch.ts` 在 `quality` 模式下要求至少 5–6 轮检索、每次最多 3 条查询，从宽泛到具体逐步收敛 [src/lib/agents/search/researcher/actions/search/webSearch.ts:1-60](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/researcher/actions/search/webSearch.ts#L1-L60)；`socialSearch.ts` 限定引擎为 `reddit`，并要求来源与分类条件同时满足才会启用 [src/lib/agents/search/researcher/actions/search/socialSearch.ts:1-40](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/researcher/actions/search/socialSearch.ts#L1-L40)；`academicSearch.ts` 使用 `arxiv` / `google scholar` / `pubmed` 三引擎 [src/lib/agents/search/researcher/actions/search/academicSearch.ts:1-40](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/researcher/actions/search/academicSearch.ts#L1-L40)。
**3. 写作阶段** —— [src/lib/prompts/search/writer.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/prompts/search/writer.ts#L1-L60) 要求模型输出"博客式"Markdown 段落，强制使用 `[number]` 内联引用并保留原始数值。
**4. 建议生成** —— [src/lib/agents/suggestions/index.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/suggestions/index.ts#L1-L50) 在对话结束后调用 `generateObject` 解析出下一轮可能的问题数组。
## 模型与配置系统
`ollamaLLM.ts` 显式列举"推理型"模型名单（`gpt-oss`、`deepseek-r1`、`qwen3`、`deepseek-v3.1`、`magistral`、`nemotron-3` 等），用于在消息转换时正确分离 `reasoning_content` 与正文 [src/lib/models/providers/ollama/ollamaLLM.ts:1-45](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/providers/ollama/ollamaLLM.ts#L1-L45)。配置系统基于文件存储 `currentConfig.json`，可与 `SEARXNG_API_URL` 等环境变量合并，作用域分 `client` 与 `server` [src/lib/config/index.ts:1-60](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/config/index.ts#L1-L60)。
## 已知问题与社区反馈
近期社区反馈集中在升级兼容性与稳定性（[v1.12.2 release notes](https://github.com/ItzCrazyKns/Vane/releases/tag/v1.12.2)）：
- 1.12.1 → 1.12.2 升级后部分用户卡在 "Brainstorming forever"（[#1154](https://github.com/ItzCrazyKns/Vane/issues/1154)）
- OpenAI 兼容提供方在 `function.arguments` 为空时流式解析崩溃（[#1150](https://github.com/ItzCrazyKns/Vane/issues/1150)）
- `OllamaEmbedding` 无并发限制，并行搜索会压垮嵌入端点（[#1147](https://github.com/ItzCrazyKns/Vane/issues/1147)）
- SearXNG 偶发返回 0 条结果导致流水线无响应（[#1143](https://github.com/ItzCrazyKns/Vane/issues/1143)）
- v1.12.2 已修复：历史双重转换、挂起请求超时、部件错误导致整条管线崩溃等问题（[v1.12.2 release notes](https://github.com/ItzCrazyKns/Vane/releases/tag/v1.12.2)）
社区功能请求主要集中在：简化 Docker 部署以免去克隆仓库（[#673](https://github.com/ItzCrazyKns/Vane/issues/673)）、集成 Tavily / Exa 等 LLM 优化搜索源（[#709](https://github.com/ItzCrazyKns/Vane/issues/709)）、引入多用户鉴权（[#708](https://github.com/ItzCrazyKns/Vane/issues/708)）、MCP 协议支持（[#758](https://github.com/ItzCrazyKns/Vane/issues/758)）等。
## See Also
- 搜索流水线
- 模型提供方（Ollama / OpenAI / LM Studio）
- 配置系统
- 已知问题与升级指南
---
## AI 模型与 Provider 集成
### 相关页面
相关主题：[Vane 项目概览与系统架构](#page-1), [搜索流水线、Researcher 与 Widget 系统](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [src/lib/models/providers/index.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/providers/index.ts)
- [src/lib/models/providers/openai/openaiLLM.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/providers/openai/openaiLLM.ts)
- [src/lib/models/providers/anthropic/anthropicLLM.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/providers/anthropic/anthropicLLM.ts)
- [src/lib/models/providers/gemini/geminiLLM.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/providers/gemini/geminiLLM.ts)
- [src/lib/models/providers/groq/groqLLM.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/providers/groq/groqLLM.ts)
- [src/lib/models/providers/ollama/ollamaLLM.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/providers/ollama/ollamaLLM.ts)
- [src/lib/models/registry.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/registry.ts)
- [src/lib/config/index.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/config/index.ts)
- [src/lib/prompts/search/writer.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/prompts/search/writer.ts)
- [CONTRIBUTING.md](https://github.com/ItzCrazyKns/Vane/blob/main/CONTRIBUTING.md)
# AI 模型与 Provider 集成
## 1. 概述与设计动机
Vane 的 AI 模型层位于 `src/lib/models/` 下，采用**多 Provider 适配器模式**，把不同厂商（OpenAI、Anthropic、Google Gemini、Groq、Ollama 等）以及任何兼容 OpenAI 接口的服务统一抽象为同一组接口（`BaseLLM`、`BaseEmbedding`）。搜索管线（分类、检索、写作、小部件）只依赖这些抽象接口，从而实现 Provider 之间的可插拔切换。
> 自 **v1.12.0** 起，Vane 完全移除 Langchain，改用自研的低层实现以获得对流式输出、JSON 函数调用以及厂商特性的细粒度控制（[CONTRIBUTING.md](https://github.com/ItzCrazyKns/Vane/blob/main/CONTRIBUTING.md)）。这一架构重构是后续 Provider 灵活性的基础。
资料来源：[src/lib/models/providers/index.ts:1-40]()、[CONTRIBUTING.md](https://github.com/ItzCrazyKns/Vane/blob/main/CONTRIBUTING.md)
## 2. Provider 注册与运行时装配
Vane 通过 `registry.ts` 统一加载所有 Provider，并以数组形式维护可用模型清单。每个 Provider 实现文件（如 `openaiLLM.ts`、`anthropicLLM.ts`）导出 `BaseLLM` 子类，覆写 `streamChat`、`generateObject` 等核心方法。
```mermaid
flowchart LR
A[Search Pipeline] --> B[BaseLLM Abstraction]
B --> C[OpenAI Compatible]
B --> D[Anthropic Native]
B --> E[Gemini Native]
B --> F[Groq Native]
B --> G[Ollama Local]
C --> C1[OpenAI / LM Studio / OpenRouter]
C --> C2[v1.12.1+ LM Studio Provider]
```
`src/lib/config/index.ts` 中定义了"基础 URL、API Key、模型选择"等可配置字段，初始化时既会写入本地配置文件，也会读取环境变量（如 `SEARXNG_API_URL`）。这种**双源配置**使 Docker 部署更友好，但也带来了 v1.12.1 → v1.12.2 升级时用户报告的"Brainstorming 永久循环"问题（[#1154](https://github.com/ItzCrazyKns/Vane/issues/1154)）。
资料来源：[src/lib/config/index.ts:1-120]()、[src/lib/models/registry.ts:1-80]()、[v1.12.1 Release Notes](https://github.com/ItzCrazyKns/Vane/releases/tag/v1.12.1)
## 3. 主要 Provider 实现要点
### 3.1 OpenAI 兼容层
`openaiLLM.ts` 是最大的一块，承担了官方 OpenAI、LM Studio（v1.12.1 引入）、OpenRouter 等所有 OpenAI 兼容协议的适配。该层最容易出现边界条件问题，例如：
- **空 function.arguments 片段**：在流式传输中部分 chunk 的 `function.arguments` 为空字符串时，JSON 解析可能抛错并导致研究流程"卡在 Brainstorming"，参见 [#1150](https://github.com/ItzCrazyKns/Vane/issues/1150)。
- **远程代码执行风险**：旧版使用 `child_process` 拼接外部输入存在 RCE 漏洞，已在生产环境被利用 [#946](https://github.com/ItzCrazyKns/Vane/issues/946)。
- **费用失控**：当"Auto Video Search"启用后，OpenRouter 路由到 Claude Opus 等昂贵模型可能产生高额账单 [#1144](https://github.com/ItzCrazyKns/Vane/issues/1144)，建议在设置中显式限定模型。
### 3.2 Anthropic、Gemini、Groq
三者各自实现原生 SDK 调用，不走 OpenAI 协议转换层，从而能利用各家原生的 function calling、缓存与安全特性。`writer.ts` 中的写作提示词要求模型生成带 `[number]` 引用的 Markdown 答案，这要求 Provider 必须稳定支持 JSON / 结构化输出。
### 3.3 Ollama 与本地模型
Ollama 既作为 LLM Provider，又作为 Embedding Provider。社区报告其 embedding 在并发搜索时缺乏限流，会压垮本地推理服务 [#1147](https://github.com/ItzCrazyKns/Vane/issues/1147)，建议自部署时增加反向代理或并发上限。
资料来源：[src/lib/models/providers/openai/openaiLLM.ts:1-200]()、[src/lib/models/providers/ollama/ollamaLLM.ts:1-200]()、[src/lib/prompts/search/writer.ts:1-80]()
## 4. 选型与故障排查指南
下表汇总了常见 Provider 的关键考量：
| Provider | 协议 | 流式支持 | 已知问题 | 缓解措施 |
| --- | --- | --- | --- | --- |
| OpenAI | 原生 | 稳定 | 高费用 | 设置 max_tokens / 限额 |
| OpenRouter | OpenAI 兼容 | 部分 | 空 args chunk 抛错 [#1150] | 升级到 ≥ v1.12.2 |
| LM Studio | OpenAI 兼容 | 稳定 | JSON 抽取曾异常 | v1.12.1 已修复 |
| Anthropic | 原生 | 稳定 | 暂无 | — |
| Ollama | 原生 HTTP | 受机器性能影响 | embedding 并发 502 [#1147] | 部署并发限制 |
升级或新增 Provider 时，建议优先参考 `CONTRIBUTING.md` 中描述的"models are loaded via `src/lib/models/registry.ts`"装配流程，并在 `config/index.ts` 中补充对应的 UI 配置项。
资料来源：[CONTRIBUTING.md](https://github.com/ItzCrazyKns/Vane/blob/main/CONTRIBUTING.md)、[v1.12.2 Release Notes](https://github.com/ItzCrazyKns/Vane/releases/tag/v1.12.2)
## See Also
- 搜索管线与 Agent 架构
- SearXNG 集成与故障排查
- 配置与环境变量参考
- 升级到 v1.12.2 的破坏性变更说明
---
## 搜索流水线、Researcher 与 Widget 系统
### 相关页面
相关主题：[Vane 项目概览与系统架构](#page-1), [AI 模型与 Provider 集成](#page-2)
相关源码文件
以下源码文件用于生成本页说明：
- [src/lib/agents/search/index.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/index.ts)
- [src/lib/agents/search/api.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/api.ts)
- [src/lib/agents/search/types.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/types.ts)
- [src/lib/agents/search/researcher/actions/plan.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/researcher/actions/plan.ts)
- [src/lib/agents/search/researcher/actions/search/webSearch.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/researcher/actions/search/webSearch.ts)
- [src/lib/agents/search/researcher/actions/search/socialSearch.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/researcher/actions/search/socialSearch.ts)
- [src/lib/agents/search/researcher/actions/search/academicSearch.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/researcher/actions/search/academicSearch.ts)
- [src/lib/prompts/search/researcher.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/prompts/search/researcher.ts)
- [src/lib/prompts/search/writer.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/prompts/search/writer.ts)
- [src/lib/prompts/search/classifier.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/prompts/search/classifier.ts)
- [src/lib/config/index.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/config/index.ts)
- [README.md](https://github.com/ItzCrazyKns/Vane/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/ItzCrazyKns/Vane/blob/main/CONTRIBUTING.md)
# 搜索流水线、Researcher 与 Widget 系统
## 概述
Vane 是一个基于 AI 的开源搜索引擎，其核心能力由 `src/lib/agents/search` 下的"分类 → 检索 → 写作"三段式流水线提供 资料来源：[README.md:1-40]()。在 1.12.0 的架构重构中，Langchain 被完全移除，改由自研的 `SearchAgent` 与 `APISearchAgent` 编排，以获得对流式、工具调用与模型差异化的细粒度控制 资料来源：[CONTRIBUTING.md:1-20]()。流水线的主要输入是用户的聊天历史与 `followUp` 查询，输出则是一段带引用、可嵌入 Widget 的最终答复。
## 流水线架构
搜索流程在 `SearchAgent.searchAsync`（用户会话场景）与 `APISearchAgent.searchAsync`（外部 API 场景）中实现，结构基本一致：先由分类器决定是否需要检索以及启用哪些来源，然后并行启动 Researcher 与 Widget 执行器，最后由 Writer 提示词合成答复 资料来源：[src/lib/agents/search/index.ts:20-58]() 资料来源：[src/lib/agents/search/api.ts:9-44]()。下游的持久化层会把消息状态写入 `messages` 表，便于断点续传与历史回放 资料来源：[src/lib/agents/search/index.ts:20-46]()。
```mermaid
flowchart LR
A[用户查询 followUp] --> B[Classifier]
B -->|skipSearch=false| C[Researcher 工具调用循环]
B --> D[WidgetExecutor 并行]
C --> E[Search Findings]
D --> F[Widget Outputs]
E --> G[Writer 提示词]
F --> G
G --> H[流式最终答复]
B -.->|skipSearch=true| H
```
## 分类器与来源路由
`SearchSources` 枚举定义了三种数据来源：`web`、`discussions`、`academic`，分别对应普通网页、Reddit 等讨论区和 arXiv/Google Scholar/PubMed 等学术站点 资料来源：[src/lib/agents/search/types.ts:1-22]()。`Classifier` 在每次查询时通过结构化提示词输出多个布尔字段：`skipSearch`、`personalSearch`、`academicSearch`、`discussionSearch`、`showWeatherWidget`、`showStockWidget` 等 资料来源：[src/lib/prompts/search/classifier.ts:1-40]()。这些字段既是研究员行动（Action）的 `enabled` 谓词，也是 Widget 触发器；任何字段被分类器否定，则对应的检索/Widget 路径都不会启动。
> 常见模式：分类器提示词中明确"如果 widget 能完全回答用户问题，请同时把 `skipSearch` 设为 true"，这避免了为简单问题无谓地消耗检索与 token 配额 资料来源：[src/lib/prompts/search/classifier.ts:30-40]()。
## Researcher 与工具调用循环
`Researcher` 是流水线的核心，它要求模型在每一轮首先调用 `__reasoning_preamble`（实现位于 `plan.ts`）输出自然语言计划，然后再选择其它工具——"如果不在任何其它工具之前先调用它，调用将被忽略" 资料来源：[src/lib/agents/search/researcher/actions/plan.ts:1-40]()。研究员提示词明确要求遵循"reasoning → tool → reasoning → tool → … → done"的迭代循环，并建议在 `quality` 模式下完成 5–6 轮以上的检索 资料来源：[src/lib/prompts/search/researcher.ts:1-80]()。
三种检索 Action 共享同一个 `executeSearch` 工具，差别仅在传入的 `engines` 列表：
| Action | 文件 | 默认 engines | 启用条件 |
|---|---|---|---|
| `webSearch` | `actions/search/webSearch.ts` | 由 SearXNG 决定 | `skipSearch === false` |
| `socialSearch` | `actions/search/socialSearch.ts` | `['reddit']` | `sources.includes('discussions')` 且 `discussionSearch === true` |
| `academicSearch` | `actions/search/academicSearch.ts` | `['arxiv', 'google scholar', 'pubmed']` | `sources.includes('academic')` 且 `academicSearch === true` |
资料来源：[src/lib/agents/search/researcher/actions/search/webSearch.ts:1-80]() 资料来源：[src/lib/agents/search/researcher/actions/search/socialSearch.ts:1-40]() 资料来源：[src/lib/agents/search/researcher/actions/search/academicSearch.ts:1-40]()。每个 Action 最多接受 3 个查询并把结果回填到当前 `ResearchBlock`，再由 `executeSearch` 调用 SearXNG 完成检索 资料来源：[src/lib/lib/config/index.ts:40-60]()。
## Widget 系统
Widget 与 Researcher 并行执行，互不阻塞。`WidgetExecutor.executeAll` 在 `APISearchAgent` 中通过 `Promise.all` 与检索一起启动，并在出错时仅记录日志而不会拖垮整条流水线——这正是 v1.12.2 中"widget 执行错误不再崩溃整个研究流水线"的修复点 资料来源：[src/lib/agents/search/api.ts:18-30]()。`Widget` 接口统一了 `shouldExecute`（基于分类结果触发）与 `execute`（产出 `WidgetOutput`，包含 `llmContext` 与结构化 `data`）两类契约 资料来源：[src/lib/agents/search/types.ts:24-40]()。Writer 提示词要求在最终答复中以 `[number]` 行内引用所有事实，并将 Widget 输出与检索结果统一拼装为带 Markdown 结构、引用与可选总结的深度回答 资料来源：[src/lib/prompts/search/writer.ts:1-40]()。
## 配置与运行时模式
`SearchAgentConfig` 暴露了 `mode`（`speed` / `balanced` / `quality`），研究员与检索均按模式调整提示词深度与循环轮数 资料来源：[src/lib/agents/search/types.ts:8-22]()。检索后端完全由 `SEARXNG_API_URL` 环境变量指向的 SearXNG 实例驱动，社区反馈显示该实例的可用性会直接影响"Vane 是否能产出非零结果"——例如 issue #1143 中"SearXNG 检索得到 82 条结果却最终 0 响应"即由下游处理异常导致 资料来源：[src/lib/lib/config/index.ts:40-60]()。
## 已知问题与社区反馈
- 1.12.2 升级后曾出现"Brainstorming forever"挂起（issue #1154），症状与研究员工具调用循环未正常终止有关，1.12.2 的"validation and timeouts to prevent hung search requests"修复正是针对此路径。
- issue #1150 报告 OpenRouter 兼容流式在空 `function.arguments` 分片上抛出，导致 UI 卡在 `Brainstorming...`——发生点在 `openaiLLM.ts` 的工具调用解析处，间接破坏研究员回路。
- issue #1147 指出 `OllamaEmbedding` 缺少并发限制，会在并行检索下打挂本地 Embedding 服务；这与本流水线中每个 Researcher 实例都会触发独立的 `embed()` 调用直接相关。
## See Also
- [Project README — Features & Installation](README.md)
- [Contributing Guide — Code Map](CONTRIBUTING.md)
- 配置系统：[src/lib/config/index.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/config/index.ts)
- 模型注册表：[src/lib/models/registry.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/registry.ts)（参见 CONTRIBUTING 指引）
---
## 部署、安装、配置与常见故障排查
### 相关页面
相关主题：[Vane 项目概览与系统架构](#page-1), [AI 模型与 Provider 集成](#page-2), [搜索流水线、Researcher 与 Widget 系统](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/ItzCrazyKns/Vane/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/ItzCrazyKns/Vane/blob/main/CONTRIBUTING.md)
- [src/lib/config/index.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/config/index.ts)
- [src/lib/agents/search/types.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/types.ts)
- [src/lib/prompts/search/classifier.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/prompts/search/classifier.ts)
- [src/lib/models/providers/ollama/ollamaLLM.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/providers/ollama/ollamaLLM.ts)
- [src/lib/agents/search/researcher/actions/search/webSearch.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/researcher/actions/search/webSearch.ts)
- [src/lib/agents/search/researcher/actions/search/academicSearch.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/researcher/actions/search/academicSearch.ts)
- [src/lib/agents/search/researcher/actions/scrapeURL.ts](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/researcher/actions/scrapeURL.ts)
- [src/components/Navbar.tsx](https://github.com/ItzCrazyKns/Vane/blob/main/src/components/Navbar.tsx)
# 部署、安装、配置与常见故障排查
本文面向希望自托管 Vane 的开发者与运维人员，聚焦项目的部署形态、运行时配置结构、安装初始化流程以及社区中常见的故障模式。Vane 是一个 AI 驱动的开源搜索引擎，由 Next.js 前端与 Node.js 后端组成，支持 Ollama、OpenAI 兼容、LM Studio 等多种模型提供方，并通过 SearxNG 完成外部网络检索 [README.md:1-30](README.md)。
## 一、部署形态与运行时组件
Vane 的官方镜像 `itzcrazykns1337/vane:latest` 以 Docker 容器形式分发，标准启动需要映射端口 `3300`，并通过环境变量或初始化向导注入基础配置 [README.md:30-60](README.md)。`CONTRIBUTING.md` 明确指出项目代码分为三层：
- `src/app`：Next.js 路由与页面（首页 `/`、聊天 `/c`、发现 `/discover`、资料库 `/library`）。
- `src/lib`：核心后端逻辑，包含搜索代理（`src/lib/agents/search`）、模型注册表（`src/lib/models/registry.ts`）、SearxNG 客户端（`src/lib/searxng.ts`）等。
- `src/components`：可复用 UI 组件，例如导出 Markdown/PDF 的 `Navbar` [src/components/Navbar.tsx:1-40](src/components/Navbar.tsx)。
社区长期存在的简化部署诉求表明，部分用户希望直接通过单镜像方式启动而不必克隆仓库 [Issue #673](https://github.com/ItzCrazyKns/Vane/issues/673)，这是当前部署仍要求执行首次访问 `Setup Wizard` 才能写入配置的原因。
## 二、配置系统结构
Vane 的运行时配置由 `Config` 类管理，首次启动时会从 `configPath` 加载（不存在则写入默认值），并允许通过环境变量覆盖 [src/lib/config/index.ts:80-130](src/lib/config/index.ts)。配置项按 `scope` 分为：
| 作用域 | 含义 | 典型字段 |
| --- | --- | --- |
| `client` | 仅前端 UI 使用 | `systemInstructions` 自定义模型语气 [src/lib/config/index.ts:40-70](src/lib/config/index.ts) |
| `server` | 后端运行时需要 | `searxngURL`，由环境变量 `SEARXNG_API_URL` 注入 [src/lib/config/index.ts:90-110](src/lib/config/index.ts) |
搜索代理侧的 `SearchAgentConfig` 描述了一次研究会话所需的全部依赖：启用的来源集合（`web`/`discussions`/`academic`）、上传文件 ID、LLM、Embedding、模式（`speed`/`balanced`/`quality`）以及系统指令 [src/lib/agents/search/types.ts:1-40](src/lib/agents/search/types.ts)。配置错误最常表现为「Brainstorming」阶段卡死，例如 1.12.2 升级后初始化未完成即触发研究请求，会导致请求挂起 [Issue #1154](https://github.com/ItzCrazyKns/Vane/issues/1154)。
## 三、初始化与安装流程
新部署后用户首次访问会自动进入 `Setup Wizard`，由 `SetupWizard.tsx` 与 `SetupConfig.tsx` 协作完成模型、搜索源、自定义指令等基础信息的录入，随后通过 `Config.saveConfig()` 写入本地 JSON 文件 [src/lib/config/index.ts:120-150](src/lib/config/index.ts)。若配置解析失败，控制台会输出 SyntaxError 并回退到默认配置，同时覆盖原文件 [src/lib/config/index.ts:130-160](src/lib/config/index.ts)。
环境变量覆写优先级最高，例如未设置 `SEARXNG_API_URL` 时 SearxNG 检索将无法工作，社区中常见的「Search is broken」通常源于此变量未配置或 SearxNG 实例返回结构异常 [Issue #1143](https://github.com/ItzCrazyKns/Vane/issues/1143)。
## 四、常见故障排查
### 4.1 检索结果为空或返回零条
典型场景：研究阶段显示「Found 82 results」但后续无响应。根因通常是 SearxNG 实例返回了非数组结构或引擎被禁用，1.12.2 已增加搜索查询的非数组边界校验 [Release v1.12.2](https://github.com/ItzCrazyKns/Vane/releases/tag/v1.12.2)。
### 4.2 UI 长时间停在「Brainstorming」
当 OpenAI 兼容提供方在流式 tool-call 阶段解析到空的 `function.arguments` 时会抛出异常，导致研究请求死亡但前端未收到终止事件。该问题在 `src/lib/models/providers/openai/openaiLLM.ts` 的流式解析器中暴露，需要对空块进行容错处理 [Issue #1150](https://github.com/ItzCrazyKns/Vane/issues/1150)。同时，OllamaEmbedding 在并发场景下没有全局并发上限，5–10 个并行检索会击穿 Ollama 服务并产生 502 [Issue #1147](https://github.com/ItzCrazyKns/Vane/issues/1147)。Ollama 提供方还需要特别注意推理类模型（`deepseek-r1`、`qwen3`、`nemotron-cascade-2` 等）启用了额外的 reasoning 字段 [src/lib/models/providers/ollama/ollamaLLM.ts:20-40](src/lib/models/providers/ollama/ollamaLLM.ts)。
### 4.3 异常费用与速率失控
启用 Auto Video Search 后，若未在路由处限制调度次数，可能在无人交互的情况下持续调用高成本模型（如 Claude Opus），造成数千美元计费 [Issue #1144](https://github.com/ItzCrazyKns/Vane/issues/1144)。建议在网关侧配置 OpenRouter 的速率与预算告警。
### 4.4 页面无法加载（Synology / NAS）
Issue #1153 报告在 Synology 上通过 Docker 启动并接入 OpenAI 兼容提供方时，搜索启动后页面出现「This page couldn't load」错误。该现象多与 Next.js 流式响应在反代下被截断有关，应在 NAS 反向代理中关闭缓冲并放行 `/api/chat`。
### 4.5 安全相关
历史版本曾报告通过不安全的 `child_process` 拼接产生 RCE 漏洞，1.12.x 重构后已移除 LangChain 并重写为自定义实现 [Issue #946](https://github.com/ItzCrazyKns/Vane/issues/946)。升级至 v1.12.0 及以上版本可消除该风险 [Release v1.12.0](https://github.com/ItzCrazyKns/Vane/releases/tag/v1.12.0)。
## 五、升级与维护建议
1. 升级前务必阅读对应版本的发布说明，1.12.0 移除了 LangChain 并重命名了所有 provider，1.12.2 修复了历史双重转换、挂起请求与 widget 崩溃等问题 [Release v1.12.0](https://github.com/ItzCrazyKns/Vane/releases/tag/v1.12.0)、[Release v1.12.2](https://github.com/ItzCrazyKns/Vane/releases/tag/v1.12.2)。
2. 自托管 SearxNG 时确认 `json` 格式与至少一个通用引擎可用，OpenAI 兼容提供方建议同时启用 LM Studio 或本地 Ollama 作为备用链路 [Release v1.12.1](https://github.com/ItzCrazyKns/Vane/releases/tag/v1.12.1)。
3. 学术与社交检索分别使用 `arxiv/google scholar/pubmed` 与 `reddit` 引擎，需要 SearxNG 实例启用对应插件 [src/lib/agents/search/researcher/actions/search/academicSearch.ts:1-40](src/lib/agents/search/researcher/actions/search/academicSearch.ts)、[src/lib/agents/search/researcher/actions/search/socialSearch.ts:1-40](src/lib/agents/search/researcher/actions/search/socialSearch.ts)。
4. 自定义系统指令应在 `Setup Wizard` 的「System Instructions」中填写，避免通过环境变量硬编码导致无法热更新 [src/lib/config/index.ts:40-70](src/lib/config/index.ts)。
## See Also
- [项目 README](README.md)
- [贡献指南](CONTRIBUTING.md)
- [配置模块源码](src/lib/config/index.ts)
- [搜索代理类型定义](src/lib/agents/search/types.ts)
- [Release v1.12.2](https://github.com/ItzCrazyKns/Vane/releases/tag/v1.12.2)
---
---
## Doramagic 踩坑日志
项目：ItzCrazyKns/Vane
摘要：发现 16 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Remote Code Execution via Unsafe child_process Usage in Perplexica (Confirmed Real-World Compromise)。
## 1. 安全/权限坑 · 来源证据：Remote Code Execution via Unsafe child_process Usage in Perplexica (Confirmed Real-World Compromise)
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Remote Code Execution via Unsafe child_process Usage in Perplexica (Confirmed Real-World Compromise)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/ItzCrazyKns/Vane/issues/946 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 2. 安全/权限坑 · 来源证据：Vane somehow charged $3000 USD to my openrouter account.
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Vane somehow charged $3000 USD to my openrouter account.
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/ItzCrazyKns/Vane/issues/1144 | 来源类型 github_issue 暴露的待验证使用条件。
## 3. 安装坑 · 依赖 Docker 环境
- 严重度：medium
- 证据强度：runtime_trace
- 发现：安装/运行入口包含 Docker 命令：docker run -d -p 3000:3000 -v vane-data:/home/vane/data --name vane itzcrazykns1337/vane:latest
- 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
- 复现命令：`docker run -d -p 3000:3000 -v vane-data:/home/vane/data --name vane itzcrazykns1337/vane:latest`
- 证据：identity.distribution | https://github.com/ItzCrazyKns/Vane | docker run -d -p 3000:3000 -v vane-data:/home/vane/data --name vane itzcrazykns1337/vane:latest
## 4. 安装坑 · 来源证据：Enhancement: Consider serpbase.dev as an optional search provider for reliable SERP retrieval
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Enhancement: Consider serpbase.dev as an optional search provider for reliable SERP retrieval
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/ItzCrazyKns/Vane/issues/1148 | 来源类型 github_issue 暴露的待验证使用条件。
## 5. 安装坑 · 来源证据：This page couldn’t load
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：This page couldn’t load
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/ItzCrazyKns/Vane/issues/1153 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。
## 6. 安装坑 · 来源证据：Update to Vane 1.12.2 from Perplexica 1.12.1 broke it. Brainstoming forever
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Update to Vane 1.12.2 from Perplexica 1.12.1 broke it. Brainstoming forever
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/ItzCrazyKns/Vane/issues/1154 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 7. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/ItzCrazyKns/Vane | host_targets=claude, chatgpt
## 8. 配置坑 · 来源证据：OpenRouter-compatible streaming can crash on empty tool-call arguments
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：OpenRouter-compatible streaming can crash on empty tool-call arguments
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/ItzCrazyKns/Vane/issues/1150 | 来源类型 github_issue 暴露的待验证使用条件。
## 9. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/ItzCrazyKns/Vane | README/documentation is current enough for a first validation pass.
## 10. 运行坑 · 来源证据：OllamaEmbedding has no concurrency limit, causing 502 errors on embedding server under parallel searches
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：OllamaEmbedding has no concurrency limit, causing 502 errors on embedding server under parallel searches
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/ItzCrazyKns/Vane/issues/1147 | 来源类型 github_issue 暴露的待验证使用条件。
## 11. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/ItzCrazyKns/Vane | last_activity_observed missing
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/ItzCrazyKns/Vane | no_demo; severity=medium
## 13. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/ItzCrazyKns/Vane | no_demo; severity=medium
## 14. 安全/权限坑 · 来源证据：Search is broken
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Search is broken
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/ItzCrazyKns/Vane/issues/1143 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。
## 15. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/ItzCrazyKns/Vane | issue_or_pr_quality=unknown
## 16. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/ItzCrazyKns/Vane | release_recency=unknown