WeKnora 部署指南：从克隆到上线，跑通 RAG 知识库、Agent 推理与 Wiki 生成

WeKnora 部署指南从克隆到上线跑通 RAG 知识库、Agent 推理与 Wiki 生成【免费下载链接】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 知识管理平台把 PDF、Word、网页等原始文档变成可提问的 RAG 知识库、会自主调用工具的推理 Agent以及一套 Agent 自己维护的 Wiki。你读完这篇部署指南后能完成 WeKnora 的容器化部署、配置好模型与向量检索、验证 RAG 问答真的能跑并把它推到生产环境。 第一次上手体验四条命令之后你能看到什么装完后打开浏览器访问http://localhost你会先遇到注册页创建账号后自动进入初始化向导website-docs/public/screenshots/quickstart-register.png、quickstart-init-wizard.png记录了这两步的样子。向导里填入 LLM 与 Embedding 模型信息接着建一个知识库、拖入几份文档几分钟后就能在对话页对着文档提问答案会带可点击的引用来源。整条链路——解析、切块、向量化、检索、生成——都在这个默认部署里。最短部署路径就四步docker compose up -d会拉起核心服务前端、API、文档解析器、PostgreSQL、Redisgit clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora cp .env.example .env # 按注释编辑文件里有全部参数说明 docker compose pull docker compose up -d启动成功判据docker compose ps里WeKnora-app状态为 healthycompose 内置了 30 秒一次的健康检查探测http://localhost:8080/health。如果你更喜欢带自检的入口./scripts/start_all.sh --check会先检查环境--all则连 Ollama 一起拉起。 系统是怎么搭起来的六个容器各司其职这一节帮你建立「哪个容器坏了影响哪块功能」的直觉。WeKnora 用 Docker Compose 编排默认栈的核心角色是frontend80 端口Nginx 托管 UI同时把/api反向代理到后端相当于前台兼网关。app8080 端口Go 写的 API 服务承载会话、检索编排、Agent 循环和任务调度是唯一的业务大脑。docreadergRPC 50051 端口独立的文档解析工作间PDF、Word、EPUB、Excel 都在这里拆成文本和分块app 通过 gRPC 调用它。postgresParadeDB 镜像一个库身兼两职——关系数据用户、知识库、任务和向量检索。混合检索靠 BM25 关键词召回 pgvector 稠密向量召回再用 Rerank 模型精排。redis既做流式响应后端也做 Asynq 任务队列——文档解析、摘要、图谱抽取都排队走它避免大文件卡死在线问答。sandboxprofile 可选Agent 执行技能代码的隔离沙箱。理解这张图有个省事的角度它不是一堆必须同时起的服务而是「核心栈 按需插件」。Neo4j、MinIO、Qdrant、Milvus、Langfuse、SearXNG 都挂在 Compose profile 后面不启动就不占资源。⚙️ 哪些配置值得动四个高频参数与两个坑默认值能跑但有几处你会在真实使用里很快碰到。参数全貌在.env.example按 A-J 十组分类注释写得很细这里只挑关键项。# .env 关键项默认值 → 何时改 DB_DRIVERpostgres # 数据库轻量玩法可换 sqlite 配 memory 流后端见 .env.lite.example RETRIEVE_DRIVERpostgres # 向量检索后端默认 pgvector可切 qdrant/milvus/weaviate 等 8 种 MAX_FILE_SIZE_MB50 # 单文件上传上限改完必须同时重启 app/frontend/docreader 四层 CONCURRENCY_POOL_SIZE5 # Embedding 并发模型服务返回 429 限流时调小另外两个高频坑Embedding 向量维度必须与模型一致常见 768/1536。在 UI 向导或config/builtin_models.yaml里配错症状是入库后检索结果乱——维度对不上时向量检索等于在噪音里捞针。切块参数在config/config.yaml默认chunk_size: 512、chunk_overlap: 50。多数文档不用动如果大量长表格或代码文档检索不准再按 docs/CHUNKING.md 的思路调。文档解析超时默认单文档 2 小时WEKNORA_DOCUMENT_PROCESS_TIMEOUT几百页的扫描版 PDF 才需要碰它。✅ 怎么判断部署成功三步验证与高频故障「容器全绿」只是及格线真正的验收是问答链路。curl -f http://localhost:8080/health # 期望 HTTP 200 docker compose logs -f app docreader postgres # 看是否有 ERROR然后走一遍完整闭环注册账号 → 建知识库 → 上传一份你熟悉的 PDF → 等状态从processing变completed→ 问一个只有这份文档里才有的问题答案应带引用浮层。三个最高频故障的排查路径完整版在 docs/QA.md文档一直处理失败/上传报错九成是 LLM 或 Embedding 模型没配好。看 app 日志里的ERROR核对.env中模型地址与 API KeyOllama 用户先确认ollama serve在跑。图片显示无效链接默认本地存储STORAGE_TYPElocal下图片走后端代理若换了 MinIO 却忘了启动它docker compose --profile minio up -d或 IM 场景下没设APP_EXTERNAL_URL让图片对外可达都会出现破图。升级后版本不对只跑docker compose up -d会复用本地缓存镜像必须docker compose pull后再起.env里用WEKNORA_VERSION固定到具体 release tag。 走向生产环境变量开关与多副本从「能用」到「敢上线」差别集中在几个开关上。生产最小改动集# .env 生产环境最小改动 GIN_MODErelease # 禁用 Swagger、降低日志噪音 LOG_LEVELinfo # 默认 debug 太吵 DISABLE_REGISTRATIONtrue # 生产建议关闭开放注册走邀请制 WEKNORA_TENANT_ENABLE_RBACtrue # 默认即 true设 false 是「只记录不拦截」的观察模式资源与扩展方面两条实用事实任务队列按「核心解析 / 后处理 / 摘要等多模态富化 / 长耗时维护 / 弹性共享」五池隔离变量如WEKNORA_ASYNQ_CORE_CONCURRENCY默认 8/2/12/4/6并且支持在系统设置页运行时改并发、不用重启。队列深度和失败任务在管理端的任务队列面板可查可重试。app 是多副本安全的Asynq 各池并发数按「每副本保底值 × 副本数」叠加副本间通过共享 Redis 分发任务。Kubernetes 部署用仓库里的 helm/ Chartvalues.yaml对应同一套环境变量。可选组件按需求加 profile要知识图谱--profile neo4j要对象存储--profile minio要自托管链路追踪--profile langfuse全量功能--profile full。️ 安全与可观测默认给你的和要自己补的WeKnora 默认已经做了一批防护API Key 与数据源凭据用 AES-256-GCM 落盘加密、出站 HTTP 有 SSRF 校验向量库等外部地址过校验时可用SSRF_WHITELIST_EXTRA放行内网服务、空间级 RBAC 是四级角色矩阵Owner/Admin/Contributor/Viewer加每空间审计日志默认保留 90 天。需要你亲手补的SYSTEM_AES_KEY必须是 32 字节且妥善保存——它丢了库里所有加密字段API Key、模型凭证无法解密JWT_SECRET同理生产别用模板默认值。docreader 与 app 之间的 gRPC 默认走内网明文可开GRPC_TLS_ENABLED加认证 tokenGRPC_AUTH_TOKEN托管 Redis 则开REDIS_USE_TLS。有统一登录需求时支持 OIDCOIDC_AUTH_ENABLEtrue配置细节见 docs/OIDC认证调用流程.md。可观测性靠 Langfuse.env里同时填LANGFUSE_PUBLIC_KEY和LANGFUSE_SECRET_KEY即自动启用连云版或--profile langfuse自建的都可之后每次 chat、embedding、rerank、VLM 调用的耗时和 token 消耗都有追踪高流量下用LANGFUSE_SAMPLE_RATE控采样。配合队列面板和docker stats延迟和瓶颈基本都能定位。 延伸阅读深入哪个方向看哪份文档部署跑通后按你的关注点继续完整产品文档站在 website-docs/VitePress覆盖约 360 个 API 端点与 150 个环境变量cd website-docs npm run dev可本地预览接口逐个查 docs/api/README.md向量库选型看 docs/使用其他向量数据库.mdRBAC 细节看 docs/RBAC说明.md。遇到问题先翻 docs/QA.md那里按「现象 → 排查步骤」整理好了最常见的坑。【免费下载链接】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），仅供参考