理由:管理界面已就位,DB 中由 UI 设置或 seed 随机生成的 key 才是唯一权威来源,
不再需要在部署时手动配置 MANAGER_API_KEY/CONNECTOR_API_KEY/INGEST_API_KEY,
避免环境变量泄漏/不同环境不一致/容器重启覆盖等运维隐患。
### 设计
- 移除 Config 中的 ManagerAPIKey/ConnectorAPIKey/IngestAPIKey 字段及对应环境变量读取。
- principalFromRequest 仅查 principals 表 api_key;不再有 env 优先回退。
- loginRequired/connectorAuth 改为查询 'DB 是否已有密钥' 判定是否进入真实鉴权模式;
manager 未配置 key 的全新库仍保留开放体验,便于首次引导(密码登录)。
- 首次启动时 seedAccessControlDefaults 为 4 个内置主体(manager/connector/public/ingest)
随机生成 API Key 并打印到 stdout(幂等,已有 key 不覆盖)。
- handlers_mcp.callConn 内部派发改用 a.builtinKey('connector') 注入 X-API-Key,
走 DB 查到的密钥而非 env。
### 加固
- 移除固定/空 key 漏洞:seed 写入前先 UPDATE...WHERE api_key IS NULL OR api_key='',
重复启动幂等;首次启动日志里打印 4 个随机值,运维保存后可在 Access Control 页重置。
### 验证(localhost:8081 真实库,go test 全绿)
- mgr-key-2213 经纯 DB 解析回 manager(manage+L0-L4);密码登录仍可引导。
- connector 端点:无 key 401,带 DB key 200;authHint 切到 DB key 状态文案。
- public key 解析为 public(L0 only),匿名请求也回退 public,无升权。
- mgmt 端点:无 key / public key 均 401;manager key 200。
- 全部测试 green (server + ai)。
### 文档同步
- README.md / docs/README.md / docs/USAGE.md / docs/IMPORT.md /
skills/ssw-ontology-reviewer/SKILL.md / web/src/views/ConnectorView.vue /
server/CHANGELOG.md 同步去掉 .env 密钥说明,改为'首次启动日志 + Access Control 页管理'。
7.6 KiB
使用说明 · Ontology Platform
本体把外部业务/数据/知识沉淀成可查询的"对象类型 + 实例 + 关系",通过 REST/MCP 连接器让外部应用精准调取。
下面的示例使用通用占位符(项目、产品、空间、组织...),把业务换成你自己的即可。
1. 启动
./build.sh # 构建前端 + 编译后端二进制
./run.sh # 直接运行,监听 http://localhost:8081
# 停止:Ctrl+C 结束进程即可(无后台容器需清理)
首次启动(SEED_ON_START=true)会自动灌入极简种子(1 个对象类型「合作企业」+ 3 条占位实例,见 server/db.go 的 seedIfEmpty),用于开箱演示。
2. 连接器 API(只读,供外部消费)
所有连接器接口前缀 /api/v1/connector,首次启动尚未生成 connector api_key 时无需鉴权;一旦 seed 为 connector 主体写入随机密钥,所有请求须在 X-API-Key 头(或 key= 查询参数)携带该密钥(在 Access Control 页可查看/重置)。
| 方法 | 路径 | 作用 |
|---|---|---|
| GET | /connector/object-types |
列出全部对象类型及属性定义(先了解有哪些实体类别) |
| GET | /connector/objects/:type |
列出某类型的全部实例(?limit=) |
| GET | /connector/object/:type/:pk |
取单个实例详情 |
| GET | /connector/search?q= |
精准检索:按名称优先排序,支持 type/field/limit |
| GET | /connector/facets |
发现维度:返回各类型可过滤的取值 |
| POST | /connector/query |
结构化过滤:按类型+属性过滤,可 expand 展开关系 |
| GET | /connector/graph |
全量图谱(节点+边),用于可视化 |
| GET | /api/v1/mcp/manifest |
MCP 工具清单(WorkBuddy 据此注册工具) |
| POST | /api/v1/mcp |
MCP JSON-RPC 2.0 Streamable HTTP 端点 |
3. 精准查询配方
原则:先发现 → 再精确。不要直接模糊搜。
3.1 先发现有哪些可过滤值 → get_facets
curl 'http://localhost:8081/api/v1/connector/facets?type=Project'
# 返回 {"facets":{"region":["华北","华东",...], "status":["active","archived"], "priority":[...]}}
拿到真实取值后,再精确过滤,避免瞎猜字段值。
3.2 按名称精准查某个实体 → search_ontology
# 默认只匹配名称、按相关度排序
curl 'http://localhost:8081/api/v1/connector/search?q=核心项目A'
# 限定类型,更准
curl 'http://localhost:8081/api/v1/connector/search?q=数据空间&type=DataSpace'
# 全字段(名称+属性)模糊(噪杂,慎用)
curl 'http://localhost:8081/api/v1/connector/search?q=信创&field=all'
3.3 结构化过滤 → query_related
用 facets 拿到的取值做过滤,结果确定、可复现。filters 支持操作符(2026-09-05 起):
{"字段":"值"} 等值、{"字段":{"ne":"值"}} 排除、{"字段":{"in":["a","b"]}} / {"nin":[...]} 枚举、{"字段":{"contains":"子串"}}、{"字段":{"exists":true}} 非空。另支持顶层 fields:["a","b"] 裁剪返回字段:
curl -X POST 'http://localhost:8081/api/v1/connector/query' \
-H 'Content-Type: application/json' \
-d '{"type":"DataSpace","filters":{"region":"华东"}}'
# → 华东的所有数据空间
curl -X POST 'http://localhost:8081/api/v1/connector/query' \
-d '{"type":"DataSpace","filters":{"industry":"物流"},"expand":"SpaceUsesAppliance"}'
# → 物流数据空间 + 其部署的设备/服务
curl -X POST 'http://localhost:8081/api/v1/connector/query' \
-d '{"type":"DataSpace","filters":{"region":{"ne":"华东"}},"fields":["name","region"]}'
# → 非华东的数据空间,只返回 name/region 两个字段
软删除约定(2026-09-05):被删除的实例是「墓碑」,连接器/检索默认排除;管理端可用
?include_deleted=true或?only_deleted=true查看。search_ontology命中别名时自动跳转到 canonical 实例。
3.4 按角色筛选组织
curl -X POST 'http://localhost:8081/api/v1/connector/query' \
-d '{"type":"MemberOrg","filters":{"role":"合作伙伴"}}'
4. 接入 WorkBuddy / 其他应用(MCP)
连接器同时暴露一份 MCP 工具清单(GET /api/v1/mcp/manifest),WorkBuddy / Claude Code 可据此把本体注册成可调用的工具:
- 查询:
get_object_types/get_objects_by_type/get_object/search_ontology/get_facets/query_related/whoami - 知识管理:
km_list_tree/km_list_files/km_create_folder/km_upload_markdown/km_extract/km_delete - 类型管理:
create_object_type/create_link_type/update_enum - 实例写入:
create_object(默认 merge,只更新传入字段)/batch_create_objects/batch_create_links/create_link/delete_object(可 propagate 血统传播)/restore_object/get_object_history/find_duplicates
写入语义要点:
create_object默认 merge:只更新传入字段,其余保留;传null删除字段;replace=true才全量替换(响应回显被清掉的字段)- 可传
source_ts(业务源时间戳毫秒):比已有值更旧的写入会被拒绝(stale_write),旧信息不覆盖新信息 delete_object响应回显source_ref(实例来源文档);propagate=true时沿溯源把来源文档全部抽取产物一并清理- 新建时响应携带
possible_duplicates高度相似实体提示,建议改用已有 pk 或same_as归并
完整约定见 INSTANCE_GOVERNANCE.md。
接入方式:在 WorkBuddy 的 MCP 配置里指向 http://<host>:8081/api/v1/mcp,之后即可用自然语言问,例如:
"项目里华东区域的数据空间有哪些?分别用了什么设备?"
WorkBuddy 会先用 get_facets 拿到 region=华东,再 query_related 过滤并 expand 关系,返回确定答案。
5. 用 AI 动态维护本体(提交资料自动更新 / 按指令更新)
管理接口前缀 /api/v1(需 manager 主体:密码登录后 cookie 鉴权,或 X-API-Key 携带 manager 的随机密钥)。AI 摄取把一段资料自动抽取成本体增量并入库。
5.1 提交资料,自动更新(mode=auto 直接入库)
curl -X POST 'http://localhost:8081/api/v1/ai/ingest' \
-H 'Content-Type: application/json' \
-d '{"raw_text":"合作伙伴「华东数据集团」与「物流行业数据空间」达成合作,并推出数据产品「XX」用于企业估值。","mode":"auto"}'
返回会列出抽取到的对象(已自动分类、生成稳定主键并写入),并打 source='ai-ingest' 标记。
5.2 按指令更新(只抽你想要的部分)
curl -X POST 'http://localhost:8081/api/v1/ai/ingest' \
-d '{"raw_text":"...同上资料...","directive":"只提取其中的数据产品","mode":"auto"}'
directive 会约束抽取范围(如「只提取数据产品」「提取所有合作伙伴并标注区域」)。
5.3 先审后入(mode=review)
把 mode 设为 review,接口只返回 suggestion 不写库,由人工确认后再调用管理接口写入。
若配置了
AI_BASE_URL+AI_KEY+AI_MODEL(OpenAI 兼容),则走真实大模型抽取;否则用内置启发式兜底(识别「」""包裹的实体 + 就近关键词分类)。
5.4 大模型支持
- URL 含
/anthropic→ Anthropic Messages 协议(需x-api-key头) - 其他 → OpenAI Chat Completions 兼容协议(DeepSeek / 通义千问 / Ollama 等均可)
6. 管理平台界面
浏览器打开 http://localhost:8081 即前端:概览统计、本体编辑(对象类型/属性/关系/动作/函数/接口/物化/同步源)、实例 CRUD、AI 摄取、图谱可视化、连接器调试(含各端点示例与代码生成)、访问控制(主体/授权/标记/字段策略/审计日志)。