从 RBAC 到 CLI/API/MCP 收官之作
WeKnora 详解系列 · 第 04 篇（收官）
各位数码圈的老铁们，我是叨叨数码。
不知不觉，这个 WeKnora 系列已经写到第 4 篇了——前 3 篇咱们聊了"怎么跑起来"、"怎么接数据"、"怎么调检索和模型"，按数码圈的话讲，硬件、软件、生态都拆完一遍了。
那这第 4 篇收官之作，咱聊点啥？
聊"怎么用得稳 + 怎么用得深"——对应两块硬核内容：
🏢 企业治理：权限、加密、审计、合规——让 IT 部门能拍板"上线" 🛠️ 开发者工具：CLI、API、MCP Server、扩展、小程序——让程序员能玩出花
这一篇是整个系列里"最硬"的一篇，但也是最能体现 WeKnora "企业级" 三字含金量的一篇。
按数码圈"测完硬件要拆机看做工"的惯例——今天咱们把 WeKnora 的"做工"拆给你看。
一、权限：4 级 RBAC，把"谁能干啥"写在规矩里
在企业里推一个 AI 系统，IT 部门第一个问题永远是："权限怎么配？"
这个好理解——总不能让实习生也能删掉公司所有产品文档吧。
WeKnora 给了一套4 级 RBAC 权限模型，从大到小：
| Owner（所有者） | ||
| Admin（管理员） | ||
| Viewer（查看者） |
资源隔离也做得够细：每个知识库都有独立的所属权配置，不同租户的资源完全隔离，跨租户访问？门儿都没有。
叨叨的实操建议：
🔹 老板/部门负责人：Owner 角色（数量控制在 1-2 个） 🔹 IT 管理员 / 业务方对接人：Admin 角色 🔹 普通员工 / 客服：Viewer 角色
如果你想细究每个角色的具体权限矩阵，可以去翻 `docs/RBAC说明.md`，里面写得明明白白。
二、安全：加密 / 沙箱 / 防护，3 层铠甲
如果说 RBAC 是"门禁系统"，那安全体系就是"铠甲 + 盾牌 + 武器"。
WeKnora 在 v0.6.0 之后把安全层做了个大满贯升级，覆盖 4 个核心维度：
第一层：数据加密（AES-256-GCM）
所有 API 密钥、MCP 服务凭证、数据源凭证，全部静态加密存。
什么叫"静态加密"？就是数据写进数据库的那一刻就是密文，就算有人把整个数据库 dump 走，看到的也是一串乱码。
而且支持"平滑密钥轮换"——这个太关键了。传统做法是：换密钥必须停机，否则新老密钥不一致会出问题。WeKnora 不用，轮换过程业务不中断，对生产环境友好度拉满。
数码类比：像 iPhone 的"高级数据保护"——数据上锁、钥匙定期换、换钥匙过程你完全无感。
第二层：传输安全（gRPC TLS + Token）
应用服务和 docreader 之间的 gRPC 通信默认开启 TLS 加密，同时支持 Token 鉴权。
这意味着什么？就算内网被监听，抓包也只能看到加密数据流，看不到具体内容。
数码类比：像 Wi-Fi 6E 的 WPA3 加密——协议级安全，不是应用层糊一层。
第三层：SSRF 防护
这是企业最容易被忽视、但后果最严重的攻击点——SSRF（服务端请求伪造）。
通俗讲：黑客诱导你的服务器去访问内网敏感地址（比如 127.0.0.1、192.168.0.1），把内部数据偷出来。
WeKnora 内置了SSRF 安全 HTTP 客户端，所有外部 HTTP 请求都过一遍白名单校验，默认禁止访问内网地址。
这一条，对所有要上生产的项目都是必选项。少了它，分分钟被安全团队打回来。
第四层：Agent 沙箱执行
ReAct Agent 调外部工具时，默认在沙箱里跑。
就算有恶意代码想"越狱"，也跑不出沙箱的边界。
数码类比：像 iOS 系统的"App 沙盒"——App 之间互相隔离，恶意 App 也影响不到系统。
三、审计：每一步都留痕，合规党狂喜
企业上线任何一个系统，合规部门都要问："出了问题能不能追溯？"
WeKnora 给的回答是："能，每一步都留痕。"
每个租户都有独立的审计日志，记录：
📝 用户管理操作（新增/删除/权限变更） 📝 知识库变更（创建/删除/文档上传） 📝 配置修改（LLM 切换、模型参数调整） 📝 对话调用（谁问了什么、AI 回了什么） 📝 权限变更（谁被提权/降权了）
支持按操作类型、时间、操作人三个维度筛选查询，金融、政务、医疗这种重合规行业直接用。
数码类比：像行车记录仪 + 飞机黑匣子——平时没用，出事就是唯一证据。
四、可观测：Langfuse 全链路追踪 + E2E 评估
这一节是程序员和运维的福音。
WeKnora v0.6.1 之后移除了 Jaeger，全栈只留一个追踪后端——Langfuse。这个决定很果断，但选得很对——工具太多反而没人用。
Langfuse 追踪能看到啥？
🧠 ReAct 循环全流程：每一步推理、每次工具调用都看得到 📊 Token 消耗统计：每次对话花了多少 Token、钱从哪儿烧的 🔧 工具调用详情：MCP 工具、内置工具、网页搜索的入参出参耗时 📄 文档解析时间线：解析每阶段进度，支持中途停止，避免跑了一小时才发现是垃圾文档
▲ Langfuse 追踪面板：ReAct 循环、Token、工具调用一屏全显（来源：官方 docs/images/langfuse.png）
E2E 评估：3 个核心指标
光看追踪还不够，你得知道"AI 答得对不对"。WeKnora 内置了 3 个指标：
| 召回命中率 | |
| BLEU | |
| ROUGE |
叨叨的实操建议：每次改完检索策略或 Prompt 模板，跑一遍 E2E 评估，看指标变化再决定是否上线。别凭感觉，别靠"我看着挺好"——数据说了算。
五、CLI：程序员的最爱，类 gh 风格
聊完治理，聊"扩展"。
先说 CLI——命令行工具。这是程序员/运维的最爱，因为它能写脚本、能批处理、能塞进 CI/CD。
WeKnora 官方 CLI 叫 weknora，当前版本 v0.9。设计风格参考 GitHub 官方的 gh 命令——名词 + 动词的结构，记忆成本极低。
5 个最常用的命令：
# 登录指定实例 weknora auth login --host https://kb.example.com
# 列出所有知识库 weknora kb list
# 绑定当前目录到指定知识库 weknora link --kb my-knowledge-base
# 上传文档到知识库 weknora doc upload notes.md
# 发起对话 weknora chat "summarise the design doc"
默认输出人类可读格式，加 --json 参数输出稳定 JSON，写脚本、做自动化、接 CI/CD 全能用。
叨叨最爱的一个场景：每天凌晨 3 点定时把当天新增的 Confluence 文档自动同步到 WeKnora，cron + weknora doc upload + 一行 shell 就完事儿。
v0.9 还内置了 Agent 技能（weknora-rag-search、weknora-shared），意思是其他 AI Agent 也能直接调用这个 CLI 当工具用。
六、API + MCP Server：让第三方系统"长出" AI 能力
CLI 是给"人"用的，API 和 MCP 是给"机器"用的。
RESTful API + OpenAPI 文档
完整的 RESTful API，覆盖所有功能：知识库管理、文档上传、对话调用、配置管理……
还配了 OpenAPI 规范文档，意味着：
✅ Swagger UI 在线调试 ✅ 一键生成各语言 SDK（TypeScript、Python、Go、Java……） ✅ Postman / Apifox 导入即用
详细文档在 docs/api/README.md，常见问题排查看 docs/QA.md。
MCP Server：AI 时代的"USB-C 接口"
这可能是整个工具链里最值得吹爆的一个。
MCP（Model Context Protocol）是 Anthropic 主导的开放协议，专门解决"AI Agent 怎么调外部工具"的问题。WeKnora 实现了完整的 MCP Server，支持三种传输方式：
| stdio | |
| SSE | |
| HTTP |
数码类比：像 USB-C 接口——一个口，走遍天下。
叨叨的脑洞场景：你团队在用 Cursor 写代码，在 Claude Desktop 里做方案设计，两边的 AI Agent 都能通过 MCP 直接调 WeKnora 查内部知识库。这就是 MCP 的"通用胶水"价值。
七、扩展生态：Chrome / 微信小程序 / ClawHub
最后聊点"边边角角但很香"的扩展。
Chrome 扩展：所见即所得的"知识采集器"
装上 Chrome 扩展后，在浏览器里看到啥都能一键存到 WeKnora：
选中文本 → 右键 → 存到知识库 选中图片 → 右键 → OCR + 存储 整个网页 → 一键归档
官方地址：Chrome 应用商店
叨叨亲测场景：刷技术博客时，看到好文章右键一下，当天就同步到 WeKnora 的"技术文章"知识库，晚上回家直接问 AI 要摘要。
微信小程序：移动端入口
在微信里就能用 WeKnora：
配置 API 地址 选择知识库 导入 URL 发起知识对话
详细说明在 miniprogram/README.md。
ClawHub Skill：Agent 调 WeKnora 的"标准接口"
已经上架 ClawHub 平台，其他 AI Agent 装上这个 Skill 就能直接调 WeKnora，支持 3 大类操作：
📥 文档导入（上传文件 / 导入网页 / 写 Markdown） 🔍 混合检索（单库 / 跨库 向量 + 关键词） 📚 知识管理（列出、浏览、编辑、删除）
官方地址：clawhub.ai/lyingbug/weknora
八、开发模式 + 部署：码农的快乐 + 生产的安心
收官最后两件事，给程序员和运维各一个交代。
开发模式：3 个终端，热重载救星
上一篇聊过，这里再强调一次——千万别每改一行就 rebuild 镜像，会哭。
# 终端 1：基础设施（数据库、Redis 这些不动的） make dev-start
# 终端 2：后端（Air 热重载，5-10 秒自动重启） make dev-app
# 终端 3：前端（Vite 热重载，改完秒级刷新） make dev-frontend
这套组合拳的好处，前面讲过——省一杯咖啡的时间，治一辈子的颈椎病（不用蹲那里等 build）。
部署：3 种姿势 + 离线能力
WeKnora 覆盖了从"个人测试"到"企业生产"的全场景部署：
| Docker Compose | |
| Kubernetes + Helm | |
| 本地/私有云/离线 |
完全离线运行是 WeKnora 的杀手锏之一——所有组件支持私有化部署，数据不出域内，合规党的福音。
叨叨的友情提醒：生产环境尽量部署在内部/私有网络，避免直接暴露公网，配好防火墙规则，定期更新版本拿安全补丁。这跟手机系统更新一个道理——别嫌烦，不更新就是给黑客送人头。
九、4 章总结：一张全景图回顾
收官了，叨叨带大家把整个系列过一遍：
| 第 1 章 | ||
| 第 2 章 | ||
| 第 3 章 | ||
| 第 4 章 |
一条主线贯穿 4 章——
"先看 → 再用 → 再扩 → 再管"，正好对应企业接入一个新系统的完整生命周期。
▲ WeKnora 设置中心：模型、检索、权限、安全一站配齐（来源：官方 docs/images/settings.png）
收官：叨叨的最后几句话
各位老铁，写完这 4 篇，叨叨心里其实挺感慨的。
2023 年那会儿，大家还在卷"哪个开源 RAG 框架跑分高"。
2024 年开始，焦点转向"哪个能上生产"。
到 2026 年的今天，能打的选手已经不多了——大家要么在企业级能力上掉队，要么在生态集成上瘸腿，要么在治理合规上缺课。
而 WeKnora，恰好把这些都做齐了。
它不是那种"PPT 上的开源项目"——是真的能跑、真有人用、真在迭代的那种。
v0.3 → v0.6.2，2,166 次提交，社区活跃度实打实。
叨叨的建议：
🔹 个人开发者：跑通 demo，感受一下 Agent + Wiki 模式的魅力 🔹 企业 IT：私有化部署，从客服 / 内部知识库场景切入 🔹 想贡献代码：去 GitHub 看 Issue，挑个顺手的 PR，社区氛围很友好
4 章写完，不算深，但算全。
如果你只想记住一句话——
WeKnora 是当下为数不多"能上生产的开源 RAG 框架"——它把企业级、AI 能力、生态集成三件事一次做齐了。
