企业官网建设流程全解析

WeKnora 部署指南：5 步搭好你的 AI 知识库 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

WeKnora 是一款开源的 AI 知识管理平台：把上传的文档变成可查询的 RAG、一个能自主推理的 Agent，以及一套自维护的 Wiki。它和"向量库封装器"类工具的区别在于，文档解析、分块、图谱构建、IM 入口全部内置，部署时只有一份.env和config/config.yaml需要关心。读完这篇，你会得到一个可访问的实例、一套检索调参的改法，以及上生产前要过的安全加固清单。

架构上它是四层：接入层（Web UI、8080 端口的 API、MCP Server 和 9 种 IM 机器人）、处理层（docreader 解析、分块、向量化、图谱构建）、存储层（内置 ParadeDB/PostgreSQL，可换 8 种以上向量库，另有 Neo4j、Redis 和 7 种对象存储）、外部服务层（各家 LLM 提供商与 Web 搜索）。下面按"跑起来 → 调出效果 → 环境适配 → 排障 → 加固"的顺序走一遍。

🚀 最小部署：三条命令拉起实例

先说结论：默认配置下你不需要单独装向量库——compose 里的 postgres 用的是 ParadeDB 镜像，向量和 BM25 全文检索都在这一个库里完成，这是最短路径。

硬件上建议 8GB 内存、4 核以上，磁盘留 20GB；软件只需要 Docker、Docker Compose 和 Git。满足后执行：

git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora cp .env.example .env # 改数据库密码、Redis 密码等必填项 docker compose pull docker compose up -d

启动后用两个动作验证：

curl -f http://localhost:8080/health # API 健康检查，返回 200 即正常

再浏览器打开http://localhost注册首个账号——它是第一个超级管理员，后续提权走管理页。如果 health 一直不通，多半是 postgres 还没就绪（它有 30s 的 start_period），等一个 healthcheck 周期再看docker compose ps。

实例跑起来后，默认参数就能回答问题，但检索质量想再上一个台阶，要动三个阈值。

⚙️ 检索阈值与分块策略怎么调

场景先摆出来：用户抱怨"答非所问"或"明明文档里有却没召回"。这两个问题九成出在config/config.yaml的conversation段和知识库分块参数上，改完重启 app 容器即可生效。

改动集中在这一段：

# config/config.yaml，改完重启 app 容器生效 conversation: keyword_threshold: 0.25 # 原 0.3，漏召回时先松这里 vector_threshold: 0.15 # 原 0.2 rerank_threshold: 0.25 # 原 0.3 embedding_top_k: 50 # 原 30，候选池加大

调参思路是"问题 → 原因 → 解法"：漏召回先看候选池（top_k），答非所问再看准入线（thresholds），重排模型没配好时调阈值收益有限——默认enable_rerank: true依赖你配的 Rerank 模型，没配就先在 UI 里挂一个。

分块策略上，默认 512 字节在大多数场景不用动。经验值：叙述类文档保持 512；表格密集或段落很长的技术文档提到 768~1024，同时把 overlap 同步调到块大小的 10% 上下，避免跨块信息断裂。改完可以进知识库详情页逐块检查切分效果：

验证方式：拿同一个问题在改前后各问一遍，对比答案引用来源是否命中你预期的文档。阈值合适后，接下来要按环境规模决定改哪些变量。

🧪 开发、测试、生产三套配置

同一套 compose，靠环境变量和 profile 就能覆盖三种环境，对照如下：

可选组件都藏在 compose profile 里，按需用--profile拉起，不需要的完全不占资源：

# 对象存储 + 知识图谱一起开 docker compose --profile minio --profile neo4j up -d # 或一把全开 docker compose --profile full up -d

注意知识图谱的唯一开关是NEO4J_ENABLE=true（旧的ENABLE_GRAPH_RAG已废弃），并且要配合 neo4j profile 把容器拉起来，两边都到位图谱查询才有返回。

数据量增长后，RETRIEVE_DRIVER可以平滑切换：默认 postgres，支持 qdrant、milvus、weaviate、opensearch、doris、tencent_vectordb 等取值，多个驱动逗号分隔可并行检索，用MULTI_STORE_RETRIEVE_TIMEOUT_SEC控制并行超时。单机资源很紧的场景，也可以直接看轻量版：docs/LITE.md，单二进制跑通核心能力。

环境定型之后，日常剩下的事就是出问题时怎么快速定位。

🔍 服务出问题时先看三处

固定的排查路径只有三条，按顺序走：

docker compose ps # 1. 谁不健康 docker compose logs -f app # 2. 看主应用日志 curl -f http://localhost:8080/health # 3. 探活

四个高频故障的定位思路：

排查上下文类问题（LLM 为什么这么答）时，打开LLM_DEBUG_LOG=true，每次大模型调用的完整请求响应会写到独立文件，比翻 stdout 快得多。

排障手段齐了，上生产前把安全清单过一遍，主要是密钥和网络两件事。

🛡️ 生产加固：密钥、网络与可观测性

密钥类变量是必须换的第一批，四个缺一不可：

# .env 中生成并替换 openssl rand -hex 32 # JWT_SECRET openssl rand -base64 32 # SYSTEM_AES_KEY（必须 32 字节） # 另改 DB_PASSWORD、REDIS_PASSWORD，勿用模板占位值

其中SYSTEM_AES_KEY要特别对待：API Key、模型凭证等敏感字段用它做 AES-256 落盘加密，丢了就无法解密已存数据，UI 里会直接显示为空，需要重新填写。

账号侧：DISABLE_REGISTRATION=true关闭开放注册，用邀请制代替；WEKNORA_TENANT_ENABLE_RBAC=true开启空间角色鉴权（默认开），审计日志保留天数用WEKNORA_AUDIT_RETENTION_DAYS控制，默认 90 天。角色与空间的完整说明见 docs/RBAC说明.md。

网络面，compose 里所有后端服务都走WeKnora-network内网通信，docreader 的 gRPC 50051 端口默认不映射到宿主机，对外只暴露前端的 80 端口——公网部署时保持这个形态，再在前面加 443 终结即可。需要加密传输时，app 与 docreader 之间用GRPC_TLS_ENABLED=true开启 TLS（支持 mTLS），Redis 用REDIS_USE_TLS，MinIO 用MINIO_USE_SSL=true。另外出站抓取的SSRF_WHITELIST控制着允许访问的外部地址，公共环境建议收紧而不是放开。

可观测性上，自建 Langfuse 栈是现成的 profile：

docker compose --profile langfuse up -d

拉起后在http://localhost:3000注册管理员、生成 API Key，再在.env里配好LANGFUSE_ENABLED、LANGFUSE_HOST和两个 key，重启 app 容器。用LANGFUSE_SAMPLE_RATE控制采样比例，生产建议 0.1 左右，延迟和错误率的趋势在界面里直接可见：

清单过完后，先拿一小批真实业务文档跑通"上传 → 问答 → 引用核对"，和上一轮的基线对比召回质量；规模继续增长时，仓库里的 helm/ chart 可以支撑把这套架构平移到 Kubernetes 集群上。

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