企业官网建设流程全解析

WeKnora 技术全景指南：企业级 RAG、ReAct Agent 与自动 Wiki 知识平台的架构与部署实践

【免费下载链接】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 是腾讯开源的 LLM 知识平台，围绕RAG 快速问答、ReAct Agent 自主推理、Wiki 自动成文三大核心能力构建，目标是"把零散文档变成可查询、可推理、持续演进的活知识资产"。本文以仓库根目录 README.md 为主线，结合 docker-compose.yml、cli/README.md、config/config.yaml、website-docs/README.md 与 docs/开发指南.md 等仓库资料，系统讲解 WeKnora 的整体架构、核心功能矩阵、Docker 部署与升级流程、CLI 命令行接入、开发者快速模式及安全基线，帮助读者从零开始完成一次"部署 → 建库 → 上传 → 问答"的完整闭环。

一、项目概览：三大核心能力与一条主线

WeKnora（仓库版本见 VERSION，当前为 v0.8.0）是面向企业级场景的开源知识框架，其能力组织围绕三条主线：

• RAG 快速问答：面向日常查询的检索增强问答，基于知识库实现快速、准确的回答；
• ReAct Agent：可自主编排知识检索、MCP 工具、租户技能目录（Skill Catalog）、会话级持久化沙箱（Docker / E2B / Cube）与网络搜索的自主推理代理，用于完成多步骤复杂任务；
• Wiki Mode：由 Agent 将原始文档蒸馏为结构化的、相互链接的 Markdown 知识库，附带交互式知识图谱，支持手动编辑、修订历史与一键回滚。

在其之上还叠加了跨会话长期记忆（记住"你是谁、你常问什么"）、树形文件夹视图（保留上传目录结构）、带修订历史的分块编辑（chunk 可像文档一样被编辑、diff 与回滚）等知识治理能力。工程上则通过多源数据导入（飞书 Wiki / 飞书云文档 / GitLab / 腾讯 IMA / Notion / 语雀 / RSS）、网页嵌入挂件、带主体验证模型的细粒度 API Key、按空间隔离的多实例存储后端、20+ LLM 厂商接入（含 LiteLLM）、Langfuse 全链路可观测、运行时任务队列看板与 worker-pool 治理、企业级多空间 RBAC（4 级角色矩阵 + 资源归属 + 空间级审计日志）以及完全可自托管的模块化架构，构成一个完整的企业知识底座。

在格式与兼容性方面：支持从飞书、GitLab、腾讯 IMA、Notion、语雀等来源自动同步知识；可处理 PDF、Word、图片、Excel、XMind 等 10+ 文档格式；可直接通过企业微信、飞书、Slack、Telegram 等 IM 渠道提供问答；兼容 OpenAI、DeepSeek、通义千问、智谱、混元、Gemini、MiniMax、NVIDIA、LiteLLM、Ollama 等主流 LLM 厂商。办公文件可在进程内通过anydoc引擎解析（Rust 静态库，make build-anydoc链接，见 Makefile）。完全模块化设计允许自由替换 LLM、向量数据库与存储后端，支持本地与私有云部署以保证数据主权。

二、架构总览：模块化流水线与组件清单

README 明确其架构为"从文档解析、向量化、检索到 LLM 推理的完全模块化流水线，每个组件都可替换、可扩展"。从 website-docs/README.md 的系统组件速览可以还原出更精确的拓扑：

• 客户端层：Web 前端（Vue 3）、CLIweknora、Go SDK（client/）、微信小程序（miniprogram/）、网页嵌入挂件、10 个 IM 平台适配器；
• 核心服务层：Go/Gin 单体后端app（默认 :8080）与 Python gRPC 文档解析微服务docreader（默认 :50051）；
• 基础设施层：PostgreSQL / ParadeDB（元数据与向量）、Redis + asynq（异步任务）、可选的多种向量/检索引擎、对象存储（local / MinIO / COS / OSS / S3 等）、可选的 Neo4j 知识图谱。

后端四层架构（handler → application/service → repository → 基础设施）与依赖注入、文档入库流水线（上传 → 存储 → 解析 → 分块 → 向量化 → 索引 → 后处理）、检索问答流水线（跨库检索与融合、重排、SSE 流式输出与引用）、asynq 异步任务系统（6 个 worker pool）等细节可继续查阅 website-docs/02-architecture/ 系列文档。

三、核心功能矩阵：智能对话、知识管理、集成扩展与平台能力

3.1 智能对话

3.2 知识管理

3.3 集成与扩展

3.4 平台能力

说明：以上三个功能矩阵源自 README.md 的 Feature Overview 章节；其中 v0.8.0 起本地 host-process 沙箱后端已移除、Docker 沙箱需显式开启（见 README v0.8.0 更新说明与 docker-compose.yml 中WEKNORA_SANDBOX_DOCKER_ENABLED默认false的注释）。

四、周边生态：Chrome 插件、小程序、ClawHub Skill 与 DeepSeek Harness 插件

除主服务外，README 还介绍了四类可直接使用的客户端/插件：

• Chrome 插件：在浏览器中选中文本、图片或整页，一键存为知识条目，无需复制粘贴或文件上传。
• 微信小程序（miniprogram/README.md）：轻量移动客户端，可配置 API 访问、选择知识库、导入 URL 并在微信内提问。
• ClawHub Skill：发布在 ClawHub 平台的 WeKnora 技能，安装后可通过 REST API 完成文档导入（文件 / URL / Markdown）、跨知识库混合检索（向量 + 关键词）、知识条目管理。
• DeepSeek Harness 插件：官方@wxg-prc-cpg/dsh-weknora（文档见 packages/dsh-weknora/README.md），为 DeepSeek Harness（dsh）编码 Agent 注入四个只读工具：
  • weknora_search：混合检索，返回逐字原文段落并附可复用的knowledge_id；
  • weknora_read_document：按顺序重组单个文档的段落，支持分页；
  • weknora_ask：调用 WeKnora 自身带引用的合成回答（RAG 或 ReAct 流水线）；
  • weknora_list_knowledge_bases：列出知识库名称与 id，便于 Agent 圈定检索范围。

安装方式：dsh plugin --profile web add @wxg-prc-cpg/dsh-weknora，指向一个已部署实例即可。

五、命令行工具：Agent 优先的weknoraCLI

README 强调weknoraCLI 是agent-first设计：默认所有命令输出稳定的 JSON 信封（typed error code 映射到退出码），--format text面向人类渲染；同时提供精选 MCP 工具面（weknora mcp serve）并内置 Agent Skills。完整安装与快速上手见 cli/README.md，Agent 依赖的运行契约见 cli/AGENTS.md。

5.1 快速上手（5 分钟）

# 1. 注册服务器 profile 并设为活动 weknora profile add prod --host https://kb.example.com --use # 2. 认证活动 profile（交互式密码提示） weknora auth login # 2b. 或从 stdin 灌入 API Key（CI / Agent 场景） echo "sk-..." | weknora auth login --with-token # 3. 列出知识库 weknora kb list # 4. 绑定当前目录到知识库——后续命令自动解析 --kb weknora link --kb my-knowledge-base # 5. 上传文档并阻塞等待解析完成 weknora doc upload notes.md weknora doc wait doc_abc # 0 完成 / 1 失败 / 124 超时 / 130 Ctrl-C # 6. 混合检索 weknora search chunks "what is reciprocal rank fusion?" # 7. 流式提问 weknora chat "summarise the design doc"

后续还有weknora agent list/weknora session ask --agent ag_abc（自定义 Agent 会话）、weknora chunk list --doc doc_xyz（RAG 检索调试）、weknora message list/weknora message search（会话消息检视与跨会话检索）以及weknora session tool-approval resolve pend_xxx -y（工具审批解锁）等高级动词。

5.2 无头 / CI 认证

Headless 场景只需两个环境变量，不需要auth login、不落盘任何凭据：

export WEKNORA_API_KEY="sk-…" # 或 WEKNORA_TOKEN 携带 bearer JWT export WEKNORA_HOST="https://kb.example.com" weknora kb list # 已认证

5.3 Wire Contract：JSON 信封、退出码与 Exit 10

• stdout 是数据通道：--format json下输出裸 JSON，永不携带错误文本；stderr 是日志/进度/错误通道，stderr 非空不代表失败——以退出码为准。
• JSON 信封：每个命令支持--format json，包装为对称信封{ok, data, meta?}；--jq作用于整个信封（如weknora kb list --format json --jq '.data[].id'）；--format ndjson用于流式 list 命令；默认即 JSON（weknora kb list | jq无需显式 flag），人类可读用--format text。
• 错误格式：失败时 stdout 为空，类型化错误输出到 stderr，形如auth.unauthenticated: fetch current user: HTTP error 401: ...加hint:行。
• 退出码（weknora exit-codes可查看机器可读矩阵）：

Exit 10是"破坏性写需要显式确认"的线上信号：kb delete/doc delete（含--all --kb=<id>）/session delete/profile remove/agent delete/chunk delete在无头运行时需传-y/--yes。切勿未经用户明确同意自动加-y。--dry-run可离线预览任意变更命令（不发起网络、不落盘、不碰凭据），且不会触发 exit-10 确认流。

5.4 多 Profile、流恢复与健康检查

• 多 profile：profile.*管理 profile 记录，auth.*作用于活动 profile（可用全局--profile覆盖）。凭据优先存 OS keyring（macOS Keychain / Linux libsecret / Windows Wincred），否则落到$XDG_CONFIG_HOME/weknora/secrets/的 0600 文件；活动 profile 记录在~/.config/weknora/config.yaml。
• 流恢复：weknora session resume sess_abc --message msg_xyz可恢复既有 assistant 消息的 SSE 事件流，服务端从起始重放全部存储事件再尾随新事件，Agent 需按 message_id 或事件哈希去重。
• 工具审批解锁链：Agent 运行可因工具审批事件暂停 → 向用户展示待批工具调用 →weknora session tool-approval resolve pend_xxx -y批准（或--reject --reason拒绝）→weknora session resume恢复流。服务端缓冲 TTL：redis 模式 1 小时，memory 模式为进程生命周期。
• 健康检查：weknora doctor提供 4 状态诊断（OK/warn/fail/skip），覆盖 base URL 可达性、认证、CLI 与服务端版本偏差、凭据存储后端；--offline跳过网络检查。资源级status（1 次 HTTP，快速快照）与check（1+N 次 HTTP，深校验，如统计failed_count）成对提供。

六、Docker 快速部署与升级

6.1 前置条件与安装

前置条件仅需Docker + Docker Compose与Git。部署步骤（见 README.md）：

git clone https://github.com/Tencent/WeKnora.git cd WeKnora cp .env.example .env # 按需编辑 .env，参考文件内注释 docker compose pull # 拉取最新镜像 docker compose up -d # 启动核心服务

启动完成后访问http://localhost即可开始使用。若使用本地 Ollama 模型，需先执行ollama serve > /dev/null 2>&1 &。

说明：README 给出的 clone 地址指向上游仓库；在本文所在仓库环境中，直接复用仓库内的 .env.example、docker-compose.yml 与 config/config.yaml 即可完成同等的 Compose 部署。

从 docker-compose.yml 可看到核心服务编排：frontend（NGINX 托管前端，默认宿主机 80 端口，通过APP_HOST/APP_BACKEND_PORT/APP_SCHEME指向上游后端）、app（Go 后端，默认 8080，/health健康检查，env_file: .env注入全部环境变量，默认信任LOG_LEVEL=debug、GIN_MODE=release、TZ=Asia/Shanghai等）、docreader（Python gRPC 解析服务，默认 50051，仅暴露在 Compose 网络内）、postgres（ParadeDB v0.22.2-pg17，承担元数据与 pgvector 检索）、redis（7.0-alpine，含 asynq 任务队列）。Docker 沙箱默认关闭，需WEKNORA_SANDBOX_DOCKER_ENABLED=true并挂载 docker.sock 后才会按会话创建沙箱容器。

6.2 可选服务（Docker Compose Profiles）

通过--profile按需叠加组件，多个 profile 可组合：

组合示例：docker compose --profile neo4j --profile minio pull && docker compose --profile neo4j --profile minio up -d。停止服务：docker compose down。

从 docker-compose.yml 中还可以看到更完整的可选侧车：qdrant/milvus/weaviate/doris-fe+doris-be（替代向量检索）、searxng（自托管元搜索）、dex（OIDC 测试身份源）、odl-hybrid（OpenDataLoader 混合解析后端）、langfuse-web+langfuse-worker+langfuse-clickhouse+langfuse-minio（自建可观测栈，复用既有 postgres/redis）。

6.3 服务地址与升级

升级流程（下载新版本后）：

# 在 .env 中设置 WEKNORA_VERSION 为目标版本（如 0.7.0），或保持 latest docker compose pull # 拉取匹配 WEKNORA_VERSION 的镜像 docker compose up -d # 用新镜像重建容器

注意：docker compose up -d单独执行会复用本地缓存镜像，可能导致 UI 版本与你下载的发行版失步。

6.4 关键环境变量速览

以 docker-compose.yml 与 .env.example 为依据，以下变量决定部署形态：

• 认证与空间：DISABLE_REGISTRATION（禁止新用户注册，生产建议 true）、WEKNORA_AUTH_COMPLEX_PASSWORD_ENABLED（强密码）、WEKNORA_AUTH_DEFAULT_TENANT_MODE（默认create_personal）、WEKNORA_TENANT_SELF_SERVICE_CREATION_ENABLED、WEKNORA_TENANT_ENABLE_RBAC（默认 true）、WEKNORA_TENANT_DEFAULT_STORAGE_QUOTA_GB（默认 10）、WEKNORA_INVITATION_TTL（默认 168h）。
• 数据库与检索：DB_DRIVER（默认 postgres，可切换 sqlite）、RETRIEVE_DRIVER（默认 postgres，可切换 elasticsearch / opensearch / qdrant / milvus / weaviate / doris / tencent_vectordb 等）、MULTI_STORE_RETRIEVE_TIMEOUT_SEC（多向量库并行检索超时）。
• 存储后端：STORAGE_TYPE（默认 local；可选 minio / tos / s3 / obs / oss）、STORAGE_ALLOW_LIST（允许用户使用的存储白名单，留空允许全部）、MINIO_*、S3_*、OBS_*、OSS_*等分组变量。
• 安全：SYSTEM_AES_KEY（敏感字段落盘 AES-256 主密钥，必须 32 字节；v0.4.0 起统一使用，丢失则加密数据不可恢复）、JWT_SECRET、SSRF_WHITELIST/SSRF_WHITELIST_EXTRA、GRPC_TLS_ENABLED/GRPC_AUTH_TOKEN（docreader 传输加密与认证）、REDIS_TLS_*。
• 可观测性：设置LANGFUSE_PUBLIC_KEY+LANGFUSE_SECRET_KEY即自动启用 Langfuse（默认LANGFUSE_HOST=https://cloud.langfuse.com）；LANGFUSE_SAMPLE_RATE等调优参数见 docs/Langfuse集成.md。
• 任务治理：WEKNORA_ASYNQ_CORE_CONCURRENCY（默认 8）/POSTPROCESS（2）/ENRICHMENT（12）/MAINTENANCE（4）/SHARED（6）/WIKI（8）对应各 worker pool 并发；WEKNORA_MODEL_MAX_CONCURRENCY（默认 32）为按模型并发上限。
• 文档处理：WEKNORA_DOCUMENT_PROCESS_TIMEOUT（默认 2h）、DOCREADER_ADDR（默认 docreader:50051）、WEKNORA_CHAT_ATTACHMENT_TTL_HOURS（默认 24）等。

七、服务端配置文件与对话策略

核心配置在 config/config.yaml，其中对话服务（conversation）区块直接对应 README"对话策略"能力，关键项包括：

conversation: max_rounds: 5 # 多轮最大轮数 keyword_threshold: 0.3 # 关键词检索阈值 embedding_top_k: 30 # 向量检索 top-k vector_threshold: 0.2 # 向量检索阈值 rerank_threshold: 0.3 # 重排阈值 rerank_top_k: 30 # 重排 top-k fallback_strategy: "model" # 兜底策略：model / 固定回复 fallback_response: "Sorry, I am unable to answer this question." enable_rewrite: true # 是否开启查询改写 enable_query_expansion: true # 是否开启查询扩展 enable_rerank: true # 是否开启重排 rewrite_prompt_id: "default_rewrite" # 改写 Prompt（rewrite.yaml） generate_summary_prompt_id: "default_summary" # 摘要 Prompt generate_session_title_prompt_id: "default_session_title"

Prompt 内容统一从 config/prompt_templates/ 下的 YAML 文件按*_id字段解析加载，包括system_prompt.yaml（知识库问答系统提示）、context_template.yaml（上下文模板）、fallback.yaml（兜底）、rewrite.yaml（查询改写）、graph_extraction.yaml（图谱抽取）、generate_questions.yaml（问题生成）等，启动时即加载。知识库区块还定义了默认chunk_size: 512、chunk_overlap: 50、split_markers分块标记，以及多模态图片处理开关knowledge_base.image_processing.enable_multimodal。

八、开发者快速模式：免镜像热重载

README 明确推荐：频繁改代码时不需要每次重建 Docker 镜像，使用快速开发模式（详见 docs/开发指南.md）：

# 启动基础设施（PostgreSQL / Redis / MinIO / Neo4j / DocReader 容器） make dev-start # 启动后端（新终端）：本地直跑 Go 应用 make dev-app # 启动前端（新终端）：Vite 开发服务器，热重载 make dev-frontend

开发优势：前端修改自动热重载（无需重启）、后端修改秒级重启（检测到 Air 时自动热重载，仓库已内置.air.toml）、无需重建 Docker 镜像、支持 IDE 断点调试。访问地址：前端http://localhost:5173、后端 APIhttp://localhost:8080、MinIO Consolehttp://localhost:9001、Neo4j Browserhttp://localhost:7474。也可用脚本形式：./scripts/dev.sh start/app/frontend/logs/stop。

后端调试可直接在 VS Code 中配置launch.json，把program指向cmd/server，环境变量填入DB_HOST=localhost、DOCREADER_ADDR=localhost:50051、MINIO_ENDPOINT=localhost:9000、REDIS_ADDR=localhost:6379等即可。生产部署仍走sh scripts/build_images.sh+sh scripts/start_all.sh。

九、API 参考、文档站与更多资料

README 将官方产品文档组织在 website-docs/README.md：按"入门 → 架构 → 功能 → API → 客户端 → 开发"六部分组织，覆盖约 360 个 API 端点、约 150 个环境变量与 9 大扩展点；该目录同时是 VitePress 站点（cd website-docs && npm install && npm run dev本地预览，或用目录内 Dockerfile 独立部署）。

其他值得继续深入的资料：

• 常见问题排查：docs/QA.md；产品计划：docs/ROADMAP.md；
• 详细 API 文档：docs/api/README.md；
• 版本演进记录：CHANGELOG.md（本仓库对应 v0.8.0）；
• RBAC 设计：docs/RBAC说明.md；MCP 配置：mcp-server/MCP_CONFIG.md；
• 项目结构：cmd/server（服务入口）、internal/handler、internal/agent、internal/application/service、docreader（Python 解析服务）、frontend（Vue 3 前端）、client（Go SDK）、helm（Kubernetes 部署）。

十、安全基线

README Security Notice 强调：自 v0.1.3 起 WeKnora 包含登录认证功能以增强系统安全，生产部署强烈建议：

• 部署在内部/私有网络而非公网，避免服务直接暴露造成信息泄露风险；
• 配置正确的防火墙规则与访问控制；
• 定期更新到最新版本获取安全补丁与改进。

叠加前述平台能力（AES-256-GCM 凭据落盘加密、SSRF 防护、gRPC TLS、密钥脱敏、沙箱隔离、OIDC JWKS 校验、可选强密码与审计日志），构成了从传输、存储到应用的纵深防御基线。

结语

WeKnora 以"文档 → 可查询的 RAG → 可推理的 Agent → 自维护的 Wiki"为产品主线，在 README.md 中给出了完整的能力矩阵与部署路径。结合 docker-compose.yml 的编排细节、cli/README.md 的 Agent 优先 CLI 契约、config/config.yaml 的对话策略配置与 docs/开发指南.md 的免镜像开发模式，开发者可以快速完成从单机部署到二次开发的全流程落地，并借助官方文档站 website-docs/README.md 持续深入架构、API 与扩展点细节。

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