WeKnora 部署实战从最小运行到生产加固的六步路径【免费下载链接】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 问答、会自主编排检索与工具的推理代理、以及自我维护的 Wiki。如果你要在内网落一套私有知识库或给团队接一个能答业务问题的问答入口这套东西可以直接跑起来。下面按能跑 → 跑得对 → 跑得稳 → 扛得住的顺序展开跳过那些不碰就不影响启动的部分。 项目速览一句话喂文档收答案。它负责解析含 PDF/Word/Excel/XMind 等十余种格式、切块、向量化、混合检索再交给大模型生成带引用的回答需要时代理会自己调用 MCP 工具、沙箱脚本和网络搜索来完成多步任务。适合两类人——要做企业知识沉淀的技术决策者以及负责把它跑在服务器上的运维工程师。 部署前置条件先把依赖对齐能少走大量弯路。三项依赖的最低档是官方docker-compose.yml默认能起的最小组合Postgres Redis 本地文件存储推荐档对应生产常见规模。依赖项最低档推荐档说明内存8 GB16 GB 以上向量库和解析都吃内存Postgres 需独立预算磁盘可用20 GB50 GB 以上文档原件、向量索引、容器镜像都要落盘CPU4 核8 核以上大扫描件解析可并行核越多越短Docker20.1024.x需支持docker composev2 插件网络端口80 / 8080 空闲同左 对象存储端口前端 80后端 API 8080注意两点默认组合里 Postgres 用的是 ParadeDB 镜像paradedb/paradedb:v0.22.2-pg17自带 pgvector 向量扩展Redis 跑在 6379。这两个容器只挂在 compose 内部网络WeKnora-network上不对外映射所以主机防火墙只需放行 80 和 8080 两个端口。 最小可运行部署整条链路是一条单向数据流frontendNginx80 端口把请求代理到appGo 主服务8080 端口app通过 gRPC 调docreader50051只在内网解析文档用两者都依赖postgres和redis。默认存储走本地磁盘向量检索落在 Postgres 的 pgvector 里所以不启动任何额外容器就能跑通最小闭环。# 1. 拉代码 git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora # 2. 生成并编辑环境变量必填项见下一节 cp .env.example .env nano .env # 3. 启动全部核心服务自动检查环境、拉镜像、起容器 ./scripts/start_all.sh --all.env里有几处占位符必须替换否则容器起不来或密钥不安全# 数据库compose 里的 Postgres 用这三个建库 DB_USERpostgres DB_PASSWORD改成强密码 DB_NAMEWeKnora # Redis 密码compose 的 redis 容器 --requirepass 读取它 REDIS_PASSWORD改成强密码 # 内置模型三件套问答能用的前提 LLM_BASE_URL你的模型服务地址 LLM_API_KEY你的 key LLM_MODEL_NAME模型名 EMBEDDING_BASE_URL向量模型地址 EMBEDDING_API_KEY向量模型 key EMBEDDING_MODEL_NAME向量模型名启动成功的三个标志./scripts/start_all.sh --all尾部打印各服务状态且无Errordocker compose ps里app、frontend、docreader、postgres、redis均为Upapp 与 docreader 带healthycurl http://localhost:8080/health返回 200。三者齐备最小闭环就绪。⚙️ 关键配置解读config/config.yaml被以只读方式挂载进app容器改完docker compose up -d app重启即生效。下面只挑五个真正影响答得准不准、跑得快不快的参数其余保持默认即可。参数默认值为什么这么设何时该改conversation.embedding_top_k30混合检索阶段粗召回的候选条数30 在精度和耗时之间平衡给重排序留足原料高精度场景调到 50召回不足时再往上conversation.rerank_top_k30重排序后的最终候选数直接决定塞进大模型上下文多少片段上下文窗口紧张就下调到 10-15conversation.vector_threshold0.2向量相似度门槛0.2 偏松宁可多召回再靠 rerank 过滤避免硬门槛漏检出现大量不相关命中时抬到 0.3conversation.max_rounds5多轮上下文保留轮数5 轮覆盖绝大多数追问链长对话场景调到 10简单 FAQ 降到 3knowledge_base.chunk_size512分块大小512 字对中英混排文档召回粒度最稳过小丢上下文、过大稀释语义长表格/代码多的库可上调到 768chunk_overlap默认 50约为chunk_size的 10%作用是让相邻块保留边界重叠避免一个段落被切断后语义断裂。它和chunk_size建议按同一比例联动不要只改一个。检索质量想再精调看keyword_threshold0.3和rerank_threshold0.3——前者管关键词匹配后者管重排两者都偏保守先动上面五个再动这两个。✅ 功能验证部署完不要直接放量按顺序逐项确认模块可用。每项给出命令和预期输出。容器健康docker compose ps。预期app显示healthy其余核心容器为Up。若有Restarting先docker compose logs --tail 50 app看报错。后端存活curl -s http://localhost:8080/health。预期返回 200 且非空。这是 compose 里 app 服务自身 healthcheck 探的同一地址。前端可达curl -I http://localhost:80。预期HTTP/1.1 200说明 Nginx 已把静态资源和服务端代理接好。解析链路在 Web UI 建一个知识库并上传一份 PDF看文档状态从processing变为已完成。这一步同时验证了app → docreader → Postgres的 gRPC 与入库链路比单测更可信。检索问答用文档里能明确命中的问题提问预期回答带引用来源且内容对得上。若答非所问先查embedding_top_k与模型是否配错。 运维与故障速查监控接入生产建议开 Langfuse 做可观测性。设LANGFUSE_ENABLED并填LANGFUSE_HOST、LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY后agent 的推理链路、token 用量、管线耗时会进入 LangfuseLANGFUSE_SAMPLE_RATE控制在 0.1 左右即可。运行时还有内置任务队列面板能看各阶段 worker 池并发和失败任务配合docker stats看容器资源、Postgres 慢查询看数据库瓶颈。高频故障按现象 → 原因 → 解法排查现象常见原因解法app 一直Restarting.env缺必填项或密钥长度不对如SYSTEM_AES_KEY非 32 字节docker compose logs app定位补全必填、密钥用 32 字节Postgres 连接失败Postgres 未就绪app 先启动等待postgres变healthydepends_on已设service_healthy勿绕过文档卡在processing单文档超时或解析 worker 不足调大WEKNORA_DOCUMENT_PROCESS_TIMEOUT默认 2hDOCREADER_PDF_RENDER_PARALLELISM加并行问答答非所问向量/对话模型配错或RETRIEVE_DRIVER与库里不一致核对LLM_*/EMBEDDING_*确认RETRIEVE_DRIVER与实际存储一致向量检索慢向量库资源不足独立给向量库加内存缩小embedding_top_k️ 生产加固开发和生产差异集中在三类必须项其余保持默认即可不必为开发机单独维护一套。安全必须# 生产务必关闭公开注册、收紧密钥 DISABLE_REGISTRATIONtrue GIN_MODErelease JWT_SECRETopenssl rand -hex 32 生成 SYSTEM_AES_KEY必须恰好 32 字节openssl rand -base64 32 后截断SYSTEM_AES_KEY是数据库里 API Key 等敏感字段落盘加密的主密钥丢失则所有已加密数据不可恢复务必离线备份。WEKNORA_AUTH_COMPLEX_PASSWORD_ENABLEDtrue可强制密码含大小写数字特殊字符。网络隔离必须对外只暴露 80前端和 8080API。Postgres、Redis、MinIO9000/9001、Neo4j7687默认只在WeKnora-network内部可达不要额外ports映射到0.0.0.0。若用 MinIO 存原件MINIO_USE_SSLtrue开 TLS并配访问策略。高可用可选要开知识图谱加--profile neo4j起 Neo4j 并在.env设NEO4J_ENABLEtrue这是图谱唯一开关旧的ENABLE_GRAPH_RAG已废弃。要换独立向量库按RETRIEVE_DRIVER选qdrant/milvus/weaviate对应 profile 启动。多副本 负载均衡属集群场景超出单机 compose 范畴以项目部署文档为准。 快速参考部署前Docker Compose v2 可用主机 80 / 8080 端口空闲内存 ≥ 8GB、磁盘 ≥ 20GB、CPU ≥ 4 核.env必填项已替换数据库三件套、Redis 密码、模型三件套启动后docker compose ps全部Upapp/docreader 带healthycurl http://localhost:8080/health返回 200前端 80 端口可访问能登录上传一份文档并完成解析问答命中且带引用生产上线前DISABLE_REGISTRATIONtrue、GIN_MODEreleaseJWT_SECRET、SYSTEM_AES_KEY已换随机值并离线备份数据库/Redis/对象存储未对外映射MinIO 开 TLS延伸阅读仓库内相对路径docs/快速开发模式说明.md — 本地快速起后端docs/使用其他向量数据库.md — 换 Qdrant/Milvus/Weaviatedocs/开启知识图谱功能.md — Neo4j 图谱启用docs/RBAC说明.md — 多空间角色与审计config/config.yaml — 对话与检索参数源头完成以上配置后建议先用docker compose logs -f app盯 10 分钟确认无异常滚动日志再放开真实流量。【免费下载链接】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），仅供参考
WeKnora 部署实战：从最小运行到生产加固的六步路径
WeKnora 部署实战从最小运行到生产加固的六步路径【免费下载链接】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 问答、会自主编排检索与工具的推理代理、以及自我维护的 Wiki。如果你要在内网落一套私有知识库或给团队接一个能答业务问题的问答入口这套东西可以直接跑起来。下面按能跑 → 跑得对 → 跑得稳 → 扛得住的顺序展开跳过那些不碰就不影响启动的部分。 项目速览一句话喂文档收答案。它负责解析含 PDF/Word/Excel/XMind 等十余种格式、切块、向量化、混合检索再交给大模型生成带引用的回答需要时代理会自己调用 MCP 工具、沙箱脚本和网络搜索来完成多步任务。适合两类人——要做企业知识沉淀的技术决策者以及负责把它跑在服务器上的运维工程师。 部署前置条件先把依赖对齐能少走大量弯路。三项依赖的最低档是官方docker-compose.yml默认能起的最小组合Postgres Redis 本地文件存储推荐档对应生产常见规模。依赖项最低档推荐档说明内存8 GB16 GB 以上向量库和解析都吃内存Postgres 需独立预算磁盘可用20 GB50 GB 以上文档原件、向量索引、容器镜像都要落盘CPU4 核8 核以上大扫描件解析可并行核越多越短Docker20.1024.x需支持docker composev2 插件网络端口80 / 8080 空闲同左 对象存储端口前端 80后端 API 8080注意两点默认组合里 Postgres 用的是 ParadeDB 镜像paradedb/paradedb:v0.22.2-pg17自带 pgvector 向量扩展Redis 跑在 6379。这两个容器只挂在 compose 内部网络WeKnora-network上不对外映射所以主机防火墙只需放行 80 和 8080 两个端口。 最小可运行部署整条链路是一条单向数据流frontendNginx80 端口把请求代理到appGo 主服务8080 端口app通过 gRPC 调docreader50051只在内网解析文档用两者都依赖postgres和redis。默认存储走本地磁盘向量检索落在 Postgres 的 pgvector 里所以不启动任何额外容器就能跑通最小闭环。# 1. 拉代码 git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora # 2. 生成并编辑环境变量必填项见下一节 cp .env.example .env nano .env # 3. 启动全部核心服务自动检查环境、拉镜像、起容器 ./scripts/start_all.sh --all.env里有几处占位符必须替换否则容器起不来或密钥不安全# 数据库compose 里的 Postgres 用这三个建库 DB_USERpostgres DB_PASSWORD改成强密码 DB_NAMEWeKnora # Redis 密码compose 的 redis 容器 --requirepass 读取它 REDIS_PASSWORD改成强密码 # 内置模型三件套问答能用的前提 LLM_BASE_URL你的模型服务地址 LLM_API_KEY你的 key LLM_MODEL_NAME模型名 EMBEDDING_BASE_URL向量模型地址 EMBEDDING_API_KEY向量模型 key EMBEDDING_MODEL_NAME向量模型名启动成功的三个标志./scripts/start_all.sh --all尾部打印各服务状态且无Errordocker compose ps里app、frontend、docreader、postgres、redis均为Upapp 与 docreader 带healthycurl http://localhost:8080/health返回 200。三者齐备最小闭环就绪。⚙️ 关键配置解读config/config.yaml被以只读方式挂载进app容器改完docker compose up -d app重启即生效。下面只挑五个真正影响答得准不准、跑得快不快的参数其余保持默认即可。参数默认值为什么这么设何时该改conversation.embedding_top_k30混合检索阶段粗召回的候选条数30 在精度和耗时之间平衡给重排序留足原料高精度场景调到 50召回不足时再往上conversation.rerank_top_k30重排序后的最终候选数直接决定塞进大模型上下文多少片段上下文窗口紧张就下调到 10-15conversation.vector_threshold0.2向量相似度门槛0.2 偏松宁可多召回再靠 rerank 过滤避免硬门槛漏检出现大量不相关命中时抬到 0.3conversation.max_rounds5多轮上下文保留轮数5 轮覆盖绝大多数追问链长对话场景调到 10简单 FAQ 降到 3knowledge_base.chunk_size512分块大小512 字对中英混排文档召回粒度最稳过小丢上下文、过大稀释语义长表格/代码多的库可上调到 768chunk_overlap默认 50约为chunk_size的 10%作用是让相邻块保留边界重叠避免一个段落被切断后语义断裂。它和chunk_size建议按同一比例联动不要只改一个。检索质量想再精调看keyword_threshold0.3和rerank_threshold0.3——前者管关键词匹配后者管重排两者都偏保守先动上面五个再动这两个。✅ 功能验证部署完不要直接放量按顺序逐项确认模块可用。每项给出命令和预期输出。容器健康docker compose ps。预期app显示healthy其余核心容器为Up。若有Restarting先docker compose logs --tail 50 app看报错。后端存活curl -s http://localhost:8080/health。预期返回 200 且非空。这是 compose 里 app 服务自身 healthcheck 探的同一地址。前端可达curl -I http://localhost:80。预期HTTP/1.1 200说明 Nginx 已把静态资源和服务端代理接好。解析链路在 Web UI 建一个知识库并上传一份 PDF看文档状态从processing变为已完成。这一步同时验证了app → docreader → Postgres的 gRPC 与入库链路比单测更可信。检索问答用文档里能明确命中的问题提问预期回答带引用来源且内容对得上。若答非所问先查embedding_top_k与模型是否配错。 运维与故障速查监控接入生产建议开 Langfuse 做可观测性。设LANGFUSE_ENABLED并填LANGFUSE_HOST、LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY后agent 的推理链路、token 用量、管线耗时会进入 LangfuseLANGFUSE_SAMPLE_RATE控制在 0.1 左右即可。运行时还有内置任务队列面板能看各阶段 worker 池并发和失败任务配合docker stats看容器资源、Postgres 慢查询看数据库瓶颈。高频故障按现象 → 原因 → 解法排查现象常见原因解法app 一直Restarting.env缺必填项或密钥长度不对如SYSTEM_AES_KEY非 32 字节docker compose logs app定位补全必填、密钥用 32 字节Postgres 连接失败Postgres 未就绪app 先启动等待postgres变healthydepends_on已设service_healthy勿绕过文档卡在processing单文档超时或解析 worker 不足调大WEKNORA_DOCUMENT_PROCESS_TIMEOUT默认 2hDOCREADER_PDF_RENDER_PARALLELISM加并行问答答非所问向量/对话模型配错或RETRIEVE_DRIVER与库里不一致核对LLM_*/EMBEDDING_*确认RETRIEVE_DRIVER与实际存储一致向量检索慢向量库资源不足独立给向量库加内存缩小embedding_top_k️ 生产加固开发和生产差异集中在三类必须项其余保持默认即可不必为开发机单独维护一套。安全必须# 生产务必关闭公开注册、收紧密钥 DISABLE_REGISTRATIONtrue GIN_MODErelease JWT_SECRETopenssl rand -hex 32 生成 SYSTEM_AES_KEY必须恰好 32 字节openssl rand -base64 32 后截断SYSTEM_AES_KEY是数据库里 API Key 等敏感字段落盘加密的主密钥丢失则所有已加密数据不可恢复务必离线备份。WEKNORA_AUTH_COMPLEX_PASSWORD_ENABLEDtrue可强制密码含大小写数字特殊字符。网络隔离必须对外只暴露 80前端和 8080API。Postgres、Redis、MinIO9000/9001、Neo4j7687默认只在WeKnora-network内部可达不要额外ports映射到0.0.0.0。若用 MinIO 存原件MINIO_USE_SSLtrue开 TLS并配访问策略。高可用可选要开知识图谱加--profile neo4j起 Neo4j 并在.env设NEO4J_ENABLEtrue这是图谱唯一开关旧的ENABLE_GRAPH_RAG已废弃。要换独立向量库按RETRIEVE_DRIVER选qdrant/milvus/weaviate对应 profile 启动。多副本 负载均衡属集群场景超出单机 compose 范畴以项目部署文档为准。 快速参考部署前Docker Compose v2 可用主机 80 / 8080 端口空闲内存 ≥ 8GB、磁盘 ≥ 20GB、CPU ≥ 4 核.env必填项已替换数据库三件套、Redis 密码、模型三件套启动后docker compose ps全部Upapp/docreader 带healthycurl http://localhost:8080/health返回 200前端 80 端口可访问能登录上传一份文档并完成解析问答命中且带引用生产上线前DISABLE_REGISTRATIONtrue、GIN_MODEreleaseJWT_SECRET、SYSTEM_AES_KEY已换随机值并离线备份数据库/Redis/对象存储未对外映射MinIO 开 TLS延伸阅读仓库内相对路径docs/快速开发模式说明.md — 本地快速起后端docs/使用其他向量数据库.md — 换 Qdrant/Milvus/Weaviatedocs/开启知识图谱功能.md — Neo4j 图谱启用docs/RBAC说明.md — 多空间角色与审计config/config.yaml — 对话与检索参数源头完成以上配置后建议先用docker compose logs -f app盯 10 分钟确认无异常滚动日志再放开真实流量。【免费下载链接】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），仅供参考
