WeKnora 本地部署：5 步从空机器到能问答的文档知识库

WeKnora 本地部署：5 步从空机器到能问答的文档知识库

【免费下载链接】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 知识库、能自主检索的 ReAct Agent，还有一份自维护的 Wiki。适合想在本地先跑通、或打算给团队搭文档问答服务的人。

全程就 3 条命令：

# 克隆仓库并复制环境变量模板（容器启动时读取 .env） git clone https://gitcode.com/GitHub_Trending/we/WeKnora && cd WeKnora cp .env.example .env # 拉取镜像并启动核心服务（frontend、app、postgres、redis、docreader 等） docker compose pull && docker compose up -d

前提是装好 Docker 和 Docker Compose，别的什么都不用装。

跑起来的 5 个步骤

第 1 步：确认 .env 已就位

上面的命令已经帮你cp .env.example .env。端口、数据库账号、模型地址全在这一个文件里。不改任何配置也能直接跑，因为模板里的默认值（本地存储 + 内置 postgres）就是可用的。

第 2 步：端口冲突才需要改端口

默认前端占 80、后端 API 占 8080。如果你的 8080 已被其他服务占用，改一下再启动：

# 把 .env 里的后端端口改成 8000，避免和其他服务抢 8080 sed -i 's/^APP_PORT=8080/APP_PORT=8000/' .env

第 3 步：验证服务健康

# 查看容器状态；frontend 要等 app 通过健康检查才会放行 docker compose ps

另外curl http://localhost:8080/health返回 200 就说明后端起来了。首次启动要拉镜像，耐心等一两分钟。

第 4 步：打开界面，上传第一篇文档

访问 http://localhost，按向导建账号、建知识库，随便传一个 PDF 或 Word。等文档解析完成，向它提个问题，能拿到带引用来源的答案，就算跑通了：

第 5 步（可选）：接本地 Ollama 模型

想省云 API 费用、用本地模型的话，先起 Ollama：

# 后台启动 Ollama；.env 默认地址指向 Docker 宿主机 ollama serve > /dev/null 2>&1 &

.env里OLLAMA_BASE_URL默认是http://host.docker.internal:11434，Ollama 装在别的机器就改成对应地址。

最容易配错的 5 个配置项

出问题了：4 个高频故障

1. 打开 http://localhost 报 502 或空白页

• 现象：frontend 容器显示在跑，页面就是打不开
• 原因：app 容器还没通过健康检查，frontend 默认要等它 healthy
• 解决：docker compose logs -f app docreader postgres找 ERROR，修好后docker compose restart app

2. 文档上传成功，但提问报模型错误

• 现象：上传流程走完了，问答环节直接报错
• 原因：对话模型或 Embedding 模型没配置完整
• 解决：在.env补齐INIT_LLM_MODEL_NAME、INIT_EMBEDDING_MODEL_NAME（含向量维度和模型 ID），本地模型再确认 Ollama 在跑，然后docker compose up -d重启

3. 多模态知识库里的图片不显示

• 现象：文档解析出图了，界面显示无效链接
• 原因：没启用 minio profile，或MINIO_PUBLIC_ENDPOINT还是localhost
• 解决：docker compose --profile minio up -d；要从别的设备访问图片，把该变量改成机器实际 IP

4. PaddleOCR 在部分平台启动失败

• 现象：扫描件或图片文档解析报错，docreader 日志有 OCR 启动失败
• 原因：OCR_BACKEND=paddle不被当前平台支持
• 解决：docreader 服务里改OCR_BACKEND=vlm并配外部 VLM（OCR_API_BASE_URL/OCR_API_KEY/OCR_MODEL），或干脆删掉 OCR 配置，再docker compose up -d

下一步

• 按需开启可选组件：知识图谱docker compose --profile neo4j up -d，链路追踪（Langfuse，端口 3000）--profile langfuse，--profile full一次全开。
• 多人协作：内置空间级 RBAC，Owner / Admin / Contributor / Viewer 四档角色，角色矩阵见 docs/RBAC说明.md。
• 接入你自己的 Agent：官方 CLI（cli/）和 MCP Server（mcp-server/）都能让编码 Agent 直接检索、问答你的文档库。
• 生产部署：设DISABLE_REGISTRATION=true关闭自助注册，服务放内网，别直接暴露公网。

跑通之后，重点就转向检索质量和权限设计了。排障手册在 docs/QA.md，完整产品文档在 website-docs/，API 参考在 docs/api/，照着往下接就行。

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