WeKnora 私有化部署实战：247 份企业语料，从 Docker 到 RAG 问答的全链路拆解

1 · 为什么选 WeKnora，而不是 Dify / 扣子 / FastGPT

选型的前提是先把需求钉死。我们要的不是「搭一个能聊天的 Demo」，而是数据不出域的企业知识库 RAG 系统——语料是企业内部文档，不能经过第三方 SaaS 的服务器；问答要可审计；模型调用要能接自有 API key。这个约束下，候选名单被快速收敛：

• 扣子（Coze）：SaaS 优先，企业版虽可私有化，但开源版本与企业版能力不对齐——排除；
• Dify：开源、可私有化，但它的强项是「LLM 应用编排」（workflow + agent 节点），知识库只是其中一个模块；
• FastGPT：开源、RAG 导向，知识库能力扎实，但 Agent 执行沙箱（可跑代码）这块比较弱；
• WeKnora：腾讯背书的开源项目（weknora/weknora），定位是「知识库 + Agent」双线——知识库端做文档型/问答型分离，Agent 端带可执行代码的沙箱。

最终选 WeKnora 的决定性理由有两条：一是数据不出域（企业合规刚需，本地 Docker 全栈，无外部依赖）；二是Agent 沙箱可执行代码——这意味着它不是纯 RAG（检索 + 拼 prompt），而是能在沙箱里跑 Python 做数据处理、再把结果回灌给 LLM。对企业语料里夹杂表格、公式、结构化数据的场景，这一步是质变。举个具体的例子：如果语料里有一份季度销售表格，纯 RAG 只能把表格原文塞进 prompt 让 LLM 读；带沙箱的 Agent 可以把表格读进 pandas、做一次聚合统计、把结果写回 prompt——后者的回答质量完全不在一个量级。推断：沙箱资源限制与并发上限未实测，待验证

2 · 五容器全栈架构：单机 16GB 能不能跑

WeKnora 的 Docker 部署不是单容器，而是五个容器各司其职。这是我在 Mac mini M4 16GB 上实际跑起来的拓扑：

实测结论：16GB 内存跑得动。五容器同时 up 后，docker ps 全部 healthy，连续运行 28 小时无重启。这个架构的关键设计决策有两点值得注意：第一，docreader 独立成容器——文档解析是 CPU 密集型任务，与主服务解耦后，解析慢不会拖垮 API 响应；第二，向量存储直接挂在 postgres 上（ParadeDB / pgvector）——不引入独立向量数据库（如 Milvus / Qdrant），减少了一个组件、一份运维成本，代价是向量规模上去后 postgres 的扩展性会成为瓶颈。对 247 份语料这个量级，pgvector 完全够用；如果未来到几万份文档，需要重新评估。待验证：10 万文档级别的 pgvector 检索性能

3 · 247 份语料的分桶规划：不是同一条 pipeline

「导入 247 份语料」这句话背后，其实是三种完全不同的处理逻辑。我在规划阶段把它们分成三桶：

为什么要分桶？因为 docreader 容器对不同格式的解析能力是不对称的。PDF 解析依赖版面分析（双栏、公式、表格跨页），Markdown/HTML 解析则是文本直读。如果把 200 份学术 PDF 当纯文本灌进去，检索时会出现「公式被切碎成乱码」「表格行错位」这类典型问题——不是 RAG 模型的问题，是上游解析的问题。我的做法是：学术 PDF 先走 docreader 的 PDF 解析通道（保留版面结构），网站文章用 Markdown 直灌，Obsidian 笔记保留 YAML 和双链语义后再入库。分桶的本质是：让每类语料走它最擅长的解析路径，而不是用一个通用 pipeline 硬吃。

4 · 模型配置路径：对话 LLM 与 Embedding 是分开的

这是部署阶段最容易走错的一步。WeKnora 的模型配置入口在：

/platform/settings?section=models

进去之后会看到两个独立配置块：对话 LLM（负责生成回答）和 Embedding 模型（负责把语料向量化）。这两个必须分开填——对话模型用一个，Embedding 用另一个，不能偷懒只配一个。原因很直接：Embedding 模型决定了检索召回的质量（向量空间相似度），对话模型决定了生成答案的流畅度，两者的能力维度不同。

这里有一个安全红线：模型 API key 必须由人在 UI 表单里手填。我在自动化脚本里尝试过用脚本写 key，被架构设计明确拒绝——Agent / 脚本不经手 key，这是 WeKnora 在凭证管理上的硬约束。理解后反而觉得这是对的：key 一旦被脚本处理过，就可能出现在日志、环境变量、shell history 里；UI 手填至少保证 key 只存在于后端加密存储里。这个设计值得其他私有化项目抄作业。

5 · 五个实测踩坑：根因和解法

坑 1 · auto-setup 接口返回 403

现象：前端注册管理员账户后，后端 auto-setup 接口返回 403。第一反应是「权限没配对」，反复检查 nginx 配置和容器权限，浪费了不少时间。根因：auto-setup 是首次部署时的初始化接口，只在还没有任何管理员账户时才开放。一旦第一个管理员注册成功，这个接口就会自动关闭，再调就是 403——这是正常状态，不是 bug。解法：忽略 403，直接用刚注册的管理员账户登录即可。

坑 2 · 模型 key 用脚本写不进去

现象：尝试用 API 脚本自动填写模型 provider 的 key，接口返回未授权。根因：如上一节所述，WeKnora 的设计就是 key 必须由管理员在 UI 手动填写，脚本/Agent 不经手。解法：接受这个约束，把 key 填写从自动化流程里拿掉，在部署清单里标注「UI 手动步骤」。教训：不是所有步骤都该自动化——凭证类操作人工介入反而更安全。

坑 3 · 标签搜索 API 异常

现象：在知识库管理页面对文档打标签后，用标签搜索功能检索时，返回结果不符合预期（多标签组合搜索异常）。根因：标签搜索接口在多标签 AND/OR 组合逻辑上存在异常，单标签检索正常。解法：现阶段用单标签做检索维度，不依赖多标签组合。对 247 份语料的规模，单标签 + 全文检索已经够用。待验证：后续版本是否修复多标签组合

坑 4 · scp 部署后文件权限 403

现象：把配置文件 / 静态资源用 scp 传到服务器后，web 服务器（nginx / frontend 容器）返回 403 Forbidden。根因：scp 上传的文件 owner 是 root，但 web 进程以 www 用户运行，读不了 root 的文件。解法：上传后必须执行 chown -R www:www <目录> + chmod -R 644 <文件>（目录用 755）。这个坑在容器化部署里特别容易被忽略——大家默认容器内文件系统是统一的，但 scp 绕过了 Docker volume 的权限映射，把宿主机的 root 权限直接带进去了。

坑 5 · 截图坐标缩放陷阱

现象：用自动化脚本对页面截图后，想在截图上点击某个按钮，按截图像素坐标点过去，点歪了。根因：截图是 1200x542 的缩放图，但浏览器真实视口是 1920x864——截图像素 ≠ 视口坐标，直接拿截图像素当点击坐标，必然偏移。解法：不要用截图像素，要用 getBoundingClientRect() 拿元素在视口里的真实坐标。这条经验对所有做浏览器自动化（CDP / Playwright / Puppeteer）的人都适用：截图是给人看的，不是给脚本用的。

6 · 28 小时稳定运行之后：下一步是什么

到这一步，部署本身算跑通了：五容器 healthy、管理员可登录、模型可配置、知识库可创建。回顾整个部署过程，最花时间的不是 Docker 命令本身（docker compose up -d 一行），而是权限模型和交互细节——五个坑里有三个是权限/认证问题（auto-setup 403、key 必须 UI 填、scp 权限 403），一个是搜索行为异常，一个是自动化坐标。这印证了一个老经验：部署文档不会告诉你的东西，往往比文档本身更重要。但「跑起来」和「用起来」之间还差三件事：

1. 语料导入：247 份分桶导入——PDF 走 docreader、网站文章走 Markdown、Obsidian 笔记保留双链语义；这是下一步的主要工作量，预计占整个落地周期的 60% 以上；
2. 问答调优：导入后做一轮真实问答测试，看召回质量（top-k 是否命中相关段落）和生成质量（回答是否基于语料而非幻觉）；
3. Agent 沙箱实测：跑一个需要代码执行的真实任务（比如对语料里的表格做统计计算），验证沙箱是否真的能跑通、资源限制是多少。

对企业用户来说，私有化部署的「部署完成」从来不是终点，而是「语料质量 + 问答质量」这两轮调优的起点。很多团队把私有化项目的 80% 时间花在「把系统跑起来」上，最后发现真正决定用户是否留下来的，是「问 10 个问题有 8 个能答到点子上」。这篇文章记录的是前半段（从 0 到能跑），后半段（从能跑到好用）会在语料导入和问答测试完成后另写。

FAQ

Q：WeKnora 能完全离线部署吗？模型 API 要不要联网？
A：WeKnora 本体（五容器）可以完全离线，但模型调用需要联网——对话 LLM 和 Embedding 都是通过 API 调用外部模型服务（火山引擎、OpenAI 等）。如果要完全离线，需要接本地部署的开源模型（如本地 Ollama / vLLM），这一步在 /platform/settings?section=models 里配置自定义 endpoint 即可，实测路径可行。推断：本地模型的 Embedding 维度需与 pgvector 表结构对齐

Q：16GB 内存跑五容器，资源会不会紧张？
A：实测 28 小时稳定运行，内存占用在可控范围。瓶颈不在容器本身，而在文档解析——如果一次性导入大量 PDF，docreader 容器的 CPU 和内存会瞬时升高。建议分批导入，避免一次性灌 200 份 PDF。

Q：WeKnora vs FastGPT，知识库能力谁强？
A：纯 RAG（文档检索 + 生成）能力，FastGPT 更成熟（分块策略、检索召回调参更丰富）。WeKnora 的差异化在 Agent 沙箱可执行代码——如果你的语料里有大量表格、公式、需要计算的场景，WeKnora 的沙箱能力是 FastGPT 暂时不具备的。选型取决于你的语料结构，不是「谁更好」。

Q：247 份语料导入要多久？
A：PDF 解析是瓶颈（版面分析 + OCR），200 份学术 PDF 预估需要数小时到十几小时（取决于 docreader 的解析速度和是否需要 OCR）。网站文章和 Obsidian 笔记是文本直读，分钟级完成。建议先小批量试跑（10 份 PDF）确认解析质量和耗时，再全量导入——避免跑了一晚上发现公式全乱码。待验证：实际导入耗时

Q：auto-setup 403 是不是部署失败了？
A：不是。403 说明第一个管理员账户已经注册成功，auto-setup 接口按设计自动关闭。这是正常状态，直接登录即可。

边界声明

作者：王亚博（Abel Wang）· 医疗行业 · AI 数字效能方向 · 转载请注明出处。本文为工程实战记录，不构成任何部署建议。