WeKnora deployment source with the reviewed wiki identity, summary and recovery fixes

2026-09-22 16:19:06 +08:00
commit f7fc992f57
3929 changed files with 1006607 additions and 0 deletions
@@ -0,0 +1,102 @@
+---
+title: 添加网络搜索引擎
+tags: [集成扩展, 搜索, 网络搜索, Provider]
+aliases: [网络搜索, WebSearch, 搜索引擎扩展]
+source: 添加新的网络搜索引擎.md
+---
+
+# 添加新的网络搜索引擎
+
+本文档说明如何在 WeKnora 中添加一个新的网络搜索引擎类型（如 Brave Search、Searx 等）。
+
+## 架构概述
+
+搜索引擎的 API 端点**硬编码**在代码中，不向用户暴露 BaseURL，从源头消除 SSRF 风险。
+
+```
+internal/types/web_search_provider.go       # 实体定义 + Provider 类型元数据
+internal/infrastructure/web_search/          # Provider 实现（bing/google/duckduckgo/tavily）
+internal/container/container.go              # DI 注册
+internal/types/interfaces/web_search.go      # WebSearchProvider 接口
+```
+
+> 类似的扩展开发模式参见 [集成向量数据库](../集成扩展/集成向量数据库.md)
+
+## 步骤
+
+以添加 **Brave Search** 为例：
+
+### 1. 注册类型常量
+
+在 `internal/types/web_search_provider.go` 中添加：
+
+```go
+WebSearchProviderTypeBrave WebSearchProviderType = "brave"
+```
+
+### 2. 添加类型元数据
+
+在 `GetWebSearchProviderTypes()` 中添加：
+
+```go
+{
+    ID: "brave", Name: "Brave Search", Free: false,
+    RequiresAPIKey: true, Description: "Brave Search API",
+    DocsURL: "https://brave.com/search/api/",
+}
+```
+
+### 3. 创建 Provider 实现
+
+新建 `internal/infrastructure/web_search/brave.go`：
+
+- 构造函数签名：`func(types.WebSearchProviderParameters) (interfaces.WebSearchProvider, error)`
+- API 端点**硬编码**为常量
+- 实现 `interfaces.WebSearchProvider` 接口：`Name()` 和 `Search()`
+
+### 4. 添加参数校验
+
+在 `isValidProviderType()` 中添加新类型。
+
+### 5. DI 注册
+
+在 `registerWebSearchProviders` 中注册。
+
+### 6. 验证
+
+```bash
+go build ./...
+# 调用 API 验证
+curl http://localhost:8080/api/v1/web-search-providers/types
+```
+
+## 需要额外参数的情况
+
+如果新引擎需要 API Key 以外的参数：
+
+- **方式一**：使用 `WebSearchProviderParameters.ExtraConfig` 字段
+- **方式二**：在 `WebSearchProviderParameters` 中添加专用字段
+
+## 文件变更清单
+
+| 文件 | 操作 |
+|------|------|
+| `internal/types/web_search_provider.go` | 添加常量 + 类型元数据 |
+| `internal/infrastructure/web_search/brave.go` | **新建** Provider 实现 |
+| `internal/application/service/web_search_provider.go` | `isValidProviderType` 加新类型 |
+| `internal/container/container.go` | `registerWebSearchProviders` 注册 |
+
+## 相关主题
+
+- [集成向量数据库](../集成扩展/集成向量数据库.md) — 同类扩展开发模式（接口实现 + 注册 + DI）
+- [MCP功能使用说明](../核心功能/MCP功能使用说明.md) — MCP 也可集成搜索工具
+- [常见问题](../运维排障/常见问题.md) — SSRF 白名单配置
+
+---
+
+## 反向链接
+
+- [Home](../Home.md) — Wiki 首页导航
+- [集成向量数据库](../集成扩展/集成向量数据库.md) — 同类扩展开发模式
+- [MCP功能使用说明](../核心功能/MCP功能使用说明.md) — MCP 搜索工具与网络搜索引擎互补
+- [版本路线图](../项目概述/版本路线图.md) — 路线图中的社区组件扩展方向