新增 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)说明。
345 lines
12 KiB
Markdown
345 lines
12 KiB
Markdown
# 尚数网本体管理平台 · 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. 快速开始
|
||
|
||
### 推荐构建与运行
|
||
|
||
```bash
|
||
./build.sh
|
||
./run.sh
|
||
```
|
||
|
||
`build.sh` 会依次完成:
|
||
|
||
1. 构建 Vue 前端;
|
||
2. 将 `web/dist` 同步到 `server/webroot`;
|
||
3. 编译 Go 二进制到 `bin/server`。
|
||
|
||
`run.sh` 默认连接:
|
||
|
||
```text
|
||
postgres://ssw:[email protected]:5432/ssw-ontology?sslmode=disable
|
||
```
|
||
|
||
如要连其他 PG 实例,覆盖 `.env` 里的 `DATABASE_URL`(格式:`postgres://user:pwd@host:port/dbname?sslmode=disable`)。
|
||
|
||
默认监听 `8081`。如果该端口被本机其他服务占用,可临时切换:
|
||
|
||
```bash
|
||
HTTP_PORT=9090 ./bin/server
|
||
```
|
||
|
||
访问:
|
||
|
||
```text
|
||
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 请求中携带:
|
||
|
||
```http
|
||
X-API-Key: <connector-key>
|
||
```
|
||
|
||
### MCP 一行注册
|
||
|
||
```json
|
||
{
|
||
"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`:计算对象必填属性完整度。
|
||
|
||
调用示例:
|
||
|
||
```bash
|
||
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` 策略 |
|
||
|
||
运行时处理链:
|
||
|
||
```text
|
||
请求
|
||
-> 识别 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 兼容服务:
|
||
|
||
```bash
|
||
AI_ENABLED=true \
|
||
AI_BASE_URL=https://api.deepseek.com/v1 \
|
||
AI_KEY=your-key \
|
||
AI_MODEL=deepseek-chat \
|
||
./run.sh
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 项目结构
|
||
|
||
```text
|
||
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 或更细粒度的审计事件,可在现有元数据与治理模型上继续演进。
|