企业官网建设流程全解析

1. 为什么我盯上了 WeKnora 这套开源知识库

第一次看到 WeKnora 这个名字，是在一个做企业内训的朋友群里。他丢了一句“腾讯微信团队开源了个 AI 知识库，能本地部署”，群里瞬间炸出一堆人问“真的假的”“吃不吃配置”“跟 Dify 比怎么样”。我当时没吭声，转头就去把仓库拉下来读了一遍 README 和目录结构，越看越觉得这东西值得写一篇完整的部署实录——因为它踩中了一个非常具体的痛点：很多团队手里有一堆内部文档、FAQ、产品手册，想搭一套能问答的知识库，但既不想把资料传到别人的服务器上，又不想从零写 RAG 链路。

WeKnora 解决的正是这件事。它是一套开源的 AI 知识库问答系统，核心能力是把文档切片、向量化、存进向量库，再通过检索增强生成的方式回答用户提问。你可以把它理解成“一个能自己部署的、带管理后台的文档问答引擎”。它适合谁？我梳理了三类人：一是中小团队里负责内部工具的技术同学，二是想把公司资料做成智能客服的产品同学，三是像我这样喜欢折腾本地 AI 应用的爱好者。哪怕你之前只跑过 Docker 的基本命令，跟着这篇实录也能把整套系统在本机跑起来。

我特别想强调“本地部署”这四个字的分量。市面上做知识库问答的产品不少，但大多数要么是纯云服务，要么是开源但部署链路极其复杂，光依赖就能劝退一半人。WeKnora 用的是 Docker Compose 编排，把后端服务、前端界面、向量库、数据库这些组件打包成一套可以一键拉起的组合，这对没有专职运维的团队来说，友好度直接拉满。接下来我会从整体设计思路讲起，再一步步拆解部署过程，最后把我踩过的坑和排查经验全部摊开讲。

2. 整体架构与方案选型拆解

2.1 这套系统到底由哪些部件组成

在动手之前，我习惯先把一个项目的组件关系画清楚，不然部署到一半报错都不知道是哪个环节出的问题。WeKnora 的整体结构可以拆成四层来看，我用一张表把每层的职责和常见实现列出来，方便你对照理解。

接入层就是你浏览器里看到的那个管理后台，用来上传文档、管理知识库、测试问答效果。应用层是真正干活的部分，它要负责把上传的 PDF、Word、Markdown 解析成纯文本，再按策略切成一段段 chunk，调嵌入模型把每段转成向量。存储层里，向量库存的是 chunk 的向量表示，关系型数据库存的是知识库、文档、会话这些结构化信息，原始文件一般放在本地磁盘或对象存储里。模型层是整套系统的“大脑”，嵌入模型决定检索准不准，生成模型决定回答顺不顺。

2.2 为什么选 Docker Compose 而不是别的编排方式

这个问题我在部署前认真想过。可选方案其实有三种：手动装依赖逐个启动、用 Docker Compose 编排、上 Kubernetes。手动装的问题在于环境差异太大，Python 版本、系统库、CUDA 驱动稍有不同就报错，复现成本极高。Kubernetes 对个人和小团队来说太重了，为了跑一个知识库去维护一套集群，性价比太低。

Docker Compose 刚好卡在中间：它把每个组件封装成独立容器，容器之间通过内部网络通信，你只需要一条docker compose up就能把整套系统拉起来。更重要的是，Compose 文件本身就是一份可读的部署文档，哪个服务依赖哪个服务、暴露哪些端口、挂载哪些卷，全都写得清清楚楚。我实测下来，只要宿主机装好了 Docker 和 Compose 插件，从零到能访问后台，顺利的话二十分钟以内能搞定。这也是我推荐绝大多数人首选 Compose 的原因——它不是最强大的，但对这个场景是最合适的。

2.3 向量库和模型的选择逻辑

向量库这块，WeKnora 支持对接多种后端，其中比较常见的是本地向量库和云上的向量数据库服务。我的建议是：如果你只是本地测试或者数据量在几万条 chunk 以内，直接用本地向量库就够了，省去申请云服务、配置网络白名单的麻烦。等数据量上来了、或者需要多实例共享向量数据，再考虑换成云上的向量数据库。

模型选择是另一个关键决策点。嵌入模型我强烈推荐用 BGE-M3 这类多语言模型，它对中文的支持明显好于很多英文为主的模型，而且能同时处理稠密检索和稀疏检索，检索召回率提升很直观。生成模型的选择就灵活多了，本地跑可以用量化后的小参数模型，追求效果就接一个能力更强的模型服务。这里有个经验：嵌入模型一旦选定，中途不要随便换，因为换模型意味着所有已入库的向量都要重新生成，数据量大的时候这个成本很高。所以部署前就要想清楚用哪个嵌入模型，一次定下来。

3. 部署前的环境准备与关键检查

3.1 硬件和系统的最低门槛

在正式动手前，我先把硬件要求说清楚，免得你跑到一半发现机器扛不住。纯 CPU 环境也能跑，但生成速度会比较慢，适合功能验证；如果想让问答响应在可接受范围内，建议至少有一块显存 8GB 以上的显卡。内存方面，我建议不低于 16GB，因为向量库、数据库、后端服务加起来本身就吃内存，再叠加模型推理，8GB 的机器很容易被 OOM 杀掉进程。

系统层面，Linux 是最省心的选择，Ubuntu 22.04 和 Debian 12 我都实测过，没遇到系统级坑。Windows 用户建议走 WSL2，直接在 Windows 原生环境跑 Docker 会有路径挂载和网络转发的小问题。macOS 用户注意，Apple Silicon 芯片在跑某些镜像时需要指定 arm64 架构，这个后面会讲到。磁盘空间至少留 50GB，因为镜像、模型权重、上传的文档加起来占用不小，模型权重动辄几个 GB。

3.2 Docker 与 Compose 的安装要点

安装 Docker 这件事本身不难，但有几个细节值得提醒。第一，一定要装 Compose V2 插件，也就是用docker compose而不是老的docker-compose命令，很多新项目的编排文件用了 V2 才支持的语法。第二，安装完记得把当前用户加入 docker 组，否则每条命令都要加 sudo，很烦。第三，国内网络环境下拉镜像可能很慢，建议提前配置好镜像加速地址，这个能省下大量等待时间。

验证安装是否到位，跑这两条命令就够了：

docker --version docker compose version

两条都能正常输出版本号，说明环境没问题。如果第二条报“command not found”，说明 Compose 插件没装上，需要单独安装。我见过不少人卡在这一步，以为是项目的问题，其实是环境没配好。

3.3 部署前必须确认的三件事

在拉代码之前，我建议你先确认三件事，能避免后面大量返工。第一，确认端口没被占用。WeKnora 默认会用到几个端口，如果宿主机上已经有服务占了这些端口，容器起不来。用ss -tlnp看一眼当前监听情况。第二，确认磁盘挂载路径有写权限，容器里的数据要持久化到宿主机，路径权限不对会导致数据库初始化失败。第三，确认模型文件的存放位置，如果你打算用本地模型，提前把权重下载好放到指定目录，别等部署到一半再去下。

提示：部署前把这几项检查做成一个清单，逐项打勾再往下走，比出了问题再回头排查效率高得多。

4. 一步步把 WeKnora 跑起来

4.1 获取代码与目录结构速览

第一步是把项目代码拉到本地。用 git clone 就行，拉下来之后先别急着启动，花两分钟看一眼目录结构，心里有个数。通常这类项目会有几个关键目录：存放编排文件的根目录、后端服务代码、前端代码、以及配置和脚本目录。编排文件是整个部署的核心，它定义了所有服务、网络、卷的关系。

我建议你打开编排文件通读一遍，重点看三样东西：每个服务用的镜像、暴露的端口映射、以及挂载的卷。读懂了这三样，后面出问题你就能快速定位是哪个服务的事。这一步很多人跳过，结果一报错就懵，其实答案全在编排文件里写着。

4.2 环境变量的配置与参数计算

绝大多数这类项目都会提供一个环境变量示例文件，你需要复制一份改成实际配置。这里面有几个参数必须认真填。数据库密码要改成强密码，别用默认值。模型相关的配置要填对，包括模型名称、服务地址、API 密钥（如果用云服务的话）。向量库的连接信息也要和编排文件里的服务名对应上。

这里有个容易踩的坑：容器之间通信用的是服务名而不是 localhost。比如后端要连向量库，地址应该写向量库的服务名，而不是 127.0.0.1。因为每个容器有自己独立的网络命名空间，localhost 指向的是容器自己。这个原理搞懂了，很多“连接被拒绝”的报错就迎刃而解了。

关于 chunk 大小这个参数，我补充一下计算思路。chunk 太大，检索时召回的内容太杂，生成模型容易被无关信息干扰；chunk 太小，单段信息不完整，回答容易断章取义。我的经验值是中文文档切 300 到 500 字比较合适，同时设置一定的重叠长度（比如 50 字），保证跨 chunk 的语义不被切断。这个值不是固定的，要结合你的文档类型调，技术文档可以小一点，叙述性文档可以大一点。

4.3 启动服务与验证运行状态

配置改好之后，就可以启动了。在编排文件所在目录执行：

docker compose up -d

-d表示后台运行。第一次执行会拉取镜像，耗时取决于网络。启动完成后，用下面这条命令看所有容器的状态：

docker compose ps

正常情况下所有服务都应该是 running 或 healthy 状态。如果有服务反复重启，用docker compose logs 服务名看日志。我实测时遇到过一次向量库启动慢导致后端连不上，后端就不断重试，等向量库起来之后自动恢复了，这种情况不用慌，等一两分钟再看。

服务都起来之后，浏览器访问配置的端口，应该能看到管理后台的登录界面。第一次登录用默认账号，进去后第一件事就是改密码。到这里，部署的主体工作就完成了。

4.4 上传文档与验证问答效果

系统跑起来只是第一步，真正验证它好不好用，得喂点文档进去测。我建议先传一份结构清晰的 Markdown 或 PDF，等解析和向量化完成，然后在问答界面提几个问题。测试的时候要分两类问题：一类是文档里明确写了答案的，看它能不能准确检索到；另一类是文档里没有的，看它会不会胡编。一个合格的知识库系统，对不知道的问题应该明确说不知道，而不是硬编一个答案。

如果检索不准，先别急着换模型，检查一下文档解析是否正常。有些 PDF 是扫描件，纯文本解析出来是空的，这种情况需要先做 OCR。还有些文档排版复杂，表格和正文混在一起，解析后顺序乱了，也会影响检索。我一般会先看解析后的文本内容，确认没问题再排查检索环节。

5. 实操中踩过的坑与排查技巧

5.1 容器启动失败的常见原因

部署过程中最容易遇到的就是容器起不来。我把遇到过的情况整理成一张速查表，方便你对照排查。

排查的核心思路永远是先看日志。docker compose logs能解决八成以上的问题，日志里通常会直接告诉你哪一行配置错了、哪个依赖连不上。我见过太多人一报错就去搜，其实日志第一行就写明了原因。

5.2 模型连接与推理相关的坑

模型这块的坑主要集中在连接和性能两方面。连接问题多半是地址填错，记住容器间用服务名。如果用的是外部模型服务，要确认网络能通、密钥有效。性能问题则表现为回答特别慢，这时候先看是不是在用 CPU 推理，如果是，换成 GPU 或者换更小的模型。

还有一个隐蔽的坑：嵌入模型和生成模型如果部署在同一个 GPU 上，显存可能不够。我建议要么分卡部署，要么把嵌入模型跑在 CPU 上（嵌入对延迟没那么敏感），把宝贵的显存留给生成模型。这个取舍在实际部署中很关键，直接决定系统能不能稳定跑起来。

5.3 检索效果不佳的调优思路

检索效果差是问得最多的问题。我的调优顺序是这样的：先确认文档解析质量，再看 chunk 切分是否合理，然后检查嵌入模型是否适合中文，最后才考虑调整检索参数。很多人一上来就调参数，其实前面的基础没打好，怎么调都白搭。

如果文档里有大量专有名词、产品代号，纯向量检索可能召回不准，这时候可以开启混合检索，把关键词匹配和向量检索结合起来。BGE-M3 这类模型本身就支持混合检索能力，配置里打开对应开关就行。我实测下来，对于术语密集的技术文档，混合检索的召回率比纯向量检索有明显提升。

注意：调优是个迭代过程，每次只改一个变量，改完测一组固定问题，对比效果。一次改好几个参数，最后根本不知道是哪个起了作用。

6. 关于这套系统后续能怎么用

跑通之后，我陆陆续续试了几个扩展方向，这里分享两个我觉得最有价值的。第一个是把它接到团队内部的聊天工具上，做成一个随时能问的助手，同事不用打开网页就能查资料。第二个是给不同的知识库设置不同的权限，比如产品文档全员可见，财务制度只有特定角色能问，这在管理后台里配置一下就能实现。

我个人在实际操作中的体会是，本地部署知识库这件事，部署本身只占两成工作量，剩下八成都在文档治理和效果调优上。文档质量差、结构乱，再好的模型也救不回来。所以如果你打算长期用，从一开始就规范文档的格式和命名，后面会省下大量精力。另外，定期把问答日志翻出来看看，哪些问题答得不好，针对性地补充文档，这套系统才会越用越聪明。