企业官网建设流程全解析

WeKnora部署指南：10分钟从零跑通一个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、能推理的智能体和自维护的Wiki。本文只靠Docker + Compose，从一台干净的机器到第一个带引用的回答，大约10分钟。适合开发者和要拍板的技术负责人。

一：动手部署前先做环境自检

动手前花30秒过一遍下面的清单，能省掉后面至少1小时排查。WeKnora在宿主机上不需要装任何组件，Docker会把应用、文档解析器、前端、数据库全部拉下来，你只需确认5件事。

硬件上，4核8GB内存跑通全流程没压力，吃资源的大头是文档解析和向量检索。内存紧张就先按第三章把并发参数调小，别先加机器。

二：10分钟跑起来：从零到一的四步

四步走完，总耗时不超过10分钟，其中一半时间在拉镜像。

第1步：克隆代码

git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora cp .env.example .env

第2步：改 .env 里的4把钥匙

.env自带默认值，原样也能跑。但生产环境至少要改这4项：

• DB_PASSWORD、REDIS_PASSWORD：数据库密码
• JWT_SECRET：前端登录的签名密钥
• SYSTEM_AES_KEY：必须恰好32字节，随机值用openssl rand -hex 32生成

最后一项最容易漏。丢了这把钥匙，数据库里已加密的 API Key 就解不回来，只能全部重填。

第3步：启动服务

docker compose pull docker compose up -d docker compose ps

首次拉镜像约1～2GB，耐心等。容器全部 running 即成功：核心是 frontend、app、docreader、postgres、redis。docreader 的 gRPC 端口 50051 只在容器内网，不映射到宿主机，别在端口表里找它。

第4步：验证

curl http://localhost:8080/health

返回 healthy 说明后端就绪。再打开 http://localhost，注册第一个账号，建一个知识库传一份文档。问题能带引用回答时，部署才算真正完成。

端口速记：80 前端，8080 后端API，8082 是可选的 MCP 服务。其余端口都在内网。

三：跑起来之后，先调这三处

默认参数能用，但未必最优。先看三处：两处检索、一处分块、一处并发，全在 config/config.yaml 和.env里。

建议动作：一次只改一个参数，改完用同一组问题复测，效果可归因、可回滚。

四：最容易踩的三个坑，以及怎么绕开

翻车基本集中在三类问题，按现象→原因→动作直接对号入座。

坑1：容器反复重启

• 现象：docker compose ps里 app 一直 Restarting，前端打不开
• 原因：.env里密码含特殊字符没加引号，或 80/8080 端口被占
• 动作：docker compose logs app看第一条报错；跑./scripts/start_all.sh --check做环境自检；端口被占就改.env里的FRONTEND_PORT、APP_PORT

坑2：检索效果差

• 现象：答案跑题，引用片段和问题不搭
• 原因：解析出来的文本就是乱的（扫描件PDF最常见），或重排没生效
• 动作：先打开知识库的分块列表看文本是否干净；再核对 config.yaml 的enable_rerank；最后才是调embedding_top_k和阈值

坑3：批量导入卡死

• 现象：几百页扫描件要处理几小时，任务中途超时
• 原因：PDF 渲染并行度默认低，任务总超时默认 2 小时
• 动作：.env调大DOCREADER_PDF_RENDER_PARALLELISM（仓库实测874页从117秒降到17秒），同步把WEKNORA_DOCUMENT_PROCESS_TIMEOUT提到 4h

五：业务长大之后：高可用与安全要点

新机器上别急着做高可用，先把下面几件安全的事做了。

• 安全：把第二章的4把钥匙换成随机值并离线备份SYSTEM_AES_KEY；设DISABLE_REGISTRATION=true关掉公开注册；RBAC 默认开启，保持不动。
• 高可用：app 无状态，状态全在 PostgreSQL 和 Redis 里。横向扩容就是加 app 副本，文件存储切到 MinIO（--profile minio）。
• 存储：RETRIEVE_DRIVER支持 postgres、qdrant、milvus 等多驱动，数据量涨起来时换成独立向量库，不用改代码。

六：进阶方向与资源索引

进阶功能都靠一条命令或一个环境变量开关，不用改代码。

• 知识图谱：启动加--profile neo4j，.env设NEO4J_ENABLE=true，系统会从文档里抽实体和关系，支撑跨文档的复杂查询。细节看 知识图谱文档。
• 多模型：config/builtin_models.yaml声明式配置内置 LLM、Embedding、Rerank，换供应商只改配置，方便做故障切换。见 内置模型说明。
• 监控：Langfuse Cloud 填两把 key 就接入；内网环境用--profile langfuse自建。能追踪每次 chat、embedding、rerank 调用和 token 消耗。见 Langfuse集成。
• 延伸阅读：常见问题、API参考、开发指南。

写在最后

WeKnora部署本身只有三行命令，真正的功夫在按你的文档类型调分块和检索参数。建议先按第二章验证跑通，再照第三章逐个调参，接入真实业务前把第四章当预演读一遍。

下一步：读 RBAC说明 配好空间权限，再把团队请进来。

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