WeKnora/website-docs

WeKnora 文档

WeKnora（维娜拉）是腾讯开源的企业级知识库与 RAG（Retrieval-Augmented Generation）系统：Go 单体后端 + Vue 3 前端 + Python 文档解析微服务（docreader），支持多租户、多知识库、混合检索、Agent 智能体、知识图谱、Wiki 生成、MCP 集成、多平台 IM 接入与网页嵌入等能力。

本目录是 WeKnora 的完整官方文档，全部内容基于源码整理，按「入门 → 架构 → 功能 → API → 客户端 → 开发」六个部分组织。

文档站点

本目录同时是一个 VitePress 站点，Markdown 即页面，新增文件会自动进入侧边栏（标题取正文一级标题，目录顺序按文件名数字前缀）。

npm install
npm run dev      # 本地预览
npm run build    # 产物输出到 .vitepress/dist
npm run preview  # 预览构建产物

主题位于 .vitepress/theme/：style.css 是排版与配色的单一来源，Landing.vue 是首页。

阅读路径建议

• 初次使用：01 快速开始 四篇按顺序读完即可完成部署与首次问答。
• 评估选型 / 了解原理：02 架构 五篇给出系统全貌与两条核心流水线（文档入库、检索问答）。
• 使用某项具体功能：直接查 03 功能模块 对应章节。
• 对接 API / 写集成：04 API 参考 + 05 客户端（CLI / Go SDK）。
• 二次开发 / 贡献代码：06 开发指南，尤其是扩展点指南。

目录

01 快速开始

文档	内容
产品介绍	WeKnora 是什么、核心概念（租户/知识库/知识/分块/会话/Agent 等）、功能总览与系统组件图
安装部署	docker-compose（含 12 个可选 profile）、开发模式、Helm、Lite 单二进制、macOS 桌面端、Homebrew
快速上手	注册 → 初始化向导 → 配置模型 → 建库 → 上传 → 问答的完整路径，含可直接执行的 curl 链路
配置详解	config.yaml 全字段、约 150 个环境变量、prompt 模板、内置模型与内置 Agent 配置

02 架构

文档	内容
总体架构	组件构成、技术栈、进程间通信、顶层目录导览
Go 后端设计	四层架构、uber/dig 依赖注入、启动与优雅退出、路由与中间件、领域模型 ER 图
文档入库流程	上传/URL/手动创建 → 存储 → 解析 → 分块 → 向量化 → 索引 → 后处理的全链路与状态机
检索问答流程	chat_pipeline 插件流水线、跨库检索与融合、重排、流式输出（SSE）与引用生成
异步任务系统	asynq 队列拓扑、6 个 worker pool、Lite 同步模式、死信与任务巡检、事件总线

03 功能模块

文档	内容
租户、用户与认证授权	多租户模型、JWT / API Key / OIDC、RBAC 角色矩阵、组织与共享空间
知识库与知识管理	知识库类型与全部可配置项、标签、预览安全、复制与移动、活动流、配额
文档解析服务 docreader	gRPC 接口、三引擎注册表、13 个解析器矩阵、并发模型、部署与扩容
分块机制	自适应分块架构（heading/heuristic/recursive）、父子分块、ContextHeader、调试端点
检索引擎与向量存储	各检索引擎（向量/BM25/全文/混合）能力对比、驱动选择、维度管理、打分归一化
模型管理	5 类模型、27 个厂商 Provider、内置模型机制、Ollama 本地模型、限流与用量
Agent 引擎	ReAct 循环、24 个内置工具、上下文与记忆管理、技能系统与沙箱、自定义 Agent
MCP 集成	MCP 客户端管理、OAuth 2.0 + PKCE 全流程、工具审批、WeKnora MCP Server
知识图谱	两级开关、LLM 实体关系抽取、Neo4j 存储、图谱增强检索
数据源导入	连接器体系（飞书/Lark/Notion/语雀/RSS）、凭据加密、同步调度与增量更新
网络搜索与网页抓取	9 个搜索引擎、SSRF 防护、web_fetch 双实现、SearXNG 自托管
IM 集成	10 个 IM 平台适配、消息处理流水线、内置命令、流式渲染、多实例协同
网页嵌入 Embed Channel	嵌入渠道配置、匿名会话与 token 交换、安全模式、webhook、接入示例
Wiki 能力	基于知识库的 LLM Wiki 站点生成、四阶段管道、slug 机制、issue 闭环
评估能力	评估任务、Parquet 数据集格式、12 项检索/生成指标
可观测性与审计	日志体系、Langfuse 追踪、审计日志与保留策略、限流、健康检查
FAQ 能力	FAQ 条目模型、批量导入与去重、检索命中策略、克隆同步

04 API 参考

以 internal/router/router.go 为事实来源整理，共覆盖约 360 个端点，每个端点含权限要求、参数表与 curl 示例。

文档	内容
API 总览	Base URL、三种认证方式、通用响应包与错误码、分页规范、SSE 协议、限流
认证与用户	/auth 注册登录、token 刷新、邀请
租户与成员	租户、成员、邀请、API Key、审计
组织与共享	组织、知识库共享、Agent 共享
知识库与知识	知识库、知识、分块、标签、分块预览
FAQ 与 Wiki	FAQ 管理与导入、Wiki 读写
会话与聊天	会话、消息、知识问答与 Agent 对话（SSE）
模型与系统	模型、初始化向导、系统设置、系统管理、评估
基础设施与数据源	向量存储、存储后端、Web 搜索、数据源
Agent 与 MCP	Agent、MCP 服务、OAuth、技能、收藏
IM、Embed 与文件	IM 回调与渠道、微信扫码、Embed、文件服务

05 客户端

文档	内容
Web 前端	Vue 3 + TDesign 技术栈、页面路由、状态管理、i18n、部署
命令行工具 CLI	17 个命令组、多 profile 配置、输出格式与退出码、脚本化用法
Go SDK	约 170 个方法的资源覆盖、流式对话、错误处理、完整示例
微信小程序	页面结构、后端地址与 API Key 配置、构建发布
桌面端	Wails macOS 应用、内嵌 Lite 后端、偏好设置与自动更新

06 开发指南

文档	内容
开发指南	环境要求、Makefile 全目标、开发模式、四条测试线、CI 与代码规范、调试技巧
数据库与迁移	40+ 张表结构与 ER 图、golang-migrate 双路径、新增迁移步骤、故障排查
扩展点指南	9 大扩展点：解析器/分块策略/检索引擎/模型 Provider/搜索引擎/数据源连接器/IM 适配器/Agent 工具/存储后端

系统组件速览

flowchart LR
    subgraph Clients["客户端"]
        FE["Web 前端 Vue 3"]
        CLI["CLI weknora"]
        SDK["Go SDK"]
        MINI["微信小程序"]
        EMBED["网页嵌入挂件"]
        IM["IM 平台 x10"]
    end
    subgraph Core["核心服务"]
        APP["app 主服务 Go/Gin :8080"]
        DR["docreader 解析服务 Python gRPC :50051"]
    end
    subgraph Infra["基础设施"]
        PG[("PostgreSQL / ParadeDB")]
        RD[("Redis + asynq")]
        VS[("向量/检索引擎 可选多种")]
        OBJ[("对象存储 local/minio/cos/oss/s3 等")]
        NEO[("Neo4j 知识图谱 可选")]
    end
    LLM["LLM / Embedding / Rerank / VLM 多厂商"]
    FE --> APP
    CLI --> APP
    SDK --> APP
    MINI --> APP
    EMBED --> APP
    IM --> APP
    APP --> DR
    APP --> PG
    APP --> RD
    APP --> VS
    APP --> OBJ
    APP --> NEO
    APP --> LLM

文档约定

• 文中源码路径均相对仓库根目录，如 internal/agent/engine.go。
• API 路径默认带 /api/v1 前缀；认证方式见 API 总览。
• 配置示例中的密钥均为占位符，生产环境务必替换（尤其 JWT_SECRET、SYSTEM_AES_KEY、数据库口令）。
• 文档基于仓库 v0.7.1 版本源码整理。