企业统一门户平台架构设计方案

本方案按照正式企业级项目的标准进行设计,覆盖需求分析、业务流程、系统架构、功能模块、数据库、Redis、Token 生命周期、跨系统认证、前后端接口、安全设计、部署架构、异常处理和测试验收。

一、项目背景与需求分析

1.1 项目背景

企业内部通常存在多个独立业务系统,例如:

  • 智能问答系统
  • 数据分析系统
  • 文档管理系统
  • 业务管理系统
  • 视频监控系统
  • 流程审批系统

这些系统可能由不同团队开发,拥有各自的访问地址和认证方式,用户需要记住不同的访问入口,管理人员也需要分别维护各系统的访问配置。

因此,需要建设统一门户平台,将各业务系统集中到一个入口,通过统一认证、统一服务管理和统一访问控制,实现业务系统的集中接入。

1.2 核心需求

需求一:统一认证

用户访问门户时,系统获取客户端 IP,根据 IP 和服务访问规则进行认证。

认证规则:

  1. 默认 Token 有效期为 1 小时。
  2. 管理员可以针对每个业务服务设置独立的 Token 有效期。
  3. 如果服务没有设置自定义有效期,则继承全局默认值。
  4. 每个 IP 对每个服务每天默认只能申请一次 Token。
  5. Token 到期后,当天不能再次申请。
  6. Token 过期时,提示用户:访问期限已到,请联系管理员。
  7. 每天 00:00 重置每日申请资格。
  8. 每个业务系统都可以调用统一认证中心验证 Token。

需求二:门户服务管理

管理员可以动态配置门户卡片。

卡片配置内容:

  • 服务名称
  • 服务编码
  • 服务图标
  • 服务描述
  • 服务跳转地址
  • Token 有效期
  • 每日申请次数
  • 是否绑定 IP
  • 是否允许续期
  • 卡片排序
  • 是否启用

需求三:业务系统跳转

用户进入门户后,能够看到具有访问权限的业务系统卡片。

点击卡片后:

  1. 门户获取服务配置。
  2. 检查用户/IP 是否具备申请资格。
  3. 获取该服务的 Token 策略。
  4. 签发对应服务的 Token,或者复用已有有效 Token。
  5. 生成一次性 Ticket。
  6. 跳转到目标业务系统。
  7. 业务系统使用 Ticket 向认证中心交换授权。
  8. 业务系统建立本地会话。
  9. 后续访问由业务系统和统一认证中心共同控制。

1.3 核心业务规则

首先明确本方案采用的业务规则:

规则 默认配置 是否可配置
全局 Token 有效期 60 分钟 是
服务 Token 有效期 继承全局配置 是
每日申请次数 1 次/IP/服务 是
每日重置时间 00:00 是,建议固定时区
Token 绑定 IP 开启 是
Ticket 有效期 60 秒 是
Token 是否允许续期 否 是
Token 是否允许主动撤销 是 是
Token 是否跨服务使用 否 否

注意:每日申请次数和 Token 有效期是两个独立概念。

例如:

  • 智能问答配置 30 分钟有效期,每天只能申请一次。那么用户 09:00 获得 Token,09:30 过期后,当天不能再次申请。
  • 如果数据分析配置 4 小时有效期,则用户可以在 4 小时内访问数据分析,但不会影响智能问答的访问。

二、总体系统架构设计

2.1 架构设计思路

采用分层架构,将系统划分为:

  1. 前端展示层
  2. API 接入层
  3. 门户业务层
  4. 统一认证层
  5. 数据存储层
  6. 业务系统接入层

2.2 总体架构图

2.3 技术选型

层次 技术 作用
前端 Vue3 + TypeScript 门户首页
UI Element Plus 卡片、表单、管理后台
状态管理 Pinia 登录态、Token 状态
HTTP Axios API 调用
后端 Spring Boot 3 核心业务服务
安全 Spring Security 管理员认证、接口权限
数据库 MySQL 8 持久化数据
缓存 Redis Token、Ticket、限流
持久层 MyBatis-Plus 数据访问
网关 Nginx 反向代理、IP 获取
认证协议 自定义 Ticket + OAuth2 思路 跨系统授权
日志 Logback + ELK/Loki 日志采集
监控 Prometheus + Grafana 运行状态监控

三、功能模块详细设计

建议划分为六个核心模块。

3.1 用户门户模块

功能:

  • 门户首页展示。
  • 业务服务卡片展示。
  • 服务分类。
  • 服务搜索。
  • 服务点击跳转。
  • Token 剩余时间展示。
  • Token 过期提醒。
  • 访问异常记录。

页面结构:

门户首页不需要提前为所有服务生成 Token。只有点击某个服务时,才进入该服务的授权流程。

3.2 服务管理模块

管理员可以维护业务服务。

功能包括:

  • 新增服务。
  • 修改服务。
  • 删除服务(建议逻辑删除)。
  • 启用或禁用服务。
  • 配置跳转地址。
  • 配置 Token 有效期。
  • 配置每日申请次数。
  • 配置 IP 绑定。
  • 配置服务访问权限。
  • 配置卡片展示顺序。
  • 访问异常记录。

服务配置应支持动态生效,不需要重新部署前端和后端。

3.3 统一认证模块

核心功能:

功能 说明
Token 签发 根据服务策略生成 Token
Token 校验 校验签名、状态、有效期
Token 撤销 管理员主动注销
Token 续期 根据服务策略决定是否允许
Ticket 签发 跨系统跳转凭证
Ticket 交换 业务系统使用 Ticket 换取授权
IP 校验 对比签发 IP 与访问 IP
服务校验 校验 Token 是否属于当前服务

3.4 权限管理模块

建议支持三个维度:

  1. 用户权限:哪些用户可以访问哪些服务。
  2. IP 权限:哪些 IP 可以申请访问。
  3. 服务权限:Token 是否允许访问当前服务。

权限判定:

\[ Allow = UserAllowed \land IPAllowed \land ServiceEnabled \]

如果暂时没有用户体系,可以先实现 IP + 服务权限,但要预留用户 ID 字段。

3.5 Token 管理模块

管理员可以查看:

  • Token 编号。
  • 关联用户。
  • 客户端 IP。
  • 所属服务。
  • 签发时间。
  • 过期时间。
  • Token 状态。
  • 是否撤销。
  • 异常服务

支持:

  • 查询 Token。
  • 查看 Token 详情。
  • 主动撤销。
  • 查询历史申请记录。
  • 异常服务查看

注意:不建议在管理后台展示 Token 明文。

3.6 日志审计模块

需要记录:

  • 用户访问门户日志。
  • Token 签发日志。
  • Token 校验日志。
  • Ticket 交换日志。
  • 服务跳转日志。
  • Token 撤销日志。
  • 管理员配置变更日志。

重点记录失败原因,以便后续分析用户无法访问的原因。

四、核心认证机制设计

4.1 认证模型

认证分为两个层次:

  • 第一层:门户访问会话

用户进入门户后,建立门户自己的会话,负责用户身份识别、门户权限控制和卡片展示。

  • 第二层:业务服务 Token

用户点击某个业务卡片时,系统为该服务签发独立 Token。

这样可以避免所有业务系统共用一个 Token。

结构:

1
2
3
4
5
6
7
8
9
10
11
12
用户
|
v
门户访问会话
|
+----> 智能问答 Token(60分钟)
|
+----> 数据分析 Token(120分钟)
|
+----> 文档管理 Token(30分钟)
|
+----> 流程管理 Token(60分钟)

门户会话本身建议使用 HttpOnly Cookie,不能直接复用业务服务 Token。

4.2 Token 类型选择

使用随机不透明 Token,而不是直接使用 JWT。

原因:

  • Token 需要统一撤销。
  • Token 有独立的服务有效期。
  • 每日申请资格需要集中控制。
  • 需要即时判断服务权限。
  • 多个业务系统需要统一认证。

随机 Token 生成:

1
2
3
4
5
6
7
8
9
10
11
public String generateToken() {

byte[] bytes = new byte[32];

SecureRandom random = new SecureRandom();
random.nextBytes(bytes);

return Base64.getUrlEncoder()
.withoutPadding()
.encodeToString(bytes);
}

生成的 Token 有 256 bit 随机熵,足以抵抗暴力猜测。

Redis 和数据库只保存 Token 哈希值,原始 Token 只在签发和安全交换过程中短暂使用。

4.3 Token 生命周期

Token 生命周期:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
      申请服务访问
|
v
查询服务配置
|
v
检查每日申请资格
|
+------+------+
| |
已申请 未申请
| |
v v
检查已有Token 生成Token
| |
+---+---+ v
| | 保存状态
有效 过期 |
| | |
v v v
复用 提示拒绝 返回授权
| |
+--------+--------+
|
v
生成Ticket
|
v
跳转业务系统
|
v
Token过期
|
v
当天禁止重新申请

注意:每日申请限制占用的是签发资格,而不是每次点击卡片都重新占用。

同一个服务重复点击时:

  • Token 仍然有效:复用已有授权。
  • Token 已经过期:提示访问期限已到。
  • Token 被管理员撤销:拒绝访问。
  • 第二天:重新获得申请资格。

4.4 Token 有效期计算

\[ ExpiresAt = IssuedAt + ExpireMinutes \times 60 \]

配置优先级:

1
2
3
4
5
6
7
8
9
10
11
12
      服务级 Token 有效期
|
v
是否启用自定义?
/ \
是 否
| |
自定义分钟数 全局默认60分钟
| |
+------v-------+
|
签发Token

必须保存签发时的有效期快照。

比如:

  • 09:00 签发 Token,有效期 60 分钟。
  • 09:30 管理员修改配置为 120 分钟。
  • 该 Token 仍然 10:00 过期。
  • 下一次签发才使用 120 分钟。

这样可以避免服务配置变化影响正在使用的业务系统。

五、完整业务流程设计

5.1 用户访问门户流程

  1. 用户访问门户

    浏览器请求门户首页。

  2. 获取访问 IP

    Nginx 从可信代理链获取真实客户端 IP。

  3. 门户身份认证

    有用户账号体系时验证用户身份;无账号体系时按配置执行 IP 准入。

  4. 建立门户会话

    使用安全 Cookie 保存门户会话。

  5. 获取服务卡片

    根据用户权限返回可访问的业务服务。

5.2 点击服务卡片流程

  1. 用户点击服务

    前端传递 serviceCode。

  2. 服务配置查询

    查询服务是否启用,以及 Token 有效期。

  3. 访问权限检查

    校验用户、IP 和服务权限。

  4. 查询 Token

    检查当前用户/IP + 服务是否已经存在有效 Token。

  5. 签发或复用 Token

    首次申请签发;重复点击复用有效授权。

  6. 创建一次性 Ticket

    生成 60 秒有效的随机授权码,绑定服务、Token 和跳转地址。

  7. 跳转业务系统

    通过 POST 表单提交 Ticket。

  8. 业务系统兑换 Ticket

    服务端通过认证中心交换授权,建立本地 Session。

5.3 跨系统认证时序图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

sequenceDiagram
autonumber
participant U as 用户浏览器
participant P as 门户前端
participant PS as Portal Service
participant A as Auth Service
participant R as Redis
participant B as 业务系统A

U->>P: 访问门户
P->>PS: 获取服务卡片
PS->>A: 验证门户会话
A-->>PS: 认证成功
PS-->>P: 返回卡片列表

U->>P: 点击智能问答
P->>PS: POST /portal/launch
PS->>A: 申请服务Token
A->>R: 查询每日申请记录及Token
R-->>A: 返回授权状态
A->>R: 原子签发或读取Token状态
A-->>PS: 返回授权结果

PS->>A: 创建一次性Ticket
A->>R: 保存Ticket,TTL=60秒
A-->>PS: 返回Ticket
PS-->>P: 返回跳转地址和Ticket

P->>B: POST /sso/callback,提交Ticket
B->>A: 服务端兑换Ticket
A->>R: 原子校验并消费Ticket
A-->>B: 返回服务授权结果
B-->>U: 设置HttpOnly Session Cookie

U->>B: 访问业务页面
B->>A: 校验服务授权
A-->>B: Token有效
B-->>U: 返回业务页面

5.4 Token 过期流程

当 Token 过期时:

  1. 业务系统访问认证中心。
  2. 认证中心判断 Token 已过期。
  3. 返回 40101。
  4. 业务系统清理本地 Session。
  5. 前端跳转到过期提示页面。
  6. 用户点击返回门户。
  7. 当天申请资格仍然被占用,不能重新签发。
  8. 提示联系管理员。

统一错误返回:

1
2
3
4
5
6
{
"code": 40101,
"message": "访问期限已到,请联系管理员",
"serviceCode": "AI_QA",
"expiredAt": 1794708000
}

六、数据库详细设计

8 张核心表。

6.1 表结构关系

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

erDiagram
PORTAL_USER ||--o{ PORTAL_USER_SERVICE : has
PORTAL_SERVICE ||--o{ PORTAL_USER_SERVICE : grants
PORTAL_SERVICE ||--o{ PORTAL_TOKEN_RECORD : issues
PORTAL_USER ||--o{ PORTAL_TOKEN_RECORD : owns
PORTAL_SERVICE ||--o{ PORTAL_DAILY_RECORD : limits
PORTAL_TOKEN_RECORD ||--o{ PORTAL_TICKET_RECORD : authorizes
PORTAL_SERVICE ||--o{ PORTAL_ACCESS_LOG : records
PORTAL_USER ||--o{ PORTAL_ACCESS_LOG : operates

PORTAL_USER {
bigint id PK
varchar username
varchar status
}
PORTAL_SERVICE {
bigint id PK
varchar service_code
varchar service_name
int token_expire_minutes
int daily_limit
}
PORTAL_USER_SERVICE {
bigint id PK
bigint user_id FK
bigint service_id FK
}
PORTAL_TOKEN_RECORD {
bigint id PK
varchar token_id
varchar token_hash
varchar service_code
datetime expires_at
}
PORTAL_DAILY_RECORD {
bigint id PK
varchar subject_key
varchar service_code
date apply_date
}
PORTAL_TICKET_RECORD {
bigint id PK
varchar ticket_hash
varchar token_id
datetime expires_at
}
PORTAL_ACCESS_LOG {
bigint id PK
varchar service_code
varchar operation
varchar result
}

6.2 核心表说明

表名 作用
portal_user 用户信息
portal_service 服务卡片及 Token 策略
portal_user_service 用户服务授权
portal_token_record Token 签发记录
portal_daily_record 每日申请记录
portal_ticket_record Ticket 交换审计
portal_access_log 用户访问日志
portal_admin_log 管理员操作日志

6.3 服务配置表

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
CREATE TABLE portal_service (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
service_code VARCHAR(64) NOT NULL,
service_name VARCHAR(100) NOT NULL,
service_url VARCHAR(500) NOT NULL,
icon VARCHAR(500),
description VARCHAR(500),

token_expire_minutes INT NOT NULL DEFAULT 60,
use_default_expire TINYINT NOT NULL DEFAULT 1,

daily_limit INT NOT NULL DEFAULT 1,
bind_ip TINYINT NOT NULL DEFAULT 1,
allow_renew TINYINT NOT NULL DEFAULT 0,

enabled TINYINT NOT NULL DEFAULT 1,
sort INT NOT NULL DEFAULT 0,

deleted TINYINT NOT NULL DEFAULT 0,

create_by VARCHAR(64),
create_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
update_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
ON UPDATE CURRENT_TIMESTAMP,

UNIQUE KEY uk_service_code (service_code)
);

6.4 用户表

1
2
3
4
5
6
7
8
9
10
CREATE TABLE portal_user (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
username VARCHAR(100) NOT NULL,
display_name VARCHAR(100),
password_hash VARCHAR(255),
status TINYINT NOT NULL DEFAULT 1,
create_time DATETIME DEFAULT CURRENT_TIMESTAMP,

UNIQUE KEY uk_username (username)
);

6.5 用户服务权限表

1
2
3
4
5
6
7
8
9
CREATE TABLE portal_user_service (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
user_id BIGINT NOT NULL,
service_id BIGINT NOT NULL,
enabled TINYINT NOT NULL DEFAULT 1,
create_time DATETIME DEFAULT CURRENT_TIMESTAMP,

UNIQUE KEY uk_user_service (user_id, service_id)
);

6.6 Token 记录表

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
CREATE TABLE portal_token_record (
id BIGINT PRIMARY KEY AUTO_INCREMENT,

token_id VARCHAR(64) NOT NULL,
token_hash VARCHAR(128) NOT NULL,

subject_id VARCHAR(128),
client_ip VARCHAR(64),
ip_hash VARCHAR(128),

service_code VARCHAR(64) NOT NULL,

expire_minutes INT NOT NULL,

issued_at DATETIME NOT NULL,
expires_at DATETIME NOT NULL,

status VARCHAR(20) NOT NULL,

revoke_time DATETIME,
revoke_reason VARCHAR(500),

create_time DATETIME DEFAULT CURRENT_TIMESTAMP,

UNIQUE KEY uk_token_id (token_id),
KEY idx_subject_service (subject_id, service_code),
KEY idx_ip_service (ip_hash, service_code),
KEY idx_expires_at (expires_at)
);

6.7 每日申请记录表

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
CREATE TABLE portal_daily_record (
id BIGINT PRIMARY KEY AUTO_INCREMENT,

subject_key VARCHAR(128) NOT NULL,
ip_hash VARCHAR(128) NOT NULL,
service_code VARCHAR(64) NOT NULL,

apply_date DATE NOT NULL,
apply_count INT NOT NULL DEFAULT 1,

last_token_id VARCHAR(64),

create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
update_time DATETIME DEFAULT CURRENT_TIMESTAMP
ON UPDATE CURRENT_TIMESTAMP,

UNIQUE KEY uk_subject_service_date (
subject_key,
service_code,
apply_date
)
);

如果业务规则是每日一次,这个表的 apply_count 最大值为 1。如果以后允许每天申请多次,可以利用该字段实现。

6.8 Ticket 记录表

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
CREATE TABLE portal_ticket_record (
id BIGINT PRIMARY KEY AUTO_INCREMENT,

ticket_hash VARCHAR(128) NOT NULL,
token_id VARCHAR(64) NOT NULL,

service_code VARCHAR(64) NOT NULL,
client_ip VARCHAR(64),

status VARCHAR(20) NOT NULL DEFAULT 'ISSUED',

expires_at DATETIME NOT NULL,
consumed_at DATETIME,

create_time DATETIME DEFAULT CURRENT_TIMESTAMP,

UNIQUE KEY uk_ticket_hash (ticket_hash),
KEY idx_token_id (token_id)
);

Ticket 的实际消费状态以 Redis 原子操作为准,MySQL 用于审计和追溯。

七、Redis 详细设计

Redis 是整个系统的实时认证状态中心。

7.1 Redis Key 规划

Key Value TTL
portal:token:{jti} Token 元信息 Token 剩余有效期
portal:daily:{subject}:{service}:{date} 申请记录 至次日零点
portal:ticket:{ticketHash} Ticket 元信息 60 秒
portal:service:{serviceCode} 服务配置缓存 5~10 分钟
portal:session:{sessionId} 门户会话 按门户会话策略
portal:token:revoke:{jti} 撤销标记 Token 剩余有效期

生产环境对 IP 和用户 ID 进行规范化后计算哈希,避免 Redis Key 中出现原始敏感信息。

7.2 Token Redis 数据结构

1
2
3
4
5
6
7
8
9
10
{
"tokenId": "uuid",
"tokenHash": "sha256-value",
"subjectId": "user-001",
"ipHash": "ip-hash",
"serviceCode": "AI_QA",
"issuedAt": 1794704400,
"expiresAt": 1794708000,
"status": "ACTIVE"
}

7.3 每日申请资格控制

使用 Redis 的 SET NX EX 或 Lua 脚本实现原子控制。

Key:portal:daily:{subjectKey}:{serviceCode}:{yyyyMMdd}

Lua 脚本:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
-- KEYS[1] 每日申请Key
-- ARGV[1] Token ID
-- ARGV[2] TTL

local result = redis.call(
'SET',
KEYS[1],
ARGV[1],
'NX',
'EX',
ARGV[2]
)

if result then
return 1
end

return 0

如果需要支持每日 N 次,则可以使用 Lua 对计数器进行原子递增。

注意:Redis 操作与 MySQL 事务并非天然原子。应使用幂等申请 ID、失败补偿和状态恢复机制处理跨存储失败。

7.4 Token 过期判断

不能仅仅依赖 Redis TTL。

业务层仍需检查:

1
2
3
4
5
6
7
8
9
10
11
if (token == null) {
return TokenStatus.NOT_FOUND;
}

if (token.getStatus() == REVOKED) {
return TokenStatus.REVOKED;
}

if (System.currentTimeMillis() >= token.getExpiresAt()) {
return TokenStatus.EXPIRED;
}

Redis TTL 负责回收数据,业务过期时间负责最终判定。

八、后端接口设计

建议统一接口前缀:

1
2
3
4
5
/api/portal/**
/api/admin/**
/api/auth/**
/api/sso/**
/api/service/**

接口分为门户接口、管理接口、认证接口和业务系统接入接口。

8.1 门户接口

接口 方法 说明
/api/portal/session GET 获取门户会话信息
/api/portal/cards GET 获取当前用户可访问的卡片
/api/portal/services GET 获取服务列表
/api/portal/launch POST 启动业务服务
/api/portal/token/status GET 查询服务 Token 状态

启动服务接口

1
POST /api/portal/launch

请求:

1
2
3
{
"serviceCode": "AI_QA"
}

返回:

1
2
3
4
5
6
7
8
9
10
11
12
{
"code": 200,
"message": "success",
"data": {
"redirectUrl": "https://ai.example.com/sso/callback",
"ticket": "random-one-time-ticket",
"ticketExpireSeconds": 60,
"serviceCode": "AI_QA",
"tokenExpiresAt": 1794708000,
"tokenExpireMinutes": 60
}
}

注意:门户后端不需要把真实 Token 返回给浏览器。它负责检查授权、生成 Ticket,Ticket 关联服务授权记录。业务系统兑换 Ticket 时,由认证中心返回授权结果。

8.2 管理后台接口

接口 方法 说明
/api/admin/service/page GET 服务分页查询
/api/admin/service POST 新增服务
/api/admin/service/{id} PUT 修改服务
/api/admin/service/{id} DELETE 删除服务
/api/admin/service/{id}/status PUT 启用/禁用服务
/api/admin/service/{id}/policy PUT 修改 Token 策略
/api/admin/user-service POST 配置用户服务权限
/api/admin/token/page GET Token 记录查询
/api/admin/token/{id}/revoke POST 撤销 Token
/api/admin/log/page GET 操作日志查询

8.3 认证中心接口

接口 方法 说明
/api/auth/token/issue POST 签发服务授权
/api/auth/token/validate POST 验证 Token
/api/auth/token/revoke POST 撤销 Token
/api/auth/token/status GET 查询 Token 状态
/api/auth/ticket/create POST 创建 Ticket
/api/auth/ticket/exchange POST 兑换 Ticket
/api/auth/ticket/consume POST 消费 Ticket

其中,issue、validate、exchange 等接口需要区分调用主体:

  • 门户调用:使用门户服务身份认证。
  • 业务系统调用:使用业务系统的 Client ID 和 Client Secret,或者 mTLS。
  • 管理员调用:使用管理员登录身份及 RBAC 权限。

不能只依赖传入的 serviceCode 判断调用方身份。

8.4 业务系统接入接口

认证中心为每个业务系统注册唯一的客户端身份。

例如:

1
2
3
4
5
6
{
"clientId": "AI_QA_CLIENT",
"serviceCode": "AI_QA",
"clientName": "智能问答系统",
"clientStatus": "ACTIVE"
}

业务系统接入后,使用服务端凭证调用:

1
POST /api/auth/ticket/exchange

请求:

1
2
3
4
{
"ticket": "random-one-time-ticket",
"clientId": "AI_QA_CLIENT"
}

认证中心校验 Ticket、业务系统身份、服务编码、IP 和关联授权状态。

返回:

1
2
3
4
5
6
7
8
9
10
{
"code": 200,
"data": {
"grantId": "grant-001",
"subjectId": "user-001",
"serviceCode": "AI_QA",
"expiresAt": 1794708000,
"status": "ACTIVE"
}
}

业务系统使用 grantId 关联自己的本地 Session。

注意:grantId 只是授权记录标识,不是可以独立使用的认证凭证。

业务系统每次需要校验授权时,使用自己的服务端身份调用认证中心,传递 grantId。认证中心根据授权记录进行验证。这样不需要把原始 Token 明文保存或暴露给浏览器。

如果未来业务系统希望直接使用 Bearer Token,也可以在 Ticket 交换时由认证中心签发独立的服务访问 Token,并且将它绑定到原始 grant 的过期时间和撤销状态。

九、前端系统设计

9.1 前端项目结构

采用 Vue3 + TypeScript + Vite + Pinia。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
portal-web/
│
├── src/
│ ├── api/
│ │ ├── portal.ts
│ │ ├── service.ts
│ │ ├── auth.ts
│ │ └── admin.ts
│ │
│ ├── components/
│ │ ├── ServiceCard.vue
│ │ ├── TokenCountdown.vue
│ │ ├── ExpireDialog.vue
│ │ └── SearchBar.vue
│ │
│ ├── layouts/
│ │ ├── PortalLayout.vue
│ │ └── AdminLayout.vue
│ │
│ ├── views/
│ │ ├── portal/
│ │ │ ├── Home.vue
│ │ │ └── Expired.vue
│ │ │
│ │ └── admin/
│ │ ├── ServiceList.vue
│ │ ├── ServiceEdit.vue
│ │ ├── TokenList.vue
│ │ ├── PermissionList.vue
│ │ └── AuditList.vue
│ │
│ ├── stores/
│ │ ├── user.ts
│ │ └── portal.ts
│ │
│ ├── router/
│ ├── utils/
│ ├── types/
│ └── App.vue
│
├── package.json
└── vite.config.ts

9.2 服务卡片组件设计

ServiceCard.vue

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
<template>
<el-card
class="service-card"
shadow="hover"
@click="handleClick"
>
<div class="card-content">
<el-image
:src="service.icon"
class="service-icon"
/>

<div class="service-name">
{{ service.serviceName }}
</div>

<div class="service-desc">
{{ service.description }}
</div>

<div class="service-expire">
有效期:{{ service.expireMinutes }} 分钟
</div>
</div>
</el-card>
</template>

<script setup lang="ts">

interface Service {
serviceCode: string
serviceName: string
icon: string
description: string
expireMinutes: number
}

const props = defineProps<{
service: Service
}>()

const emit = defineEmits<{
click: [service: Service]
}>()

function handleClick() {
emit('click', props.service)
}

</script>

9.3 服务跳转逻辑

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
import { ElMessage } from 'element-plus'
import { launchService } from '@/api/portal'

export async function openService(serviceCode: string) {
try {
const result = await launchService({
serviceCode
})

// 由后端返回经过白名单校验的跳转地址
const { redirectUrl, ticket } = result.data

const form = document.createElement('form')

form.method = 'POST'
form.action = redirectUrl
form.target = '_blank'

const input = document.createElement('input')

input.type = 'hidden'
input.name = 'ticket'
input.value = ticket

form.appendChild(input)
document.body.appendChild(form)

form.submit()
form.remove()

} catch (error: any) {

if (error.response?.data?.code === 40101) {
ElMessage.error('访问期限已到,请联系管理员')
return
}

ElMessage.error('服务访问失败')
}
}

生产环境还需要处理浏览器弹窗拦截问题:建议在用户点击时同步预打开一个空白窗口,待服务端返回 Ticket 后再向该窗口提交表单;请求失败则关闭空白窗口。

9.4 Token 倒计时组件

前端倒计时不应该依赖用户本地时间作为唯一判断依据。

应该使用后端返回的 expiresAt 和服务器时间计算剩余时长。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
const remaining = ref(0)

function updateRemaining(expiresAt: number, serverNow: number) {

const duration = expiresAt - serverNow

remaining.value = Math.max(
0,
Math.floor(duration / 1000)
)
}

const countdownText = computed(() => {

const hours = Math.floor(remaining.value / 3600)

const minutes = Math.floor(
(remaining.value % 3600) / 60
)

const seconds = remaining.value % 60

return [
hours,
minutes,
seconds
].map(v => String(v).padStart(2, '0')).join(':')

})

服务卡片上展示:

  • 未申请:尚未访问。
  • 使用中:剩余时间。
  • 已过期:访问期限已到。
  • 已撤销:服务授权已被管理员撤销。

对于用户已经打开的多个业务系统,应分别管理每个服务的倒计时。

十、业务系统接入方案

这是系统能否真正落地的关键。

不能只完成门户跳转,还需要确保各业务系统在跳转后能够独立验证授权。

10.1 接入方式

建议提供统一的 Spring Boot Starter:

1
2
3
4
5
6
7
8
9
portal-auth-spring-boot-starter
│
├── PortalAuthAutoConfiguration
├── PortalAuthProperties
├── PortalAuthInterceptor
├── PortalAuthClient
├── PortalSessionManager
├── PortalExceptionHandler
└── PortalAuthFilter

每个业务系统引入依赖:

1
2
3
4
5
<dependency>
<groupId>com.company</groupId>
<artifactId>portal-auth-spring-boot-starter</artifactId>
<version>1.0.0</version>
</dependency>

配置:

1
2
3
4
5
6
7
8
9
10
11
portal:
auth:
server: https://auth.example.com
client-id: AI_QA_CLIENT
client-secret: ${PORTAL_CLIENT_SECRET}
service-code: AI_QA

connect-timeout: 2000
read-timeout: 3000

fail-open: false

这里的 client-secret 必须放在服务端安全配置中,不能暴露给浏览器。

10.2 业务系统接入流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
用户点击门户卡片
|
v
业务系统接收Ticket
|
v
PortalAuthClient兑换Ticket
|
v
认证中心返回授权结果
|
v
业务系统建立Session
|
v
用户访问业务页面
|
v
PortalAuthInterceptor
|
v
校验本地Session和授权状态
|
v
请求认证中心验证Grant
|
+---+---+
| |
有效 过期/撤销
| |
v v
放行 清除Session
|
v
提示联系管理员

10.3 业务系统每次请求如何校验

  • 本地 Session 保存 grantId、serviceCode、expiresAt。
  • 每次请求先检查本地过期时间。
  • 使用短时间授权状态缓存,例如 10~30 秒。
  • 管理员撤销 Token 时,通过 Redis Pub/Sub 或消息通知主动清除相关缓存。
  • 高安全级别接口可以强制实时查询认证中心。

注意:明确安全边界,如果使用 30 秒缓存,撤销操作可能存在最多约 30 秒的传播延迟。要求即时撤销的系统不能依赖普通短缓存。

另外,业务系统的本地 Session 必须设置:

\[ SessionExpiry \leq GrantExpiry \]

不能让本地 Session 的过期时间超过授权过期时间。

十一、安全设计

统一门户虽然业务逻辑不复杂,但它相当于企业所有业务系统的统一入口,因此安全设计非常重要。

11.1 IP 获取安全

Nginx 配置:

1
2
3
4
5
6
7
8
9
10
11
location /api/ {

proxy_pass http://portal_backend;

proxy_set_header Host $host;

proxy_set_header X-Real-IP $remote_addr;

proxy_set_header X-Forwarded-For
$proxy_add_x_forwarded_for;
}

Spring Boot 只能信任来自指定代理的 IP 转发头。

不能直接信任用户自己构造的 X-Forwarded-For,否则用户可以伪造 IP 绕过每日申请限制。

11.2 Token 安全

采用以下措施:

安全措施 具体实现
高强度随机数 SecureRandom,至少 256 bit
Token 哈希 SHA-256
Token 传输 HTTPS
Token 存储 Redis、MySQL 仅保存哈希
Token 过期 服务独立有效期
Token 撤销 维护授权状态
服务隔离 serviceCode 绑定
IP 绑定 签发 IP 与请求 IP 比较
防重放 Ticket 一次性消费
敏感信息 日志脱敏

11.3 Ticket 安全

Ticket 必须满足:

  1. 随机生成,不能通过递增 ID 生成。
  2. 有效期默认 60 秒。
  3. 只能使用一次。
  4. 必须绑定目标服务。
  5. 必须绑定业务系统客户端身份。
  6. 只能从指定业务系统兑换。
  7. 兑换成功后立即失效。
  8. Ticket 不得出现在 URL Query 参数中。

建议使用 Redis Lua 实现原子消费:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
-- KEYS[1] Ticket Key
-- ARGV[1] 目标服务编码
-- ARGV[2] 客户端ID

local data = redis.call('GET', KEYS[1])

if not data then
return -1
end

local ticket = cjson.decode(data)

if ticket.serviceCode ~= ARGV[1] then
return -2
end

if ticket.clientId ~= ARGV[2] then
return -3
end

if ticket.status ~= 'ISSUED' then
return -4
end

redis.call('DEL', KEYS[1])

return 1

实际实现时,建议通过 Lua 完成读取、校验和删除的原子操作,并将 Ticket 绑定的 grantId 一并返回。

11.4 服务跳转安全

这是一个容易遗漏的安全问题。

假设管理员配置了:

1
https://ai.example.com

如果允许普通用户修改跳转地址,可能造成开放重定向,甚至将 Ticket 泄露到恶意网站。

采用:

  • 跳转地址只能由管理员配置。
  • 限制 HTTPS 地址。
  • 禁止 javascript: 等危险协议。
  • 对域名进行白名单校验。
  • Ticket 只能兑换到指定服务。
  • 禁止用户提交任意跳转地址。

11.5 管理后台安全

建议采用 RBAC:

角色 权限
超级管理员 所有管理功能
服务管理员 管理指定服务
审计人员 查看日志、Token 记录
普通用户 访问授权服务

管理员修改 Token 有效期、每日申请次数、服务地址时,必须记录修改前后内容。

十二、异常处理与高可用设计

12.1 核心异常场景

异常场景 处理策略
Token 不存在 返回 40102
Token 过期 返回 40101
Token 被撤销 返回 40103
IP 不匹配 返回 40301
服务编码不匹配 返回 40302
服务已禁用 拒绝访问
每日申请次数已用完 提示联系管理员
Ticket 过期 重新发起跳转,但不重新签发 Token
Ticket 重复使用 拒绝兑换
Redis 不可用 认证失败,告警
MySQL 不可用 停止新授权签发,已有授权按安全策略处理
认证中心不可用 高安全业务默认拒绝访问

12.2 Redis 与 MySQL 一致性

假设:

  1. Redis 成功写入每日申请记录。
  2. Token 写入 Redis 失败。
  3. MySQL 写入也失败。

就会出现用户已经占用了每日申请资格,但实际上没有获得 Token 的情况。

使用状态机:

1
2
3
4
5
6
7
8
9
10
11
12
13
INIT
|
v
RESERVED
|
v
ISSUED
|
+------> FAILED
|
+------> REVOKED
|
+------> EXPIRED

处理过程:

  1. 生成唯一 requestId。
  2. MySQL 创建 INIT 申请记录。
  3. Redis 原子占用每日申请资格。
  4. 保存 Token 哈希及状态。
  5. 更新申请记录为 ISSUED。
  6. 只有 ISSUED 状态才允许创建 Ticket。

如果第 3~5 步失败:

  • 记录失败原因。
  • 执行补偿。
  • 对已经失败的申请释放资格,或者由管理员处理。
  • 通过定时任务检查长时间处于 RESERVED 的申请记录。

Redis Lua 只能保证 Redis 内部操作原子性,不能代替 MySQL 事务。

12.3 高可用部署

组件 部署策略
Nginx 双节点负载均衡
Portal Service 至少 2 个实例
Auth Service 至少 2 个实例
MySQL 主从或高可用集群
Redis Sentinel 或 Cluster
业务系统 独立部署
日志服务 集中式日志管理

12.4 认证中心性能优化

认证中心是整个系统的关键服务,需要重点考虑:

  • Token 校验接口无状态化。
  • Redis Pipeline 批量查询。
  • 服务配置使用本地缓存 + Redis 缓存。
  • 对相同 grantId 的重复校验进行短时缓存。
  • 使用连接池管理数据库和 Redis。
  • 限制单个 IP 的认证请求频率。
  • 对认证接口进行独立监控。

设计性能目标:

指标 初期目标
Token 校验 P95 小于 100ms
Ticket 兑换 P95 小于 200ms
门户首页 P95 小于 500ms
服务签发 P95 小于 200ms
认证服务可用性 99.9%

在实际硬件、网络和并发规模下压测确认。

十三、部署架构设计

13.1 物理部署架构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

flowchart TB
U[用户浏览器]

U --> LB[Nginx负载均衡]

LB --> P1[Portal Service 1]
LB --> P2[Portal Service 2]

LB --> A1[Auth Service 1]
LB --> A2[Auth Service 2]

P1 --> R[(Redis高可用集群)]
P2 --> R
A1 --> R
A2 --> R

P1 --> DB[(MySQL高可用)]
P2 --> DB
A1 --> DB
A2 --> DB

A1 --> B1[业务系统A]
A2 --> B2[业务系统B]

B1 --> A1
B2 --> A2

P1 --> LOG[日志监控平台]
P2 --> LOG
A1 --> LOG
A2 --> LOG

注意:图中业务系统与认证中心的交互应通过 HTTPS 内网接口完成,不能依赖某一个认证实例的固定地址,应通过内部负载均衡访问认证服务。

13.2 网络安全分区

网络区域 组件 访问要求
接入区 Nginx 对外开放 HTTPS
应用区 Portal、Auth 仅接受可信入口请求
数据区 Redis、MySQL 禁止公网访问
业务区 各业务系统 通过内网访问认证中心
运维区 监控、日志 运维权限访问

十四、项目开发计划

  1. 第一阶段:基础框架搭建

    P0

    • Vue3 项目初始化
    • Spring Boot 项目初始化
    • MySQL 表结构
    • Redis 配置
    • 管理员认证
    • Nginx 配置
  2. 第二阶段:门户管理

    P0

    • 服务卡片 CRUD
    • 服务图标上传
    • 服务地址配置
    • Token 有效期配置
    • 每日申请次数配置
    • 服务启用与禁用
  3. 第三阶段:统一认证中心

    P0

    • IP 获取
    • Token 签发
    • 服务级有效期
    • 每日申请限制
    • Token 校验
    • Token 撤销
    • Ticket 生成与消费
  4. 第四阶段:业务系统接入

    P1

    • Ticket 交换
    • Spring Boot Starter
    • 业务系统 Session
    • 统一认证拦截器
    • 授权状态检查
  5. 第五阶段:安全与运维

    P1

    • RBAC 权限
    • 审计日志
    • 并发申请测试
    • Token 过期测试
    • Ticket 重放测试
    • 高可用部署

14.1 测试验收用例

编号 测试场景 预期结果
T01 首次访问智能问答 成功签发 60 分钟 Token
T02 首次访问数据分析 成功签发 120 分钟 Token
T03 修改服务有效期 只影响新签发授权
T04 同 IP 同服务重复申请 不重复占用申请资格
T05 同 IP 不同服务申请 各自独立签发
T06 Token 过期 返回 40101
T07 Token 跨服务使用 返回 40302
T08 IP 发生变化 按 IP 绑定策略拒绝
T09 管理员撤销 Token 授权失效
T10 Ticket 重复兑换 第二次拒绝
T11 Ticket 超过 60 秒 拒绝兑换
T12 100 个并发申请请求 只能成功占用一次申请资格
T13 服务被管理员禁用 不允许新建授权
T14 Redis 短暂故障 不产生错误放行
T15 业务 Session 超过 Token 期限 Session 仍按授权期限失效

还需要进行浏览器多标签页、同 IP 多用户、NAT 网络、IPv6、系统时钟偏差等专项测试。

十五、业务规则

1. 每日申请次数的限制范围

同一个 IP,每个服务每天只能申请一次(推荐)

2. Token 过期后的处理方式

允许管理员授权续期

3. 用户身份识别方式

仅根据 IP 识别,不需要用户登录

4. 业务系统的授权校验方式

统一认证中心校验 Grant + 业务系统本地 Session(推荐)

十六、最终架构

核心架构:

核心模块 最终方案
门户展示 Vue3 卡片式服务导航
管理后台 服务卡片、Token 策略、权限配置
身份识别 IP 或用户 + IP
Token 管理 随机不透明 Token / Grant
Token 有效期 全局默认 60 分钟,服务级覆盖
每日申请控制 Redis 原子控制
跨系统跳转 一次性 Ticket
业务认证 统一认证中心
本地会话 HttpOnly Cookie
数据存储 MySQL + Redis
业务接入 Spring Boot Starter
安全管理 RBAC + 审计 + IP 绑定
运维监控 日志、指标、链路追踪

设计思想:将服务配置、访问资格、Token 生命周期和业务系统会话分离。

最后更新: 2026年11月17日 16:47