Files
ssw-ontology/docs/IMPORT.md
T
admin d938462bd6 refactor(access): 完全移除 .env 显式密钥,密钥统一由 principals 表管理
理由:管理界面已就位,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 页管理'。
2026-09-07 15:29:20 +08:00

150 lines
6.3 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.
# 外部数据源导入 · 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`);链接是两端具体对象的关系,任意一端缺失都建不上去。