docs(design): 多本体/多租户设计(每租户一套 schema + 1:1 隐式路由)
- 选型:多本体(schema-per-tenant),非行级 tenant_id - 控制面(ontologies 表 + 管理页)留在默认租户 public,租户 schema 只装业务本体 - 主体↔租户 1:1,不带 ontology_id 时隐式落到家租户,替换原 ACL 名单方案 - 前置项:ctxPool 修 a.pool 全局替换的并发串味(零 handler 改动) - migrate() 拆带版本号迁移段,启动按 schema_version 自动补跑 - 备份按租户切,snapshot_path 与 tenant_path 同句叠加;补表数完整性硬约束 - 记录现存越权洞:X-Principal 头无鉴权,多租户下会放大为跨租户洞 Co-Authored-By: Claude <[email protected]>
This commit is contained in:
1 parent
7d4a0c26e3
commit
1e0807ea7a
1 file changed
+269
@@ -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 <tenant>, 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_<id>, <tenant>, 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_<id>
|
||||
3. 开事务 SET LOCAL search_path TO ontology_<id>, public → migrateSchema(upTo=len)
|
||||
4. 事务提交后写 ontologies 记录
|
||||
```
|
||||
|
||||
任一步失败 → `DROP SCHEMA` 回滚,不留半成品。
|
||||
|
||||
## 5. 备份 / 快照
|
||||
|
||||
### 5.1 语义
|
||||
|
||||
`backup_create` 作用于**当前租户**:只把该租户 schema 的全部表复制到 `backups_<id>`。默认租户(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 张表 | 暂不设上限;上千租户时应评估「行级」或混合方案 |
|
||||
Reference in new issue
Block a user