企业官网建设流程全解析

WeKnora部署实践：5分钟跑通一个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 知识管理平台，能把 PDF、网页、Office 文档这些原始资料变成可问答的 RAG 知识库，还能派生出推理 Agent 和自动维护的 Wiki。想给团队搭一套"文档问得懂"的内部知识库，照着这篇部署实践走，Docker 环境下 5 分钟左右就能跑起来。

先认识一下这个项目

WeKnora 做的事情很简单：你上传文档，它负责解析、切块、向量化，之后你用自然语言提问，它从你的资料里检索并生成带引用的回答。最大的亮点是"一份数据，多种用法"——同一批文档既能做传统 RAG 问答，也能让 Agent 自主检索推理，还可以沉淀成带图谱的 Wiki 页面。

整体由几个容器分工协作：前端界面、Go 后端（app）、文档解析服务（docreader）、PostgreSQL 和 Redis，架构如下：

部署前准备

部署前先把环境自查一遍，缺一项都会卡住后面的步骤：

文档解析流水线本身比较重，扫描件 PDF 尤其耗资源，机器低配的话上传大文档时耐心等待即可，别急着重启。

5分钟跑起来

整个过程就四步，每步执行完看下输出再继续：

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

拿到全部代码和配置文件。

cp .env.example .env

复制环境变量模板。.env里的数据库账号、Redis 地址、存储类型都有可直接用的默认值，首次体验不改也能跑。

docker compose pull

拉取最新镜像，第一次会比较久。

docker compose up -d

后台启动核心服务，然后打开浏览器访问http://localhost，看到初始化向导界面就算成功了：

两个验证动作：

• 浏览器访问http://localhost:8080/health，返回正常说明后端已就绪；
• 在界面上新建一个知识库，传一个 PDF，稍后对它提问，回答能带引用就代表整条链路通了。

停止服务用docker compose down，数据在 Docker 卷里，重启不丢。

按场景配置

.env变量很多，但不同场景真正要动的只有几个。检索和分块参数集中在 config/config.yaml（app 容器启动时会挂载它），下面是三种典型场景的关键差异。

场景一：本地试玩

保持默认即可，什么都不用改：STORAGE_TYPE=local文件落在本地卷，GIN_MODE=release，并发池CONCURRENCY_POOL_SIZE默认 5。大模型用本机 Ollama 最省心——先ollama serve拉一个对话模型和一个 embedding 模型，再在设置页选为默认模型。

场景二：小团队试用

重点是把"文件存得稳、图谱能用"这两件事做上：

docker compose --profile neo4j --profile minio up -d

neo4jprofile 启动知识图谱（端口 7474/7687），minioprofile 启动对象存储（9000/9001），MinIO 控制台可在 9001 端口查看上传的原始文件。

同时在.env里把STORAGE_TYPE改为minio，NEO4J_ENABLE设为true，MAX_FILE_SIZE_MB（默认 50）按团队习惯放宽，改完docker compose up -d生效。

场景三：生产环境

生产上只动安全相关参数，性能参数保持默认先观察：

• GIN_MODE=release、LOG_LEVEL=info，日志走 stdout 由容器采集；
• DISABLE_REGISTRATION=true关闭公开注册，新用户通过邀请链接加入；
• SYSTEM_AES_KEY必须换成自己生成的 32 字节强随机值——API Key、模型凭证等敏感字段靠它加密落盘，丢了就无法恢复；
• WEKNORA_VERSION从latest固定到具体 release tag，升级时先docker compose pull再up -d，避免"拉了没换、换了没拉"。

检索质量调优放在 config/config.yaml 的conversation段：embedding_top_k: 30是向量初筛条数，回答不准时先调它；keyword_threshold（0.3）、vector_threshold（0.2）、rerank_threshold（0.3）分别对应关键词、向量、重排三道门槛，阈值调低会多召回。分块参数chunk_size: 512/chunk_overlap: 50对长文档问答效果影响大，改完需要重新解析知识库才生效。

常见坑与排查

现象一：app 容器反复重启，前端打不开

• 可能原因：后端没通过健康检查，常见是数据库连不上，或DB_PASSWORD里的特殊字符（#、@等）没处理好。
• 排查动作：docker compose logs app看报错；重点核对.env中DB_USER/DB_PASSWORD/DB_NAME和 postgres 容器是否健康（docker compose ps）。

现象二：能打开界面，但提问无响应或 502

• 可能原因：app 还没就绪时前端就转发了请求，或者模型没配好。
• 排查动作：curlhttp://localhost:8080/health；在设置页确认默认 LLM 和 embedding 模型都能连通——用 Ollama 时注意容器默认访问host.docker.internal:11434，Mac/Win 上没问题，Linux 上如果host.docker.internal不通，把OLLAMA_BASE_URL改成http://172.17.0.1:11434试试。

现象三：上传大文件失败或解析卡住

• 可能原因：超过MAX_FILE_SIZE_MB（默认 50MB）限制；扫描件 PDF 解析本身耗时长。
• 排查动作：先确认文件大小；确实在限制内还卡住，调大WEKNORA_DOCREADER_CALL_TIMEOUT（默认 30 分钟，单次解析 RPC 超时），日志里看 docreader 容器的输出。

现象四：知识图谱菜单是灰的 / 图谱查不到

• 可能原因：光设NEO4J_ENABLE=true没用，Neo4j 容器本身要用 profile 拉起来。
• 排查动作：用docker compose --profile neo4j up -d启动 Neo4j，确认 7687 端口在监听，再回设置页验证连接。具体见 docs/开启知识图谱功能.md。

现象五：换了向量库之后检索结果为空

• 可能原因：RETRIEVE_DRIVER换了（比如从postgres换成qdrant），但向量数据还留在旧库里，新库是空的。
• 排查动作：新库需要先重新向量化已有知识库；同时确认新库里 embedding 维度和模型一致。选型细节参考 docs/使用其他向量数据库.md。

上生产之前

扩展性：向量检索默认走 PostgreSQL（ParadeDB）内建能力，数据量大或想单独扩容时，通过 profile 换成 Qdrant、Milvus、Weaviate 等独立向量库，RETRIEVE_DRIVER甚至支持多库并行检索。App 是无状态服务，加副本时注意共享同一个 Redis 和存储后端即可。

安全：关闭公开注册、邀请制加人（docs/RBAC说明.md 有完整的多租户角色设计）；JWT_SECRET和SYSTEM_AES_KEY用随机值并离线备份；数据库和 MinIO 默认只监听容器内部网络，不要额外映射到宿主机。

监控：接上 Langfuse 能看清每次问答的完整链路——docker compose --profile langfuse up -d自建一套（Web 界面在 3000 端口），或在.env里指向云端 Langfuse，配合LANGFUSE_SAMPLE_RATE控制采样率，说明文档在 docs/Langfuse集成.md。

部署本身只是起点，真正拉开差距的是后续的知识库组织方式和检索调参。建议接着看 README_CN.md 里的功能全貌，命令行重度用户可以试一下 cli/README.md 的官方 CLI，用weknora doc upload直接把本地文档灌进知识库。

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