首页 / 开源热榜 / weknora / 使用教程

WeKnora 教程：先跑核心服务，再开启 Skill 沙箱

更新于 2026-09-23 · NGJOO AI 实验室 · 约 12 分钟

WeKnora 把文档解析、混合检索、RAG 问答、ReAct Agent、自动 Wiki 和知识图谱放进一套自托管平台。v0.8.0 又加入 Docker、E2B、Cube Skill 沙箱、租户 Skill 目录和跨会话记忆，权限面比普通知识库更大。

v0.8.0 发布于 2026-09-03。官方 LICENSE 说明主体代码为 MIT，第三方组件按 THIRD_PARTY_NOTICES 和 licenses 目录中的条款处理。

1. 固定版本和密钥

git clone https://github.com/Tencent/WeKnora.git
cd WeKnora
git checkout v0.8.0
cp .env.example .env

把 WEKNORA_VERSION 设为 v0.8.0，不要留在 latest。按 .env.example 替换数据库、对象存储、JWT、AES、模型和搜索服务占位值，并确保 .env 不进入版本控制。

2. 只启动核心服务

docker compose pull
docker compose up -d
docker compose ps

默认 Web UI 是 http://localhost，API 是 http://localhost:8080。先用防火墙限制访问，再建立管理员账号。第一次只导入一份无敏感信息的样本文档，检查解析、切分、引用、删除和备份恢复。

3. 可选 profile 逐项打开

Neo4j、MinIO、Langfuse 和其他向量库通过 Compose profile 增加。每开一个 profile，先记录新增容器、端口、凭据、存储卷和资源消耗。不要一开始使用 --profile full，否则故障时很难判断由哪个组件引起。

4. Skill sandbox 的权限

v0.8.0 已移除直接运行宿主进程的旧后端，Skill 可放在 Docker、E2B 或 Cube 会话沙箱。Docker 后端默认关闭，因为给 app 挂载 docker.sock 等同授予宿主 root。需要它时应使用隔离主机，固定允许的镜像，配置 CPU、内存、TTL、DNS 和默认拒绝的出站网络策略。

从 ClawHub、SkillHub、Git 或 zip 安装的 Skill 都是代码来源。入库前审查内容和依赖，给租户限定安装权限，避免把模型 key、数据库凭据或企业文档注入不可信 Skill。

5. 常见失败怎么排

升级后界面还是旧版：先固定 WEKNORA_VERSION，执行 pull，再重新 up。单独 up 会复用缓存镜像。
本地 Ollama 不可达：容器内 localhost 指向容器自身，改为容器能访问的宿主地址，并检查模型名。
文档一直解析中：查看 app 与 docreader logs、任务超时、文件大小和解析格式。
启用 profile 后端口冲突：对照 compose 的主机端口，修改 env 后重建对应服务。
Agent 工具失败：确认 MCP、搜索、sandbox 的网络策略和租户凭据，先用最小工具集复现。

验证边界：本轮只核对官方 README、CHANGELOG、LICENSE、.env.example、docker-compose.yml 与 Releases。未拉取镜像，未启动前后端、数据库、docreader、向量库、Langfuse 或 sandbox，未导入文档，也未配置模型、数据源和 IM 凭据。

6. 与 RAGFlow 对比

RAGFlow同样提供文档解析、RAG、Agent 和自托管，重点在复杂文档理解和可视化 RAG 流程。WeKnora 还提供自维护 Wiki、页面修订、租户 Skill 目录、会话沙箱与长期记忆。应使用自己的文档集比较解析成功率、召回、引用、延迟和运维成本。

这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。

先判断这个项目是否适合你

适合谁用

适合把企业文档做成可引用问答、维护 Wiki、跨知识库检索或让 Agent 在受控沙箱调用工具的团队。只需要轻量单机向量检索时，核心服务和可选 profile 的运维成本可能过高；涉及企业数据时应先定义租户、保留、删除和模型传输政策。

采用建议

适合把企业文档做成可引用问答、维护 Wiki、跨知识库检索或让 Agent 在受控沙箱调用工具的团队。只需要轻量单机向量检索时，核心服务和可选 profile 的运维成本可能过高；涉及企业数据时应先定义租户、保留、删除和模型传输政策。采用前需要核对：默认和可选 profile 涉及多种数据库、存储与端口。

原教程未展开的系统信息

核心功能

RAG、Agent 与 Wiki
Quick Q&A 做知识库检索问答，ReAct Agent 编排检索、MCP、Skill 沙箱和网络搜索，Wiki Mode 把原始文档整理成可编辑、可回滚的互链页面。
多源与多后端
支持飞书、GitLab、腾讯 IMA、Notion、语雀及 10 多种文档格式，可更换 LLM、向量数据库和对象存储。
多租户与可观测
平台提供 RBAC、OIDC、凭据加密、审计及 Langfuse 链路观测，并能通过 IM、CLI、MCP 和 Chrome 扩展访问知识库。

架构与数据流

默认 Compose 启动 frontend、Go app、docreader、PostgreSQL 与 Redis 等核心服务；可选 profile 增加 Neo4j、MinIO、Langfuse 和其他向量库。app 协调文档解析、知识库、检索、Agent、MCP、记忆和沙箱。Docker Skill 后端默认关闭，因为挂载 docker.sock 等同宿主 root；也可接 E2B 或 Cube 并配置租户网络策略。

常见问题

WeKnora 升级后为什么界面版本没有变化？

只运行 docker compose up -d 会复用本地缓存镜像。先把 WEKNORA_VERSION 固定为目标标签，再执行 docker compose pull 和 docker compose up -d，并在系统信息页核对版本。

WeKnora 的 Docker Skill 沙箱为什么默认关闭？

官方指出 app 挂载 docker.sock 后等同拥有宿主 root 权限。只有在隔离主机上确认镜像、网络策略、资源配额和租户权限后才应开启，也可改用受控的 E2B 或 Cube 后端。

WeKnora 接本地 Ollama 后模型不可达怎么办？

容器内的 localhost 不是宿主机。先确认宿主已运行 ollama serve，再按官方网络说明设置容器可访问的宿主地址，并从 app 容器检查 DNS、端口和模型名。

WeKnora 首次验证应该导入企业文档吗？

不应该。先用无敏感信息的样本文档检查解析、切分、引用、删除和备份，再确认模型、对象存储、日志、Langfuse、IM 和外部数据源的数据边界。

WeKnora 和 RAGFlow 怎样选？

RAGFlow 更侧重复杂文档解析和可视化 RAG 流程；WeKnora 还提供自维护 Wiki、修订历史、租户 Skill 目录、会话沙箱和长期记忆。应按文档类型、权限模型和运维成本实测。