# 尚数网本体管理平台 · 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:ssw@127.0.0.1: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: ``` ### 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 或更细粒度的审计事件,可在现有元数据与治理模型上继续演进。