Files
ssw-ontology/docs/README.md
T
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

345 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 尚数网本体管理平台 · 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 或更细粒度的审计事件,可在现有元数据与治理模型上继续演进。