理由:管理界面已就位,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 页管理'。
150 lines
6.3 KiB
Markdown
150 lines
6.3 KiB
Markdown
# 外部数据源导入 · Ontology Platform
|
||
|
||
把外部数据源(API、文件、数据库、其他平台)导入到平台,让本体从"人工编辑"变成"实时镜像"。
|
||
|
||
平台提供两条导入路径,各有所长:
|
||
|
||
| 路径 | 适用 | 入口 |
|
||
|---|---|---|
|
||
| **平台内 AI 摄取** | 文本/少量文件/外部资源定义 | `POST /api/v1/ai/ingest` / `POST /api/v1/km/extract` |
|
||
| **外部脚本(自定义 importer)** | 大批量、异构、定时同步 | 自己写 Node/Python 脚本,upsert 到 `/api/v1/objects` |
|
||
|
||
下面重点说第二种:平台本身只提供管理 API,**导入逻辑由采用方按需编写**。
|
||
|
||
---
|
||
|
||
## 通用模式(三步)
|
||
|
||
任何外部数据源都可以按下面三步走:
|
||
|
||
```text
|
||
外部 API/数据库/文件
|
||
↓ ① 抓取 + normalize(字段映射 + 中文翻译 + 字段类型归一)
|
||
↓ ② 映射为本体对象(加前缀避免 pk 与种子冲突 + 决定 object_type)
|
||
POST /api/v1/objects (upsert by (object_type, pk))
|
||
↓ ③ 尽力匹配 → POST /api/v1/links (建关系)
|
||
```
|
||
|
||
要点:
|
||
- **抓取与翻译**用采用方已有的代码(没有就 `fetch` + JSON.parse),平台不强制抓取实现
|
||
- **upsert** 靠平台主键策略 + `source` 字段做溯源,撞 pk 时是覆盖
|
||
- **链接**按采用方业务规则建,匹配不上保留原始字段
|
||
|
||
---
|
||
|
||
## 通用模式:你自己接入任意数据源
|
||
|
||
> 平台不绑定任何特定数据源。**采用方按需编写自己的 importer**,三步不变:
|
||
|
||
1. **抓取 + normalize**:用你最熟悉的方式(fetcher / ORM / parser)
|
||
2. **字段映射**:在脚本里维护一个 `externalType → ontologyType + props` 的转换表
|
||
3. **upsert + 链接**:调 `POST /api/v1/objects`(撞 pk 自动更新)+ `POST /api/v1/links`
|
||
|
||
建议放在 `scripts/` 目录下(平台本身不提供 importer,只提供管理 API)。
|
||
|
||
### 最小骨架(Node.js 示例)
|
||
|
||
```javascript
|
||
#!/usr/bin/env node
|
||
/**
|
||
* 通用 importer 骨架:抓取 → normalize → upsert
|
||
* 替换 fetch 逻辑与映射表即可适配任意数据源
|
||
*/
|
||
const BASE = process.env.ONTO_API_BASE || 'http://localhost:8081';
|
||
const KEY = process.env.ONTO_API_KEY || ''; // 首次启动日志里打印的 manager api_key
|
||
|
||
async function req(method, p, body) {
|
||
const r = await fetch(BASE + p, {
|
||
method,
|
||
headers: { 'Content-Type': 'application/json', ...(KEY ? { 'X-API-Key': KEY } : {}) },
|
||
body: body ? JSON.stringify(body) : undefined,
|
||
});
|
||
if (!r.ok) throw new Error(`${method} ${p} failed: ${r.status} ${await r.text()}`);
|
||
return r.json();
|
||
}
|
||
|
||
// 1. 抓取
|
||
async function fetchAll() {
|
||
// 这里换成你的数据源:DB query / REST API / file parser / ...
|
||
return [];
|
||
}
|
||
|
||
// 2. 字段映射:externalItem → { type, pk, properties, link? }
|
||
function map(externalItem) {
|
||
return {
|
||
type: 'YourObjectType',
|
||
pk: 'ext_' + externalItem.id, // pk 加前缀避免冲突
|
||
properties: { name: externalItem.name }, // 按需映射字段
|
||
source: 'my-importer-2026-08', // 删除时按 source 级联
|
||
};
|
||
}
|
||
|
||
async function run() {
|
||
const items = await fetchAll();
|
||
for (const it of items) {
|
||
const o = map(it);
|
||
await req('POST', '/api/v1/objects', o);
|
||
}
|
||
console.log(`Imported ${items.length} items.`);
|
||
}
|
||
|
||
run().catch(e => { console.error(e); process.exit(1); });
|
||
```
|
||
|
||
### 关键约定
|
||
|
||
- **`pk` 加前缀**避免冲突(如 `crm_` / `wiki_` / `mkt_`)
|
||
- **`source` 字段**填本次导入的标识(如 `crm-monday-sync` / `wiki-export-2026-08`),删除时按 source 级联,`propagate=true` 时沿溯源整体清理
|
||
- **稳定映射**:每次重跑都生成**相同 pk**,upsert 走 merge(只更新传入字段,其余保留),重跑不会清掉既有字段
|
||
- **`source_ts` 增量时间戳**(推荐):填外部系统的更新时间(毫秒)。平台侧比已有值更旧的写入直接拒绝(`stale_write`),乱序到达的旧数据不会覆盖新数据;不传则不检查
|
||
- **批量导入用 `POST /api/v1/objects/batch`**(单事务,逐条 ok/fail 明细),不要逐条循环调用
|
||
- **链接建不上不硬连**:匹配不上保留原始字段作属性,后续手工补
|
||
|
||
> 写入语义完整约定(merge/null 删字段/软删除/去重提示/审计回滚)见 [INSTANCE_GOVERNANCE.md](INSTANCE_GOVERNANCE.md)。
|
||
|
||
---
|
||
|
||
## 平台内导入(更简单,无脚本)
|
||
|
||
### `POST /api/v1/ai/ingest`
|
||
|
||
粘一段文本 → AI 抽取 → 自动落库(`mode=auto`)或仅生成建议(`mode=review`)。
|
||
|
||
```bash
|
||
curl -X POST 'http://localhost:8081/api/v1/ai/ingest' \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"raw_text":"合作伙伴「XX」与「XX 行业空间」达成合作,推出数据产品「X」...","mode":"auto"}'
|
||
```
|
||
|
||
### `POST /api/v1/km/extract`
|
||
|
||
知识管理 Tab 上传文件后,批量调 AI 抽取。
|
||
|
||
详见 [docs/USAGE.md](USAGE.md) 第 5 节。
|
||
|
||
### `POST /api/v1/km/connections/:id/import`
|
||
|
||
数据连接资源:定义外部数据库/API/文件 → 一键导入本体,source=`conn:<id>`。
|
||
|
||
---
|
||
|
||
## 增量与定时同步
|
||
|
||
- 每类按外部 id 生成稳定 pk(如 `mkt_{id}`),`POST /objects` 是 upsert(按 `(object_type, pk)` 冲突更新),**默认 merge 语义**:只更新传入字段,其余保留;重跑覆盖、不重复、不丢字段
|
||
- **带 `source_ts` 做增量保护**:每条记录填外部系统的时间戳,乱序/重放的旧数据会被拒(`stale_write`);批量接口里该条标 `stale_skipped` 跳过,不影响其他条目
|
||
- 优先用 `POST /api/v1/objects/batch` 单事务批量写入(上限 500 条/次),返回逐条 `created/updated/unchanged/stale_skipped/failed` 明细
|
||
- 可做成定时任务(如每日一次)调用本脚本,外部新增的数据自动同步进本体,连接器与 MCP 实时可读
|
||
- **删除时按 source 级联**:`DELETE /api/v1/km/files?source=mkt_*` 会一并清掉 objects + links + 关联记录;单实例 `DELETE /objects/:type/:pk?propagate=true` 也可沿溯源整体遗忘
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
**Q:导入撞 pk 时 source 字段不更新?**
|
||
A:升级到 2026-08-24 后已修复。`ON CONFLICT ... DO UPDATE SET source=COALESCE(NULLIF(EXCLUDED.source,''), objects.source)` 是统一语义(必须加表名限定 `objects.source`)。
|
||
|
||
**Q:导入后 AI 摄取为啥查不到?**
|
||
A:检查 `source` 字段是否正确写入,管理接口 `/api/v1/objects?type=xxx&source=xxx` 可按 source 过滤。
|
||
|
||
**Q:链接建不上?**
|
||
A:先确认目标对象存在(`get_objects_by_type` 或 `search_ontology`);链接是两端具体对象的关系,任意一端缺失都建不上去。 |