系统架构设计说明书 (SAD)

项目名称： sup-iam 身份识别与访问管理系统

编写人： 沈冬法

日期： 2025年12月15日

版本号： V1.0

1.引言

1.1编写目的

基于《sup-iam SAD》说明系统的总体架构设计，明确系统模块划分，职责边界与交互方式，为后序开发和运维提供参考

1.2 参考文献

《软件需求规格说明书.md》

2.架构设计目标与原则

2.1架构设计目标

高内聚、低耦合
支持高并发
支持高可用
明确的信任边界
支持后续演进

2.2架构设计原则

控制面与数据面分离
无状态鉴权
最小权限原则
默认拒绝原则

3.系统总体架构

3.1 系统概念架构视图

描述 IAM 系统在整体安全架构中的角色划分，
包括 Client、Resource Server、Auth Server 与 IAM 管理系统之间的职责与信任边界。

其中Client和Resource Server为非项目组件

3.2 系统部署视图

描述 sup-iam 项目内部的实际组件拆分、部署关系与数据流，
不包含业务侧 Resource Server 的具体实现。
iam-api-server

角色：控制面核心服务
职责：
- 管理User/Secret/Policy元数据
- 为Auth Server和其它调用者提供策略与密钥查询能力
不承担：
- 在线鉴权决策
- 实际业务流量入口
  iam-auth-server
角色：数据面鉴权决策服务
职责：
- 校验请求签名
- 加载并评估授权策略
- 返回可解释的鉴权决策
不承担
- 对元数据的直接管理
设计约束
- 无状态
- 不保存用户登录状态

sup-iam-sdk-go

角色：客户端集成层
开发阶段: 项目主体阶段性完善后封装并提供的额外服务
职责：
- 封装签名，鉴权请求，API调用的细节
- 降低接入IAM的成本
接入方式：go包的方式接入，参数通过环境变量传参

redis

角色：数据库缓冲与持久化层
职责：
- 缓存对元数据的查询结果
- 缓存Auth Server产生的授权日志
设计约束：
- 应部署在可信网络中

MySQL

角色：数据持久化层
职责：
- 持久化存储元数据
- 自动化管理元数据
- 提供高效的查询功能

iam-watcher

角色：数据库监控层
职责：
- 定期处理过期数据
设计约束:
- 不能过度影响数据库效率

MongoDB

角色：日志数据持久化层
职责：持久化存储和管理日志数据

iam-pump

角色：日志存储中间层
职责：负责把日志从Redis转存到MongoDB中

iam-operating-system

角色：运维组件
职责：
- 管理日志
- 管理整个系统的全局参数
开发阶段：属于项目主体完成后额外提供的运维组件

iam-webconsole

角色：系统前端层
职责：
- 提供可视化的IAM管理功能
- 降低管理的理解门槛
开发阶段：属于项目主体完成后额外提供的前端组件
部署网络环境：可信任的内网

iam-ctl

角色：系统软件层
职责：将SDK或者API调用封装成命令行工具
开发阶段：属于项目主体完成后额外提供的命令行软件
部署网络环境：可信任的内网

LoadBalance

角色：负载均衡层
职责：
- 实现整体系统的横向扩展，高可用，负载均衡等
部署：与IAM项目一同部署，或者购买第三方服务

架构图如下

3.2 系统部署流量视图

在 sup-iam 架构中，系统交互被划分为三类流量：

控制流（Control Plane）
- 指用户或运维人员通过 Web / CLI / API 对 User、Secret、Policy 等元数据进行管理的请求。
鉴权流（Authorization Flow / Data Plane）
- 指业务请求在访问受保护资源时，由 Resource Server 发起的实时鉴权请求。
数据访问路径
- 指 IAM 内部组件在处理控制流或鉴权流过程中，对 MySQL、Redis、MongoDB 等存储系统的访问关系。

3.2.1 控制面流量

[Auth Server]->[IAM系统]->[数据库]->[返回结果]
					^
					|
				[Client]

3.2.2 鉴权流量

1	[Client]->[Auth Server]->[IAM系统]->[返回结果]->[Resource Server]

3.2.3数据访问路径

4.核心服务架构设计

4.1 IAM管理服务架构

4.1.1 IAM组件

组件名称:iam-api-server
子模块划分
- User管理模块
- Secret管理模块
- Policy管理模块
职责边界
- 不负责鉴权

4.1.2 Auth Server组件

组件名称: iam-auth-server
子模块划分
- 请求校验模块
- Secret加载模块
- Policy加载模块
- 策略评估模块
- 决策输出模块

5. 鉴权处理流程

5.1 鉴权处理时序图

1	Client--发起带签名的访问请求-->Resource Server---发起鉴权请求->Auth Server

5.2 请求声明周期说明

请求访问
身份校验
权限评估
决策返回

6.数据架构与存储设计

6.1 MySQL存储

存储User数据
存储Secret数据
存储Policy数据
存储审计Policy数据

6.2 MongoDB存储

存储日志数据

6.3 Redis存储

缓存日志数据
缓存IAM的查询结果

7.安全架构设计

7.1信任边界映射

进入iam-auth-server的通信:不可信
进入iam-api-server的通信：可信
Resource Server：半可信
MySQL:可信
Redis：可信
MongoDB：可信
iam-operating-system：可信

7.2 凭证保护策略

7.2.1 SK存储策略

（MySQL明文存储有泄漏风险，加密的话还要再解密，解密怎么设计呢？）

7.2.2 传输安全策略

通过保证IAM系统的所有内部组件的通信都是走的可信任的安全内网来保证传输安全，若需要增加防护等级，则可使用HTTPS加密通信

7.3 防攻击机制概览

（我的没系统学过计算机安全，这一块需要AI帮忙了）

8.可扩展性与演进设计

Policy版本管理：预计使用Policy存储的扩展字段存储版本信息，若实际性能问题严重，再改数据库表
鉴权策略插件化：未来提供更多版本的鉴权策略，形成策略插件库

9. 接口与通信设计

9.1 接口设计目标

明确分离控制面接口与鉴权接口
避免组件间的职责重叠
为后序Swagger文档与SDK实现提供稳定抽象
支持接口版本化与平滑演进

9.2接口分层与调用关系

9.2.1 控制面接口

提供方:iam-api-server
调用方:
- iam-auth-server
- iam-ctl
- iam-webconsole
- 管理类SDK
接口风格: RESTful API
核心特征:
- 有状态的（用户登录态
- 强一致性
- 高并发
- 低延迟
- 面向人类管理行为

9.2.1 数据面接口/鉴权接口

提供方:iam-auth-server
调用方
- Resource Server
- 服务类SDK
接口风格
- 对外: RESTful API
- 对内: gRPC调用iam-api-server
核心特征：
- 无状态的
- 高并发
- 低延迟
- 面向机器调用

9.2.3内部服务接口

提供方:iam-api-server
调用方:
- iam-auth-server
调用方式：grpc
核心特点：
- 不对外暴露
- 保证接口性能和稳定性
- 不保证向后兼容

10.非目标与设计限制

本版本不支持 Policy 版本管理
本版本不支持跨 User 的 Secret 共享
所有未在 SAD 中声明的能力均视为非功能需求
本版本暂不开发
- sup-iam-sdk-go
- iam-webconsole
- iamctl
- iam-operating-system