xiner/Edu

Files

SpecialX a35e759d64 feat(iam): 完整实现 iam 身份认证与权限服务

包含 jwt/jwks/audit/grpc、rbac、cache、redis/kafka 配置等完整实现

2026-07-10 19:09:39 +08:00

25 KiB

Raw Blame History

模块架构设计文档 — iam

模块：IAM（身份认证与权限）版本：v1.0（最终态，对齐 coord-final-decisions I1-I8 + president §2.15/§2.16/§3.2/§5.5）日期：2026-07-10 关联：

004 架构影响地图

仲裁决策

总裁裁决

iam 对接契约

1. 模块内部分层图

1.1 调用链总览

flowchart TB
    subgraph Client["客户端 / Gateway / BFF"]
        REST[HTTP 请求<br/>带 x-user-id / x-user-roles / x-user-data-scope 头]
        GRPC[gRPC 调用<br/>next_edu_cloud.iam.v1]
    end

    subgraph NestJS["iam 服务（NestJS Hybrid App）"]
        direction TB
        MW[AuthMiddleware<br/>已注册：me/logout/viewports/<br/>permissions/roles/audit/children]
        Guard[PermissionGuard<br/>APP_GUARD 全局守卫<br/>DB 驱动 + Redis 缓存]
        Filter[GlobalErrorFilter<br/>全局异常过滤器]

        subgraph Controllers["Controller 层（双入口）"]
            IamCtl[IamController<br/>REST /v1/iam/*]
            RbacCtl[RbacController<br/>REST /v1/iam/roles, /permissions]
            AuditCtl[AuditController<br/>REST /v1/iam/audit]
            JwksCtl[JwksController<br/>GET /v1/iam/.well-known/jwks.json]
            GrpcCtl[IamGrpcController<br/>12 RPC @ GrpcMethod]
        end

        subgraph Services["Application Service 层"]
            IamSvc[IamService<br/>认证 + RBAC + 审计编排<br/>REST 与 gRPC 共用]
            CacheSvc[PermissionCacheService<br/>Redis 权限缓存 TTL 5min]
            BlacklistSvc[TokenBlacklistService<br/>Redis jti 黑名单]
            JwksSvc[JwksService<br/>PEM→JWK 转换]
        end

        subgraph Repo["Repository 层"]
            IamRepo[IamRepository<br/>Drizzle 查询 10 表]
        end

        subgraph Outbox["Outbox 模块（shared-ts）"]
            OutboxPub[OutboxPublisher<br/>事务内写入]
            OutboxRelay[OutboxRelayWorker<br/>后台轮询 + Kafka 投递]
        end

        subgraph Infra["基础设施"]
            Db[(MySQL<br/>iam_db)]
            Redis[(Redis<br/>权限缓存 + token 黑名单)]
            Kafka[(Kafka<br/>edu.iam.* topics)]
        end
    end

    REST --> MW
    MW --> Guard
    GRPC --> Guard
    Guard --> Controllers
    Controllers --> IamSvc
    IamSvc --> IamRepo
    IamSvc --> CacheSvc
    IamSvc --> BlacklistSvc
    IamSvc --> OutboxPub
    IamRepo --> Db
    CacheSvc --> Redis
    BlacklistSvc --> Redis
    OutboxPub --> OutboxRelay
    OutboxRelay --> Kafka
    Controllers -.异常.-> Filter

1.2 中间件 / Guard / Filter 拦截顺序

请求进入
  → AuthMiddleware（注册于 me/logout/viewports/permissions/roles/audit/children）
  → PermissionGuard（APP_GUARD，data_scope=all 直放行 + DB 驱动 + Redis 缓存）
  → Controller Handler（Zod 校验 body / @GrpcMethod）
  → Application Service（业务编排：Repository + Cache + Outbox + 审计）
  → Repository（Drizzle 查询）
  → 异常抛出
  → GlobalErrorFilter（统一兜底，注入 traceId）
  → 响应返回

1.3 目录结构（最终态）

services/iam/src/
├─ iam/                          # 限界上下文：认证 + RBAC + 审计
│  ├─ iam.controller.ts          # REST /v1/iam 入口
│  ├─ iam.grpc.controller.ts     # gRPC 12 RPC 入口
│  ├─ rbac.controller.ts         # REST /v1/iam/roles, /permissions
│  ├─ audit.controller.ts        # REST /v1/iam/audit
│  ├─ jwks.controller.ts         # REST /v1/iam/.well-known/jwks.json
│  ├─ jwks.service.ts            # PEM→JWK 转换
│  ├─ iam.service.ts             # Application Service（12 RPC + Outbox + 审计）
│  ├─ iam.repository.ts          # Drizzle 查询（10 表）
│  ├─ iam.schema.ts              # 10 张表 schema + DataScope/RoleType 枚举
│  └─ iam.dto.ts                 # Zod schema
├─ config/
│  ├─ database.ts                # Drizzle 池 + getDbInstance + closeDb
│  ├─ redis.ts                   # Redis 单例
│  ├─ jwt.ts                     # RS256 密钥加载 + ttlToSeconds
│  ├─ kafka.ts                   # Kafka producer 单例 + IAM_KAFKA_TOPICS
│  └─ env.ts                     # Zod 校验环境变量
├─ middleware/
│  ├─ auth.middleware.ts         # 解析 x-user-* 头
│  └─ permission.guard.ts        # DB 驱动 + Redis 缓存权限校验
├─ shared/
│  ├─ cache/
│  │  ├─ permission-cache.service.ts  # Redis 权限缓存
│  │  └─ token-blacklist.service.ts   # Redis jti 黑名单
│  ├─ errors/                    # ApplicationError 层次 + GlobalErrorFilter
│  ├─ health/                    # /healthz + /readyz（5 依赖检查）
│  ├─ lifecycle/                 # 优雅停机（Kafka→Redis→DB）
│  └─ observability/             # logger / metrics / tracer
├─ app.module.ts                 # 根模块（IamModule + HealthModule + OutboxModule + APP_GUARD）
└─ main.ts                       # Hybrid 启动（gRPC + HTTP）

2. 领域模型

2.1 聚合根与实体

classDiagram
    class UserEntity {
        -id: string
        -email: string
        -passwordHash: string
        -name: string
        -status: UserStatus
        -dataScope: DataScope
        -passwordChangedAt: Date
        +verifyPassword(plain) bool
    }

    class RoleEntity {
        -id: string
        -name: string
        -description: string?
        -roleType: RoleType
        -level: int
    }

    class Permission {
        +id: string
        +name: string
        +resource: string
        +action: string
    }

    class RoleViewport {
        +id: string
        +roleId: string
        +viewportKey: string
        +label: string
        +route: string
        +level: ViewportLevel
        +sortOrder: int
        +requiredPermission: string?
    }

    class RefreshToken {
        +id: string
        +userId: string
        +tokenHash: string
        +jti: string
        +expiresAt: Date
        +revokedAt: Date?
    }

    class StudentGuardian {
        +id: string
        +studentId: string
        +guardianId: string
        +relation: string
    }

    class AuditLog {
        +id: string
        +actorUserId: string?
        +action: string
        +resourceType: string
        +resourceId: string
        +beforeState: string?
        +afterState: string?
        +ipAddress: string?
        +userAgent: string?
    }

    UserEntity "1" --> "many" RefreshToken : 拥有
    UserEntity "1" --> "many" StudentGuardian : 作为 guardian
    RoleEntity "1" --> "many" Permission : 通过 role_permissions
    RoleEntity "1" --> "many" RoleViewport : 配置
    UserEntity "1" --> "many" AuditLog : 作为 actor

2.2 值对象（枚举）

enum UserStatus {
  ACTIVE = "active",
  DISABLED = "disabled",
}

// DataScope 6 级（I8 裁决：SUBJECT 替代 DISTRICT）
enum DataScope {
  SELF = "self", // L0：仅自己
  SUBJECT = "subject", // L1：科目（教师所教科目+班级）
  CLASS = "class", // L2：班级（班主任所带班级）
  GRADE = "grade", // L3：年级
  SCHOOL = "school", // L4：全校
  ALL = "all", // L5：跨校（系统管理员）
}

// 三层角色模型（§2.15）
enum RoleType {
  SYSTEM = "system", // 系统预设（admin/teacher/student/parent），level=0
  ORGANIZATION = "organization", // 组织分配（年级组长/班主任/学科组长），level=1
  TEMPORARY = "temporary", // 临时授权（代课教师），level=2
}

enum ViewportLevel {
  ADMIN = "admin",
  TEACHER = "teacher",
  STUDENT = "student",
  PARENT = "parent",
}

2.3 聚合间通信

同服务内：IamService 直接调用 PermissionCacheService、TokenBlacklistService、JwksService、IamRepository（NestJS DI）
跨服务：通过 Kafka 事件（Outbox 发布），不直接访问其他服务 DB

3. 数据模型

3.1 表清单（10 张表）

表名	用途	主键	唯一索引
`iam_users`	用户主表	`id`	`email`
`iam_roles`	角色表（role_type + level）	`id`	`name`
`iam_user_roles`	用户-角色绑定	`id`	`(userId, roleId)`
`iam_permissions`	权限点表	`id`	`name`
`iam_role_permissions`	角色-权限映射	`id`	`(roleId, permissionId)`
`iam_refresh_tokens`	refresh token（含 jti）	`id`	`jti`
`iam_role_viewports`	角色-视口配置（含 level）	`id`	`(roleId, viewportKey)`
`iam_student_guardians`	学生-家长关系（I6 裁决表名）	`id`	`(studentId, guardianId)`
`iam_user_audit_log`	审计日志（§5.5）	`id`	—
`iam_password_history`	密码重用限制	`id`	—

3.2 索引策略

表	索引	用途
`iam_users`	PK(`id`)、UNIQUE(`email`)	主键查询、登录
`iam_user_roles`	UNIQUE(`userId`,`roleId`)、INDEX(`roleId`)	防重、按角色查用户
`iam_role_permissions`	UNIQUE(`roleId`,`permissionId`)、INDEX(`permissionId`)	防重、按权限查角色
`iam_refresh_tokens`	UNIQUE(`jti`)、INDEX(`userId`)、INDEX(`tokenHash`)	jti 黑名单、按用户、按 hash 校验
`iam_role_viewports`	UNIQUE(`roleId`,`viewportKey`)	防重
`iam_student_guardians`	UNIQUE(`studentId`,`guardianId`)、INDEX(`guardianId`)	防重、按家长查学生
`iam_user_audit_log`	INDEX(`actorUserId`)、INDEX(`resourceType`,`resourceId`)、INDEX(`createdAt`)	按操作者、按资源、按时间查审计
`iam_password_history`	INDEX(`userId`,`createdAt`)	按用户查密码历史

3.3 读写分离策略

写路径：所有 Command 走 MySQL 主库（iam 独占库）
读路径：MySQL 直接读（iam 读多写少但数据量小，无需 ClickHouse 读模型）
缓存层：
- getEffectivePermissions 结果走 Redis 缓存（TTL 5min），Key: iam:perm:{userId}
- refresh token jti 黑名单走 Redis，Key: iam:bl:{jti}，TTL 与 refresh_token 剩余有效期对齐

4. API 设计

4.1 REST API 清单

Method	Path	权限	说明
POST	`/v1/iam/register`	公开	注册
POST	`/v1/iam/login`	公开	登录
POST	`/v1/iam/refresh`	公开	刷新令牌（轮换 + 旧 jti 加黑名单）
POST	`/v1/iam/logout`	`IAM_USER_READ`	登出（refresh token 加黑名单）
GET	`/v1/iam/me`	`IAM_USER_READ`	当前用户信息
GET	`/v1/iam/viewports`	`IAM_USER_READ`	当前用户视口
GET	`/v1/iam/permissions/effective`	`IAM_USER_READ`	当前用户有效权限
GET	`/v1/iam/children`	`IAM_USER_READ`	家长的孩子列表
GET	`/v1/iam/roles`	`IAM_ROLE_MANAGE`	角色列表
GET	`/v1/iam/permissions`	`IAM_ROLE_MANAGE`	权限点列表
GET	`/v1/iam/audit`	`IAM_AUDIT_READ`	审计日志（支持 actor/resource 查询）
GET	`/v1/iam/.well-known/jwks.json`	公开	RS256 公钥 JWK Set（Gateway 拉取验签）

4.2 gRPC API 清单（12 RPC，package `next_edu_cloud.iam.v1`）

RPC	请求	响应	说明
`Register`	`{email, password, name}`	`{user, tokens}`	注册
`Login`	`{email, password}`	`{user, tokens}`	登录
`RefreshToken`	`{refreshToken}`	`{tokens}`	刷新令牌
`Logout`	`{refreshToken, userId}`	`{success}`	登出
`GetUserInfo`	`{userId}`	`UserInfo`	查询用户信息
`BatchGetUsers`	`{userIds[]}`	`{users[]}`	批量查询用户（BFF 聚合用）
`GetEffectivePermissions`	`{userId}`	`{permissions[]}`	用户有效权限
`GetEffectiveAccess`	`{userId, permission}`	`{allowed, dataScope}`	用户对某权限的有效访问判定
`GetEffectiveDataScope`	`{userId}`	`{dataScope}`	用户数据范围
`GetViewports`	`{userId}`	`{viewports[]}`	用户视口
`GetPublicKey`	—	`{kid, alg, pem}`	公钥拉取（备用 JWKS）
`GetChildrenByParent`	`{parentId}`	`{children[]}`	家长的孩子列表

4.3 JWT Payload（RS256 签发）

interface JwtPayload {
  sub: string; // userId
  email: string;
  roles: string[]; // ['teacher', 'grade_leader']
  dataScope: DataScope; // 'class' | 'grade' | ...
  type: "access" | "refresh";
  iat: number; // 签发时间
  exp: number; // 过期时间
  iss: "next-edu-cloud";
  aud: "next-edu-cloud";
  jti: string; // JWT ID（仅 refresh token，用于黑名单）
  kid: string; // 密钥 ID（header，支持 JWKS 轮换）
}

access_token：TTL 15min（ACCESS_TOKEN_TTL），RS256 签名
refresh_token：TTL 7day（REFRESH_TOKEN_TTL_DAYS），RS256 签名，含 jti
密钥：本地文件（IAM_PRIVATE_KEY_PATH / IAM_PUBLIC_KEY_PATH），启动时一次性加载

5. 事件设计

5.1 我发布的领域事件

事件	触发时机	Topic	消费者
`UserCreated`	注册成功	`edu.iam.user.events`	core-edu / msg
`AuditCreated`	关键操作（登录/角色变更/密码修改等）	`edu.iam.audit.created`	data-ana
`RoleChanged`	角色绑定变更	`edu.iam.role.events`	msg / 缓存失效

5.2 事件 Schema（events.proto）

message UserEvent {
  string event_id = 1;
  string aggregate_id = 2;
  string event_type = 3;
  int64 occurred_at = 4;
  string user_id = 5;
  string email = 6;
  string name = 7;
  repeated string roles = 8;
  string data_scope = 9;
  string action = 10;
  map<string, string> metadata = 11;
}

message RoleEvent {
  string event_id = 1;
  string aggregate_id = 2;
  string event_type = 3;
  int64 occurred_at = 4;
  string role_id = 5;
  string role_name = 6;
  string action = 7;
  map<string, string> metadata = 8;
}

message AuditEvent {
  string event_id = 1;
  string actor_user_id = 2;
  string action = 3;
  string resource_type = 4;
  string resource_id = 5;
  int64 occurred_at = 6;
  string ip_address = 7;
  map<string, string> metadata = 8;
}

5.3 我消费的事件

无。iam 是权限中枢，单向发布，不消费业务事件。

5.4 Outbox 实现策略

shared-ts OutboxModule（I4 裁决）：OutboxModule.forRoot({ config, db, kafkaProducer })
表名：iam_outbox
topic：edu.iam.user.events（默认）/ edu.iam.role.events / edu.iam.audit.created
轮询间隔：1000ms，批量 20 条，最大重试 5 次，退避 1000ms
幂等性：producer idempotent=true + transactionalId: "iam-tx"，consumer 基于 event_id 去重

sequenceDiagram
    participant Ctl as Controller
    participant Svc as IamService
    participant DB as MySQL
    participant Pub as OutboxPublisher
    participant Relay as OutboxRelayWorker
    participant Kafka as Kafka

    Ctl->>Svc: register(dto)
    Svc->>DB: BEGIN TX
    Svc->>DB: INSERT iam_users
    Svc->>DB: INSERT iam_user_roles
    Svc->>DB: INSERT iam_user_audit_log
    Svc->>Pub: publish(UserCreated + AuditCreated)
    Pub->>DB: INSERT iam_outbox
    Svc->>DB: COMMIT TX
    Svc-->>Ctl: {user, tokens}

    loop 每 1000ms 轮询
        Relay->>DB: SELECT pending LIMIT 20
        Relay->>Kafka: produce(topic, payload)
        Kafka-->>Relay: ack
        Relay->>DB: UPDATE status='published'
    end

6. 横切关注点对齐清单

6.1 权限装饰器

每个 Controller 方法用 @RequirePermission() 装饰器声明权限点。权限点常量：

export const Permissions = {
  IAM_USER_READ: "iam:user:read",
  IAM_USER_MANAGE: "iam:user:manage",
  IAM_ROLE_MANAGE: "iam:role:manage",
  IAM_AUDIT_READ: "iam:audit:read",
  IAM_VIEWPORT_READ: "iam:viewport:read",
} as const;

6.2 错误码清单

错误码	HTTP	触发条件
`IAM_VALIDATION_ERROR`	400	Zod 校验失败
`IAM_UNAUTHORIZED`	401	未登录、密码错误、token 失效、refresh token 在黑名单
`IAM_PERMISSION_DENIED`	403	缺少所需权限点
`IAM_NOT_FOUND`	404	用户/角色/权限/视口不存在
`IAM_CONFLICT`	409	邮箱已注册、角色名重复、家长-学生关系已存在
`IAM_BUSINESS_ERROR`	422	账号禁用、系统角色禁止删除、refresh token 已撤销
`IAM_DATABASE_ERROR`	500	Drizzle 操作失败
`IAM_INTERNAL_ERROR`	500	未预期异常
`IAM_OUTBOX_ERROR`	500	Outbox 写入或投递失败

6.3 可观测性

日志：pino，base: { service: 'iam', version: '0.2.0' }，level: env.LOG_LEVEL，注入 traceId
指标：prom-client，/metrics 端点
- iam_login_attempts_total、iam_login_duration_seconds
- iam_jwt_issued_total（type=access/refresh）
- iam_permission_cache_hits_total / iam_permission_cache_misses_total
- iam_outbox_pending、iam_outbox_publish_duration_seconds
链路：OpenTelemetry SDK + OTLP exporter，serviceName: iam

6.4 健康检查

/healthz：liveness，仅返回进程存活
- 响应：{ status: 'ok', service: 'iam', timestamp: ISO }
/readyz：readiness，5 依赖检查
- DB：SELECT 1
- Redis：ping
- Kafka：producer 实例存在且已连接
- JWKS：密钥文件可读
- gRPC：进程内 microservice 存在
- 失败：HTTP 503，响应体含失败项详情

6.5 优雅关闭顺序

async onApplicationShutdown(signal?: string) {
  // 1. 停止接收新请求（NestJS 自动）
  // 2. 停止 OutboxRelayWorker（shared-ts 自动）
  // 3. 关闭 Kafka producer
  await closeKafkaProducer();
  // 4. 关闭 Redis 连接
  await closeRedis();
  // 5. 关闭 MySQL 连接池
  await closeDb();
}

7. 与其他模块的交互点（契约清单）

方向	对方服务	协议	接口/事件	用途
被调用	api-gateway	HTTP	`POST /v1/iam/register` 等	Gateway 反向代理 `/iam/v1/*`
被调用	api-gateway	HTTP	`GET /v1/iam/.well-known/jwks.json`	Gateway 拉取 RS256 公钥校验 JWT
被调用	teacher-bff	gRPC	`GetUserInfo`、`BatchGetUsers`、`GetViewports` 等	BFF 聚合用户身份与视口
被调用	student-bff	gRPC	同上	同上
被调用	parent-bff	gRPC	`GetChildrenByParent`	家长视角聚合孩子信息
发布	—	Kafka	`edu.iam.user.events`	core-edu / msg 消费
发布	—	Kafka	`edu.iam.role.events`	msg / 缓存失效
发布	—	Kafka	`edu.iam.audit.created`	data-ana 消费

7.1 端口分配

服务	端口	备注
iam HTTP	3002	REST 入口
iam gRPC	50052	gRPC 入口（I1 裁决）

7.2 Topic 命名

edu.iam.user.events
edu.iam.role.events
edu.iam.audit.created

8. 仲裁裁决对齐

8.1 I1-I8 裁决

裁决	内容	实现位置
I1	双入口（REST + gRPC），gRPC 50052	main.ts Hybrid app + iam.grpc.controller.ts
I2	JWT RS256 本地文件密钥	config/jwt.ts + env IAM_PRIVATE/PUBLIC_KEY_PATH
I3	DB 驱动 + Redis 缓存 PermissionGuard	permission.guard.ts + permission-cache.service.ts
I4	shared-ts OutboxModule 接入	app.module.ts OutboxModule.forRoot
I5	/iam/v1/* 前缀	iam.controller.ts @Controller("v1/iam")
I6	iam_student_guardians 表名	iam.schema.ts + iam-init.sql
I7	jti 黑名单	token-blacklist.service.ts
I8	DataScope SUBJECT 替代 DISTRICT	iam.schema.ts DataScope enum

8.2 总裁裁决

裁决	内容	实现位置
§2.15	三层角色模型（system/organization/temporary）	iam.schema.ts RoleType + iam_roles.level
§2.16	双入口策略（同一 IamService）	iam.service.ts REST 与 gRPC 共用
§3.2	AuthMiddleware 注册	app.module.ts configure()
§5.5	审计日志（iam_user_audit_log + AuditEvent）	iam.schema.ts + iam.service.ts writeAuditLog

9. 技术风险

风险	影响	缓解措施
Redis 不可用	权限校验回退到 DB 查询，性能下降	`getEffectivePermissions` catch 后走 DB，不抛错
Kafka 不可用	Outbox 事件积压，下游服务感知延迟	Relay Worker 重试 + `status='failed'` 记录，不阻塞主流程
RS256 密钥泄露	任何人可伪造 JWT	密钥文件权限 600 + 容器 Secret 挂载
权限缓存与 DB 不一致	用户角色变更后 5min 内旧权限仍生效	角色变更主动 DEL + 短 TTL
Outbox 表膨胀	磁盘占用增长	已发布事件定期清理（保留 7 天）

模块: iam-service（@edu/iam-service v0.2.0）分支: feat-implement-iam-module 入口: HTTP 3002 + gRPC 50052

25 KiB Raw Blame History Unescape Escape