企业官网建设流程全解析

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/WeKnora

合规要求文档问答全部走内网、大模型 API 一个都不许调？这就是 WeKnora 本地部署要解决的问题。WeKnora 是开源的 LLM 知识平台，能把原始文档变成可查询的 RAG 问答系统、自主推理 Agent 和自维护的 Wiki 知识库，适合对数据主权有硬要求的内网团队、政企场景。

场景速览：它到底能帮你解决什么

先看拿到手之后能干什么，功能列表不展开了：

架构速写：一张图看懂数据流向

架构就一句话：文档从 Web UI 或 API 进来，走 docreader 解析器（Python gRPC 服务）完成 OCR 和标题提取，再分块、向量化，写入 PostgreSQL（pgvector）和本地文件存储；查询端走 BM25 + 向量 + 图谱混合检索，ReAct Agent 按需编排 MCP 工具，最后 SSE 流式返回答案。容器编排用 docker-compose，核心服务是 frontend、app、docreader、postgres、redis 五个，可选组件（MinIO、Neo4j、Langfuse）通过 profile 开关启用。模型侧只要求一个 OpenAI 兼容端点，接 Ollama 本地模型即可完全离线。

从零到跑通：WeKnora 部署实操

第一步：准备环境并拉代码

宿主机只需装好 Docker（20.10+）和 Git。然后：

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

.env.example的注释写得很细，默认值基本能直接跑。本地部署必须改动的几项：

# 存储默认 local，内网单机不用动 STORAGE_TYPE=local # 数据库密码确认一下 DB_PASSWORD=postgres123!@# # 不接外部 API 时，指向宿主机上的 Ollama OLLAMA_OPTIONAL=true OLLAMA_BASE_URL=http://host.docker.internal:11434

想省掉外部模型服务的话，先在宿主机跑一个ollama serve，后面加载 bge-m3（嵌入）和一个对话模型即可。

第二步：启动服务并确认健康

docker compose pull docker compose up -d

确认成功的标志是docker compose ps里全部 Up，且健康检查通过：

curl -s http://localhost:8080/health

浏览器打开 http://localhost 能看到初始化向导，说明前端代理和后端都通了。

第三步：配置模型，完成初始化向导

首次进入 Web UI 会走初始化向导：注册管理员账号，然后配置 LLM、Embedding 模型。这一步是新手最容易卡住的地方——不配置模型，后面所有功能都动不了，填错地址也不报错，而是静默失败。接 Ollama 时 base URL 填容器视角能解析的地址，保存前先用设置页的模型测试按钮验一下连通性。

第四步：建知识库，跑通第一次问答

创建知识库 → 上传几份 PDF/Word → 等解析完成 → 提问。解析是异步任务，慢的话去日志和任务队列面板看，别干等。

跑通验证 checklist：

• 能用注册的管理员账号登录 Web UI（http://localhost）
• 上传的文档解析完成，状态为成功
• 提问后答案带知识库引用来源
• Agent 模式下能看到工具调用过程，而非直接回答
• 按角色把其他成员拉进工作区，权限符合预期

官方文档：docs/QA.md 里按日志、上传、图片、兼容性整理了常见问题，卡住时先查它。

跑起来之后：调优与安全合写

资源分配。解析任务走 Asynq worker 池，如果上传后解析一直排队，优先调WEKNORA_ASYNQ_CORE_CONCURRENCY（默认 8）和WEKNORA_ASYNQ_ENRICHMENT_CONCURRENCY（默认 12）；这两个值在系统设置里可运行时改，不用重启容器。模型推理慢就先怀疑宿主机 Ollama 的 CPU/内存配额，再谈软件参数。

检索参数。config/config.yaml的conversation段控制混合检索，部署时通过挂载的配置文件生效：

conversation: embedding_top_k: 30 # 向量召回数 vector_threshold: 0.2 keyword_threshold: 0.3 # BM25 侧阈值 rerank_top_k: 30 enable_rerank: true

答案相关但不准时，优先调embedding_top_k和 rerank 阈值；答案完全跑偏时，先去知识库 UI 里直接编辑 chunk——检索单元不对，参数怎么调都没用。

权限控制。多租户 RBAC 是工作区级别的 4 级角色矩阵（Owner / Admin / Contributor / Viewer），加每个知识库的属主控制和空间审计日志。生产环境把DISABLE_REGISTRATION=true关掉开放注册，程序化调用发受限 API Key（能力级授权 + 按知识库限定范围），文档见 docs/RBAC说明.md。

数据加密与备份。API Key、MCP 和数据源凭证默认走 AES-256-GCM 静态加密，支持密钥轮换；审计日志默认保留 90 天，WEKNORA_AUDIT_RETENTION_DAYS可调。备份很简单：pg_dump数据库 + tar 一下data-files卷，再加.env和config/，定时任务挂上就行。

卡住了怎么办：排障与下一步

• API 参考：docs/api/README.md
• 排障 FAQ：docs/QA.md
• RBAC 与审计：docs/RBAC说明.md
• 功能规划：docs/ROADMAP.md

WeKnora 本地部署没有想象中重：一台内网机器加一套 docker-compose 就能起步，Postgres、Redis、App、docreader 和前端全在本地。建议先跑通解析到问答的主链路，再按需开知识图谱、对象存储和 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