- 新增 docs/ONTOLOGY_IMPORT.md:本体 schema 导入的硬约束(fail-fast 闸门、整事务、 幂等键、IRI 双空间映射、不做范围对账删除),并记录实现落点与逐条偏差 - 新增 docs/auto-ontology-benchmark-20261106.md:NVIDIA auto-ontology 对标分析与 Top-8 路线图,本版已落地项逐条标注 - docs/README.md 同步 API 清单与 MCP 工具表(54 个:只读 27 / 写入 27) - 项目 CLAUDE.md 补「本体 schema 导入」小节:闸门顺序、事务与串行理由、幂等表、 RDF Schema 命名空间年份坑 - README.md 镜像标签更新到 1.8.0,本地构建镜像补上 Linux 静态二进制交叉编译步骤, 健康检查端点改回 /api/v1/version - scripts/ 收拢本体 v2 迁移与分级校正脚本(一次性运维工具,不参与构建) Co-Authored-By: Claude Code <[email protected]>
通用本体元数据平台 · Ontology Platform
把业务实体、属性、关系、动作、函数、接口与访问控制统一纳入一套可查询、可治理、可审计的本体元数据平台。 既适合企业沉淀内部业务(数据要素、可信数据空间、CRM、组织架构、产品目录…),也适合个人/小团队管理自己的知识网络。
设计对标 Palantir Ontology 的 6 元原语(Object / Property / Link / Interface / Action / Function)+ Dynamic Security 治理 + AI 摄取 + 只读 REST/MCP 连接器。 详细架构、API、能力清单与 Palantir 对标表见 docs/README.md。
文档导航
| 文档 | 用途 |
|---|---|
| docs/README.md | 架构总览、6 元原语、API 全清单、Palantir 对标 |
| docs/INSTANCE_GOVERNANCE.md | 实例治理:merge/软删除/批量/审计回滚/去重/血统传播/source_ts |
| docs/PLAN.md | 设计目标、能力边界、演进计划(P1/P2/P3) |
| docs/USAGE.md | 启动 + 连接器查询 + AI 摄取 实战 |
| docs/IMPORT.md | 把外部数据源(API/文件/数据库)导入本体 |
| docs/BACKUP.md | 备份与快照路由 |
| docs/TESTING.md | 测试约定 |
| docs/WORKBUDDY.md | 一键注册到 WorkBuddy |
| docs/STANDARD_GB48000_3_2026_GAP.md | 与 GB/T 48000.3-2026《标准数字化 第3部分:本体建模要求》的符合性差距矩阵 |
| docs/product-intro.html | 营销/介绍页 |
核心能力
- 6 元原语 + 物化层:Object / Property / Link / Interface / Action / Function + Materialization / Backing Source,完整覆盖"数据 + 计算 + 接口"三面
- Dynamic Security:Principal + Marking + Grant + FieldPolicy + 审计日志,与对象/链接/动作平级的治理元能力
- AI 摄取:粘贴文本、批量文件、数据连接资源三种入口,自动抽 schema 并写入本体,可精确指定抽取范围(
directive) - 只读 REST/MCP:连接器对外暴露本体子集,所有读路径过同一套授权 + 字段脱敏;MCP 一行注册到 WorkBuddy / Claude Code
- 提示调度:
/api/v1/ontology/suggestions按上下文(context/type/stage)推 Function/Action;UI 用统一的 💡 SuggestionHints 组件 - 物化 + 同步源:Materialization 把多表 join 物化成快读行,Backing Source 描述外部数据源的字段映射
- 实例治理(2026-09-05):写入默认 merge 不丢字段、软删除墓碑 + 回滚、批量事务导入、字段级变更审计、重复实体提示、显示名物化(title_property 回退链)、
source_ts乱序写入丢弃、删除沿溯源传播(propagate,对标 Palantir Lineage-Aware Deletion)
快速开始
平台强依赖 PostgreSQL。表结构由代码在启动时自动创建(server/db.go 的 migrate() + server/access_control.go 的 ensureAccessControlSchema()),并自动灌入极简种子(1 个对象类型「合作企业」+ 3 条示例,部署后可一键清掉),只要有可用的 Postgres 空库,即可直接运行,无需手动建表或导入。
方式 A:Docker 一键镜像(自带 PG,推荐用于部署/分发)
mkdir -p ~/ontology-data/pg ~/ontology-data/archive
docker run -d --name ontology -p 8081:8081 \
-v ~/ontology-data:/data --restart unless-stopped \
crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/ssw-ontology:1.8.0
- 自带 PostgreSQL(容器内 5432,本体后端映射到宿主机 8081)
- 默认账户:数据库
ssw-ontology/ 用户ssw/ 密码ssw - 挂
-v /host/x:/data后,/data/pg存 PG 数据、/data/archive存文档;不挂则匿名卷,重启丢 - 健康检查:
wget --spider http://127.0.0.1:8081/api/v1/version,docker ps看 STATUS 是否(healthy) - 详见 Dockerfile 与 docker/entrypoint.sh
方式 B:本机 ./run.sh(开发用)
./build.sh && ./run.sh # 监听 http://127.0.0.1:8081
需要本机有 PostgreSQL(可以是 Docker 镜像外的任意实例)。DATABASE_URL 与其他配置都在仓库根 .env 里设置(参考 .env.example),不在仓库里出现真实凭据。
快速起本地 PG 示例:
docker compose up -d # 起 jnpf-postgres,端口 15432 映射
Docker 镜像配置
覆盖 PG 账户:
docker run ... -e POSTGRES_USER=myuser -e POSTGRES_PASSWORD=mypwd -e POSTGRES_DB=mydb ...
自定义 PG 数据目录路径(保留自带 PG,只改数据存哪):
优先级:用户显式传 PGDATA > 挂载 /data/pg > 默认匿名卷
# 用自己的目录存 PG(不挂 /data/pg 时这条才生效)
docker run -d --name ontology -p 8081:8081 \
-e PGDATA=/var/lib/postgresql/data/myapp \
crpi-.../ssw188/ssw-ontology:1.8.0
# 或结合挂载:让 /data/pg 路径下再分一层
docker run -d --name ontology -p 8081:8081 \
-v ~/pgdata:/var/lib/postgresql/data \
crpi-.../ssw188/ssw-ontology:1.8.0
连外部 PG(不跑镜像自带 PG,-e EXTERNAL_PG=true 跳过自带 PG 启动):
docker run -d --name ontology -p 8081:8081 \
-e EXTERNAL_PG=true \
-e DATABASE_URL=postgres://user:pwd@host:port/dbname?sslmode=disable \
crpi-.../ssw188/ssw-ontology:1.8.0
适用场景:连宿主已有的 PG(如 localhost:15432/shangshu 的 jnpf-postgres)、其他 PG 容器、外部云库等。DATABASE_URL 是 ontology 二进制的连接串(Go 端 loadConfig 读取,PGDATA/POSTGRES_USER 等内置 PG 环境变量在外部 PG 模式下被忽略)。
启用 AI 智能导入(默认 AI_ENABLED=false 走启发式抽取,只能识别引号实体;开启后大模型会建对象类型/属性/链接类型/动作类型/实例/关系):
docker run -d --name ontology -p 8081:8081 \
-v ~/ontology-data:/data --restart unless-stopped \
-e AI_ENABLED=true \
-e AI_BASE_URL=https://api.minimaxi.com/anthropic \
-e AI_KEY=<your-key> \
-e AI_MODEL=MiniMax-M3 \
crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/ssw-ontology:1.8.0
- URL 含
/anthropic子串 → Anthropic Messages 协议;其余按 OpenAI Chat Completions 兼容协议(DeepSeek / 通义千问 / Ollama 等均可) - 4 个变量必须全设;只设 KEY 但
AI_ENABLED=false仍走启发式 - 适用接口:
POST /api/v1/ai/ingest(粘贴文本摄取)、POST /api/v1/km/extract(从 archive 文件摄取)
启用管理接口鉴权:默认不读取任何 .env 密钥,主体(manager/connector/public/ingest)的 api_key 在首次启动时由 server 自动随机生成并打印到 stdout;通过密码登录后可访问 Access Control 页查看/重置/清空各主体密钥,或用 X-API-Key: <key> 调用管理接口。生产环境请妥善保存首次启动日志,并通过 HTTPS 或反向代理保护服务。
本地构建镜像(如需):
# 1) 先编 Linux 静态二进制(Dockerfile 从 bin/server-linux 取产物)
VERSION=$(git describe --tags --always --dirty)
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build \
-ldflags "-s -w -X main.Version=${VERSION} -X main.Commit=$(git rev-parse --short HEAD) -X main.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
-o bin/server-linux ./server
# 2) 再打镜像
docker build --provenance=false --sbom=false -t ontology:1.8.0 .
--provenance=false --sbom=false是推私仓的前提:buildx 默认附带的 attestation manifest 私仓不认,本地 build 正常但 push 会报unknown manifest class。详见Dockerfile头部注释。
适用场景(不限于)
| 场景 | 典型对象类型 | 价值 |
|---|---|---|
| 企业数据资产盘点 | 数据资源/产品/需求/空间 | 资产可发现、可查询、可授权 |
| CRM / 销售管理 | 客户/合同/订单/产品 | 关系驱动,精准展开客户全貌 |
| 知识管理 | 文档/概念/人/项目 | AI 摄取 + 关系图谱 + 全文检索 |
| 可信数据空间 | 空间/会员/产品/设备 | 合规授权 + 审计日志 |
| 个人 / 小团队 | 项目/任务/笔记/人脉 | 单机部署 + REST/MCP 查询 |
许可与品牌
- 平台是通用的:不绑定任何特定业务,可独立部署、改造、商用
- 采用方示例:尚数网(shangshuwang.cn)是当前采用此平台的项目之一,主要用其做数据要素与可信数据空间的本体管理
- Docker 镜像、默认端口(8081)、默认账户(
ssw/ssw)沿用尚数网最初部署约定,改用其他镜像/账户不影响功能