diff --git a/docs/superpowers/plans/2026-10-17-multi-ontology-tenancy-design.md b/docs/superpowers/plans/2026-10-17-multi-ontology-tenancy-design.md new file mode 100644 index 0000000..45712a0 --- /dev/null +++ b/docs/superpowers/plans/2026-10-17-multi-ontology-tenancy-design.md @@ -0,0 +1,269 @@ +# 多本体 / 多租户设计 + +> 目标:一套部署跑若干个彼此隔离的本体,每个租户一套完整 schema。 +> 生成时间:2026-10-17。上游讨论:2026-09-08 会话提出的「动态切 schema 的第二个用法:多本体」。 +> 状态:设计已确认,待实施。 + +## TL;DR + +选**多本体(每租户一整套 schema)**,不是行级 `tenant_id`,也不只是分级/域。 + +- 隔离层:PostgreSQL schema,请求级 `SET LOCAL search_path` 切换,复用现有 `snapshot_router.go` 的 `dbRunner`/`txPool` 机制 +- 控制面:租户注册表 + 管理页留在**默认租户 `public`**;租户 schema 只装业务本体 +- 路由:主体与租户 **1:1**,请求不带 `ontology_id` 时隐式落到主体的「家租户」 +- 结构同步:`migrate()` 拆成带版本号的迁移段,启动时按 `schema_version` 给落后的租户自动补跑 +- 备份:每租户各备各的,快照层与租户层在同一条 `search_path` 上叠加 +- 前端:只做「租户生死」管理页,不做切换器,不做跨租户检索 + +**历史数据零迁移**:现有 3000+ 实例原地留在 `public`,`public` 就是默认租户。 + +## 1. 数据模型 + +### 1.1 ontologies(控制面表,只存在于默认租户) + +```sql +CREATE TABLE IF NOT EXISTS ontologies ( + id TEXT PRIMARY KEY, -- 'alpha',同时是 schema 名后缀 + schema_name TEXT NOT NULL, -- 'ontology_alpha';默认租户为 'public' + display_name TEXT NOT NULL, + home_principal TEXT NOT NULL, -- 家主体(1:1),指向 principals.name + schema_version INT NOT NULL DEFAULT 0, -- 该租户已应用到的迁移版本 + status TEXT NOT NULL DEFAULT 'active', -- active | dropped + created_at TIMESTAMPTZ NOT NULL DEFAULT now(), + created_by TEXT NOT NULL DEFAULT '', + dropped_at TIMESTAMPTZ +); +CREATE INDEX IF NOT EXISTS idx_ontologies_home ON ontologies(home_principal); +CREATE INDEX IF NOT EXISTS idx_ontologies_status ON ontologies(status); +``` + +约束: + +- `id` 只允许 `[a-z0-9_-]{1,32}`,全小写——它会拼进 schema 名,必须挡住注入 +- `schema_name` 由 `id` 派生(`public` 除外),不单独自由输入 +- **`public` 自己建成一条记录**(`id='public'`、`schema_name='public'`、`home_principal='manager'`),保证「家租户指向 public」和「家租户指向 alpha」走同一套逻辑,不留双分支 +- 默认租户记录**不允许删除或改家主体** + +### 1.2 principals 加一列 + +```sql +ALTER TABLE principals ADD COLUMN IF NOT EXISTS home_ontology TEXT NOT NULL DEFAULT 'public'; +``` + +1:1 之后不再需要 ACL 名单表——「谁能进这个租户」就是这一列。上次讨论里的 `principals_allowed JSONB` 方案作废。 + +### 1.3 每个租户 schema 内的 schema_meta + +```sql +CREATE TABLE IF NOT EXISTS schema_meta ( + key TEXT PRIMARY KEY, + value TEXT NOT NULL +); +-- key='schema_version' +``` + +与 `public` 里那张 append-only 的 `schema_versions`(审计流水,与 `ontology_audit_log` 同点挂钩)**不是一回事**,后者不动。前者是「这个租户的结构到第几段了」,后者是「变更历史」,跨租户共享一份全局流水。 + +## 2. 请求路由 + +### 2.1 入口 + +``` +HTTP: X-Ontology-Id: alpha (REST / 管理页 / MCP 透传) +MCP: arguments.ontology_id: "alpha" (可选;不传 = 主体家租户) +``` + +两条都支持,MCP 参数在 `callConn`/`mcpCall` 里翻译成内层请求的 `X-Ontology-Id` 头——和现有 `X-Snapshot-Id` 透传是同一处、同一写法。 + +### 2.2 ontologyMiddleware + +挂在 `/api/v1` 组最前,与 `snapshotMiddleware` 并列: + +```go +api.Use(a.snapshotMiddleware(), a.ontologyMiddleware()) +``` + +五步: + +1. **定租户**:无 `X-Ontology-Id` 头 → 取主体的 `home_ontology`(默认 `public`);有头 → 用头里的值 +2. **定主体**:调 `a.principalFromRequest(c)`(既有单一入口,复用不违背设计) +3. **校验**:查 `ontologies`(**用真池查,不能被切 schema 影响**) + - 无记录 / `status='dropped'` → 404 + - `home_principal != 调用主体` 且调用主体不是 `manager` → 403 + - `manager` 可进任意 active 租户(运维/评审需要) +4. **切**:`BeginTx` → `SET LOCAL search_path TO , public` → tx 挂进请求 context(见 §3) +5. **收尾**:`defer` 里 `c.IsAborted()` → rollback,否则 commit + +### 2.3 中间件顺序的坑 + +`principalFromRequest` 现在由 `loginRequired`/`managerAuth` 调用,而 `ontologyMiddleware` 必须挂在它们**之前**(否则 managerAuth 查库就已经切到错租户了)。解法:`ontologyMiddleware` 自己调一次 `principalFromRequest`。 + +这之所以安全:它内部用 `a.pool` 解析 api_key,而此时请求 context 里**还没有 tx**(第 4 步才挂),`ctxPool` 会落到真池 → 查的是 `public.principals` → 正确。 + +### 2.4 MCP 侧 + +`callConn`(`handlers_mcp.go:1265`)已透传 `X-API-Key` 和 session cookie,加两行: + +```go +if v := c.GetHeader("X-Ontology-Id"); v != "" { + req.Header.Set("X-Ontology-Id", v) +} +``` + +工具参数表给所有工具加可选 `ontology_id`;不传即主体家租户——**现有 MCP 客户端一行配置都不用改**。 + +新增 4 个管理工具(manager 限定):`list_ontologies` / `create_ontology` / `set_home_ontology` / `delete_ontology`。 + +## 3. 并发安全(前置项,必须先做) + +### 3.1 现状缺陷 + +`snapshot_router.go` 的 `snapshotMiddleware` 这样切库: + +```go +origDB := a.pool +a.pool = &txPool{tx: tx} // 改 app 结构体上的共享字段,全程无锁 +defer func() { a.pool = origDB }() +``` + +两个并发请求:A 换成 `txPoolA`,B 又换成 `txPoolB`,A 的 handler 随后读 `a.pool` 拿到的是 **B 的事务**——跨请求串味。快照模式因为用得少、且全只读,撞上了不易发现;**多租户是每个请求都走这条路,必然踩**。 + +### 3.2 修法:ctxPool(零 handler 改动) + +启动时**一次性**把 `a.pool` 设成永久的 `ctxPool`,此后永不改动: + +```go +type ctxPool struct{ base *pgxpool.Pool } + +func (p *ctxPool) Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error) { + if tx, ok := ctx.Value(txKey{}).(pgx.Tx); ok { return tx.Query(ctx, sql, args...) } + return p.base.Query(ctx, sql, args...) +} +// QueryRow / Exec / Begin / BeginTx / Close 同构 +``` + +中间件把 tx 塞进请求 context: + +```go +c.Request = c.Request.WithContext(context.WithValue(c.Request.Context(), txKey{}, tx)) +``` + +业务代码仍写 `a.pool.Query(c, sql, ...)`——`c` 是 `gin.Context`,实现 `context.Context`,其 `Value()` 会代理到请求 context → 自动命中事务。**几百个 handler 一个都不用改**,且天然并发安全。 + +`dbRunner` 接口保留(`txPool` 降级为内部类型或直接删除,由 §3.3 决定)。 + +### 3.3 snapshotMiddleware 一并改造 + +改造后快照中间件不再替换 `a.pool`,同样走 context 挂载。两个中间件叠加时: + +```go +SET LOCAL search_path TO backups_, , public +``` + +一条语句搞定,顺序即优先级。 + +## 4. 迁移分段 + +### 4.1 现状 + +`migrate(ctx, p dbExec)`(`db.go:37`)是一整段 DDL 字符串 + 若干后置修复(`backfillMissingIRI`、seed),硬编码跑在 `public` 上。 + +### 4.2 目标 + +```go +type migration struct { + Version int + Name string + SQL string // 或 func(ctx context.Context, p dbExec) error +} + +var migrations = []migration{ + {Version: 1, Name: "schema_meta", SQL: `CREATE TABLE IF NOT EXISTS schema_meta(...)`}, + {Version: 2, Name: "core_objects", SQL: `...object_types/properties/objects/links...`}, + // …按现有 DDL 的自然边界切分,每段内部保持幂等 +} + +func (a *app) migrateSchema(ctx context.Context, db dbExec, upTo int) error +``` + +`migrate(ctx, p)` 保留为「跑全部段到 public」的薄封装,调用点不变。 + +### 4.3 只对默认租户执行的部分 + +`backfillMissingIRI` 和 `seedIfEmpty` 是**存量修复/演示种子**,不能对每个新租户跑: + +- `backfillMissingIRI` → 迁移段的一种,只对已有数据的 schema 有意义 +- `seedIfEmpty`(「合作企业」示例)→ 迁到 `initDB` 里对 `public` 单独调用 + +### 4.4 启动时自动补跑 + +```go +func (a *app) syncTenantSchemas(ctx context.Context) error { + // 1. 从 public.ontologies 列出所有 active 租户 + // 2. 对每个租户读 schema_meta 的 schema_version + // 3. version < len(migrations) 的,补跑缺失段(逐租户独立事务) + // 4. 单个租户失败 → 记日志 + 该租户标记 degraded,继续处理其他 +} +``` + +在 `initDB` 之后、`seedIfEmpty` 之后调用。失败**不阻断启动**——一个坏租户不该拖垮整台服务。 + +### 4.5 建租户 + +``` +create_ontology(id, display_name, home_principal) + 1. 校验 id 词法 + 未重名 + 2. CREATE SCHEMA ontology_ + 3. 开事务 SET LOCAL search_path TO ontology_, public → migrateSchema(upTo=len) + 4. 事务提交后写 ontologies 记录 +``` + +任一步失败 → `DROP SCHEMA` 回滚,不留半成品。 + +## 5. 备份 / 快照 + +### 5.1 语义 + +`backup_create` 作用于**当前租户**:只把该租户 schema 的全部表复制到 `backups_`。默认租户(public)行为不变。 + +### 5.2 硬约束(会静默出错,必须防) + +快照 schema 必须**完整包含源租户的全部表**。否则 `search_path TO backups_x, tenant_y, public` 在缺表时会**漏到下一级**,读出「一部分快照 + 一部分活库」的混合数据,且不报错。 + +在建快照时断言:源租户表数 == 快照表数,不等则拒绝创建并报错。 + +### 5.3 快照元数据 + +`backup_inspect` / `backup_list` 增加 `source_ontology` 字段(从 `backups.snapshot_runs` 读)。`switch_via` 提示文案补充 `X-Ontology-Id`。 + +### 5.4 reviewkit 工具链 + +`server/reviewkit/` 内嵌二进制 + reviewkit.go 要能接受并透传 `ontology_id`,否则对接核对会在默认租户上跑,结论失真。 + +## 6. 管理页(前端) + +新增「多租户」tab,**只管生死**: + +- 列表:名称 / 家主体 / 实例数 / 创建时间 / 结构版本 / 状态 +- 操作:新建、改家主体、删除 +- 实例数:管理 handler 里对每个 active 租户 schema 单独 `count`(租户数量级小,可接受;不做跨租户联合查询) + +删除租户:`status='dropped'` 软标记 + 二次确认;`DROP SCHEMA` 单独一步(可保留 dropped 状态的 schema 数据,人工确认后再物理清)。参考现有 `objects.deleted` 的软删除做法。 + +## 7. 明确不做 + +- 跨租户联合查询 / 全景检索(跨 N 个 schema 联合分页,成本高且易错) +- 前端全局租户切换器(管理页之外,前端所有请求不带 `ontology_id`,各管各的) +- 行级 `tenant_id`(选了 schema-per-tenant 就没有这条路) +- 租户级对象类型模板/市场 +- 跨租户物化、跨租户 AI 摄取 + +## 8. 风险与未决 + +| 项 | 说明 | 处置 | +|---|---|---| +| 迁移分段回归 | 现有 DDL 切段时切错边界,老租户结构不完整 | 切完在默认租户上验证表/列与切段前逐一对齐 | +| 串味 | §3.2 的 `ctxPool` 是所有后续工作的前置 | 单独一个 commit,先跑并发集成测试验证 | +| 快照表数断言 | §5.2 | 建快照时硬校验,不等即失败 | +| **`X-Principal` 头越权(现存洞,多租户会放大)** | `principalFromRequest`(`access_control.go:83`)把 `X-Principal` 头作为最高优先级且**完全无鉴权**地决定主体。任何请求 `X-Principal: manager` 即取得 manager 身份。多租户下再配一个 `X-Ontology-Id`,即可无凭据进入任意租户 | **多租户上线前必须先封**:外部入口一律不接受 `X-Principal` 头,该头只允许来自进程内自调用(`callHandler`/`mcpCall`,`handlers_mcp.go:1219/1246`)。建议同时清理进程内自调用改为在 context 里带主体 | +| 租户数量 | 每租户一整套 schema,25 张表 | 暂不设上限;上千租户时应评估「行级」或混合方案 |