WeKnora 本地部署指南：30 分钟跑起你自己的 RAG 知识库

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/WeKnoraWeKnora 是一个开源 LLM 知识平台把原始文档变成可检索的 RAG 问答、自主推理 Agent 和自动维护的 Wiki。这篇部署指南写给想把内部资料留在本机的人不需要把文档交给第三方 API跟着做就能在约 30 分钟内得到一台可上传、可提问的知识库实例首次拉取标准版镜像另需 10–20 分钟。硬件参考 4 核 8GB 起步若叠加 Ollama 本地模型请再按模型体积预留内存。先定路线标准版、Lite 还是 Helm部署 WeKnora 前先决定用哪种形态后文步骤以标准版为主线Lite 的差异在步骤里行内标注。维度Docker Compose 标准版Lite 单二进制Helm依赖Docker 20.10 与 Compose v2Go 1.26 CGO Node构建期Kubernetes ≥ 1.25资源要求4 核 8GB 起步docreader 含 LibreOffice/Playwright 较吃内存低资源本机即可取决于集群规格账号与协作多空间注册登录RBAC 成员协作单空间浏览器访问仍需注册同标准版数据与检索ParadeDBPostgreSQL 17 BM25/向量 Redis单文件 SQLiteFTS5 sqlite-vec无 RedisParadeDB Redischart 内置解析引擎多引擎可选profile 按需扩展内置 Simple 引擎同标准版团队共享知识库选标准版只想在本机离线试用选 Lite已有 K8s 集群则用 helm/ 下的 chart。动手前5 项前置检查Docker 与 Compose仅标准版/Helmdocker --version与docker compose version能正常输出版本号。端口宿主机 80前端由FRONTEND_PORT控制与 8080后端 API未被占用ss -lntp | grep -E :80|:8080无输出即空闲。模型服务本地推理用 Ollamacurl http://127.0.0.1:11434/api/tags返回 JSON 即已就绪已有 OpenAI 兼容 API 可跳过。编译工具链仅 Lite 源码构建Go 1.26、CGO依赖 libsqlite3-dev、Node.js npm、Python 3.10 uv。磁盘标准版要预留 Postgres 数据卷与文件卷的空间按知识库规模估。部署过程6 步完成启动克隆仓库git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora成功标志目录下能看到docker-compose.yml与.env.example。生成配置文件cp .env.example .env # Lite 路线改执行cp .env.lite.example .env.lite成功标志.env存在。app 容器通过env_file读取它文件缺失会导致 Compose 直接解析失败所以这一步不能省。改必填项。标准版生成两把密钥并填入JWT_SECRETopenssl 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。成功标志两个密钥均非空。启动。标准版docker compose pull docker compose up -dLite 单条命令即可先构建前端再编译 Go 二进制make run-lite等服务就绪docker compose ps # 标准版frontend/app/docreader/postgres/redis 均 running 或 healthy curl http://localhost:8080/health # 两种形态都监听 8080成功标志返回{status:ok}。app 有健康检查30s 间隔首次冷启动等一两轮探针属正常现象。注册账号并配模型。浏览器打开http://localhostLite 同样访问http://localhost:8080注册第一个账号系统会自动创建个人空间并把你设为 Owner。在「知识库」页新建文档库初始化向导里分别填对话模型与向量模型点向导内的「测试」按钮确认两者连通后再保存。成功标志两项连通性测试都通过。确认跑通5 个验收信号界面http://localhost出现登录/注册页。没看到 →docker compose logs --tail200 app看后端报错。模型连通设置页对 LLM 与 Embedding 各测一次均返回成功。失败 → 先ollama list确认模型已拉取再核对标准版容器内必须用http://host.docker.internal:11434而不是127.0.0.1。上传链路新建文档库传一份 PDF状态按pending → processing → finalizing → completed走完。卡在 processing → 在解析追踪时间线里定位卡住的阶段确认挂死可点击「中止解析」。问答链路向这份文档问一个事实性问题回答末尾带可展开的引用来源。没有引用 → 检查向量模型维度是否与入库时一致更换 Embedding 模型需要重建索引。容器状态标准版docker compose ps中五个核心服务无 restarting。反复重启 →docker compose logs 服务名逐一定位。用真实数据练手感批量导入一批制度文档想做什么把散落的技术手册变成可搜索的库。怎么操作新建文档知识库后直接拖入文件目录结构保留成文件夹树可在上传确认框里批量打标签。你会看到状态列从处理中翻成已完成检索走向量与关键词双路召回返回带出处的原文片段。提问并回溯原文出处想做什么确认某条报销规定的准确口径。怎么操作进入对话页选择知识库后提问。你会看到默认「快速问答」智能体先检索再组织回答点引用角标即可跳到原文段落核对。改一个检索块并回滚想做什么发现某分块是错版内容。怎么操作在文档详情页进分块编辑改完保存。你会看到索引自动重建下一次检索立刻生效界面保留版本历史支持 diff 与回滚。出问题怎么办对照表现象常见原因处理前端打不开80 端口被占或容器未就绪改FRONTEND_PORTdocker compose psdocker compose logs --tail200 app看具体报错模型测试失败Ollama 未启动或地址写错Lite 指向127.0.0.1:11434标准版容器内指向host.docker.internal:11434ollama list确认模型已拉取文档一直停在处理中Embedding 未配好或解析任务挂起文档详情的解析追踪时间线定位阶段docker compose logs --tail200 docreader看解析侧改完.env没生效容器未重建restart不重读环境变量用docker compose up -d app重建对应容器图片在别处打开是死链存储后端对外不可达标准版用 MinIO--profile minio时给它配一个外部可达地址保存的配置几秒后恢复旧值操作发生在别人的空间里切回自己创建的空间再改或用X-Tenant-ID核对当前空间数据变多以后4 个调优参数BATCH_EMBED_SIZE.env— 默认 5批量入库建议设 64 — 一次请求向量化更多分块明显减少与 Ollama 的往返次数。CONCURRENCY_POOL_SIZE.env— 默认 5Lite 默认 3 — 控制在 3–8并发太高挤占内存拖慢在线问答太低拖慢入库。DOCREADER_GRPC_MAX_WORKERS.env— 默认 4建议设为 CPU 核数 — 文档解析是 CPU 密集型并行度直接缩短排队时间。模型参数num_ctxOllama 侧— 按模型上限调大 — 上下文足够时检索片段不被截断长文档问答更稳。8B 级模型上两者要二选一要单条质量就加num_ctx要吞吐就压低并发。继续深入website-docs/01-getting-started/02-installation.mdCompose、Helm、Lite 与源码编译的完整差异和可选 profile 清单。website-docs/01-getting-started/03-quickstart.md初始化到首次问答的界面流程附纯 curl 的 API 调用示例。website-docs/01-getting-started/04-configuration.md四层配置体系的优先级与全部环境变量。client/example.goGo 客户端示例写上传与检索脚本时可直接照抄结构。下一步建议先导入 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考