文章

WeKnora知识库简介

WeKnora（维娜拉）是腾讯开源的知识库框架：同一套库同时做 RAG 问答、ReAct 智能体和 Wiki。空间内置四级角色、API Key 与 MCP 端点可限定知识库范围；WorkBuddy 用 Streamable HTTP 接内置端点即可检索。部署、权限边界和与 Dify、FastGPT、RAGFlow 的对照以官方文档当时说明为准。

发表于
Preview Image
作者 handsomestwei
24 分钟阅读
WeKnora知识库简介

WeKnora知识库简介

WeKnora（维娜拉） 是腾讯开源的企业级知识管理框架，许可证为 MIT（第三方组件另有许可证，再分发时要带上 THIRD_PARTY_NOTICES）。它把文档解析、混合检索、引用问答、智能体工具和 Wiki 整理放在同一套知识库上，并按 工作空间 做多租户隔离。本文说明主要功能、部署形态、权限模型，以及怎样用 MCP 接到 WorkBuddy。接口、菜单和默认值以 官方文档 当时版本为准（文中能力对照约到 v0.8.2 的发布说明）。

参考与延伸阅读：

目录

一、定位

WeKnora 的主路径是：资料进知识库 → 检索 → 带引用的回答。智能体和 Wiki 共用这批资料，而不是另建一套文档库。

项说明
形态开源自托管（Go 后端 + Vue 3 前端 + Python docreader），不是只能用的云 SaaS
三种用法RAG 问答、ReAct 智能体、Wiki 整理，检索同一知识库
权限边界工作空间（后端称 Tenant）；组织可把知识库 / 智能体共享给其它空间
模型LLM、Embedding、Rerank、VLM、ASR 分开配置；Ollama 或 OpenAI 兼容接口均可
和「再套一层工作流」的差别编排节点不是它的主界面；强项是文档理解、检索、空间权限，以及把库发布成 MCP

系统由三块组成：app（Gin，默认 8080）负责 API、检索、Agent 和异步任务；frontend（Nginx，默认 80）反代 /api；docreader（gRPC 50051，不映射到宿主机）把文件转成 Markdown。检索引擎默认是 ParadeDB（PostgreSQL 17 + BM25 / 向量扩展），队列用 Redis。

二、主要功能

文档接入与解析

上传 PDF、Word、PPT、Excel、Markdown、HTML、EPUB、XMind、图片、音频；也可抓 URL、手写 Markdown、整目录上传。数据源可定时同步飞书 / Lark、Notion、Confluence、语雀、钉钉文档、腾讯 IMA、GitLab、RSS。

解析侧包括版式分析、扫描件 OCR、表格抽取、VLM 图片描述、ASR 转写。解析引擎可按文件类型切换，文档提到可接 MinerU、OpenDataLoader / Docling。分块支持父子分块和自适应策略；索引可以是向量、关键词、FAQ、预生成问题，以及可选的知识图谱（Neo4j）。

检索与问答

默认是向量 + BM25 混合检索，RRF 融合，再可选 Rerank。查询侧有改写、扩展和意图识别（寒暄、闲聊、要不要走网页搜索等）。问答走 SSE 流式输出，带回引用。会话可以多轮压缩、从历史提问分叉或回滚。

RETRIEVE_DRIVER 可换成 Qdrant、Milvus、Weaviate、Doris、Elasticsearch 或腾讯云向量库；后两者不随 compose 一起启动，要自备。

智能体、技能与 MCP 客户端

内置快速问答、智能推理、数据分析和 Wiki 等 Agent。自定义 Agent 绑定模型、知识范围和工具。工具包括检索知识、读文档、列文档、搜 Wiki、对 CSV / Excel 做 SQL 分析，以及网页搜索（可自建 SearXNG）。

这里的 MCP 服务（MCPService） 是 WeKnora 去调用外部工具：传输支持 SSE 和 Streamable HTTP，认证可以是 API Key、Bearer 或 OAuth 2.0。技能在 Docker、Cube 或 E2B 沙箱里跑脚本；Docker 沙箱默认关闭，打开后挂载 docker.sock 等同宿主机 root，生产上要单独评估。长期记忆按空间和调用者保存偏好与事实，默认关闭。

把知识库发布出去

同一套库还可以对外：REST（/api/v1）、空间级 API Key、内置 MCP Server、CLI、微信小程序、浏览器插件、嵌入渠道、企业微信 / 飞书等 IM。可观测可接 Langfuse（compose 的 langfuse profile）。敏感凭证以 AES-256 落盘，密钥是 SYSTEM_AES_KEY，升级时必须沿用原值，否则已存凭据解不开。

三、部署

官方给出的形态如下。团队自托管推荐 Docker Compose；个人离线用 Lite。

形态数据与队列适合
Docker ComposeParadeDB + Redis / Asynq生产、团队，推荐
Helm（helm/）chart 内置 ParadeDB 与 RedisKubernetes ≥ 1.25
Lite 单二进制SQLite（FTS5 + sqlite-vec）+ 内存队列个人、离线、低资源
桌面应用（文档标明未正式发布）SQLite + 内存队列本机图形界面

标准 Compose 建议 4 核 / 8GB 起，这 8GB 不含 本地模型权重。docreader 带 LibreOffice、Playwright，内存占用高于纯 API 服务。打开 Milvus、Langfuse、Neo4j 要再加资源。Neo4j 默认不启，图谱要单独开 neo4j profile。

最短启动路径（密钥必须自己生成，不要用文档示例里的空值上生产）：

1
2
3
4
5
6

git clone https://github.com/Tencent/WeKnora.git && cd WeKnora
cp .env.example .env
# JWT_SECRET: openssl rand -hex 32
# SYSTEM_AES_KEY: openssl rand -hex 16   （32 字节；升级时禁止更换）
# 同时填写 DB_USER / DB_PASSWORD / DB_NAME、REDIS_PASSWORD
make start-all

浏览器打开 http://localhost（FRONTEND_PORT，默认 80）。前端把 /api/ 反代到后端；http://localhost:8080/health 可直接探活。停止用 docker compose down；加 -v 会删数据卷。升级时先把 .env 里的 WEKNORA_VERSION 设到目标版本再 docker compose pull && docker compose up -d，只 up -d 可能继续用本地旧镜像。

Lite：make build-lite / make run-lite，依赖 .env.lite，没有 Redis。不适合多副本和要持久任务队列的团队部署。

镜像名形如 wechatopenai/weknora-app、weknora-ui、weknora-docreader。Postgres 默认不映射到宿主机端口。

四、多租户与数据访问权限

工作空间是资源边界：知识库、模型、智能体、会话和存储配额都属于空间。一个用户可以加入多个空间，每个空间一套角色。平台级系统管理员（管全局设置、任务队列、跨空间审计）和空间 Owner 分开授予，Owner 不能自动变成平台管理员。

角色能做什么
Viewer读取、用会话提问
Contributor可创建知识库和智能体；改的是自己创建的资源
Admin成员之外的空间级配置（模型、渠道、基础设施等）
Owner空间生命周期、成员与角色、API Key；可删除或转让空间

删除空间是软删除：成员立刻失去访问，库内数据不会马上物理清空。

组织用来跨空间共享。两个空间先加入同一组织，再把知识库或智能体「共享到组织」。接收方的有效权限取 共享记录上限 和 对方在组织里的角色 的交集，本空间若只是 Viewer，共享侧给到编辑也会被压成只读。来源空间退出组织后，它共享出去的库和智能体会一并撤销。接收方改不了存储绑定，也看不到模型 Base URL 一类凭据。

程序访问不走登录角色，而走 API Key（请求头 X-API-Key）：

Key范围
空间 Key绑在一个空间；带 X-Tenant-ID 指到别的空间会 403
平台 Key系统管理员签发，调用时必须带 X-Tenant-ID 选择空间
full_access空间内近似 Owner 的机器身份
受限 Key按能力放行：检索 retrieve、入库 ingest、问答 chat，以及管理知识库、智能体、模型、渠道等；并可加 knowledge_base_ids 白名单

未在路由上声明策略的接口，对任何 API Key 默认 403。也就是说：Key 不是「登录令牌的另一种写法」，漏标能力就进不去。

另外几道闸门：注册可改成仅邀请（auth.registration_mode=invite_only，旧变量 DISABLE_REGISTRATION=true 在启动时会写成同一模式，但库里的系统设置优先级更高）；可接 OIDC，不过 OIDC 首次登录不读邀请开关，IdP 里的人仍可能开户，范围要在 IdP 侧收。审计日志默认保留约 90 天。WEKNORA_TENANT_ENABLE_RBAC 关掉时，空间角色守卫只记日志不拦截（系统管理员守卫不受影响），上线前确认它是开的。

出站还有 SSRF 防护，可选只允许白名单域名。

五、和其他平台对照

下面比的是 知识库产品里的租户和数据范围，不是召回率。Dify、FastGPT 的强项在工作流编排；RAGFlow 的强项在文档解析。WeKnora 把「空间角色 + 组织共享 + Key/MCP 限定库」做进开源主线。

维度WeKnoraDifyFastGPTRAGFlow
主界面知识库、引用问答、Agent、Wiki应用与工作流知识库与工作流数据集、解析与对话
开源协议MIT（第三方组件除外）社区版开源；细粒度权限在企业版文档开源，权限模型在其官方博客中按团队 + ACL/RBAC 描述Apache-2.0；更细的知识库 RBAC 常见于 KnowFlow 等扩展
租户工作空间；一人多空间；组织跨空间共享Workspace；企业版另有管理后台角色模板团队隔离，资源按团队切开有团队/租户；开源侧知识库可见性更接近「仅自己 / 团队」
人的角色Viewer / Contributor / Admin / Owner，再加独立系统管理员社区版成员角色较粗；企业版可到「知识库只读 / 编辑 / 指定成员」资源上的角色位，支持继承开源默认不做部门级只读/编辑矩阵
程序访问范围API Key 按能力 + 知识库白名单；MCP 端点再收一层工具和库知识库 Service API Key；企业版可配谁能进哪个库应用与知识库权限走团队 ACL多为数据集 API，库级 ACL 要自建或用扩展
对外给别的 Agent内置 MCP 端点，按空间发布插件 / 工具视版本工作流里接工具节点以 HTTP API 为主
检索底座默认 ParadeDB 混合检索，可换向量库，可选图谱向量检索 + 可选重排混合检索与重排深度解析、版式和分块是长项

选型可以这么看：

  • 要在 一个开源部署里 把「谁能看哪套制度文档」和「机器人 Key 只能搜某几个库」一起做完，WeKnora 的空间、组织共享和 Key 白名单是直接能力。
  • 要的是 可视化编排（意图分库、参数自检、多节点），Dify / FastGPT 的工作流更顺手，权限以各自企业版或团队 ACL 为准。
  • 痛点在 扫描件、复杂版式、解析质量，RAGFlow 仍是更常被拿来对比的解析引擎；它的开源权限不等于 WeKnora 这套四级角色加组织共享。

三者可以叠：解析用 RAGFlow 一类管道，编排用工作流，权限和对外 MCP 用 WeKnora。叠的时候各管各的租户 ID，不要假设账号体系自动打通。

六、用 MCP 接到 WorkBuddy

MCP 在 WeKnora 里有两个方向，接到 WorkBuddy 用的是 第二个。

方向是什么谁发起调用
MCP 服务（工具箱里的 MCPService）WeKnora 的智能体去调外部工具WeKnora
内置 MCP Server把本空间的知识库发布成 MCP，给 WorkBuddy、Cursor、Claude 等用外部客户端

自 v0.8.2 起，不必再单独起仓库里的 Python mcp-server/（文档已标为弃用）。在空间里打开 设置 → 发布集成 → MCP Server，新建端点：

  1. 勾选可访问的知识库。空列表表示空间内全部库；要做数据隔离就只勾该 WorkBuddy 场景需要的库。
  2. 勾选工具。工具分四组：检索与阅读、问答（跑端点上指定的智能体）、Wiki、写入。写入默认关闭。创建时若不指定工具，默认是全部只读工具。
  3. 记下端点路径 /mcp/<endpoint_id>（没有 /api/v1 前缀）和 一次性令牌。令牌可轮换，轮换后旧令牌立即失效。默认每分钟 60 次，上限 6000。
  4. 管理端点要 Admin 及以上；只读成员可以看列表，看不到完整令牌。用受限 API Key 去创建端点时，端点的库和工具不能超出该 Key 的能力，否则 403。

认证头是：

1

Authorization: Bearer <endpoint_token>

请求以 端点所属空间的机器身份 执行，看不到端点没勾的库，也调不了没勾的工具。这和「拿一个用户的登录 JWT 去搜全部库」不是同一条路径。

WorkBuddy 的 MCP 配在界面里：侧边栏 → 插件 → MCP 服务器 → 配置 MCP。配置文件二选一：

级别路径何时用
用户级~/.workbuddy/mcp.json这台机器上的项目都连同一套知识库
项目级<项目>/.workbuddy/mcp.json只让当前项目看见这套库

内置端点是 Streamable HTTP，按 WorkBuddy 的 HTTP MCP 写法：

1
2
3
4
5
6
7
8
9
10
11

{
  "mcpServers": {
    "weknora": {
      "type": "http",
      "url": "https://kb.example.com/mcp/<endpoint_id>",
      "headers": {
        "Authorization": "Bearer <endpoint_token>"
      }
    }
  }
}

保存后看状态：绿色表示连上，红色则查地址、令牌和反代是否把 /mcp/ 转到 app:8080（不要只反代 /api/）。只支持 stdio 的客户端要用 mcp-remote 做桥；WorkBuddy 文档支持 HTTP 类型，不必再包一层本地 Python 进程。

令牌不要写进仓库。用户级配置放在本机家目录；项目级文件若提交，应改成环境变量占位，由 WorkBuddy 自己的密钥机制注入。一个空间可以发多个端点：制度库只读端点给全员 WorkBuddy，写入端点只给维护组，调用频率分开限。

更早的部署若仍在跑独立 MCP 进程（WEKNORA_BASE_URL + WEKNORA_API_KEY，stdio），那是旧路径。新接入以空间内端点为准。社区的多用户派发网关面向更老的 v0.7.x MCP 进程，不是 v0.8.2 内置端点的替代品。

七、其它接入

方式用途
REST + X-API-Key业务系统检索、入库、问答；用受限 Key 把库收窄
组织共享两个团队各一个空间，只共享某一库，不合并成员
IM / 嵌入渠道企微、飞书、网页挂件；嵌入走单独的 publish token，和 API Key 不是同一套
Claw Skill面向 OpenClaw 一类客户端，用空间 API Key 调 REST，覆盖导入、检索、浏览；要问答和按库限权仍用 MCP 端点
CLI设置 → 发布集成 → CLI
可观测Langfuse profile，或把现有 Langfuse 指到模型调用

图片引用默认是内部句柄 resource://，客户端再凭登录去拉 /files。改成公开预签名直链（resource_urls=public）后，链接在过期前匿名可读，限定了知识库的 API Key 会被 403 挡住，避免用直链绕过白名单。

八、适用边界

适合。 私有化、多团队共用一套部署，又要按空间和知识库切开；希望 WorkBuddy 或 Cursor 用 MCP 查制度、项目文档，且写入默认关掉；模型要能换成内网推理。

不适合当唯一编排器。 复杂分支、多知识库意图路由、人工审批节点，仍是 Dify / FastGPT 一类工作流更直接。WeKnora 的 Agent 是 ReAct 和工具，不是一张可视化流程图。

权限要配完才算隔离。 只建空间、Key 却用 full_access，或 MCP 端点的知识库列表留空，机器人就能看见该空间全部库。组织共享再叠 Viewer 封顶，配错会出现「共享了但对方只能看」或「AND 过滤为空」。RBAC 开关、邀请注册和 OIDC 是否放行，上线时单独核对。

Lite 不是团队权限方案。 单机 SQLite 能体验解析和问答，多租户、队列和对象存储以 Compose / Helm 为准。

九、小结

要点结论
是什么腾讯开源的知识库框架：RAG、Agent、Wiki 共用一套库
部署团队用 Compose（ParadeDB + Redis）或 Helm；个人用 Lite
权限空间四级角色 + 组织共享取交集；API Key 按能力并白名单知识库
接到 WorkBuddyv0.8.2 起用内置 MCP 端点 /mcp/<id>，Bearer 端点令牌，写入默认关
和编排平台Dify / FastGPT 强在工作流；RAGFlow 强在解析；WeKnora 强在开源主线里的租户和对外发布
注意SYSTEM_AES_KEY 不能换；RBAC 关掉等于角色不拦截；端点不勾库等于空间内全库

先定空间怎么划、哪些库能进 MCP，再选 Compose 还是 Lite。WorkBuddy 只配只读端点，写入留在 WeKnora 控制台或单独的维护端点上。

AI, RAG
AI RAG WeKnora WorkBuddy
本文由作者按照 CC BY 4.0 进行授权