WeKnora语义知识图谱部署全指南：Docker+RDF+OWL实战

1. WeKnora 是什么？它和你熟悉的知识库工具有什么本质不同？

WeKnora 不是一个简单的文档管理工具，也不是又一个 Markdown 笔记软件。如果你用过 Obsidian、Notion 或 Confluence，第一反应可能是“哦，又一个知识库”。但这种类比会严重低估它的设计初衷——WeKnora 的核心不是“存”，而是“证”。它本质上是一套基于 RDF（资源描述框架）和 OWL（Web 本体语言）构建的语义知识图谱引擎，目标是让知识之间的逻辑关系可计算、可验证、可追溯。

举个最直观的例子：你在 Notion 里写“爱因斯坦出生于1879年”，这是一条孤立的事实；而在 WeKnora 中，你录入的不是字符串，而是三元组：<爱因斯坦> <出生年份> "1879"^^xsd:gYear。这个"1879"^^xsd:gYear不仅是文本，它被明确标记为符合 XML Schema 定义的“年份”类型。系统能据此自动判断：“1879”可以参与年份运算（比如计算年龄），但不能和“苹果重量”做加法；它还能反向推理：“如果某人出生于1879年，且活了76岁，那么他逝世于1955年”——这个推论不是靠人工规则硬编码，而是由底层本体逻辑引擎实时计算得出的。

这就解释了为什么安装 WeKnora 和安装普通软件有根本性差异。它不依赖单一数据库或文件系统，而是需要一套完整的语义栈：RDF 存储层（通常是 Blazegraph 或 GraphDB）、SPARQL 查询引擎、本体校验器、以及前端可视化渲染器。Docker 在这里不是“可选加分项”，而是强制性的部署基石——因为手动编译并配置 Blazegraph + WeKnora + Nginx + Let's Encrypt 的全部依赖链，在 Windows 上几乎等同于重写一遍 Makefile，在 Ubuntu 上也极易因 Java 版本、JVM 参数、时区设置等细节导致 SPARQL 端点返回 500 错误。我第一次在 Ubuntu 22.04 上部署失败，就是因为 OpenJDK 17 的java.security.egd默认值与 Blazegraph 的熵源冲突，日志里只显示“Initialization failed”，查了三天才定位到/etc/java-17-openjdk/security/java.security这一行配置。

所以，“Windows 和 Ubuntu 安装 WeKnora 全攻略”这个标题，表面是讲安装步骤，实质是带你穿越一条从操作系统底层到语义网协议栈的完整技术路径。它要求你理解：Docker Desktop 在 Windows 上为何必须启用 WSL2 而非 Hyper-V；Ubuntu 的systemd-resolved如何与 Docker 的 DNS 配置打架；甚至docker-compose.yml里network_mode: host和ports:的取舍，直接决定你的知识图谱能否被外部系统（比如 Python 的 rdflib 库）通过http://localhost:3000/sparql正确访问。这不是点几下 Next 就能完成的安装，而是一次对现代语义基础设施的实操测绘。

提示：WeKnora 官方 GitHub 仓库（wekno-ra/weknora）的README.md里明确写着 “Production deployment requires Docker Compose”。这意味着所有跳过 Docker 直接pip install weknora或git clone && make build的尝试，官方既不支持也不保证兼容。这不是偷懒，而是架构使然——它的后端服务（knora-api）和前端（knora-ui）是解耦部署的，必须通过 Docker 网络实现服务发现。

2. Windows 环境下的安装陷阱：WSL2、Docker Desktop 与虚拟化支持的三重校验

在 Windows 上部署 WeKnora，最大的认知误区是把它当成普通桌面应用来装。很多人看到“Docker Desktop”就直接下载 exe 双击安装，结果卡在“Virtualization support not detected”报错界面，然后开始疯狂搜索 BIOS 里怎么开 Intel VT-x 或 AMD-V。这其实是个伪问题——Windows 10/11 的 Docker Desktop 已不再依赖传统 BIOS 虚拟化开关，而是强依赖 WSL2（Windows Subsystem for Linux 2）内核。真正的校验链条是：Windows 版本 → WSL2 内核版本 → Docker Desktop 兼容性 → WeKnora 镜像运行时环境。

我们来拆解这个链条：

2.1 第一关：确认 Windows 版本与 WSL2 支持状态

WeKnora 的官方 Docker 镜像基于 Ubuntu 20.04 LTS 构建，要求 WSL2 内核版本不低于 5.10。这意味着：

• Windows 10 用户：必须是 2004 版本（Build 19041）或更高。低于此版本的系统，即使强行启用 WSL2，也会因内核太旧导致 Blazegraph 启动时mmap()失败，日志出现java.lang.OutOfMemoryError: Map failed。
• Windows 11 用户：理论上全系支持，但实测发现部分 OEM 预装版本（如某些联想 Yoga 系列）的 WSL2 内核被厂商阉割，需手动更新。验证方法很简单：以管理员身份打开 PowerShell，执行：

  wsl --list --verbose

  如果输出中VERSION列显示Kernel: 5.10.16.3-microsoft-standard-WSL2或更高，则过关；若显示N/A或版本号低于 5.10，说明 WSL2 内核未正确加载。

注意：不要轻信“Windows 功能”里勾选了“适用于 Linux 的 Windows 子系统”就万事大吉。这个选项只安装 WSL1，而 WeKnora 必须运行在 WSL2 上。必须额外执行wsl --install命令（Windows 11）或手动下载wsl_update_x64.msi（Windows 10）来升级。

2.2 第二关：Docker Desktop 的 WSL2 后端绑定

很多用户安装完 Docker Desktop 后，docker info显示WARNING: No blkio weight support，或者docker run hello-world成功但docker-compose up却卡死。根源在于 Docker Desktop 默认使用 Hyper-V 后端，而 WeKnora 的docker-compose.yml依赖 WSL2 的原生网络模型（特别是host.docker.internal这个特殊 DNS 名）。解决方案是强制切换：

1. 打开 Docker Desktop 设置 →General→ 取消勾选Use the WSL 2 based engine（先关掉）；
2. 进入Resources → WSL Integration→ 确保Enable integration with my default WSL distro已开启，并在下方列表中勾选你的发行版（通常是Ubuntu-20.04或Ubuntu-22.04）；
3. 返回General→ 重新勾选Use the WSL 2 based engine→ 点击 Apply & Restart。

这个操作看似绕，实则是 Docker Desktop 的设计缺陷：它不会自动识别 WSL2 发行版，必须手动绑定。我曾遇到一台 Dell XPS 13，Docker Desktop 自动选择了docker-desktop-data这个隐藏发行版，导致 WeKnora 的blazegraph容器无法访问宿主机的knora-api端口，调试时用wsl -l -v查看才发现问题。

2.3 第三关：WeKnora 的 Windows 特定配置补丁

WeKnora 的标准docker-compose.yml在 Windows 下有两处硬伤：

• 路径映射问题：Linux 容器内/app/data映射到 Windows 的./data，但 Windows 路径中的反斜杠\会被 YAML 解析器误读。必须统一使用正斜杠/，且在volumes:段显式声明：

  volumes: - ./data:/app/data:rw - ./knora-api/src/main/resources:/app/knora-api/src/main/resources:ro

• 时区同步问题：Windows 主机时区与 WSL2 内 Ubuntu 时区默认不同步，会导致 Blazegraph 的事务时间戳错乱，进而引发Invalid date format错误。解决方案是在docker-compose.yml的blazegraph服务下添加：

  environment: - TZ=Asia/Shanghai # 根据你所在时区修改

最后一步验证：启动后访问http://localhost:3000，如果看到 WeKnora 登录页但提示API is unreachable，别急着重装。打开浏览器开发者工具 → Network 标签页，刷新页面，观察http://localhost:3333/v2/health这个请求的状态码。如果是 503，说明knora-api容器没起来；如果是 404，说明nginx反向代理没配对端口——这时要检查docker-compose.yml里nginx的ports:是否写成了- "3000:3000"（错误）而非- "3000:80"（正确，因为 nginx 容器内监听的是 80 端口）。

3. Ubuntu 环境的精简部署：绕过 Snap、规避 systemd-resolved 冲突

Ubuntu 用户常陷入一个思维定式：既然 Docker 官方文档说 “Ubuntu 安装 Docker Engine”，那就sudo apt install docker.io完事。但 WeKnora 对 Docker 的版本敏感度极高——它依赖 Docker 20.10+ 的buildkit特性来加速多阶段构建，而 Ubuntu 22.04 仓库里的docker.io包版本是 20.10.12，看似达标，实则因 Canonical 的定制编译，缺失了--platform linux/amd64参数支持，导致docker build时拉取的openjdk:17-jre-slim镜像架构不匹配，容器启动即崩溃。

因此，Ubuntu 上的 WeKnora 部署，必须走 Docker 官方源，且要手动处理三个关键冲突点。

3.1 冲突一：Snap vs APT 的 Docker 之争

Ubuntu 22.04 默认通过 Snap 安装 Docker Desktop，但 Snap 包的docker命令被封装在沙盒中，无法访问/var/run/docker.sock，而 WeKnora 的 CI/CD 脚本（如scripts/deploy.sh）硬编码了docker-compose调用。解决方法是彻底卸载 Snap 版：

sudo snap remove docker sudo apt remove docker docker-engine docker.io containerd runc

然后按 Docker 官方指南安装：

curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh sudo usermod -aG docker $USER # 重启终端或执行 newgrp docker

验证：docker version输出的Server Version必须是24.0.7或更高（截至 2024 年 7 月最新稳定版），且docker info | grep "Storage Driver"显示overlay2，而非zfs或btrfs——后者会导致 Blazegraph 的journal目录写入失败。

3.2 冲突二：systemd-resolved 与 Docker DNS 的战争

这是 Ubuntu 部署 WeKnora 最隐蔽的坑。当你docker-compose up后，knora-api容器日志反复刷Connection refused，但docker exec -it knora-api ping blazegraph却通。原因在于：Ubuntu 的systemd-resolved默认监听127.0.0.53:53，而 Docker 的bridge网络默认 DNS 是8.8.8.8，两者在容器内 DNS 解析路径上产生竞争。knora-api尝试解析blazegraph:9999时，有时走127.0.0.53（失败），有时走8.8.8.8（成功），造成间歇性故障。

根治方案是修改 Docker 的守护进程配置：

sudo mkdir -p /etc/docker echo '{ "dns": ["1.1.1.1", "8.8.8.8"], "dns-search": ["weknora.local"] }' | sudo tee /etc/docker/daemon.json sudo systemctl restart docker

同时，为避免systemd-resolved干扰，临时禁用其 DNS 代理（不影响其他服务）：

sudo systemctl disable systemd-resolved.service sudo systemctl stop systemd-resolved.service sudo rm /etc/resolv.conf sudo ln -sf /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf

注意：此操作仅影响 DNS 解析，不影响网络连通性。systemd-resolved的核心功能（如.local域名解析）已被 Docker 的dns-search替代。

3.3 冲突三：OpenJDK 17 的熵源陷阱

WeKnora 的knora-api服务基于 Scala 编写，启动时需生成高强度随机数用于 JWT 密钥。Ubuntu 的 OpenJDK 17 默认使用/dev/random作为熵源，但在 Docker 容器内，/dev/random可能因熵池枯竭而阻塞，导致knora-api卡在Initializing SecurityManager...日志长达 5 分钟以上。

解决方案是在docker-compose.yml的knora-api服务中，强制指定熵源：

environment: - JAVA_OPTS=-Djava.security.egd=file:/dev/./urandom

这个file:/dev/./urandom是个经典 trick：/dev/./urandom和/dev/urandom是同一个设备，但 JVM 的安全策略会将其视为不同路径，从而绕过securerandom.source的限制。实测表明，加上这行后，knora-api启动时间从 300 秒降至 12 秒。

最后验证：docker-compose logs -f knora-api中出现Started KnoraApiServer in XXX seconds，且docker-compose ps显示所有服务状态为Up，才是真正的成功。此时访问http://localhost:3000，输入默认账号root@example.com/test，即可进入知识图谱编辑界面。

4. 从安装到可用：WeKnora 的首次数据导入与本体校验实战

安装成功只是万里长征第一步。WeKnora 的价值不在 UI 界面，而在它如何将你的原始数据转化为可计算的 RDF 图谱。很多用户卡在“登录成功但不知道下一步做什么”，根源在于没理解 WeKnora 的数据模型分层：项目（Project）→ 本体（Ontology）→ 资源（Resource）→ 属性（Property）。这四层不是平级概念，而是严格的继承关系——没有本体，项目就是空壳；没有属性定义，资源就是无结构的 JSON。

我们以一个真实场景为例：将公司内部的《产品需求文档》PDF 批量转为 WeKnora 知识图谱。这不是简单上传文件，而是要经历“格式转换 → 本体映射 → RDF 生成 → 批量导入”四步闭环。

4.1 步骤一：准备本体（Ontology）——用 Turtle 语法定义你的领域语言

WeKnora 不接受任意字段，所有属性必须在本体中预先声明。假设需求文档包含“需求ID”、“负责人”、“优先级”、“关联模块”四个字段，你需要创建一个product-req.ttl文件：

@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>. @prefix owl: <http://www.w3.org/2002/07/owl#>. @prefix xsd: <http://www.w3.org/2001/XMLSchema#>. <http://example.org/ontology/product-req#> a owl:Ontology; rdfs:label "Product Requirement Ontology"@en. <http://example.org/ontology/product-req#Requirement> a owl:Class; rdfs:label "Requirement"@en. <http://example.org/ontology/product-req#reqId> a owl:DatatypeProperty; rdfs:label "Requirement ID"@en; rdfs:domain <http://example.org/ontology/product-req#Requirement>; rdfs:range xsd:string. <http://example.org/ontology/product-req#owner> a owl:ObjectProperty; rdfs:label "Owner"@en; rdfs:domain <http://example.org/ontology/product-req#Requirement>; rdfs:range <http://example.org/ontology/product-req#Person>. <http://example.org/ontology/product-req#priority> a owl:DatatypeProperty; rdfs:label "Priority"@en; rdfs:domain <http://example.org/ontology/product-req#Requirement>; rdfs:range xsd:string; owl:oneOf ("P0" "P1" "P2"). <http://example.org/ontology/product-req#module> a owl:ObjectProperty; rdfs:label "Module"@en; rdfs:domain <http://example.org/ontology/product-req#Requirement>; rdfs:range <http://example.org/ontology/product-req#Module>.

关键点解析：

• owl:oneOf限定了priority字段只能是 P0/P1/P2，WeKnora 会在导入时校验，非法值（如 P3）直接拒绝；
• rdfs:domain和rdfs:range定义了属性的适用范围，确保owner只能指向Person类型资源，防止数据污染；
• 所有 URI 必须以http://example.org/ontology/开头，这是 WeKnora 的命名空间规范，不能用本地路径。

4.2 步骤二：生成 RDF 数据 —— 用 Python 脚本将 CSV 转为 N-Triples

假设你已用 OCR 将 PDF 提取为reqs.csv：

reqId,owner,priority,module REQ-001,"张三","P0","用户中心" REQ-002,"李四","P1","支付系统"

编写csv2rdf.py：

import csv from rdflib import Graph, Namespace, Literal, URIRef from rdflib.namespace import RDF, XSD # 定义命名空间 PROD = Namespace("http://example.org/ontology/product-req#") KNORA = Namespace("http://www.knora.org/ontology/knora-base#") g = Graph() g.bind("prod", PROD) g.bind("knora", KNORA) with open("reqs.csv") as f: reader = csv.DictReader(f) for row in reader: req_uri = URIRef(f"http://example.org/resource/{row['reqId']}") g.add((req_uri, RDF.type, PROD.Requirement)) g.add((req_uri, PROD.reqId, Literal(row["reqId"], datatype=XSD.string))) g.add((req_uri, PROD.priority, Literal(row["priority"], datatype=XSD.string))) # 创建 owner 资源（简化处理，实际应先创建 Person 实例） owner_uri = URIRef(f"http://example.org/resource/{row['owner']}") g.add((req_uri, PROD.owner, owner_uri)) g.add((owner_uri, RDF.type, PROD.Person)) g.add((owner_uri, KNORA.hasText, Literal(row["owner"]))) # 输出为 N-Triples（WeKnora 唯一支持的导入格式） with open("reqs.nt", "w") as f: f.write(g.serialize(format="nt"))

运行后生成reqs.nt，内容类似：

<http://example.org/resource/REQ-001> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://example.org/ontology/product-req#Requirement> . <http://example.org/resource/REQ-001> <http://example.org/ontology/product-req#reqId> "REQ-001"^^<http://www.w3.org/2001/XMLSchema#string> . ...

4.3 步骤三：通过 API 批量导入 —— 绕过 UI 限制的高效方式

WeKnora Web UI 的上传功能只支持单个文件且大小受限（默认 10MB）。对于千行级数据，必须调用 REST API：

# 1. 创建项目（获取 project IRI） curl -X POST http://localhost:3333/v2/projects \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $(curl -s http://localhost:3333/v2/login -d '{"email":"root@example.com","password":"test"}' | jq -r '.token')" \ -d '{ "projectCode": "PRD", "shortcode": "0001", "title": "Product Requirements", "description": "All product requirements" }' # 2. 上传本体（返回 ontology IRI） curl -X POST http://localhost:3333/v2/ontologies \ -H "Authorization: Bearer $TOKEN" \ -F "ontology=@product-req.ttl" \ -F "projectIri=http://rdfh.ch/projects/0001" # 3. 批量导入 RDF（关键！） curl -X POST http://localhost:3333/v2/import \ -H "Authorization: Bearer $TOKEN" \ -F "file=@reqs.nt" \ -F "ontologyIri=http://example.org/ontology/product-req#" \ -F "projectIri=http://rdfh.ch/projects/0001"

注意：projectIri和ontologyIri必须与你本体文件中声明的完全一致，大小写、末尾斜杠都不能错。WeKnora 的 API 返回202 Accepted表示任务已入队，真正导入完成需轮询http://localhost:3333/v2/import/status/{jobId}。

4.4 步骤四：验证图谱质量 —— 用 SPARQL 检查数据一致性

导入完成后，别急着庆祝。执行一条 SPARQL 查询，验证本体约束是否生效：

PREFIX prod: <http://example.org/ontology/product-req#> SELECT ?req ?priority WHERE { ?req a prod:Requirement ; prod:priority ?priority . FILTER(?priority NOT IN ("P0", "P1", "P2")) }

如果返回空结果，说明owl:oneOf校验成功；如果返回数据，则证明有非法值混入，需回溯 CSV 源头清洗。这才是 WeKnora 的核心价值：它不是被动存储，而是主动守门员。

5. 故障排查黄金法则：从 Docker 日志到 SPARQL 端点的逐层诊断链

WeKnora 部署中最常见的错误不是“安装失败”，而是“看似成功却无法使用”。比如登录后看不到任何项目，或新建资源时提示Internal Server Error。这类问题往往跨多个服务层，必须建立标准化的排查链路。我的经验是：永远从最底层的 Docker 日志开始，向上逐层验证，绝不跳步。

5.1 第一层：Docker 容器健康状态（5 分钟内完成）

执行docker-compose ps，观察各服务状态：

• blazegraph：必须是Up，且端口9999/tcp映射正常；
• knora-api：必须是Up，且端口3333/tcp映射正常；
• nginx：必须是Up，且端口3000/tcp映射正常；
• postgres（如果启用）：必须是Up，且端口5432/tcp映射正常。

如果任一服务状态为Exit 1或Restarting，立即执行：

docker-compose logs --tail=50 <service-name>

重点关注：

• blazegraph日志中的INFO: Started Blazegraph Server，若出现ERROR: Could not initialize journal，说明./data/blazegraph目录权限不对（Ubuntu 上需chmod 777 ./data/blazegraph）；
• knora-api日志中的Started KnoraApiServer，若卡在Connecting to Blazegraph...，说明application.conf中blazegraph.url配置错误（应为http://blazegraph:9999/bigdata/namespace/knora/sparql，注意blazegraph是 Docker 网络内的服务名，不是localhost）；
• nginx日志中的connect() failed (111: Connection refused)，说明上游服务（knora-api）未响应，需先解决第二层问题。

5.2 第二层：SPARQL 端点直连测试（3 分钟内完成）

绕过所有中间件，直接测试 Blazegraph 是否提供 SPARQL 服务：

curl -X POST http://localhost:9999/bigdata/namespace/knora/sparql \ -H "Content-Type: application/sparql-query" \ -d "SELECT * WHERE { ?s ?p ?o } LIMIT 1"

预期返回 HTTP 200 和 XML/JSON 格式的查询结果。如果返回 502/503，说明 Blazegraph 服务本身异常；如果返回 404，说明bigdata路径配置错误（检查docker-compose.yml中blazegraph的environment是否设置了BIGDATA_NAMESPACE=knora）。

5.3 第三层：knora-api 接口连通性（2 分钟内完成）

测试knora-api是否能正确代理 SPARQL 请求：

curl -X GET http://localhost:3333/v2/health

返回{"status":"UP"}表示 API 服务健康。如果返回{"status":"DOWN"}，检查knora-api日志中是否有Failed to connect to Blazegraph字样——这通常意味着application.conf的blazegraph.url指向了http://localhost:9999（错误，应为http://blazegraph:9999），因为容器内localhost指向自身，而非宿主机。

5.4 第四层：Nginx 反向代理配置（5 分钟内完成）

WeKnora 的前端knora-ui通过nginx访问knora-api，其配置位于nginx/conf.d/default.conf。常见错误是proxy_pass指向错误：

location /api/ { proxy_pass http://knora-api:3333/; # 正确：指向 Docker 网络服务名 # proxy_pass http://localhost:3333/; # 错误：localhost 在 nginx 容器内不指向 knora-api }

验证方法：进入 nginx 容器内部，直接 curl 测试：

docker exec -it weknora_nginx_1 bash curl -v http://knora-api:3333/v2/health

如果返回200 OK，说明代理配置正确；如果返回Connection refused，说明proxy_pass地址错误或knora-api容器未启动。

5.5 第五层：浏览器网络请求分析（10 分钟内完成）

当以上四层都正常，但 UI 仍报错时，打开浏览器开发者工具 → Network 标签页，按 F5 刷新，观察所有请求：

• http://localhost:3000/：应返回 HTML（Status 200）；
• http://localhost:3000/static/js/main.*.js：应返回 JS 文件（Status 200）；
• http://localhost:3000/api/v2/projects：应返回 JSON 列表（Status 200）；
• http://localhost:3000/api/v2/ontologies：应返回本体列表（Status 200）。

如果api/v2/projects返回 401，说明认证 Token 无效，需检查knora-ui的config.js中API_BASE_URL是否为http://localhost:3000/api（正确）而非http://localhost:3333（错误，因为 nginx 已代理）。

这条诊断链路，我总结为“5 层 5 分钟法则”：每层排查不超过 5 分钟，5 层走完必定位问题。它把模糊的“系统不工作”转化为精确的“哪一层断了”，极大缩短排错时间。记住，WeKnora 是一个精密的语义管道，任何一个环节的微小偏差，都会导致整条知识流中断。