WeKnora 完整部署指南：Docker Compose 四步跑通私有 RAG 知识库

WeKnora 完整部署指南Docker Compose 四步跑通私有 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这篇文章只讲一件事在一台 Linux 机器上用 Docker Compose 把 WeKnora——一个能把原始文档变成可检索 RAG 知识库、推理 Agent 和自动维护 Wiki 的开源 LLM 知识平台——完整跑起来。从克隆代码到打开网页开始提问顺利的话 10 分钟可以完成。下文覆盖环境自检、启动、验证、扩展、调优和上线加固照着顺序做完即可。备齐硬件并运行自检命令WeKnora 本身只是应用层真正的计算量在文档解析和向量检索上。只要大模型走云端 API配置要求不高如果你打算在同一台机器上用 Ollama 跑本地模型内存要看你加载多大的模型。使用场景CPU内存磁盘个人体验LLM 走 API2 核8GB20GB团队生产4 核16GB100GB本机跑 Ollama 大模型8 核32GB100GB一条命令把硬件和 Docker 状态一起摸清楚# 查看 CPU 核数、内存、磁盘余量并确认 Docker Compose 可用 nproc free -h df -h . docker compose version 最后一条命令报command not found或权限错误先解决 Docker 安装或用户组问题见文末速查再往下走。克隆代码并四步启动所有命令都在项目根目录执行共四条# 克隆代码仓库并进入项目目录 git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora# 从模板生成环境变量文件模板内每个变量都带中文注释 cp .env.example .env用编辑器打开.env只动下面这几项其余保持默认变量默认值说明DB_PASSWORD示例占位数据库密码必须换成自己的强密码REDIS_PASSWORD示例占位Redis 密码同上SYSTEM_AES_KEY示例占位32 字节主密钥用于加密数据库里的 API Key 等敏感字段丢了数据不可恢复务必离线备份STORAGE_TYPElocal文件存本地卷最省事有对象存储需求再换minio/s3等WEKNORA_VERSIONlatest生产环境建议锁定具体版本 tag升级才可控向量检索默认复用 ParadeDB 版 PostgresRETRIEVE_DRIVERpostgres无需额外动作。然后拉镜像并启动# 拉取最新镜像并后台启动核心服务 docker compose pull docker compose up -d仓库里的 scripts/start_all.sh 也能一键拉起附带可选装 Ollama但手动执行 compose 更容易定位问题建议先用上面这套。首次拉取镜像较大等待时间与网速有关。验证服务健康并配置第一个模型# 查看各容器状态app 显示 healthy 即代表这一步完成 docker compose ps前端等app容器健康检查通过后才启动所以看到 frontend 在跑说明整条链路已就绪。浏览器打开http://localhost进入 Web 界面API 在http://localhost:8080。第一次进入时你会看到初始引导注册管理员账号然后在「设置」里配置 LLM 和 Embedding 模型API 或 Ollama 均可。模型不配好文档解析完也不会产生可问答的内容这一步别跳过。如果你用本机 Ollama 供模型需先ollama serve并ollama pull一个模型不配 Ollama 也不影响启动。看懂容器布局并按需叠加扩展默认up -d只起核心五件套容器作用宿主端口frontendWeb 界面Nginx80app主应用API 与业务逻辑8080postgresParadeDB关系库与向量库二合一不对外redis流处理与任务队列不对外docreader文档解析gRPC仅容器网络内其余组件通过--profile开关叠加多个可组合# 例同时启用知识图谱Neo4j与对象存储MinIO docker compose --profile neo4j --profile minio pull docker compose --profile neo4j --profile minio up -d常用开关full全量功能、neo4j知识图谱、minio对象存储、langfuse链路追踪、searxng自建网页搜索还有qdrant、milvus、doris等替代向量库。完整说明见 README_CN.md 的可选服务一节。做三处让解析更快的调优按收益排序每条都给出改什么、为什么、怎么生效提高解析并发。文档解析是异步队列驱动的.env里WEKNORA_ASYNQ_CORE_CONCURRENCY默认 8控制解析主链路并发WEKNORA_MODEL_MAX_CONCURRENCY默认 32限制每个模型的后台并发上限。机器余量足就把前者从 8 提到 16批量导入速度明显上升。放宽单文件限制。MAX_FILE_SIZE_MB默认 50会同时约束上传、解析和前端校验四层。经常传大文件时统一调大注意这项改了必须同时重启app和frontend两个容器。日志降噪。默认LOG_LEVEL是debug日志量很大稳定后改为info再设LOG_PATH落盘排障时直接翻文件。前两项改的都是环境变量统一用这条命令让 app 容器重建生效# 重新加载 .env 并重建 app 容器使新配置生效 docker compose up -d app完成上线前加固与备份设置默认配置里多处是占位密码暴露到公网前逐项过一遍这份清单已替换DB_PASSWORD和REDIS_PASSWORD为强密码已设置SYSTEM_AES_KEYopenssl rand -hex 16生成且已离线保管——丢失意味着所有加密字段永久解不开已设DISABLE_REGISTRATIONtrue新用户只能由管理员邀请不能公开注册前端已挂 HTTPS反代 nginx/caddy 终止证书即可备份脚本已实际执行过一次数据都在 Docker 卷里导出数据库即可还原数据库备份一条命令用户名、库名按.env实际值替换# 导出数据库到本地 SQL 文件文件名带当天日期 docker compose exec postgres pg_dump -U postgres -d WeKnora weknora_$(date %F).sql升级同样两步先把.env里WEKNORA_VERSION指到目标版本再拉取并重建只执行up不pull会复用旧镜像# 拉取与 WEKNORA_VERSION 匹配的镜像并用新镜像重建容器 docker compose pull docker compose up -d日常巡检看两处就够docker stats盯资源占用docker compose logs -f app盯报错。更细的排障经验见 docs/QA.md。遇到问题先查这里点击展开常见问题速查Q:docker: command not found或连不上 daemon 报权限错误 A: 前者安装 Docker 后重新自检后者把当前用户加进 docker 组sudo usermod -aG docker $USER重开终端再试。Q: 80 端口被占用前端起不来 A: 把.env里FRONTEND_PORT80改成别的值如 8088再执行docker compose up -d重建。Q:app容器反复重启 A: 先docker compose logs -f app定位最常见原因是.env里DB_USER/DB_PASSWORD/DB_NAME与 postgres 容器实际初始化值对不上。Q: 文档上传成功但一直卡在处理中问不出答案 A: 多半是模型没配好。进「设置」确认 LLM 和 Embedding 模型均已填写API 方式还需BASE_URL和 API Key然后重传一篇文档验证。Q: 没装 Ollama 会不会启动失败 A: 不会。OLLAMA_OPTIONAL默认开启Ollama 不可用时只告警不阻断用云端 API 模型可完全忽略这个变量。按自检、启动、验证、加固的顺序做完WeKnora 就从跑起来了进入能长期跑的状态。下一步建议把第一批文档灌进一个知识库用真实问题检验检索质量再按需打开知识图谱或 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），仅供参考