Files
ssw-ontology/docs
admin 993f74c2b2 feat: Docker 单镜像分发 + 默认端口统一 8081 + seed 极简化
新增 Dockerfile + docker/entrypoint.sh:
- 基础 crpi-.../ssw188/postgres:16-alpine + ontology 二进制,单镜像
- 默认端口 8081 / 库 ssw-ontology / 用户 ssw / 密码 ssw
- /data/pg 自动挂 PG 数据,/data/archive 挂文档根目录
- trap 收尸保证 PG + ontology 同生命周期

seed 极简化为 1 个对象类型「合作企业」+ 3 条示例
(尚数网/腾讯/阿里巴巴),便于演示也便于清理。

默认 HTTP_PORT 统一为 8081(覆盖 server/config.go、run.sh、
vite.config.js、importer/import-from-xeo.js、docs/README.md、
docs/USAGE.md、docs/IMPORT.md、.env.example 等所有文档/代码)。

docs/README.md / .env.example 默认 DATABASE_URL 改为
ssw/[email protected]:5432/ssw-ontology(与 Docker 镜像自带 PG 一致);
run.sh 删 dacli 硬编码 fallback,改从 .env 读(不存在则报错退出)。

README 重整:分「方式 A Docker 镜像 / 方式 B 本机 ./run.sh」,
新增 AI 智能导入(-e AI_*)与管理接口鉴权(-e MANAGER_API_KEY)说明。
2026-08-13 15:59:27 +08:00
..

尚数网本体管理平台 · ShangShu Ontology

面向尚数网数据要素与可信数据空间业务的本体管理平台。平台将业务实体、属性、关系、动作、函数和接口统一纳入本体元数据,并通过访问控制与运行时审计控制信息的安全使用。

技术栈:Go + Gin + PostgreSQL + Vue3 + Element Plus。前端构建产物复制到 server/webroot 后由 Go //go:embed 内嵌进二进制。


1. 架构定位

平台采用 Semantic / Kinetic 双层模型:

  • Semantic 语义层:描述企业有什么以及实体之间如何关联。
    • Object Type / Object:对象类型与对象实例
    • Property:对象属性
    • Link Type / Link:关系类型与关系实例
    • Interface Type:对外 REST / MCP 接口契约
  • Kinetic 行为层:描述业务如何计算、执行和变化。
    • Action Type:用户主动触发、通常带副作用的动作
    • Function Type:可复用、类型化的计算函数
    • Dynamic Security:运行时执行主体识别、授权、标记过滤、字段脱敏和审计

本平台本身承担类似 Ontology Metadata Service(OMS)的职责:管理元数据、实例数据、治理规则和对外查询接口。

当前元数据组件

组件 数据表 / 实现 当前状态
Object object_types、objects 已实现
Property properties 已实现
Link link_types、links 已实现
Action action_types、AI 摄取及管理动作接口 已实现元数据与部分运行入口
Function function_types、builtin registry、invoke API 已实现 4 个内置函数
Interface interface_types、REST/MCP 契约 已实现并自动注册 6 个连接器接口
Dynamic Security Principal / Marking / Grant / FieldPolicy + access_log 已实现读写控制、过滤、脱敏、审计

2. 尚数网业务本体

当前种子本体围绕数据要素流通和可信数据空间展开,包含:

  • 数据资源、数据产品、数据需求
  • 可信数据空间、数据交易所、会员单位
  • 应用场景、分支机构、密算一体机
  • 核心服务、知识产权、新闻文章

关系覆盖空间与产品、会员与交易所、资源与场景、空间与设备、产品与资源等业务联系。实际对象类型和链接类型以数据库及 Web UI 中的本体元数据为准,后续可通过本体编辑、知识管理或 AI 摄取持续扩展。

早期尝试增加的 12 个“安全策略对象类型”已移除。安全策略不再作为业务对象灌入本体,而是作为与对象、链接、动作平级的治理元能力执行。


3. 快速开始

推荐构建与运行

./build.sh
./run.sh

build.sh 会依次完成:

  1. 构建 Vue 前端;
  2. 将 web/dist 同步到 server/webroot;
  3. 编译 Go 二进制到 bin/server。

run.sh 默认连接:

postgres://ssw:[email protected]:5432/ssw-ontology?sslmode=disable

如要连其他 PG 实例,覆盖 .env 里的 DATABASE_URL(格式:postgres://user:pwd@host:port/dbname?sslmode=disable)。

默认监听 8081。如果该端口被本机其他服务占用,可临时切换:

HTTP_PORT=9090 ./bin/server

访问:

http://127.0.0.1:8081

使用 127.0.0.1 可绕过部分本机 HTTP 代理对 localhost 的影响。

关键环境变量

变量 说明 默认
DATABASE_URL PostgreSQL 连接串 workspace PostgreSQL
HTTP_PORT HTTP 监听端口 8081
SEED_ON_START 本体为空时灌入业务种子;同时初始化治理、函数、接口元数据 true
ARCHIVE_DIR 知识文件归档目录 ../archive
AI_ENABLED 是否启用 OpenAI 兼容大模型 false
AI_BASE_URL / AI_KEY / AI_MODEL 大模型服务配置 空 / 默认模型
MANAGER_API_KEY 生产环境管理主体密钥 空
CONNECTOR_API_KEY 连接器入口密钥 空
ALLOW_CORS 是否允许跨域 按配置加载

前端修改后不能只替换磁盘上的静态文件。由于 server/main.go 使用 //go:embed all:webroot,必须重新执行 ./build.sh 或完成“前端 build → 同步 webroot → go build”。


4. Web UI

当前 Web UI 包含以下入口:

  1. 概览:对象类型、实例、关系和摄取概览。
  2. 本体编辑:Object / Property / Link / Action / Function / Interface 元数据管理。
  3. 实例管理:按对象类型创建、编辑和删除对象实例。
  4. 知识管理:
    • 知识文件目录树与文件列表;
    • 上传、建子文件夹、简单预览、单条或批量提取;
    • 删除文件时级联清理关联对象、链接和摄取记录;
    • 数据连接资源定义、导入本体、提取和级联删除。
  5. 关系图谱:可视化对象节点和链接边,并按当前主体权限过滤。
  6. 连接器:查询 REST / MCP 端点、工具清单和测试参数。
  7. 访问控制:
    • 主体 Principal;
    • 授权 Grant;
    • 对象 Marking;
    • 字段 FieldPolicy;
    • Dynamic Security 执行日志和 24 小时统计。

5. 连接器 REST API

连接器是只读查询面,所有查询都会经过当前主体的 Dynamic Security 决策:授权检查、对象标记过滤和字段策略处理。

方法 路径 用途
GET /api/v1/connector/object-types 列出对象类型及属性定义
GET /api/v1/connector/objects/:type 按类型列出可见对象
GET /api/v1/connector/object/:type/:pk 获取单个可见对象
GET /api/v1/connector/search?q=&type=&field=&limit= 关键词检索可见对象
GET /api/v1/connector/facets?type= 获取过滤维度取值
POST /api/v1/connector/query 按类型和属性过滤,并可展开关系邻居
GET /api/v1/connector/graph?type=&pk= 查询对象关系图
GET /api/v1/mcp/manifest 获取人类可读 MCP 自描述
POST /api/v1/mcp MCP Streamable HTTP JSON-RPC 端点

当配置 CONNECTOR_API_KEY 时,在连接器和 MCP 请求中携带:

X-API-Key: <connector-key>

MCP 一行注册

{
  "mcpServers": {
    "shangshu-ontology": {
      "url": "http://127.0.0.1:8081/api/v1/mcp"
    }
  }
}

然后在 WorkBuddy 的自定义连接器入口中信任该 MCP 服务。远程部署时,将 127.0.0.1:8081 替换为实际可访问地址;如果启用了连接器密钥,按 WorkBuddy 的 MCP 配置增加请求头。

当前 MCP 原生暴露 6 个查询工具:

  • get_object_types
  • get_objects_by_type
  • get_object
  • search_ontology
  • get_facets
  • query_related

6. Function 与 Interface

Function

Function 是可复用计算单元,不等同于 Action:Action 通常由用户触发并产生副作用;Function 通常是类型化、可复用、偏纯计算的能力。

当前内置函数:

  • mask_field_by_policy:按字段策略对属性脱敏;
  • compute_object_link_strength:根据对象关联数量计算关系强度;
  • compute_data_asset_value:按对象属性进行启发式资产价值估算;
  • derive_object_completeness:计算对象必填属性完整度。

调用示例:

curl -X POST \
  http://127.0.0.1:8081/api/v1/ontology/function-types/derive_object_completeness/invoke \
  -H 'Content-Type: application/json' \
  -d '{"object_type":"TrustedDataSpace","object_pk":"tds_logistics"}'

Function 类型接口:

  • GET /api/v1/ontology/function-types
  • GET /api/v1/ontology/function-types/:name
  • POST /api/v1/ontology/function-types
  • DELETE /api/v1/ontology/function-types/:name
  • POST /api/v1/ontology/function-types/:name/invoke

目前 builtin 函数可直接调用;script 和 external_api 是元数据扩展位,尚未作为通用执行沙箱实现。

Interface

interface_types 用来描述外部可调用接口的协议、方法、路径、输入输出和 MCP 暴露属性。启动时自动登记 6 个连接器 REST 接口,作为 Interface 元数据,而不是另建一套查询逻辑。

Interface 类型接口:

  • GET /api/v1/ontology/interface-types
  • GET /api/v1/ontology/interface-types/:name
  • POST /api/v1/ontology/interface-types
  • DELETE /api/v1/ontology/interface-types/:name

内置 Interface 不允许删除。当前 MCP 工具清单与 handlers_mcp.go 的实际实现保持一致,Function 尚未自动加入 MCP 工具清单。


7. Dynamic Security 访问控制

安全控制不是普通业务对象,而是平级于对象、链接、动作的治理元能力。

四类治理原语

原语 作用
Principal 请求主体,如 manager、connector、public 或自定义主体
Marking 对象访问标记,默认使用 L0~L4
Grant (principal, action, scope) -> allow/deny 授权规则
FieldPolicy 字段级 redact / hide / full 策略

运行时处理链:

请求
  -> 识别 principal
  -> 检查 grant
  -> 检查 object marking
  -> 过滤对象 / 关系
  -> 应用字段策略
  -> 写入 access_log
  -> 返回结果

覆盖范围:

  • 连接器 REST 查询;
  • MCP 工具调用;
  • 对象和链接写入;
  • 本体 schema 管理;
  • 关系图谱;
  • 访问控制管理接口。

开发模式下,当 MANAGER_API_KEY 与 CONNECTOR_API_KEY 都为空时,匿名请求按 manager 处理以保持本地开发体验。生产环境应设置密钥并通过 HTTPS 或反向代理保护服务。

相关接口:

  • GET /api/v1/access/whoami
  • GET|POST /api/v1/access/principals
  • GET|PUT /api/v1/access/principals/:name/clearances
  • GET|POST|DELETE /api/v1/access/grants
  • GET /api/v1/access/markings
  • GET|PUT /api/v1/access/objects/:type/:pk/markings
  • GET|POST|DELETE /api/v1/access/field-policies
  • GET /api/v1/access/preview?principal=
  • GET /api/v1/access/log
  • GET /api/v1/access/log/stats

8. AI 与知识管理

AI 摄取支持两类入口:

  1. 知识管理中的文本粘贴摄取;
  2. 知识文件和数据连接资源的提取。

流程是:资料输入 → AI / 启发式抽取 → 建议或自动应用 → 对象与链接写入 PostgreSQL。文件和连接资源会通过 source 记录溯源,删除时级联清理关联本体数据。

生产环境可设置 OpenAI 兼容服务:

AI_ENABLED=true \
AI_BASE_URL=https://api.deepseek.com/v1 \
AI_KEY=your-key \
AI_MODEL=deepseek-chat \
./run.sh

9. 项目结构

ssw-ontology/
├── build.sh
├── run.sh
├── go.mod / go.sum
├── .gitignore
├── server/
│   ├── main.go
│   ├── config.go
│   ├── db.go
│   ├── models.go
│   ├── access_control.go
│   ├── access_log.go
│   ├── functions.go
│   ├── handlers_access.go
│   ├── handlers_functions.go
│   ├── handlers_mcp.go
│   ├── handlers_connector.go
│   ├── handlers_km.go
│   ├── handlers_ai.go
│   └── webroot/          (前端构建产物,内嵌进二进制,git 忽略)
├── web/
│   └── src/views/
├── docs/                (项目文档)
│   ├── README.md
│   ├── PLAN.md
│   ├── USAGE.md
│   ├── IMPORT.md
│   └── product-intro.html
├── archive/             (知识文件,AI 摄取来源)
├── importer/
├── scripts/
└── bin/                 (编译产物,git 忽略)

10. 当前状态与注意事项

  • 当前代码已完成 Object / Property / Link / Action / Function / Interface 元数据,以及 Dynamic Security 运行时治理。
  • 前端改动后必须重新构建并重新编译 Go 二进制,原因是前端静态资源被 //go:embed 内嵌。
  • script / external_api Function 类型目前只完成元数据定义,尚未提供通用脚本沙箱或外部 HTTP 执行器。
  • 当前 MCP 仍暴露 6 个查询工具;Interface 元数据已登记,但并不自动替代 MCP 工具清单。
  • 如需扩展 Action 的真实业务副作用、Function 编排、接口级 grant 或更细粒度的审计事件,可在现有元数据与治理模型上继续演进。