理由:管理界面已就位,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 页管理'。
6.3 KiB
外部数据源导入 · Ontology Platform
把外部数据源(API、文件、数据库、其他平台)导入到平台,让本体从"人工编辑"变成"实时镜像"。
平台提供两条导入路径,各有所长:
| 路径 | 适用 | 入口 |
|---|---|---|
| 平台内 AI 摄取 | 文本/少量文件/外部资源定义 | POST /api/v1/ai/ingest / POST /api/v1/km/extract |
| 外部脚本(自定义 importer) | 大批量、异构、定时同步 | 自己写 Node/Python 脚本,upsert 到 /api/v1/objects |
下面重点说第二种:平台本身只提供管理 API,导入逻辑由采用方按需编写。
通用模式(三步)
任何外部数据源都可以按下面三步走:
外部 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,三步不变:
- 抓取 + normalize:用你最熟悉的方式(fetcher / ORM / parser)
- 字段映射:在脚本里维护一个
externalType → ontologyType + props的转换表 - upsert + 链接:调
POST /api/v1/objects(撞 pk 自动更新)+POST /api/v1/links
建议放在 scripts/ 目录下(平台本身不提供 importer,只提供管理 API)。
最小骨架(Node.js 示例)
#!/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。
平台内导入(更简单,无脚本)
POST /api/v1/ai/ingest
粘一段文本 → AI 抽取 → 自动落库(mode=auto)或仅生成建议(mode=review)。
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 第 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);链接是两端具体对象的关系,任意一端缺失都建不上去。