企业官网建设流程全解析

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

第一次看到 WeKnora 这个项目，是在一个做企业内训的朋友群里。他当时吐槽说，公司攒了七八年的产品文档、售后 FAQ、培训手册，全躺在共享盘里吃灰，新来的客服遇到问题还是靠老员工口口相传。他试过几个商业知识库方案，要么按席位收费贵得离谱，要么数据必须传到别人服务器上，法务那边过不了。后来有人甩了个链接给他，说是腾讯微信团队开源的一套 AI 知识库工具，能本地部署，支持文档解析、向量检索、大模型问答一条龙。他折腾了一个周末跑通之后，在群里发了一句“真香”。

我这个人有个毛病，看到“本地部署”加“开源”这两个词凑一块儿，手就痒。更何况还挂着腾讯微信团队的名头——这帮人做工程化落地的能力，业内是有共识的。于是我也拉了一份代码，在自己那台闲置的迷你主机上从头到尾搭了一遍。整个过程踩了不少坑，也积累了一些官方文档里没写的经验，索性整理成这篇实录，给同样想自己搭一套问答系统的朋友做个参考。

WeKnora 本质上是一个检索增强生成（RAG）的知识库系统。说人话就是：你把 PDF、Word、Markdown 这些文档丢进去，它帮你切碎、向量化、存进数据库；你提问的时候，它先从数据库里捞出最相关的几段内容，再交给大模型组织成通顺的回答。整套东西可以完全跑在你自己的机器上，数据不出内网，模型可以接本地的，也可以接云端 API。适合谁呢？我总结下来是三类人：一是手里有一堆私有文档、又不想把数据交出去的小团队；二是想学习 RAG 系统完整工程实现的技术爱好者；三是需要给内部系统加一个智能问答入口的开发者。

下面我就按实际操作的顺序，把整个部署过程、关键决策点和踩坑记录拆开来讲。

2. 部署前的整体设计与选型考量

2.1 为什么选 Docker Compose 而不是裸机安装

WeKnora 官方提供了两种部署方式：一种是手动装 Python 环境、数据库、向量库，逐个配置；另一种是直接用 Docker Compose 一把梭。我毫不犹豫选了后者，原因有三。

第一，依赖隔离。这套系统涉及 Python 运行时、PostgreSQL（带 pgvector 扩展）、Redis、对象存储（MinIO）等一堆组件，裸机装的话，版本冲突能把你折腾到怀疑人生。Docker Compose 把每个组件关进自己的容器里，互不干扰，删起来也干净。

第二，可复现性。Compose 文件本身就是一份部署文档，换台机器把文件一拷，docker compose up -d就完事。我后来在另一台机器上复现，前后不到十分钟。

第三，资源可控。Compose 里可以给每个服务限制 CPU 和内存，避免某个组件把整机资源吃光。我那台迷你主机只有 16G 内存，不限制的话 PostgreSQL 和向量检索服务能把内存撑爆。

注意：Docker Compose 有两个大版本，v1 是docker-compose（带横杠），v2 是docker compose（空格）。现在新装的基本都是 v2，命令别写错了，否则会报cannot start docker compose application之类的错。

2.2 向量数据库和嵌入模型怎么选

这是整个部署里最关键的决策点，直接决定了检索效果和硬件开销。

WeKnora 默认支持多种向量存储后端，我实测下来，PostgreSQL + pgvector是最省心的组合。原因很简单：它跟业务数据共用一个数据库实例，少维护一个组件，备份也方便。如果你追求极致检索性能，可以换成专门的向量库，但对中小规模知识库（几万到几十万条切片）来说，pgvector 完全够用，没必要给自己加运维负担。

嵌入模型这块，我强烈推荐BGE-M3。这个模型在中文语义检索上的表现相当扎实，而且支持多语言、支持长文本，最关键的是它能在消费级显卡甚至纯 CPU 上跑。我一开始用的是某个更小的模型，检索召回率明显不行，换成 BGE-M3 之后，同一个问题的命中率肉眼可见地提升。部署 BGE-M3 也有现成的 Docker 镜像，Compose 里加一个服务就行。

至于大模型，看你手头有什么。有显卡的可以本地跑量化版模型，没显卡的就接云端 API。WeKnora 的模型接入层做得比较灵活，改配置文件就能切换。

2.3 硬件配置的底线在哪里

我把实测的配置需求整理成了一张表，供你参考：

纯 CPU 也能跑，就是文档入库慢一些，问答响应大概在几秒到十几秒。如果你只是自己用或者小团队内部用，这个延迟完全可以接受。

3. 核心组件拆解与实操要点

3.1 目录结构规划：别等数据丢了才后悔

很多人上来就git clone然后docker compose up，跑是能跑起来，但数据卷全在默认位置，哪天容器重建或者系统重装，几年的文档就没了。我建议在部署前先把目录规划好。

我的做法是在数据盘上建一个总目录，比如/data/weknora，下面再分几个子目录：

/data/weknora/ ├── docker-compose.yml ├── .env ├── data/ │ ├── postgres/ # 数据库数据 │ ├── redis/ # 缓存数据 │ ├── minio/ # 对象存储 │ └── models/ # 本地模型文件 └── logs/ # 各服务日志

然后在 Compose 文件里把这些目录挂载进容器。这样做的好处是，所有持久化数据集中在一处，备份的时候直接打包整个data目录就行。我吃过亏——之前有个项目数据卷散落在 Docker 默认路径下，迁移的时候找都找不全。

3.2 环境变量配置：那些容易填错的参数

WeKnora 用.env文件管理配置，里面有几个参数特别容易踩坑，我逐个说。

数据库连接串。格式是postgresql://用户名:密码@主机:端口/库名。注意主机名要填 Compose 里的服务名，不是localhost。因为容器之间通过内部网络通信，填localhost会指向容器自己，连不上数据库。我第一次就栽在这儿，日志里报连接拒绝，排查了半天。

嵌入模型地址。如果你用独立的嵌入模型服务，地址要填那个服务的容器名加端口。比如嵌入服务叫embedding，端口 80，那就填http://embedding:80。同样别填localhost。

大模型 API Key。如果用云端模型，Key 直接写在.env里。这里有个安全建议：.env文件权限设成600，别让其他用户读到。另外，.env千万别提交到 Git 仓库，.gitignore里加上。

文件上传大小限制。默认值可能偏小，如果你要传大 PDF，记得调大。这个参数在不同版本里名字可能不一样，一般在应用服务的环境变量里，找带MAX或SIZE字样的。

3.3 文档解析与切片策略：决定问答质量的关键

文档丢进去之后，系统要把它切成一段一段的“切片”，再向量化。切片策略直接决定了检索质量，这是很多人忽略的地方。

WeKnora 默认的切片是按固定字符数切的，比如每 500 字一段，段之间留 50 字重叠。这个策略对结构规整的文档还行，但遇到表格、代码块、多级标题的文档就容易切碎语义。

我的经验是：按文档类型分别设置切片参数。纯文本类文档，切片可以大一些，800 到 1000 字，重叠 100 字；技术文档和 FAQ，切片小一些，300 到 500 字，因为问答对本身就很短；表格密集的文档，最好先转成 Markdown 再入库，让解析器能识别表格结构。

提示：切片重叠（overlap）这个参数别省。它保证相邻切片之间有内容交叠，避免一个完整的语义被硬生生切断。我一般设成切片长度的 10% 到 20%。

3.4 检索参数调优：召回率和准确率的平衡

检索环节有几个参数值得调：

• Top K：每次检索返回多少个切片。设太小，可能漏掉关键信息；设太大，会引入噪声，还会拖慢大模型的处理速度。我一般设 5 到 8。
• 相似度阈值：低于这个阈值的切片直接丢弃。设太高，可能什么都召不回；设太低，会混进不相关的内容。建议从 0.5 开始试，根据实际效果微调。
• 重排序（Rerank）：如果系统支持，强烈建议开启。它会对初步召回的切片做二次精排，把最相关的排到前面。开了之后，回答准确率提升很明显。

这些参数在 WeKnora 的配置文件里都能找到，改完重启服务生效。调参是个细活，建议准备一组测试问题，每次改完跑一遍，对比效果。

4. 完整部署流程与关键环节实现

4.1 环境准备：Docker 和 Compose 的安装

先确认你的系统里有没有 Docker。终端里敲：

docker --version docker compose version

如果两条命令都能输出版本号，说明环境 OK。如果提示找不到命令，就得先装。

Linux 上装 Docker 最省事的方式是用官方脚本，但有些发行版的软件源里版本太老，建议直接参考 Docker 官方文档添加软件源安装。装完之后记得把当前用户加进docker组，否则每次敲 docker 命令都要加sudo：

sudo usermod -aG docker $USER

执行完这条命令要重新登录才生效，别问我怎么知道的。

Windows 和 macOS 用户直接装 Docker Desktop 就行，里面自带 Compose。注意 Windows 上要开启 WSL2 后端，性能会好很多。

4.2 拉取代码与配置文件准备

从代码仓库把 WeKnora 拉下来：

git clone <仓库地址> weknora cd weknora

然后找到.env.example或者类似的模板文件，复制一份改名为.env：

cp .env.example .env

接下来就是编辑.env，把前面说的那些参数填进去。我建议用vim或者nano直接改，改完保存。

4.3 启动服务与验证

一切就绪后，在项目根目录执行：

docker compose up -d

-d表示后台运行。第一次执行会拉取镜像，视网速而定，可能要等几分钟到十几分钟。拉完之后容器会依次启动。

用下面这条命令看容器状态：

docker compose ps

正常情况下，所有服务的状态应该是running或者healthy。如果有服务显示restarting或者exited，说明启动失败了，得看日志排查：

docker compose logs -f <服务名>

-f是持续输出日志，按Ctrl+C退出。重点看报错信息，一般是配置填错或者端口被占用。

所有服务正常后，打开浏览器访问http://你的机器IP:端口，应该能看到 WeKnora 的登录界面。默认端口在.env里配置，一般是 8080 或者 3000 之类。第一次登录用默认管理员账号，登录后第一件事就是改密码。

4.4 上传文档与构建知识库

登录进去之后，创建一个知识库，然后把文档拖进去。系统会自动解析、切片、向量化。这个过程的时间取决于文档数量和硬件性能。我传了大概 200 个 PDF，纯 CPU 环境下跑了将近一个小时。

入库完成后，可以在知识库里看到每个文档被切成了多少片。这时候建议抽查几个切片，看看切得合不合理。如果发现切片把表格切得七零八落，就得回去调整切片策略，删掉重新入库。

4.5 问答测试与效果评估

知识库建好后，就可以提问了。我建议准备一组“标准问题”，覆盖不同难度：有直接答案在文档里的，有需要跨文档综合的，还有文档里根本没提的（测试它会不会胡编）。

实测下来，BGE-M3 加 pgvector 的组合，在中文技术文档上的召回效果相当不错。问一个产品参数问题，它能把相关的几个切片都捞出来，大模型组织出来的回答也基本准确。但遇到需要多跳推理的问题，比如“A 产品的某个功能在 B 场景下怎么配置”，效果就一般了，这跟切片策略和检索深度都有关系。

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

5.1 容器起不来怎么办

这是最常见的问题，我整理了一张速查表：

我遇到最多的是数据库连接失败，十有八九是主机名填了localhost。记住，容器之间通信要用服务名。

5.2 文档入库卡住或失败

如果文档传上去一直显示“处理中”，或者直接报错，先看应用服务的日志。常见原因有几个：一是文档格式不支持，比如加密的 PDF 或者扫描件（没有文字层）；二是文件太大，超过了配置的上限；三是嵌入模型服务挂了，导致向量化步骤失败。

扫描件这个问题特别常见。很多人以为 PDF 都能解析，其实扫描件本质是图片，得先做 OCR。WeKnora 是否内置 OCR 要看版本，如果没有，就得自己先用 OCR 工具处理一遍再入库。

5.3 问答答非所问或胡编乱造

这个问题分两种情况。一种是检索没召回到正确内容，那就要调检索参数，或者检查切片策略。另一种是召回了正确内容，但大模型没用好，那就是提示词（Prompt）的问题。

WeKnora 的问答提示词模板一般可以在配置文件里改。核心思路是明确告诉模型：“只根据下面提供的资料回答，资料里没有的就说不知道。”这句话能大幅降低胡编的概率。另外，可以在提示词里要求模型引用来源，这样你还能追溯它是根据哪段内容回答的。

5.4 性能优化的一些实操心得

跑了一段时间之后，我做了几项优化，效果比较明显：

• 给 PostgreSQL 调参：默认配置偏保守，适当调大共享缓冲区和工作内存，检索速度能快不少。
• 嵌入模型用 GPU：如果有显卡，把嵌入模型跑在 GPU 上，入库速度能提升好几倍。
• 开启 Redis 缓存：重复问题的检索结果可以缓存，减少数据库压力。
• 定期清理日志：容器日志不清理会越积越多，占满硬盘。可以配置日志轮转。

注意：调 PostgreSQL 参数前先备份数据，改错了可能导致服务起不来。不确定的参数就保持默认，别乱动。

5.5 数据备份与迁移

前面强调过目录规划，这里说备份的具体操作。最简单的办法是停掉服务，然后打包整个data目录：

docker compose down tar -czvf weknora-backup-$(date +%Y%m%d).tar.gz /data/weknora/data docker compose up -d

迁移到新机器时，把备份包解压到相同路径，再把 Compose 文件和.env拷过去，docker compose up -d就能恢复。注意.env里的路径配置要跟新机器一致。

6. 我踩过的坑和最后想说的

回过头看，整个部署过程最耗时间的不是技术难点，而是那些“想当然”的地方。比如以为localhost万能，结果在容器网络里栽了跟头；比如没规划目录，数据卷散落各处，迁移时手忙脚乱；比如切片参数用默认值，导致检索效果一直上不去，还以为是模型不行。

还有一个体会是：别追求一步到位。我一开始想把所有参数都调到最优，结果改来改去把自己绕晕了。后来学乖了，先用默认配置跑通，确保整个链路没问题，然后再针对具体问题逐个调优。这样每改一个参数，都能清楚知道它带来了什么变化。

WeKnora 这套东西，工程完成度确实对得起“微信团队出品”这几个字。Compose 文件写得规整，配置项注释清楚，日志输出也够详细。但它毕竟是个开源项目，不是开箱即用的商业产品，很多地方需要你根据自己的场景去调。如果你只是想快速体验一下 RAG 问答，那跑通默认配置就够了；如果你想把它用在生产环境，那切片策略、检索参数、提示词模板这几块，值得花时间好好打磨。

最后分享一个小技巧：建知识库的时候，先拿一小批有代表性的文档做测试，把切片和检索参数调满意了，再批量导入全部文档。这样能省下大量反复入库的时间。我一开始就是一股脑全传进去，结果参数不对，删了重来，白白等了好几个小时。