架构与系统设计 / 系统课时
租户状态联动
租户状态联动
本课把租户停用、过期和冻结状态接入登录与请求处理,确保新用户无法进入、存量令牌也不能继续访问,并通过统一状态判定避免不同服务各自解释租户状态。
学习目标
- 建立租户状态、有效期和冻结信息的统一判定规则
- 在登录阶段与每次请求阶段执行不同强度的校验
- 实现状态变更后的缓存失效和存量会话收敛
可用性规则与双阶段校验
租户是否可访问不能只看一个 status 字段。完整判断通常至少包含启停状态、订阅到期时间、冻结状态和删除标记,并且要明确各状态的优先级。
推荐按“已删除 → 已停用 → 已冻结 → 已过期 → 正常”的顺序判定。前面的状态一旦命中就立即返回,避免同一租户同时满足多个条件时出现不同错误码。
可以将最终结果归一为 ACTIVE、DISABLED、FROZEN、EXPIRED 四类。认证服务和业务服务只依赖这个归一结果,不直接拼接数据库条件。
登录与请求双阶段校验
登录阶段负责阻止新会话创建。密码、验证码或第三方身份验证成功后,在签发令牌前查询租户状态;租户不可用时,不创建 Redis 会话,也不签发访问令牌。
请求阶段负责处理状态变更后的存量令牌。即使令牌签发时租户正常,也必须在请求进入业务逻辑前再次确认租户仍可用,否则租户被停用后,旧令牌会一直工作到自然过期。

双阶段校验不能互相替代:只校验登录会遗漏存量令牌,只校验请求则会创建无意义会话并增加后续清理成本。
状态判定服务实现
下面是片段示例,依赖项目已有的租户仓储、统一错误码和时钟配置。把时间比较集中在一个服务中,可避免不同节点因时区或边界规则不同而产生结果偏差。
@Service
public class TenantAvailabilityService {
private final TenantRepository tenantRepository;
private final Clock clock;
public TenantAvailabilityService(
TenantRepository tenantRepository,
Clock clock) {
this.tenantRepository = tenantRepository;
this.clock = clock;
}
public TenantAccessStatus evaluate(Long tenantId) {
Tenant tenant = tenantRepository.findById(tenantId)
.orElseThrow(() -> new AuthException("TENANT_NOT_FOUND"));
if (tenant.isDeleted() || !tenant.isEnabled()) {
return TenantAccessStatus.DISABLED;
}
if (tenant.isFrozen()) {
return TenantAccessStatus.FROZEN;
}
Instant now = Instant.now(clock);
// 到期时间等于当前时间时视为已过期,避免边界时刻继续放行。
if (tenant.getExpireAt() != null
&& !tenant.getExpireAt().isAfter(now)) {
return TenantAccessStatus.EXPIRED;
}
return TenantAccessStatus.ACTIVE;
}
public void checkAccessible(Long tenantId) {
TenantAccessStatus status = evaluate(tenantId);
if (status != TenantAccessStatus.ACTIVE) {
throw new AuthException("TENANT_" + status.name());
}
}
}生效行为:登录服务在签发令牌前调用 checkAccessible;认证过滤器从令牌中取出 tenantId 后再次调用。状态异常时应在进入控制器前终止请求。
使用停用租户的账号尝试登录,可通过以下请求验证。实际端口、账号和密码按环境替换。
curl -i -X POST "http://localhost:<PORT>/api/auth/login" -H "Content-Type: application/json" -d '{"tenantCode":"demo","username":"alice","password":"<PASSWORD>"}'预期结果
HTTP/1.1 403 Forbidden
{"code":"TENANT_DISABLED","message":"租户已停用","data":null}如果租户在用户登录后被停用,继续携带旧访问令牌请求业务接口,也应得到同样的租户状态错误,而不是继续返回业务数据。
缓存、边界与验收
每次请求都直接查数据库会增加认证链路延迟,因此可以缓存租户归一状态,例如键 tenant:access:<tenantId>,并设置较短过期时间。缓存值只保存归一结果和状态版本,不缓存复杂租户对象。
租户状态发生变更时,应先提交数据库事务,再删除或更新状态缓存,同时发布 TenantStatusChanged 事件。认证服务收到事件后,可按租户索引批量删除会话,或递增租户级 tokenVersion,让旧令牌在下一次请求中立即失效。
仅依赖缓存自然过期会形成安全窗口。对停用、冻结这类高风险操作,应主动失效缓存并收敛会话;对套餐到期这种可预测事件,还应使用统一时钟判断,不能只依赖后台定时任务修改状态。
错误码与边界处理
不同状态应返回稳定错误码,便于前端决定提示和跳转:TENANT_DISABLED 表示管理员停用,TENANT_FROZEN 表示临时冻结,TENANT_EXPIRED 表示服务期限结束。
认证失败时不要返回租户内部配置、到期原因或管理员备注。响应只暴露必要状态,详细原因写入审计日志,并记录 tenantId、操作者、状态变更时间和请求追踪号。
对于平台管理员访问租户管理接口,可以设计明确的白名单能力,但不能在公共认证过滤器中简单跳过租户校验。豁免应基于独立身份类型和受限路由,避免普通租户账号伪造管理员路径。
验收清单
完成实现后,至少验证以下场景:
- 正常租户可以登录并访问业务接口
- 停用、冻结和过期租户均无法创建新会话
- 租户状态在登录后变更时,旧令牌下一次请求立即被拒绝
- 状态缓存删除失败时有重试或消息补偿机制
- 平台管理员豁免不会扩大到普通租户接口
本课总结
- 租户可用性应由统一服务归一判定,不能散落在各业务模块
- 登录阶段阻止新会话,请求阶段阻断状态变更后的旧会话
- 高风险状态变更必须主动清缓存并收敛存量会话
下一课预告
下一课将继续完善认证安全策略,围绕登录审计、异常行为识别和风险控制建立可追踪的认证闭环。