企业官网建设流程全解析

WeKnora 本地部署指南：3 步搭好私有 RAG 知识库

【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora

照着本文操作，约 30 分钟你能得到一台可提问的 WeKnora 实例：文档解析、向量检索、RAG 问答全链路在你自己的机器上跑通（标准版首次拉取镜像另需 10–20 分钟，取决于网速）。它适合不想把内部资料交给第三方 API 的个人和小团队：所有数据留在本地，部署完当天就能导入自己的资料。

H2 部署前准备：环境与路线

WeKnora 有两条部署路线：Lite 单机版是「一个二进制 + 一个 SQLite 文件」，标准版是 Docker Compose 多容器栈（app、docreader、postgres 等）。先按下表定位，后文以标准版为主线展开。

默认推荐标准版：镜像开箱即用，不用本地装构建工具链，多空间协作也齐。如果你的诉求只是「在本机离线问答自己的文档、绝不联网」，选 Lite。两条路线都建议搭配 Ollama 跑本地模型实现完全离线推理；已有云端模型 API 的话，Lite 通过环境变量指向它即可。

H2 安装：3 步跑起来

第 1 步：拉取代码并进入目录

git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora

你会看到：当前目录下出现Makefile、docker-compose.yml、.env.example、.env.lite.example等文件。

第 2 步：生成配置并修改

cp .env.example .env

用编辑器打开.env，标准版只需确认两处：OLLAMA_BASE_URL在容器内必须指向http://host.docker.internal:11434（文件默认值已正确，不要改成127.0.0.1）；SYSTEM_AES_KEY填入openssl rand -hex 32生成的值。LLM 与 Embedding 模型不用写在环境变量里，启动后在「设置 → 模型」页面配置即可。

如果你选的是 Lite：执行cp .env.lite.example .env.lite，然后改两处——OLLAMA_BASE_URL保持http://127.0.0.1:11434，SYSTEM_AES_KEY与JWT_SECRET换成自己生成的值。

第 3 步：启动

docker compose pull docker compose up -d

你会看到：docker 终端开始拉取 frontend、app、docreader、postgres、redis 等镜像，数分钟后全部容器进入运行状态。

如果你选的是 Lite：执行make run-lite，它先构建前端再编译 Go 二进制，首次约 5–10 分钟；构建期间建议让挂 GPU 的 Ollama 并行ollama serve。

H2 装完先过这 4 关（部署验证）

四项全过再导资料，否则后面对错号方向。

1. 页面能打开。通过标准：浏览器访问http://localhost（前端端口由FRONTEND_PORT控制，默认 80），出现登录/注册页。第一排查点：跑docker compose ps，看 app 是否卡在 restarting，是的话接着看docker compose logs -f app。
2. 模型连通。通过标准：在设置页对 LLM 与 Embedding 分别点测试，两项都返回成功。第一排查点：ollama list确认模型已拉取，且标准版容器内的地址是host.docker.internal:11434而不是127.0.0.1。
3. 能上传。通过标准：新建一个文档知识库，拖入一份 PDF，几秒后状态从处理中变为完成。第一排查点：Embedding 模型没配对，回设置页重测模型。
4. 能提问。通过标准：就刚上传的文档问一个事实性问题，回答末尾带来源引用段落。第一排查点：检查回答是否引用了无关文档，若是说明向量检索没建好，重新查看该文档的解析状态。

H2 上手：3 个真实场景

场景一：上传一批文档做混合检索。想做什么：把散落的制度文档、技术手册变成可搜索的库。 怎么操作：新建文档知识库后直接拖入文件，支持框选多选和批量打标签。 你会看到：上传目录结构被保留成文件夹树，检索时向量与关键词并行召回，返回带出处的原文片段。

场景二：提问并回溯原文出处。想做什么：确认某条报销规定的准确口径。 怎么操作：在知识库问答模式下提问；高频问题可以单独建 FAQ 类知识库固定答案。 你会看到：模型先检索相关段落再组织回答，回答可逐段回溯到原文。

场景三：改一个检索块并回滚。想做什么：发现某个检索块是错版内容。 怎么操作：在文档详情页进入分块编辑，直接改内容。 你会看到：改完自动重建索引，下一次检索立刻生效；界面保留版本历史，支持 diff 和回滚。

H2 卡住了：按顺序自查（问题排障）

Web 页面打不开常见原因：端口被占用或容器未就绪。 处理：查.env中FRONTEND_PORT的映射值，再依次看docker compose ps与docker compose logs -f app的报错。

模型测试失败常见原因：Ollama 没启动或地址写错。 处理：确认ollama serve在跑、ollama list有目标模型；Lite 用127.0.0.1:11434，标准版容器内必须用host.docker.internal:11434。

上传后一直停在「处理中」常见原因：Embedding 模型没配好，或解析任务挂死。 处理：回设置页重测 Embedding 模型；到解析追踪时间线里看卡在哪一阶段，确认挂死就点「中止解析」再重新上传。

图片显示为无效链接常见原因：存储后端对外不可达。 处理：Lite 默认STORAGE_TYPE=local不会遇到；标准版若切到 MinIO，给它配一个外部可达的 endpoint（MINIO_ENDPOINT等变量见.env.example注释）。

刚保存的配置几秒后消失常见原因：登录账号与空间归属不一致，你在别人的空间里改配置。 处理：切回自己创建的空间再操作。

H2 进阶与延伸

文档量上来后，按顺序调这 4 个参数：

• BATCH_EMBED_SIZE：建议设 64。一次请求向量化 64 条，明显减少与 Ollama 的往返次数。
• DOCREADER_GRPC_MAX_WORKERS：设为 CPU 核数（默认 4）。解析是 CPU 密集型任务，并行度直接缩短排队时间。
• CONCURRENCY_POOL_SIZE：控制在 3–8（默认 5）。太高挤占内存拖慢在线问答，太低拖慢入库。
• 模型参数里的num_ctx：按所选模型上限调大。上下文足够时检索片段不被截断，长文档问答更稳。

用 8B 级本地模型时记住这个互斥权衡：要单条回答质量就加大num_ctx，要整体吞吐就压低CONCURRENCY_POOL_SIZE、分批入库，两者不能同时要满。

延伸入口（都在仓库内）：

• docs/LITE.md：Lite 与标准版逐条差异表，选型摇摆时看这篇。
• docs/README.md：仓库文档目录总览，排障与 API 文档的索引。
• client/example.go：Go 客户端示例，写上传与检索脚本时直接照抄结构。
• website-docs/README.md：完整产品文档站入口，覆盖 API 端点与环境变量说明。

下一步：先导入 10–20 份最高频的文档，用 5 个真实问题校准检索与回答质量；确认满意后，再用docker compose --profile minio、--profile neo4j等按需加可选服务扩展标准版。

【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora