Skip to content

权限系统 (PBAC) ​

核心设计理念 ​

  1. RBAC + ABAC 混合模型:角色负责标准授权,内联策略负责灵活的通配符授权
  2. 权重压制:管理员仅能委派等级低于自身的权限
  3. 应用隔离与全局可见:通过 GLOBAL 占位符区分
  4. Deny 优先:Deny 规则始终覆盖 Allow 规则
  5. 权限点在代码中,角色策略在数据库中

权限字典规范 ​

权限编码遵循 {应用域}:{资源名}:{动作} 三段式小写格式:

js
// src/app/oauth21/permission/index.js
const OAUTH_PERMISSIONS = createPermissionRegistry('oauth21', 'OAuth 2.1 授权中心', {
  CLIENT: {
    READ: { code: 'oauth:client:read', label: '查看客户端', type: 'read' },
    UPDATE: { code: 'oauth:client:update', label: '编辑客户端', type: 'write' }
  },
  TOKEN: {
    READ: { code: 'oauth:token:read', label: '查看 Token', type: 'read' },
    REVOKE: { code: 'oauth:token:revoke', label: '吊销 Token', type: 'high_risk' }
  },
  ADMIN: {
    ALL: { code: 'oauth:admin:*', label: '管理员全量通配符', type: 'wildcard' }
  }
});

角色体系 ​

角色层次 ​

superadmin (rank:99) → 所有应用管理员(自动继承)
  ├── oauth_admin (rank:80) → 授权中心管理员
  └── oauth_viewer (rank:10) → 观察者(默认授予)

角色定义 ​

js
// src/app/oauth21/permission/roles.js
defineRoles([
  {
    code: 'oauth_viewer',
    app_id: 'oauth21',
    name: 'OAuth 观察者',
    rank_level: 10,
    is_default: true, // 授权即送的默认角色(见下一节)
    policy: {
      Version: '2026-06-06',
      Statement: [
        { Effect: 'Allow', Action: [OAUTH_PERMISSIONS.CLIENT.READ, OAUTH_PERMISSIONS.TOKEN.READ] }
      ]
    }
  }
]);

默认角色(授权即送) ​

用户首次授权某应用时,系统会自动授予一个"普通档"角色。它在两处声明, 解析时 config 为主、代码为辅:

  1. src/app/<app>/config.js 的 default_role —— 主口径,改配置即可覆盖代码;
  2. roles.js 里该角色的 is_default: true —— 辅口径,贴着定义写,不容易漏。
js
// src/app/oauth21/config.js
default_role: 'oauth_viewer',

解析顺序(src/app/oauth21/dao/approval.dao.js): config.default_role → is_default → 该权限命名空间职级最低的角色(要求 rank_level <= 20)。 写 default_role: null 表示"有意不自动授予"(例如只有一个管理员角色的 notice)。

封闭应用:写 null,角色由管理员分配 ​

有些应用注册了也不该能进,管理后台就是典型:config.access 声明了准入闸门 (anyPermission: ['admin:*']),没有管理能力的账号在 bind-session 阶段就被拒, 前端拿到的是 access.denyMessage。

这类应用必须 default_role: null,并且不要在 roles.js 上标 is_default:

  • 默认角色满足闸门(admin_viewer 持有全站读码,admin:* 直接命中)→ 任何注册用户 点一下"同意授权"就能看用户、部门、角色与日志,闸门形同虚设;
  • 默认角色不满足闸门 → 用户拿到一个进不去任何页面的假角色,登录即 403, 比"什么都不授"更让人困惑。

那角色怎么给:

  1. 管理员在「用户管理 → 分配角色」手工授予 (POST /admin/console/v1/users/roles/batch,支持追加/移除、跨应用批量);
  2. GLOBAL 的 superadmin 由 permission-loader 自动继承各应用的 {appId}_admin, 不需要逐个授。

判据:启动期 auditDefaultRoles 对"有闸门 + 有默认角色"直接报 error; __tests__/permission/role-rank-levels.test.js 用真实 config 跑一遍,写错测试就红。

写角色定义时必须一起把默认角色写对

  • 注册期直接抛错(import 期 = 启动失败):缺 app_id / rank_level / policy.Statement, 同一应用声明两个 is_default,或默认角色的 rank_level 超过普通档上限(20)。
  • 启动期日志提示(auditDefaultRoles):config.default_role 拼错、两处声明不一致、 什么都没声明(会回落最低职级)。前两种是 error,最后一种是 warn。
  • 判据被 src/__tests__/permission/role-rank-levels.test.js 卡死: 真实 config + 真实 roles.js 跑一遍审计,有问题测试就红,不用等部署。

命名空间注意:管理后台的应用标识、OAuth 客户端 id、角色命名空间都是 admin (2026-11-21 把 console 并入 admin,permission_app_id 已删除)。 default_role 写 admin 命名空间下的 code(如 admin_viewer)。

rank_level 有硬上限

职级区间由 src/models/iam/Role.js 的 validate: { min: 0, max: 99 } 决定,99 是最大值。 写成 100 不会在本地报错(角色早已落库时 Role.findOrCreate() 只走"更新 policy"分支), 但空库首次部署(新环境 / CI 的 compose 冒烟)会真的 insert,于是抛 SequelizeValidationError: Validation max on rank_level failed,而 appsLoader 是 fail-fast 的 —— 应用直接起不来。src/__tests__/permission/role-rank-levels.test.js 用模型自身的边界 守卫这条约束(边界从模型派生,不手抄 0/99)。

新职级必须严格低于自己

写接口(建角色 / 改职级)统一走 assertRankBelowActor:新职级 < 我自己的最高职级, 等于也不行。理由是职级就是"能管谁"的闸 —— 同级的角色在列表里是 manageable: false、在授予侧也被 rank >= maxRank 拒掉;如果填表时允许"等于自己", 就能造出一个谁也管不到的角色(只能超管收拾)。所以 99 只能来自代码声明 (superadmin、poseadmin),界面最高只能填到 98。

编辑时只判「值真的变了」:表单会连未改字段一起回传,回传原值不算调整职级。

策略格式 ​

Statement 格式(推荐):

json
{
  "Version": "2026-06-06",
  "Statement": [
    { "Effect": "Allow", "Action": ["fw:config:read", "fw:config:write"] },
    { "Effect": "Deny", "Action": ["fw:config:delete"] }
  ]
}

权限加载流程 ​

loadUserPermissions(userId, appId)
  → 查 UserRole(当前应用 + GLOBAL)
  → 解析 role.policy
  → superadmin 自动注入 {appId}_admin 角色
  → 查 InlinePolicy(当前应用 + GLOBAL)
  → 合并 allows/denies
  → 由 perm-cache 以 60s TTL 缓存(`auth:perm` 命名空间)

权限匹配引擎 ​

匹配实现单一来源:src/framework/security/auth/permission/wildcard-match.js(isWildcardMatch), api/guard.js 的路由守卫与 StpUtil._isMatch 共用同一实现(此前是两份漂移的副本)。

js
// src/framework/security/auth/permission/wildcard-match.js(真实源码)
function isWildcardMatch(pattern, target) {
  if (typeof pattern !== 'string' || typeof target !== 'string') return false;
  if (pattern === '*') return true;
  if (pattern === target) return true;
  if (!pattern.includes('*')) return false;
  // 先转义全部正则元字符,再以 * 为界拼回 .*——防止 pattern 里的
  // '.'、'('、'[' 等被当正则语法解释
  const regex = new RegExp(
    '^' +
      pattern
        .split('*')
        .map(seg => seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
        .join('.*') +
      '$'
  );
  return regex.test(target);
}

// Deny 优先(调用方向:pattern = 用户持有的权限模式,target = 待检的具体权限)
function matchSingle(perm, allows, denies) {
  if (denies.some(d => isWildcardMatch(d, perm))) return false;
  return allows.some(a => isWildcardMatch(a, perm));
}

语义要点:

模式语义
*匹配一切
user:*user: 开头的一切(* 可跨 : 段)
user:*:read中段通配同样支持
其他字面量匹配——元字符不解释,user:read 不会误匹配 userXread(2026-11-01 修复:旧实现未转义正则元字符)

分级委派管理 ​

角色级别权重作用域管理能力
L1: 超级管理员99GLOBAL系统最高权限
L2: 全局管理员80GLOBAL跨应用管理
L3: 应用管理员60specific_app单应用管理
L4: 模块管理员40specific_app局部管理

OAuth 2.1 与 PBAC 的交互 ​

OAuth Token 的 scope = 用户申请了什么权限
PBAC 的 allows/denies = 用户实际拥有什么权限

最终权限 = Token scope ∩ PBAC allows - PBAC denies

即使第三方拿到了最高 Scope 的 Token,只要管理员下发了 Deny 策略,请求仍然被拦截。

StpUtil 静态鉴权 ​

源码:src/framework/security/auth/context/stp-util.js(业务代码统一经 framework/security/auth/index.js 门面 re-export 引入,勿直接 import 子路径)。对标 Java Sa-Token,全部静态方法、依赖 AsyncLocalStorage 取当前请求——必须在 HTTP 请求上下文中调用(ALS 外抛错)。

loginId 的两种语义,传错不报错但必然失效

  • 权限/角色系列:操作"当前请求用户",无此问题;
  • 封禁系列(disable/untieDisable/isDisable/checkDisable/getDisableTime):loginId 必须是数字主键(ban store 按 userId:service 数字键控)——传 getLoginId() 返回的 uid 字符串不报错但永远封不中;管理端按 uid 查出 user.id 再传入;
  • 二级认证系列(openSafe 等):内部已取 state.user.userId(数字主键),直接传 service 即可。

认证与身份 ​

方法功能失败行为
getLoginId()当前用户标识(uid UUID;client_token 上下文返回客户端名)—
check()强制登录检查未登录抛 401
checkRole(role)角色校验(精确匹配,不支持通配;角色无 deny 维度)不匹配抛 403

权限校验(Deny 优先 + 通配符) ​

权限来源与认证路径解耦:Session 路径读 createSession 预热的快照;JWT 路径由 bearer-auth 经 perm-cache(数字主键 + 指纹校验)读实时快照——JWT 不嵌入权限, 权限变更即时生效。形状不完整按空集处理(fail-closed),鉴权失败不会伪装成 500。

方法功能失败行为
getPermissionList()取 { allows, denies }(只读引用,勿修改)—
hasPermission(perm)判断,返回 true/false—
checkPermission(perm)校验单个抛 NotPermissionException(403)
checkPermissionAnd(...perms)AND:全部通过任一不足抛 403;零参显式报错(空真 = 无守卫,疑似笔误)
checkPermissionOr(...perms)OR:任一通过全部不足抛 403;零参显式报错
js
import { StpUtil } from '../../src/framework/security/auth/index.js';

StpUtil.hasPermission('user:admin:*'); // 判断:返回 true/false
StpUtil.checkPermission('user:write'); // 校验:不通过抛 403(statusCode=403)
StpUtil.checkPermissionAnd('a', 'b'); // AND:全部通过
StpUtil.checkPermissionOr('a', 'b'); // OR:任一通过

账号封禁(disable 系列,async) ​

按 userId:service 数字键控存 Redis,TTL 到期自动解封;service='login' 拦新登录、 'access' 拦请求,业务可自定义维度。详见 src/framework/security/auth/security/ban.js 头注。

方法功能
disable(loginId, service, time, opts?)封禁(秒;-1=永久),opts 支持 { reason, level, operator }
disableLevel(loginId, service, level, time, opts?)阶梯封禁:按等级处罚(level≥1,语义业务自定义)
untieDisable(loginId, ...services)解封,返回实际解封的服务数
isDisable(loginId, service)是否被封禁(不区分等级)
checkDisable(loginId, ...services)校验未封禁,被封禁抛 403(code=ACCOUNT_BANNED)
getDisableTime(loginId, service)剩余封禁秒数:-2=未封禁,-1=永久

二级认证(openSafe 系列,async) ​

敏感操作"再次确认"机制:业务路由完成身份确认(重输密码/验证码)后 openSafe 开时间窗, 窗口内 safe 路由放行,窗口外 checkSafe 抛 403(code=SECOND_AUTH_REQUIRED)。 操作对象是当前请求用户;Redis 故障 fail-closed(视为未开启)。详见 src/framework/security/auth/security/safe.js。

方法功能
openSafe(service, safeTime?)开启时间窗(默认 1800s),返回 { openedAt, expireAt }
isSafe(service)是否在时间窗内
checkSafe(service)校验,未开启/已过期抛 403(details.service 供前端定位)
closeSafe(service)主动关闭(敏感操作完成后调用,缩短暴露窗)
getSafeTime(service)剩余秒数:-1=未开启

为什么没有 StpUtil.login()

登录入口是 oauth21 的 login.service(密码校验 + createSession + Cookie 下发的完整编排)。 曾有一个占位 login(),但 ALS 上下文里只有 request 没有 reply,Cookie 永远下发不了—— 2026-11-01 审查后删除。

基于 GPL-3.0 许可发布