企业官网建设流程全解析

WeKnora 本地部署指南：30 分钟跑起你自己的 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

WeKnora 是一个开源 LLM 知识平台，把原始文档变成可检索的 RAG 问答、自主推理 Agent 和自动维护的 Wiki。这篇部署指南写给想把内部资料留在本机的人：不需要把文档交给第三方 API，跟着做就能在约 30 分钟内得到一台可上传、可提问的知识库实例（首次拉取标准版镜像另需 10–20 分钟）。硬件参考 4 核 8GB 起步，若叠加 Ollama 本地模型请再按模型体积预留内存。

先定路线：标准版、Lite 还是 Helm

部署 WeKnora 前，先决定用哪种形态，后文步骤以标准版为主线，Lite 的差异在步骤里行内标注。

团队共享知识库选标准版；只想在本机离线试用选 Lite；已有 K8s 集群则用 helm/ 下的 chart。

动手前：5 项前置检查

1. Docker 与 Compose（仅标准版/Helm）：docker --version与docker compose version能正常输出版本号。
2. 端口：宿主机 80（前端，由FRONTEND_PORT控制）与 8080（后端 API）未被占用；ss -lntp | grep -E ':80|:8080'无输出即空闲。
3. 模型服务：本地推理用 Ollama，curl http://127.0.0.1:11434/api/tags返回 JSON 即已就绪；已有 OpenAI 兼容 API 可跳过。
4. 编译工具链（仅 Lite 源码构建）：Go 1.26、CGO（依赖 libsqlite3-dev）、Node.js + npm、Python 3.10 + uv。
5. 磁盘：标准版要预留 Postgres 数据卷与文件卷的空间，按知识库规模估。

部署过程：6 步完成启动

1. 克隆仓库

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

成功标志：目录下能看到docker-compose.yml与.env.example。

2. 生成配置文件

cp .env.example .env # Lite 路线改执行：cp .env.lite.example .env.lite

成功标志：.env存在。app 容器通过env_file读取它，文件缺失会导致 Compose 直接解析失败，所以这一步不能省。

3. 改必填项。标准版生成两把密钥并填入JWT_SECRET（openssl rand -hex 32）与SYSTEM_AES_KEY（必须是 32 字节，openssl rand -hex 16），数据库账号沿用模板里的DB_USER/DB_PASSWORD/DB_NAME即可；OLLAMA_BASE_URL默认指向http://host.docker.internal:11434，容器内的localhost指向容器自身，所以要写宿主机的网关地址才能访问你本机的 Ollama。Lite 则在.env.lite里把OLLAMA_BASE_URL指向http://127.0.0.1:11434（单进程跑在本机，直连回环即可），并填入SYSTEM_AES_KEY与JWT_SECRET。成功标志：两个密钥均非空。

4. 启动。标准版：

docker compose pull docker compose up -d

Lite 单条命令即可，先构建前端再编译 Go 二进制：

make run-lite

5. 等服务就绪

docker compose ps # 标准版：frontend/app/docreader/postgres/redis 均 running 或 healthy curl http://localhost:8080/health # 两种形态都监听 8080

成功标志：返回{"status":"ok"}。app 有健康检查（30s 间隔），首次冷启动等一两轮探针属正常现象。

6. 注册账号并配模型。浏览器打开http://localhost（Lite 同样访问http://localhost:8080），注册第一个账号，系统会自动创建个人空间并把你设为 Owner。在「知识库」页新建文档库，初始化向导里分别填对话模型与向量模型，点向导内的「测试」按钮确认两者连通后再保存。成功标志：两项连通性测试都通过。

确认跑通：5 个验收信号

1. 界面：http://localhost出现登录/注册页。没看到 →docker compose logs --tail=200 app看后端报错。
2. 模型连通：设置页对 LLM 与 Embedding 各测一次，均返回成功。失败 → 先ollama list确认模型已拉取，再核对标准版容器内必须用http://host.docker.internal:11434而不是127.0.0.1。
3. 上传链路：新建文档库传一份 PDF，状态按pending → processing → finalizing → completed走完。卡在 processing → 在解析追踪时间线里定位卡住的阶段，确认挂死可点击「中止解析」。
4. 问答链路：向这份文档问一个事实性问题，回答末尾带可展开的引用来源。没有引用 → 检查向量模型维度是否与入库时一致，更换 Embedding 模型需要重建索引。
5. 容器状态（标准版）：docker compose ps中五个核心服务无 restarting。反复重启 →docker compose logs <服务名>逐一定位。

用真实数据练手感

批量导入一批制度文档想做什么：把散落的技术手册变成可搜索的库。怎么操作：新建文档知识库后直接拖入文件，目录结构保留成文件夹树，可在上传确认框里批量打标签。你会看到：状态列从处理中翻成已完成，检索走向量与关键词双路召回，返回带出处的原文片段。

提问并回溯原文出处想做什么：确认某条报销规定的准确口径。怎么操作：进入对话页，选择知识库后提问。你会看到：默认「快速问答」智能体先检索再组织回答，点引用角标即可跳到原文段落核对。

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

出问题怎么办：对照表

数据变多以后：4 个调优参数

• BATCH_EMBED_SIZE（.env）— 默认 5，批量入库建议设 64 — 一次请求向量化更多分块，明显减少与 Ollama 的往返次数。
• CONCURRENCY_POOL_SIZE（.env）— 默认 5，Lite 默认 3 — 控制在 3–8：并发太高挤占内存拖慢在线问答，太低拖慢入库。
• DOCREADER_GRPC_MAX_WORKERS（.env）— 默认 4，建议设为 CPU 核数 — 文档解析是 CPU 密集型，并行度直接缩短排队时间。
• 模型参数num_ctx（Ollama 侧）— 按模型上限调大 — 上下文足够时检索片段不被截断，长文档问答更稳。8B 级模型上两者要二选一：要单条质量就加num_ctx，要吞吐就压低并发。

继续深入

• website-docs/01-getting-started/02-installation.md：Compose、Helm、Lite 与源码编译的完整差异和可选 profile 清单。
• website-docs/01-getting-started/03-quickstart.md：初始化到首次问答的界面流程，附纯 curl 的 API 调用示例。
• website-docs/01-getting-started/04-configuration.md：四层配置体系的优先级与全部环境变量。
• client/example.go：Go 客户端示例，写上传与检索脚本时可直接照抄结构。

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

【免费下载链接】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