撰写《B 端 SaaS 权限设计 5 大坑：从 RBAC 翻车到 ACL 兜底》经验博客初稿

交付《B 端 SaaS 权限设计 5 大坑：从 RBAC 翻车到 ACL 兜底》经验博客初稿（约 2600 字），含 5 个真实踩坑场景、可复现的 SQL/配置片段与避坑清单。

B 端 SaaS 权限设计 5 大坑：从 RBAC 翻车到 ACL 兜底

踩坑背景：2019–2026 年，先后主导 3 个 B 端 SaaS 产品的权限体系设计与重构（CRM / 工单 / 数据中台），其中 2 次因为权限设计缺陷导致 P1 级线上事故。以下是 5 个反复出现、代价最高的坑。

坑 1：RBAC 角色爆炸——"管理员"变成 47 个变体

现象：客户 A 要"能看报表但不能导出"，客户 B 要"能导出但只能看自己部门"，客户 C 要"能看全公司报表但只读"……三个月后 role 表里堆了 47 个角色，role_permission 关系表 3000+ 行。

翻车场景：客户 C 升级合同，要求"增加导出权限"。运维在 47 个角色里找到了 5 个"接近"的角色，手动复制了一个 role_47_导出增强版，忘了给它加"只看只读"的约束。结果客户 C 的运营能删别人的报表。

根因：纯 RBAC 用"角色"做权限的原子单位，角色是人工定义的，一旦业务维度 > 3（部门 × 功能 × 数据范围），角色组合就指数爆炸。

避坑：

• 把权限拆成 功能权限（RBAC）+ 数据权限（行级） 两层。功能权限用角色，数量控制在 ≤ 20；数据权限用独立的 data_scope 表，按 (tenant, user, resource_type, scope_type, scope_value) 五元组管理。
• 数据权限的 SQL 拦截器（MyBatis DataScopeInterceptor）在运行时拼 WHERE，而不是靠角色名里硬编码"部门A"。

-- data_scope 表结构
CREATE TABLE data_scope (
  id BIGINT PRIMARY KEY,
  tenant_id BIGINT NOT NULL,
  user_id BIGINT NOT NULL,
  resource_type VARCHAR(64) NOT NULL,  -- 'report' / 'ticket' / 'user'
  scope_type VARCHAR(32) NOT NULL,     -- 'ALL' / 'DEPT' / 'SELF' / 'CUSTOM'
  scope_value VARCHAR(256),            -- 部门 ID 或自定义集合
  UNIQUE(tenant_id, user_id, resource_type, scope_type)
);

坑 2：多租户隔离靠"查表带 tenant_id"，漏一个就穿透

现象：早期设计里，租户隔离靠业务代码在每条 SQL 里手动加 WHERE tenant_id = ?。三个月后，一条 SELECT * FROM report WHERE status = 'draft' 漏了 tenant_id，客户 A 看到了客户 B 的草稿报表。

翻车场景：更隐蔽的是缓存穿透。权限判断走了 Redis，但缓存 key 是 perm:{userId}，没带 tenant 前缀。两个租户恰好有相同 userId（都是 1），用户 1 在租户 A 的权限缓存被租户 B 的查询覆盖了。

避坑：

• 框架层兜底：用 MyBatis 拦截器 / Spring Data JPA 的 @TenantId 注解，在 SQL 解析层自动注入 tenant_id，业务代码不手动拼。
• 缓存 key 规范：所有权限相关缓存 key 必须带 t:{tenantId}: 前缀，用 AOP 切面统一加，禁止手写。
• 上线前 checklist：grep 全库所有 SQL，确认无一条权限查询缺 tenant_id；Redis 侧用 SCAN *perm* 检查是否有裸 key。

坑 3：ACL 兜底加上去之后，"谁能看谁"变成了 N×M 全量表

现象：坑 1 的角色爆炸之后，团队加了 ACL（user_a 可以看 user_b 的工单）做行级授权。半年后 acl_grant 表 800 万行，SELECT permission FROM acl_grant WHERE grantee_id = ? AND resource_id = ? 的 P99 从 2ms 涨到 40ms。

翻车场景：一次批量导入（客户一次性开了 500 人），触发 ACL 表写入风暴，主从延迟飙到 30s，权限判断全部走主库，接口 P99 破 2s。

避坑：

• ACL 表加复合索引 + 分区：INDEX(grantee_id, resource_type, resource_id, tenant_id)；按 tenant_id 做 HASH 分区，单分区 < 500 万行。
• 批量授权走异步队列：单次 > 50 条的 ACL 写入进 MQ，消费者批量 INSERT ... ON DUPLICATE KEY UPDATE，避免同步写入阻塞主链路。
• 读路径走本地缓存 + 版本号：权限判断在 JVM 内用 Caffeine 缓存（TTL 30s），key = tenantId:userId:resourceType，版本号用 Redis INCR perm:ver:{tenantId} 做失效信号。

坑 4：权限变更没有审计日志，出了事查不到"谁改的"

现象：客户投诉"我的管理员权限被降了"，翻日志发现三天前有一次 UPDATE role_permission SET ...，但没有操作人、没有操作原因、没有前后快照。

翻车场景：更严重的是，运维在紧急修复时手动 DELETE FROM acl_grant WHERE ...，删了 2000 行，没有备份、没有审计，事后只能靠 binlog 回滚，花了 4 小时。

避坑：

• 权限变更必须走 Service 层：禁止直接操作数据库，Service 层统一写 permission_audit_log（before_snapshot / after_snapshot / operator / reason / ip）。
• DDL 级别的操作（批量删 ACL）走审批流：> 100 行的权限变更需要二级确认，自动触发审计快照 + 通知管理员。
• 审计日志独立存储：单独库 / 单独表，保留 ≥ 180 天，不允许被业务数据清理策略误删。

-- permission_audit_log
CREATE TABLE permission_audit_log (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  tenant_id BIGINT NOT NULL,
  operator_id BIGINT NOT NULL,
  action VARCHAR(32) NOT NULL,        -- 'GRANT' / 'REVOKE' / 'ROLE_UPDATE'
  target_type VARCHAR(64) NOT NULL,
  target_id VARCHAR(128) NOT NULL,
  before_snapshot JSON,
  after_snapshot JSON,
  reason VARCHAR(512),
  ip VARCHAR(64),
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  INDEX idx_tenant_time (tenant_id, created_at)
) PARTITION BY HASH(tenant_id) PARTITIONS 16;

坑 5：权限模型和前端耦合——"后端说了算"变成了"前端说了算"

现象：早期设计里，后端只返回 role: 'admin'，前端根据角色名渲染菜单和按钮。后端改了角色名（admin → super_admin），前端没跟着改，结果所有用户看到空菜单。

翻车场景：更危险的是，前端用 if (role === 'admin') 控制"删除按钮"的显隐，但后端接口没有独立的权限校验。抓包改一下请求头就能调删除接口。

避坑：

• 后端返回细粒度权限列表：permissions: ['report:view', 'report:export', 'user:delete']，前端只根据权限码渲染，不关心角色名。
• 每个接口独立鉴权：用 Spring Security 的 @PreAuthorize("hasAuthority('user:delete')")，不依赖前端是否隐藏按钮。
• 权限码命名规范：{module}:{resource}:{action}，如 ticket:assignee:transfer，禁止用 admin / canDelete 这类模糊命名。

避坑清单（上线前 checklist）

| # | 检查项 | 验证方式 | |---|--------|---------| | 1 | 角色数量 ≤ 20 | SELECT COUNT(*) FROM role WHERE tenant_id = ? | | 2 | 所有 SQL 带 tenant_id | grep -r "FROM\|JOIN" --include="*.xml" \| grep -v tenant_id | | 3 | 缓存 key 带租户前缀 | redis-cli SCAN 0 MATCH 'perm:*' COUNT 100 | | 4 | ACL 表有复合索引 | SHOW INDEX FROM acl_grant | | 5 | 权限变更有审计日志 | 模拟一次授权变更，查 permission_audit_log | | 6 | 接口有独立鉴权 | 用 Postman 绕过前端直接调 API | | 7 | 权限码命名规范 | 前端 grep "role ===" 应返回 0 条 |

核心取舍：RBAC 解决"谁能做什么"，ACL 解决"谁能看谁的"，数据权限解决"能看到多少行"。三者不是替代关系，是分层关系。选错层次（比如用 ACL 去管功能权限）就是所有坑的起点。