架构与系统设计 / 系统课时

租户状态联动

租户状态联动

本课把租户停用、过期和冻结状态接入登录与请求处理,确保新用户无法进入、存量令牌也不能继续访问,并通过统一状态判定避免不同服务各自解释租户状态。

学习目标

  • 建立租户状态、有效期和冻结信息的统一判定规则
  • 在登录阶段与每次请求阶段执行不同强度的校验
  • 实现状态变更后的缓存失效和存量会话收敛

可用性规则与双阶段校验

租户是否可访问不能只看一个 status 字段。完整判断通常至少包含启停状态、订阅到期时间、冻结状态和删除标记,并且要明确各状态的优先级。

推荐按“已删除 → 已停用 → 已冻结 → 已过期 → 正常”的顺序判定。前面的状态一旦命中就立即返回,避免同一租户同时满足多个条件时出现不同错误码。

可以将最终结果归一为 ACTIVE、DISABLED、FROZEN、EXPIRED 四类。认证服务和业务服务只依赖这个归一结果,不直接拼接数据库条件。

登录与请求双阶段校验

登录阶段负责阻止新会话创建。密码、验证码或第三方身份验证成功后,在签发令牌前查询租户状态;租户不可用时,不创建 Redis 会话,也不签发访问令牌。

请求阶段负责处理状态变更后的存量令牌。即使令牌签发时租户正常,也必须在请求进入业务逻辑前再次确认租户仍可用,否则租户被停用后,旧令牌会一直工作到自然过期。

租户状态联动校验流程

双阶段校验不能互相替代:只校验登录会遗漏存量令牌,只校验请求则会创建无意义会话并增加后续清理成本。

状态判定服务实现

下面是片段示例,依赖项目已有的租户仓储、统一错误码和时钟配置。把时间比较集中在一个服务中,可避免不同节点因时区或边界规则不同而产生结果偏差。

java
@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 后再次调用。状态异常时应在进入控制器前终止请求。

使用停用租户的账号尝试登录,可通过以下请求验证。实际端口、账号和密码按环境替换。

bash
curl -i -X POST "http://localhost:<PORT>/api/auth/login" -H "Content-Type: application/json" -d '{"tenantCode":"demo","username":"alice","password":"<PASSWORD>"}'

预期结果

text
HTTP/1.1 403 Forbidden
{"code":"TENANT_DISABLED","message":"租户已停用","data":null}

如果租户在用户登录后被停用,继续携带旧访问令牌请求业务接口,也应得到同样的租户状态错误,而不是继续返回业务数据。

缓存、边界与验收

每次请求都直接查数据库会增加认证链路延迟,因此可以缓存租户归一状态,例如键 tenant:access:<tenantId>,并设置较短过期时间。缓存值只保存归一结果和状态版本,不缓存复杂租户对象。

租户状态发生变更时,应先提交数据库事务,再删除或更新状态缓存,同时发布 TenantStatusChanged 事件。认证服务收到事件后,可按租户索引批量删除会话,或递增租户级 tokenVersion,让旧令牌在下一次请求中立即失效。

仅依赖缓存自然过期会形成安全窗口。对停用、冻结这类高风险操作,应主动失效缓存并收敛会话;对套餐到期这种可预测事件,还应使用统一时钟判断,不能只依赖后台定时任务修改状态。

错误码与边界处理

不同状态应返回稳定错误码,便于前端决定提示和跳转:TENANT_DISABLED 表示管理员停用,TENANT_FROZEN 表示临时冻结,TENANT_EXPIRED 表示服务期限结束。

认证失败时不要返回租户内部配置、到期原因或管理员备注。响应只暴露必要状态,详细原因写入审计日志,并记录 tenantId、操作者、状态变更时间和请求追踪号。

对于平台管理员访问租户管理接口,可以设计明确的白名单能力,但不能在公共认证过滤器中简单跳过租户校验。豁免应基于独立身份类型和受限路由,避免普通租户账号伪造管理员路径。

验收清单

完成实现后,至少验证以下场景:

  • 正常租户可以登录并访问业务接口
  • 停用、冻结和过期租户均无法创建新会话
  • 租户状态在登录后变更时,旧令牌下一次请求立即被拒绝
  • 状态缓存删除失败时有重试或消息补偿机制
  • 平台管理员豁免不会扩大到普通租户接口

本课总结

  • 租户可用性应由统一服务归一判定,不能散落在各业务模块
  • 登录阶段阻止新会话,请求阶段阻断状态变更后的旧会话
  • 高风险状态变更必须主动清缓存并收敛存量会话

下一课预告

下一课将继续完善认证安全策略,围绕登录审计、异常行为识别和风险控制建立可追踪的认证闭环。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

租户状态联动

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通