RushWind Admin --- 多租户行级隔离与租户回收站:Viewer 三态、repo_shell! 与全域级联清除
本文回答一个问题:一个列表查询怎么做到「想查出别家租户的行都漏不掉」?租户被删之后数据去哪了、恢复时凭什么不撞名、彻底清除时怎么不留下孤儿行?
多租户系统最怕的不是没有隔离,而是"靠每个开发者记得加租户条件"的隔离------新人一个 find_by_id 没带谓词,别家的数据就顺着接口流出去,而且没有人知道。RushWind Admin 把隔离做成两层结构:HTTP 门负责"这个租户能不能用这个接口",数据层谓词负责"这个查询能不能看见那行数据"。删除则更进一步------delete 不是删除,是停车。本文把这两层和一条回收站链路全部拆开。
一、两道闸:HTTP 门与数据层谓词
先看官方教程里对这套分层的定义(docs/tutorial/06):
两层都过才有数据。只懂其中一层就会把"接口 403"和"列表为空"混为一谈:接口 403 是 HTTP 闸拒绝(租户没这个模块的套餐),列表为空是数据层谓词把别家的行滤掉了------同一次请求只撞其一。
这句话是全篇的地图。排障时先分清撞的是哪道闸,再去对应章节找机制。
二、HTTP 门:租户阶段夹在认证与授权之间
门在 wire 上的顺序是固定的:认证 (JWT RS256 验签 + Redis 会话检查,一次调用完成,401)→ 租户检查 (403)→ 授权评估 (403)→ 放行注入 claims 。租户阶段是中间那道,它对每个租户请求跑一串有明确先后顺序的失败语义,代码里的自述(backend/apps/admin/src/admin/authorizer.rs):
rust
/// The tenant access checks behind the gate's tenant stage. The
/// reference semantics, in order: unknown tenant → `access denied`;
/// status off `ON` → `tenant is not active`; expired under a
/// `READONLY` plan → writes denied (`tenant is read-only due to
/// expiry`); the route unregistered in `sys_apis` → fail-closed
/// `access denied`; unclassified business module → `module not
/// allowed`; a tenant without a plan → `no subscription plan`; a plan
/// with no whitelisted module → `tenant plan has no whitelisted
/// modules`; a module outside the whitelist → `module not allowed`.
逐条翻译:租户不存在拒绝、停用拒绝、到期只读(写拒读通) 、然后是这条链上最有性格的一条------fail-closed 的接口表校验:
rust
// backend/apps/admin/src/admin/authorizer.rs
// 3. The route's business module; an unregistered route cannot
// be classified and fails closed.
let api = sys_apis::Entity::find()
.filter(
Condition::all()
.add(sys_apis::Column::Path.eq(path))
.add(sys_apis::Column::Method.eq(method.to_uppercase())),
)
.one(db)
.await
.map_err(|_| denied())?
.ok_or_else(denied)?;
let module = api.business_module.clone().unwrap_or_default();
if module.is_empty() || module == "MODULE_UNSPECIFIED" {
return Err("module not allowed".to_string());
}
按 (路径模板, 方法) 查接口表,查不到即拒绝------不是默认放行。新加的路由忘了登记,租户侧一律 403,生产环境不会替你兜底。fail-closed 的取向要大声说出来:开放系统的默认是"没禁就允许",多租户系统的默认必须是"没准就拒绝"。
顺带一提,门前的免鉴权白名单同样是钉死的:8 个端点(登录、验证码、刷新令牌、MFA 挑战等)在 auth_free.rs 里逐一列出,守卫测试双向校验------公开路由集合必须恰好等于白名单,多一个少一个都不过。
三、Viewer:全仓唯一的租户判定点
数据层的隔离只有一个判定点。Viewer 是一个三态的小结构,每个仓储方法都收它,查询谓词由它派生:
rust
// backend/apps/admin/src/admin/data/scope.rs
#[derive(Clone, Debug, Copy, PartialEq, Eq)]
pub enum ViewerKind {
/// No credentials (public routes).
Noop,
/// A verified user context: platform when tenant 0.
User,
/// Bypasses tenancy (seeds, internal jobs).
System,
}
pub fn tenant_scope(&self) -> Option<i64> {
match self.kind {
ViewerKind::User if self.tenant_id > 0 => Some(self.tenant_id),
_ => None,
}
}
/// Create stamping: tenant viewers force their tenant onto new rows.
pub fn stamp_tenant(&self, requested: Option<i64>) -> Option<i64> {
match self.kind {
ViewerKind::User if self.tenant_id > 0 => Some(self.tenant_id),
_ => requested.or(Some(0)),
}
}
三态的语义边界:
- 租户视图 (
User且tid > 0):每次查询/更新/删除都约束tenant_id = tid,建行强制盖章,跨租户写入被拒; - 平台视图 (
User且tid == 0):不加租户谓词,所有租户的行全见; - 系统视图 (
System):启动种子、内部作业等无凭据场景,旁路全部租户谓词。
关键设计是**"只有一处"**:文件头自述它是 "the standalone tenancy rule. there is exactly one place that decides tenancy filtering"。租户判断不散落在各服务里,也就不存在"某个服务忘了判"这一类 bug------判断只可能写对一次,然后被所有仓储复用。
四、repo_shell!:谓词长在骨架上
判定点有了,怎么保证每个仓储方法都用它?答案是骨架宏:repo_shell! 生成的仓储结构自带谓词,业务代码拿到的查询天生带着隔离条件。
租户臂 ------谓词是 tenant_id + 软删两连:
rust
// backend/apps/admin/src/admin/data/repos/mod.rs
/// The tenancy predicate: tenant viewers are constrained,
/// platform/system viewers see all rows. Soft-deleted rows are
/// invisible on every listing face ...
fn condition(&self) -> sea_orm::Condition {
use sea_orm::ColumnTrait as _;
match self.viewer.tenant_scope() {
Some(tid) => sea_orm::Condition::all()
.add($entity::Column::TenantId.eq(tid))
.add($entity::Column::DeletedAt.is_null()),
None => sea_orm::Condition::all()
.add($entity::Column::DeletedAt.is_null()),
}
}
全局臂 给平台级表(无租户谓词,只铺软删);名词臂 在全局臂之上追加 get_by_id------查不到或已软删,一律 404。
一个值得驻足的细节:宏故意没有"租户名词臂" 。文件头的原话:"There is deliberately no tenant noun arm: a tenant-scoped get/delete must carry the viewer predicate, and those stay hand-written beside the invocation." 租户表的按 id 取行全部手写,因为它们必须显式携带 viewer 谓词------生成一个"看起来方便"的裸 find_by_id 正是要避免的事。手写的样子(BiDashboardRepo::find_scoped):
rust
// backend/apps/admin/src/admin/data/repos/bi_dashboard.rs
/// The scoped row lookup --- tenant viewers see own-tenant rows only,
/// platform/system viewers any named row.
pub async fn find_scoped(&self, id: i64) -> Result<Option<entity::Model>, StatusError> {
let mut query = entity::Entity::find_by_id(id).filter(entity::Column::DeletedAt.is_null());
if let Some(tid) = self.viewer.tenant_scope() {
query = query.filter(entity::Column::TenantId.eq(tid));
}
query.one(self.db).await.map_err(db_err)
}
写路径同构。create 的租户字段根本不读请求体,一律服务端盖章:
rust
// backend/apps/admin/src/admin/data/repos/user.rs
let tenant_id = self.viewer.stamp_tenant(None);
users::ActiveModel {
tenant_id: Set(tenant_id),
...
update / delete 的第一跳走 find_scoped------谓词叠在 find_by_id 上,别家的行、已软删的行,在"取行"这一步就 404。教程里把这写成一条陷阱清单:
服务里绕开仓储直接
Entity::find_by_id(id)是唯一能造出越权读的写法------骨架方法全带谓词,裸查全不带。
隔离的完整闭环由此成形:读有骨架谓词、写有强制盖章、取行有作用域检查,唯一能绕过的是"明知道规则还要绕"------而那是代码审查的问题,不再是机制的问题。
五、X-Tenant-Id:平台管理员的替身通道
平台管理员(tid = 0)经常需要"进入"某个租户排查问题。这条通道做在门里,而不做在业务层:
rust
// backend/crates/auth/src/lib.rs
// 代租户操作(`X-Tenant-Id`):平台管理员可携带该头把本请求的生效
// 租户切到所选租户------门对该租户跑完租户阶段(存在/启用/到期/套餐
// 白名单,与租户成员同一标准),随后把 claims 的 tid 覆写为生效租户:
// 下游 Viewer 的租户视图、建行的租户归属、/me 归属全部按所选租户行事,
// 而 token 未动------审计里的 uid/tid 仍是真实操作者(平台侧)。头缺失
// 即平台全域视图(现状);租户成员携带该头一律忽略(其租户由 token
// 决定);非平台管理员(tid=0 但无 platform:admin 角色)同样忽略。
let impersonated = if token_tenant_id == 0 && is_platform_admin {
parse_impersonated_tenant(
req.headers().get("x-tenant-id").and_then(|v| v.to_str().ok()),
)
} else {
None
};
let tenant_id = impersonated.unwrap_or(token_tenant_id);
三个值得抄走的决策:
- 替身也要过同一道租户阶段------平台管理员带 X-Tenant-Id 进入租户,走的检查与租户成员完全一致(存在/启用/到期/套餐白名单),"管理员"不是绕过检查的特权;
- token 不动,claims 覆写------生效租户只活在这一次请求里,签发的 JWT 保持原样;
- 审计记真人 ------下游一切按替身租户行事,但审计日志里的操作者仍是平台侧真实账号。教程里的那句:"审计答'谁干的',业务行归属答'给谁干的',两个问题两个来源。"
解析端从严:垃圾值不得变成另一个身份。"42"、" 7 " 生效;"0"、"-3"、"abc"、"1.5"、空串、缺失头全部不生效------单测逐值钉死。
六、租户回收站:delete 是停车,不是删除
租户删除走的不是 DELETE。删除动作把租户停车:级联清理 + 状态 OFF + 记下"谁停的":
rust
// backend/apps/admin/src/admin/services/tenant.rs
// Cleanup semantics ride along: the tenants themselves are parked,
// not deleted (module Delete → cleanup + OFF). deleted_by stamps the
// operator so the recycle-bin face can show who parked it.
let payload = operator_of(&ctx)?;
self.cleanup_rows(row.id).await?;
let mut a: crate::admin::data::sys_tenants::ActiveModel = row.into();
a.status = Set(Some("OFF".into()));
a.deleted_by = Set(Some(payload.user_id));
a.deleted_at = Set(Some(crate::admin::data::now()));
a.update(&self.state.db).await.map_err(db_err)?;
回收站三个 RPC,全部过平台管理员闸。
列表 :停车行按删除时间降序。在营面读 deleted_at IS NULL,回收站读 is_not_null------同一列两副面孔:
rust
// backend/apps/admin/src/admin/data/repos/tenant.rs
// 回收站:停车行(deleted_at 非空),删除时间降序
.filter(tenants::Column::DeletedAt.is_not_null())
.order_by_desc(tenants::Column::DeletedAt)
教程对此的表述:"is_not_null 与在营面的 is_null 是同一列的两副面孔,互不可见;分页走同一条 fetch_paged 管线。"
恢复 :先把"在营域"查重做完再动手------code 或 name 已被在营租户占用即拒绝;恢复成功也只是清掉盖戳、状态回 ON。文档诚实写明:恢复出来的是空壳------关联在删除时已清理,平台管理员恢复后需另行补建管理员。
rust
// backend/apps/admin/src/admin/services/tenant.rs
// alive 域查重:code/name 被在营租户占用即拒绝(与 create 同文案)。
if !row.code.is_empty() && repo.find_by_code(&row.code).await?.is_some() {
return Err(status_error("BAD_REQUEST", "tenant already exists"));
}
if !row.name.is_empty() && repo.find_by_name(&row.name).await?.is_some() {
return Err(status_error("BAD_REQUEST", "tenant already exists"));
}
let mut a: crate::data::sys_tenants::ActiveModel = row.into();
a.status = Set(Some("ON".into()));
a.deleted_at = Set(None);
a.deleted_by = Set(None);
彻底清除 :再跑一遍级联清扫,然后物理删除。级联是一张 wipe! 宏展开的清单------40 张表逐一按 tenant_id 清除,含用户角色绑定、部门、角色、字典、审计表,以及 AI 提供商、BI 仪表盘、打印模板这些容易漏掉的跨域残余:
rust
// backend/apps/admin/src/admin/services/tenant.rs
macro_rules! wipe {
($($entity:ident)::+) => {
$($entity)::+::Entity::delete_many()
.filter($($entity)::+::Column::TenantId.eq(tenant_id))
.exec(&self.state.db)
.await
.map_err(db_err)?;
};
}
wipe!(sys_user_roles);
// ......共 40 张表,含 6 张审计表收尾
审计层为回收站单设了动词------restore / purge 不落 OTHER:
rust
// backend/apps/admin/src/admin/audit.rs
// 回收站两动词:restore/purge 不落 OTHER。
"RestoreTenant" => "RESTORE",
"PurgeTenant" => "PURGE",
审计动词的颗粒度是排障效率的下限。RESTORE 和 PURGE 在日志里各自成行,"谁在什么时候恢复了哪个租户、谁彻底清掉了哪个租户"是一行查询的事;落成 OTHER 的日志排障时只能靠猜。
七、机制 × 关键决策 × 失败模式
| 机制 | 关键决策 | 失败模式(若无此决策) |
|---|---|---|
| 两道闸分层 | HTTP 门管接口资格,数据层管行可见性 | "接口 403"与"列表为空"混为一谈,排障无从下手 |
| 接口表 fail-closed | 未注册的 (path, method) 一律拒绝 | 新路由默认放行,租户越权访问静默成型 |
| Viewer 三态单点 | 全仓只有一个租户判定处 | 各服务各自判断,"某个服务忘了判"成整类 bug |
| repo_shell! 骨架谓词 | 租户臂/全局臂/名词臂自带谓词;无租户名词臂是故意的 | 裸 find_by_id 遍地开花,越权读只靠 review 拦 |
| 写路径盖章 | create 不读请求体租户字段;update/delete 首跳 find_scoped | 伪造 tenant_id 建行;跨租户 UPDATE/DELETE 落库 |
| X-Tenant-Id 替身 | 同一租户阶段、token 不动、审计记真人 | 管理员通道绕过检查;审计丢失真实操作者 |
| 回收站停车 | delete 级联 + OFF + deleted_by;恢复前 alive 域查重 | 误删租户不可逆;恢复后 code/name 撞车 |
| purge 全域级联 | 40 表清单含跨域残余(AI/BI/打印) | 孤儿行挂在别家表里,泄漏已删租户数据 |
多租户隔离的成熟度,不看宣传页上的"支持多租户",看三件事:判定点是不是只有一个、绕过骨架是不是比走骨架更难、误删之后还有没有退路。RushWind Admin 把第一件做成一个 85 行的文件,第二件做成一个故意少一条臂的宏,第三件做成一座回收站------机制的边界画在哪里,事故的边界就在哪里。
系列文章: