做知识库项目的人，最近几乎都在聊 WeKnora 的本地部署。我也趁着周末把整套环境在本地完整跑通了，配合 Ollama 加开源模型，把团队的一堆技术文档索引进去之后，直接变成了一个可以内部问话的“私有知识助手”。这篇文章不打算讲官方案例，而是把我在实际操作中踩过的坑、验证过的配置、以及那些文档里不会明说的细节，全部整理出来，给准备在本地折腾 WeKnora 的朋友一份可以直接参考的实操记录。

1. WeKnora是什么，为什么值得折腾本地部署

1.1 WeKnora不是又一个Dify

聊 WeKnora 之前，得先把它和市面上常见的那几个开源项目分清楚。很多人一听到开源 AI 应用平台，第一反应就是 Dify、RAGFlow、FastGPT，而 WeKnora 的定位和他们有一点微妙的不同。

WeKnora 更多是围绕“知识库”和“RAG 检索增强生成”来设计的。它把文档管理、知识库索引、权限体系、应用发布这几个环节做得更重，尤其是文档级别的内容管理和团队协作场景，明显比通用应用平台更贴近企业内部知识中台的需求。你可以把它理解成“带 RAG 能力的知识管理平台”，而不是一个从零开始拖拽聊天机器人的 Agent 平台。

我选择它来做本地部署，主要原因是它真正把一个知识库该有的功能做了闭环：上传文档、后台解析、切片向量化、权限控制、对外发布问答应用，全都在一条链路里完成。对于手里有大量私有文档、又不想把数据送到云端的团队来说，这种闭环价值非常高。

1.2 本地部署的核心优势

说回“本地部署”四个字。为什么不在线直接用？很多团队的文档里包含了内部架构设计、运营数据、商务报价，哪怕只是被用来做大模型检索的上下文，也存在数据外泄的隐患。把 WeKnora 部署在本地或内网，至少主动权掌握在自己手里。

从使用体验上看，本地部署还有三个很实在的好处：

第一，离线可用。本地部署完成后，不依赖任何外部 API，网络断了也能继续做文档检索和问答。对于技术文档可能涉及内部系统截图、代码片段、流程说明的场景，离线意味着随时可以查。

第二，成本可控。接入本地开源模型之后，每次提问不再按 token 计费。对于反复检索、多轮对话、测试调试这类高频操作，本地推理的成本优势非常明显。哪怕你的电脑只能跑小参数量模型的量化版，答案质量在文档检索场景下也足够用。

第三，可定制性。部署在本地之后，无论是改系统配置、调整向量化策略，还是做内部工具的接口对接，都不会受 SaaS 平台的功能边界限制。第三方平台的页面、字段、用户体系再灵活，也难比自己掌控的本地实例更自由。

1.3 和Dify、RAGFlow的取舍对比

我给不少团队做过知识库选型咨询，大家最纠结的往往不是“要不要做”，而是“用哪套框架”。我直接把我最后的对比结论摆出来，省得你再踩一遍选择困难。

如果你要处理大量版式复杂的 PDF、扫描件、网页长文，RAGFlow 的深度文档理解确实强；如果你要快速搭出各种 Agent 工具链和工作流，Dify 的灵活度很高。而 WeKnora 最适合的场景是：你手里有一批内部文档，需要变成可搜索、可问答、可分组授权的结构化知识库，同时希望这个系统能长期沉淀和扩展。我最后选择 WeKnora，是因为它开箱即用的知识库属性最强，文档级权限和协作能力正好补上了开源圈子里最稀缺的那块拼图。

2. 部署前的准备：硬件、依赖与模型选型

2.1 硬件配置参考

本地部署的第一步，不是敲命令，而是确认手里的机器能不能扛得住。WeKnora 本身是 Java 和 Python 混合的架构，核心服务、中间件、向量库、模型推理服务都会占资源。

我的经验分档如下：

• 最低配置：4 核 CPU、16GB 内存、无 GPU。这个配置可以跑通部署流程和基础问答，但只能接量化程度很高的 7B 模型，文档一旦多起来，向量化会很煎熬。适合探索试玩。
• 推荐配置：8 核 CPU、32GB 内存、8GB 以上显存的 NVIDIA GPU。这个档位可以流畅跑 7B~14B 的量化模型，处理几百份 PDF 不卡顿，多人测试也基本够用。
• 高配参考：16 核 CPU、64GB 内存、24GB 显存。这个配置上 32B 模型也从容了，适合几十人团队日常使用，文档库可以做到上万页级别。

需要特别提醒的是，磁盘空间比很多人预想的更占用资源。Docker 镜像、多个模型文件、向量库索引、文档原始文件、日志加起来很容易超过 50GB。如果你计划上 14B 以上模型，固态硬盘建议直接预留 150GB 以上。另外，向量化期间 CPU 会长时间高负载，散热不好的机器建议降压或者控制批量任务并发。

2.2 基础环境与工具

WeKnora 最常见的部署方式是 Docker Compose，原因很简单：依赖太多，用容器编排可以一次性把 Web 服务、MySQL、Redis、向量数据库等组件全部拉起，省去手工安装配置的麻烦。

我强烈建议在部署前把这几件事做好：

• 安装较新版本的 Docker Engine 和 Docker Compose 插件。旧的 Docker 版本对 Compose v2 支持不好，后面跑起来会踩很多怪坑。
• 检查本机端口占用。WeKnora 默认会用 8080、3306、6379 等端口，如果本机已经跑着别的 MySQL 或 Redis，需要提前修改映射关系，否则容器启动大概率失败。
• 给 Docker 配置国内镜像加速。对于国内网络环境，拉取官方镜像时经常超时，配好镜像加速之后可以少浪费很多时间。
• 在 Linux 环境下，记得检查 selinux 和防火墙规则。虽然普通用户触碰不到生产防火墙，但本地系统防火墙也可能挡住容器端口映射，启动容器后页面打不开，十有八九是这里的问题。

这些准备工作听起来琐碎，但它们决定了后面每一步能不能顺利推进。我第一次部署时就是因为没改端口映射，结果容器一直重启，排查了大半天。

2.3 模型与向量化选型

部署 WeKnora 之前还要想清楚一件事：用哪套大模型做生成，哪套模型做向量化。这两个角色是分开的。

我本地选用的是 Ollama 作为模型运行环境，主要看中它对量化模型的支持好、内存占用可控、接口兼容 OpenAI 格式，WeKnora 对接起来非常省事。生成模型我用了 DeepSeek 蒸馏版的 7B/14B 量化包，在文档问答场景下，回答结构清晰，中文表现比同尺寸的通用模型更稳。

向量化模型也是整个链路里容易被低估的一环。很多人只关心生成模型，却忽略了 embedding 模型的质量会直接决定检索的准确性。我的建议是优先考虑中文表现好的 embedding 模型，比如 bge-m3、bge-large-zh 这一系。尤其知识库里夹杂大量中文技术名词和缩写时，好的中文 embedding 能让检索结果的命中率有质的提升。

如果你不确定该选哪个，可以先在配置里用 bge-m3 做向量化跑一批测试文档，再看问答效果。如果检索结果经常答非所问，先别急着换大模型，换向量化模型试试往往更有效。

2.4 目录规划与存储设计

这一节容易被新手忽略，但对长期使用影响很大。启动 WeKnora 时，我们需要把数据目录挂载到宿主机上，这样可以避免容器删了数据也丢掉。

我的习惯是单独建立一套清晰的目录结构，比如/data/weknora下面再拆分：

• data/：数据库持久化数据、配置文件
• models/：本地模型文件和向量模型映射
• docs/：待导入的原始文档
• logs/：应用日志和中间件日志

这么做的好处有三个：备份只需针对一个根目录；容器升级时可以无损迁移；排查问题时日志集中在一个地方，不用跑到容器内部到处翻。

从底层逻辑来看，WeKnora 的索引和文件存储本质上都是磁盘上的数据，容器只是运行时的外壳。如果把所有数据都塞在容器可写层里，下次升级或重建容器就是一场灾难。所以，挂载目录这件事，必须在启动前就规划好。

3. 完整部署实操：从拉取项目到首次问答

3.1 拉取项目并准备配置文件

一切准备就绪后，我们开始进入真正的部署环节。首先从代码仓库拉取项目，具体地址以你正在使用的官方仓库为准，我这里用占位符代替：

git clone https://github.com/your-org/weknora.git cd weknora

进入项目目录后，通常有一份.env.example或docker-compose.yml文件。我的做法是先复制环境变量模板：

cp .env.example .env

然后编辑.env文件，把关键项改成符合本地环境的配置。最常改的是这几个：

• 服务端口，默认管理端口如果是 8080，建议改成不冲突的端口，比如 18080，避免和本地开发工具打架；
• 数据库和 Redis 的持久化路径，指向我们在 2.4 节规划的目录；
• 管理员初始密码，一定要改掉默认值，尤其是要暴露到局域网给同事用时。

如果你在 Windows 或者 Mac 上通过 Docker Desktop 部署，容器内访问宿主机的 Ollama 服务时，需要用到host.docker.internal这个地址。Linux 环境下如果没这个域名，需要使用--add-host=host.docker.internal:host-gateway给容器加上映射。

3.2 启动核心服务与校验状态

配置文件准备好之后，就可以拉取并启动服务了。

docker compose pull docker compose up -d

第一次启动会拉取多个镜像，耗时取决于网络带宽和镜像大小。启动完成后，用下面的命令看容器状态：

docker compose ps

正常情况下，核心服务都应该处于running状态，建议观察两分钟，确认没有不断重启的容器。如果出现重启循环，先看对应容器的日志：

docker compose logs -f [服务名]

日志里大概率会暴露问题方向。比如端口被占用会提示 bind address already in use，内存不足会在 Java 进程启动时报OutOfMemoryError，数据库连不上会直接抛连接异常。把这些日志按关键词找出来，解决起来就快了。

服务启动后，在浏览器打开http://localhost:18080，用管理员账号登录，进入初始化引导。此时系统会让你配置模型服务连接和知识库存储路径，先别急着点下一步，我们直接进入下一节接入大模型。

3.3 接入Ollama本地大模型

这一步是整个部署里最核心的地方。我本地用 Ollama 跑模型，所以接入思路都是围绕这个展开。如果你用其他的本地推理服务，只要接口兼容 OpenAI 格式，方向是一样的。

先确认宿主机上 Ollama 服务已经启动，并提前拉好你需要的模型：

ollama pull deepseek-r1:7b ollama pull bge-m3

然后在 WeKnora 的管理后台找到“模型供应商”或“模型配置”入口，新增一个 OpenAI 兼容的 Provider。关键参数如下：

• API 地址：http://host.docker.internal:11434/v1
• 模型名称：deepseek-r1:7b（按实际 OLLama 里的名字填）
• 向量化模型：bge-m3

连接方式可以学我一样先做一次测试调用，确认连通性。如果测试失败，不要着急，极大概率是下面几个原因：

第一，容器内访问不了host.docker.internal。Linux 下需要额外加 host 映射，Docker Desktop 环境一般自带。第二，Ollama 默认只监听本地回环地址，需要把监听地址设置成允许局域网访问，比如OLLAMA_HOST=0.0.0.0:11434。第三，Ollama 的 API 路径要确认有没有多加/api之类的层级，OpenAI 兼容路径一般是/v1/chat/completions，配置时填基础路径/v1就行。

3.4 创建知识库并导入文档

模型接入后，下一步就是把文档喂给 WeKnora。在管理后台新建一个知识库，命名随意，关键是选择向量模型和切片策略时要想清楚。

切片策略是控制文档拆分成多大检索单位的配置。我的经验是：普通技术文档用中等长度切片，比如 300 到 500 字，重叠区域控制在 10% 左右。代码为主的文档建议缩小切片，避免一段代码被截成两半。切片设置可以在导入之后调，但后期重建索引比较费时间，所以最好一开始就按文档类型规划。

文档导入这块，WeKnora 对 Markdown、PDF、Word、Excel 都有内置解析。导入后系统会进入异步处理，包括内容抽取、清洗、切片、向量化。期间可以去查看后台的索引任务状态。

我第一次导入一批 PDF 时，发现部分文档索引状态一直不结束。后来定位是文档里包含大量扫描图片，OCR 能力有限导致解析卡住。如果你的文档也有大量扫描件，建议先转成文字版 PDF 再导入，或者先小批量测试解析效果。

3.5 发布第一个问答应用

知识库内容就绪后，就可以在 WeKnora 里创建一个问答应用。这个流程很像 Dify 里创建应用，选择你刚建的知识库作为数据源，设置提示词模板，然后发布。

发布完成后，可以拿到一个网页访问地址，如果配置了 API Key，还可以直接通过 HTTP 接口对接自己的前端或内部系统。

我建议第一版应用不要加太多复杂逻辑。先把检索召回、模型生成、引用来源这三项跑通，之后再考虑意图识别、多轮对话、权限过滤这些高级功能。RAG 应用的效果好坏，很大程度上取决于基础链路的稳定性。基础链路通了，后续优化才有意义。

4. 常见问题与排查技巧实录

4.1 镜像拉取与容器启动问题

这一节我专门用来记录实际操作中反复出现的问题，也算给自己留一份排查速查表。

镜像拉不下来，是国内网络环境最典型的痛。解决方式是配好 Docker 镜像加速，配置修改之后重启 Docker 服务再重新拉。如果某些镜像仓库仍然超时，可以考虑通过代理中转下载后导出再导入，但注意这属于环境问题，不要在业务层面过度纠结。

容器启动后不断重启，先docker compose logs看日志。不同问题对应不同服务：

4.2 模型调用失败

第二个高频问题区就是模型调用。我在接入 Ollama 时遇到最多的报错是connection refused，以及一直卡在请求中直到超时。

connection refused通常指向三个原因：容器内访问宿主机地址写错；Ollama 没监听外部端口；端口被系统防火墙拦截。按这个顺序排查最有效，而不是一上来就改代码。

请求超时则多见于生成模型较大、K 线推理慢的情况。可以调高 WeKnora 侧的请求超时时间，或者换更小参数量模型。如果只是测试连通性，建议先用 7B 模型验证，确认稳定后再换成更大的模型。

4.3 文档解析与检索效果差

文档解析效果差主要体现在两个方向：一个是内容没解析出来，一个是检索答非所问。

内容没解析出来，九成是文档本身格式问题。扫描版 PDF、加密 PDF、超长表格、复杂页眉页脚都会干扰解析。处理办法是尽量提供可复制文本的 PDF 或 Markdown 原文，避免对扫描件硬碰硬。

检索答非所问，则要先看检索阶段召回的结果。WeKnora 后台一般能看到“引用片段”或“召回内容”，如果召回的是不相关内容，问题大概率出在向量化模型或切片策略上。换一个中文 embedding 模型，或者调整切片长度，通常能改善。

我遇到过特别特殊的情况：技术文档里充满了英文缩写和中文混合表述，默认向量模型把“RAG”和“检索增强生成”当成两个完全不同的语义，搜索结果自然很差。换用 bge-m3 后明显好转，说明 embedding 模型对专业术语的语义理解至关重要。

4.4 性能优化与扩展建议

如果你和我一样，是想在团队内长期使用，部署完只是开始，性能优化才是持续要做的事。

先说并发。多人同时提问时，显存和内存的消耗会成倍上涨。推荐做法是在模型服务层限制并发数，让请求排队处理，而不是一下子把资源打满。也就是在 Ollama 的启动环境里设置并发参数，控制同时推理的请求数量。

再说检索。文档量一旦超过几千份，向量检索的延迟会上升。可以通过给知识库分区、按团队或项目隔离索引来降低单次检索压力。WeKnora 的多知识库结构本身支持分域管理，所以尽量把一个知识库控制在一个合理规模内。

日志和备份也要纳入日常。建议定期导出知识库配置和数据目录，防止容器异常导致丢失。我的习惯是每周做一次增量备份，关键节点再做全量快照。

4.5 结合Obsidian等工具的联动思路

很多人除了 Web 管理端，还希望把知识库接入 Obsidian 之类的本地笔记工具。这个我虽然没有在 WeKnora 里完成完整联动，但从接口思路上可以给一些方向。

WeKnora 提供了 API 接口，理论上可以做到外部工具调用知识库检索。如果想让 Obsidian 里的笔记直接成为知识库内容，最简单的方案是定期把 Obsidian 的 Markdown 文件同步到docs/目录，再通过脚本调用 WeKnora 的导入接口更新索引。这样笔记和问答知识库之间就形成了“本地编辑 → 自动同步 → 检索问答”的闭环。

更深一步的做法是，用 WeKnora 的开放接口对接一个中间层，让 Obsidian 里可以直接唤起知识库搜索并返回结果。这个方案复杂度高一些，但对知识工作者来说，检索效率的提升非常可观。我目前还在试验阶段，等完全跑通后再单独写一篇细节。

5. 部署完成后的几点真心建议

整趟部署下来，我最深的体会是：WeKnora 本地部署的难点从来不是工具本身，而是部署前的规划和对整个 RAG 链路的理解。硬件选型、模型选型、向量化策略、目录规划，每一个决策都会影响后续的使用体验。把这些基础打扎实，后续遇到问题才有清晰的排查路径。

如果你打算在团队中落地，我特别建议先不要急着铺开所有功能。先把一个小团队的高频文档导入进去，让两三个人真实使用两周，看看检索效果和问答质量，再逐步调整模型和切片。这样既能验证系统的可靠性，也能避免一上来就把资源耗在不常用的大文档上。

最后分享一个小技巧：部署完后，把 WeKnora 的管理员账号和模型服务配置单独记在一处，同时备份.env文件。这个文件里包含了端口、路径、密钥等信息，很多看似莫名其妙的问题，最后都能追溯到配置不一致上。重视配置管理，就等于给这个系统上了一份长久的保险。