企业官网建设流程全解析

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

你手上有几百份 PDF、Word 和网页笔记，想问一句"上次评审结论是什么"，却只能靠人肉翻文件。WeKnora 是一个开源 LLM 知识平台，能把这些原始文档变成可查询的 RAG 知识库、自主推理 Agent 和自维护的 Wiki，并且整套服务可以完全跑在你自己的机器上。

它和"直接调云端 API"差在哪

最常见的做法是把文档丢进某个云端问答服务，问题在于三件事：文档要出内网、调用费用随量上涨、模型和解析行为你控制不了。

WeKnora 的思路是把整条链路搬进你自己的 Docker 网络里：

• 文档解析在本地：独立容器负责解析 PDF、Word、Excel、PPT、Markdown 等 10 多种格式，原文不出内网；
• 模型可替换：接本地 Ollama，也可以接任意 OpenAI 兼容的 API，模型在界面上按知识库配置；
• 检索是混合的：默认用 ParadeDB（PostgreSQL 17 + BM25 与向量扩展），也可以换 Milvus、Qdrant、OpenSearch 等；
• 三种问法：快速问答（RAG）、会多步推理的 ReAct Agent、把文档自动整理成互相链接 Markdown 页面的 Wiki 模式。

架构上它是一条模块化流水线，每个组件都能换：

数据从进来到被问到的全过程大致如下：

环境要求与准备工作

部署前确认宿主机满足这两点即可，官方文档建议 4 核 CPU / 8GB 内存起步（解析服务里带了 LibreOffice 和 Playwright，比较吃内存）：

模型服务二选一：本机装好 Ollama 并启动（ollama serve），或者准备一个 OpenAI 兼容 API 的base_url和密钥。注意容器里访问宿主机 Ollama 要填http://host.docker.internal:11434，填localhost是连不通的。

克隆仓库：

# 克隆 WeKnora 源码 git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora

一条命令拉起全部服务

先把环境变量文件从模板复制出来。模板里标了必填项，重点是数据库账号密码、Redis 密码，以及JWT_SECRET和SYSTEM_AES_KEY（32 字节，用于 API Key 等敏感字段的落盘加密，丢了加密数据就解不回来）：

# 从模板生成 .env，然后编辑必填项 cp .env.example .env nano .env

然后启动：

# 拉取镜像并在后台启动核心服务 docker compose pull docker compose up -d

默认会拉起 5 个容器：frontend（Nginx 前端，80 端口）、app（Go 后端，8080 端口）、docreader（文档解析）、postgres（ParadeDB）和redis。docker compose ps里看到它们都是 running/healthy 就可以继续。

可选组件按需加 profile 启动，比如知识图谱加neo4j，对象存储加minio，链路追踪加langfuse，全量加full。不想手工敲 compose 的话，也可以跑 scripts/start_all.sh，它会顺带做 Ollama 检查和.env兜底。

部署后先做三步验证

1. 浏览器打开http://localhost，看到注册页即前端正常（没有内置默认账号，注册后自动成为自己空间的 Owner）；
2. 终端确认后端：curl http://localhost:8080/health返回{"status":"ok"}；
3. 在「设置」里配好对话模型和向量模型，并用向导里的"测试"按钮确认连通。

核心能力上手：上传文档到第一轮问答

以下操作全部在网页界面完成，不用敲命令。

建库并选模型：进入「知识库」页新建，类型选document。初始化向导会引导你选对话模型（LLM）和向量模型（Embedding）——向量模型建库后不建议再换，换了需要重建索引。

上传文档：把文件拖进上传区，或粘贴网页 URL。上传确认对话框里可以顺手打标签、调整解析参数。文档会异步解析，状态依次经过pending → processing → finalizing → completed，扫描件和超大 PDF 会慢一些。

提问：进入对话页选中这个知识库直接问。默认用内置"快速问答" Agent，检索相关片段交给大模型作答，回答里的引用角标可以点回原文出处：

到这一步，"文档 → 索引 → 问答"的最小闭环就通了。剩下两个模式看需求再开：

• 智能推理 Agent：对话页顶部切换到"智能推理"，它自己决定检索几轮、要不要联网、要不要调 MCP 工具，适合多步问题；
• Wiki 模式：Agent 把原始文档蒸馏成结构化、互相链接的 Markdown 页面，带版本历史和一键回滚，还能在浏览器里直接编辑：

排查与调优：几个高频问题

• 容器起不来或一直重启：先用docker compose ps看哪个不健康，再看docker compose logs <服务名>。多数情况是.env必填项没改（compose 解析依赖.env存在）或端口被占用。
• 模型测试连不上：本地 Ollama 的地址必须是http://host.docker.internal:11434；Ollama 没启动时后端只告警不崩溃（OLLAMA_OPTIONAL=true默认开启），容易误以为是 WeKnora 的问题。
• 文档卡在 processing：查看知识库里的解析状态和任务队列。批量导入大文件时，解析走异步队列，属于正常排队；长期卡住可调大.env里的文档处理超时变量。
• 升级版本：把.env里WEKNORA_VERSION设为目标 tag，重新docker compose pull && docker compose up -d。只执行up -d会复用本地旧镜像，UI 版本可能对不上。
• 多人使用：默认任何人可注册，团队部署建议设DISABLE_REGISTRATION=true改为邀请制，并用工作空间 RBAC（Owner / Admin / Contributor / Viewer 四级角色）分配权限，说明见 docs/RBAC说明.md。

更完整的排障条目在 docs/QA.md。

总结与关键路径

WeKnora 给自托管场景提供的是一条完整链路：本地解析、可换的模型与向量库、混合检索，以及 RAG / Agent / Wiki 三种消费方式，数据全程留在你的机器上。从git clone到第一次带引用的回答，顺利的话十几分钟，主要耗时在等文档解析。

常用入口：

• 安装与部署详解：website-docs/01-getting-started/02-installation.md
• 服务编排文件：docker-compose.yml
• 官方文档站点（可独立部署）：website-docs/

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