PandaWiki搜索功能详解：快速定位知识内容

一、搜索功能架构概述

PandaWiki作为一款企业级知识库管理系统，其搜索功能采用多维度检索架构，支持节点内容、飞书Wiki（维基）、文档文件等多源数据的统一查询。系统通过分层设计实现高效搜索：

flowchart LR
    A[用户搜索请求] --> B{请求类型}
    B -->|节点搜索| C[PostgreSQL模糊查询]
    B -->|飞书Wiki搜索| D[飞书API对接]
    B -->|文档搜索| E[MinIO文件索引]
    C --> F[结果排序与过滤]
    D --> F
    E --> F
    F --> G[前端展示]

核心技术特性：

• 多源数据整合：支持知识库节点、飞书文档、本地文件的跨源检索
• 实时索引更新：内容变更后自动同步索引，确保搜索结果时效性
• 权限控制：基于节点可见性（NodeVisibility）的权限过滤机制
• 高性能查询：PostgreSQL LIKE查询优化与飞书API分页加载结合

二、核心搜索功能实现

2.1 知识库节点搜索

节点搜索是PandaWiki最基础的搜索能力，通过PostgreSQL数据库实现对知识库节点（Node）的快速检索。

2.1.1 数据模型定义

// backend/domain/node.go
type GetNodeListReq struct {
    KBID   string `json:"kb_id" query:"kb_id" validate:"required"`
    Search string `json:"search" query:"search"` // 搜索关键词
}

type NodeListItemResp struct {
    ID         string         `json:"id"`
    Type       NodeType       `json:"type"`       // 1:文件夹 2:文档
    Status     NodeStatus     `json:"status"`     // 1:草稿 2:已发布
    Visibility NodeVisibility `json:"visibility"` // 1:私有 2:公开
    Name       string         `json:"name"`       // 节点名称
    Summary    string         `json:"summary"`    // 节点摘要
    // ...其他字段
}

2.1.2 SQL查询实现

// backend/repo/pg/node.go
func (r *NodeRepository) GetList(ctx context.Context, req *domain.GetNodeListReq) ([]*domain.NodeListItemResp, error) {
    var nodes []*domain.NodeListItemResp
    query := r.db.WithContext(ctx).
        Model(&domain.Node{}).
        Where("nodes.kb_id = ?", req.KBID).
        Select("nodes.id, nodes.type, nodes.status, nodes.visibility, nodes.name, nodes.parent_id, nodes.position, nodes.created_at, nodes.updated_at, nodes.meta->>'summary' as summary, nodes.meta->>'emoji' as emoji")
    
    // 搜索关键词处理
    if req.Search != "" {
        searchPattern := "%" + req.Search + "%"  // 前后模糊匹配
        query = query.Where("name LIKE ? OR content LIKE ?", searchPattern, searchPattern)
    }
    
    if err := query.Find(&nodes).Error; err != nil {
        return nil, err
    }
    return nodes, nil
}

查询优化策略：

• 使用LIKE %keyword%实现前后模糊匹配
• 同时检索节点名称（name）和内容（content）字段
• 通过kb_id过滤确保数据隔离性
• 利用JSONB字段meta提取摘要信息，减少表连接操作

2.2 飞书Wiki集成搜索

针对企业用户常用的飞书生态，PandaWiki实现了飞书Wiki的深度集成搜索，支持通过飞书API检索空间（Space）和文档内容。

2.2.1 搜索接口实现

// backend/usecase/feishu.go
func (f *FeishuUseCase) SearchWiki(ctx context.Context, req *domain.SearchWikiReq) ([]*domain.SearchWikiResp, error) {
    client := lark.NewClient(req.AppID, req.AppSecret)
    var (
        respData  []*domain.SearchWikiResp
        pageToken string
    )
    
    // 分页获取搜索结果
    for {
        r := larkwiki1.NewSearchNodeReqBuilder().
            PageSize(20).
            PageToken(pageToken).
            Body(larkwiki1.NewSearchNodeReqBodyBuilder().
                Query(req.Query).       // 搜索关键词
                SpaceId(req.SpaceId).   // 飞书空间ID
                Build()).
            Build()

        resp, err := client.Wiki.V1.Node.Search(
            ctx, 
            r, 
            larkcore.WithUserAccessToken(req.UserAccessToken)
        )
        if err != nil {
            return nil, fmt.Errorf("search Wiki failed: %v", err)
        }

        // 处理返回结果
        for _, v := range resp.Data.Items {
            if *v.ObjType == 9 {  // 过滤不需要的对象类型
                continue
            }
            respData = append(respData, &domain.SearchWikiResp{
                Title:    *v.Title,
                Url:      *v.Url,
                SpaceId:  *v.SpaceId,
                ObjToken: *v.ObjToken,
                ObjType:  *v.ObjType,
            })
        }
        
        if !*resp.Data.HasMore {  // 分页终止条件
            break
        }
        pageToken = *resp.Data.PageToken
    }
    return respData, nil
}

2.2.2 数据模型定义

飞书搜索相关的数据结构定义在domain层，确保接口一致性：

// backend/domain/feishu.go
type SearchWikiReq struct {
    AppID          string `json:"app_id" validate:"required"`
    AppSecret      string `json:"app_secret" validate:"required"`
    UserAccessToken string `json:"user_access_token" validate:"required"`
    SpaceId        string `json:"space_id" validate:"required"`
    Query          string `json:"query" validate:"required"`
}

type SearchWikiResp struct {
    Title    string `json:"title"`
    Url      string `json:"url"`
    SpaceId  string `json:"space_id"`
    ObjToken string `json:"obj_token"`
    ObjType  int    `json:"obj_type"`  // 5:文件 8:文档 2:表格
}

2.3 文档文件搜索

PandaWiki支持上传文档（如Markdown、PDF、Excel）的全文检索，通过MinIO存储与内容提取实现文件搜索能力。

2.3.1 文件搜索流程

sequenceDiagram
    participant User
    participant API
    participant MinIO
    participant Parser
    participant DB
    
    User->>API: 发起文件搜索请求(关键词)
    API->>DB: 查询文件元数据索引
    DB-->>API: 返回匹配的文件列表
    loop 处理每个文件
        API->>MinIO: 获取文件内容
        MinIO-->>API: 返回文件数据流
        API->>Parser: 解析文件内容
        Parser-->>API: 提取文本内容
        API->>API: 关键词匹配验证
    end
    API-->>User: 返回搜索结果

核心实现代码位于FeishuUseCase的ListDocx方法，支持并发处理多个文件的内容提取与关键词匹配。

三、搜索功能使用指南

3.1 基础搜索操作

用户可通过两种方式发起搜索：

1. 全局搜索：页面顶部搜索框输入关键词，系统自动检索所有可访问内容
2. 知识库内搜索：在特定知识库页面使用搜索框，仅检索当前知识库内容

搜索语法支持：

• 空格分隔多个关键词（逻辑与）
• 支持中文、英文、数字混合检索
• 忽略特殊字符（如_、-、#）的精确匹配

3.2 高级搜索技巧

3.2.1 节点类型过滤

通过节点类型（文件夹/文档）过滤搜索结果：

关键词 type:document  # 仅搜索文档节点
关键词 type:folder    # 仅搜索文件夹节点

3.2.2 状态过滤

根据节点状态（草稿/已发布）筛选：

关键词 status:draft     # 仅显示草稿节点
关键词 status:released  # 仅显示已发布节点

3.2.3 组合条件搜索

使用逻辑运算符组合多个条件：

关键词 AND type:document AND status:released

3.3 搜索结果解读

搜索结果页面包含以下关键信息：

• 匹配度标识：关键词高亮显示，反映匹配程度
• 节点路径：显示节点在知识库中的层级位置
• 更新时间：内容最后更新时间戳
• 访问权限标识：显示内容的可见性状态

四、性能优化与最佳实践

4.1 性能优化建议

1. 索引优化：对频繁搜索的字段（name、content）建立合适索引

   CREATE INDEX idx_nodes_name ON nodes USING btree (name);
   CREATE INDEX idx_nodes_content ON nodes USING gin (to_tsvector('english', content));
   

2. 查询优化：避免使用%keyword前缀模糊查询，会导致索引失效

3. 结果缓存：对热门搜索词结果进行缓存，减少重复查询

4. 异步处理：飞书API调用使用异步处理，避免阻塞主线程

4.2 常见问题解决

4.2.1 搜索结果不完整

可能原因及解决方法：

• 权限限制：确认是否有访问相关节点的权限
• 索引未更新：内容刚更新可能未同步索引，等待1-2分钟后重试
• 关键词过于特殊：尝试更通用的关键词或减少关键词数量

4.2.2 搜索响应缓慢

优化措施：

• 减少单次搜索的关键词数量
• 缩小搜索范围（如指定知识库或节点类型）
• 避开系统高峰期使用搜索功能
• 联系管理员检查数据库性能状态

五、未来功能规划

1. 全文检索引擎集成：计划引入Elasticsearch实现更高效的全文检索
2. 语义搜索：基于向量数据库实现语义相似性搜索，支持同义词和相关概念推荐
3. 搜索分析：增加搜索行为分析，提供热门搜索词和用户搜索习惯统计
4. 高级筛选器：添加更多维度的筛选条件（如创建时间、更新时间、作者等）

通过持续优化搜索功能，PandaWiki将进一步提升知识管理效率，帮助企业用户快速定位所需信息，实现知识资产的最大化利用。