新增Sa-Id模块，解决微服务内部调用鉴权问题

2025-04-30 04:45:51 +08:00 · 2021-07-24 01:10:46 +08:00 · 2021-07-24 01:10:46 +08:00 · 64beb7a18a
commit 64beb7a18a
parent bffdd0f2e1
12 changed files with 767 additions and 16 deletions
--- a/sa-token-core/src/main/java/cn/dev33/satoken/config/SaTokenConfig.java
+++ b/sa-token-core/src/main/java/cn/dev33/satoken/config/SaTokenConfig.java
@ -18,7 +18,7 @@ public class SaTokenConfig implements Serializable {
 	private String tokenName = "satoken";

 	/** token的长久有效期(单位:秒) 默认30天, -1代表永久 */
-	private long timeout = 30 * 24 * 60 * 60;
+	private long timeout = 60 * 60 * 24 * 30;

 	/**
 	 * token临时有效期 [指定时间内无操作就视为token过期] (单位: 秒), 默认-1 代表不限制
@ -70,6 +70,12 @@ public class SaTokenConfig implements Serializable {
 	 */
 	private String jwtSecretKey;
 	
+	/**
+	 * Id-Token的有效期 (单位: 秒)
+	 */
+	private long idTokenTimeout = 60 * 60 * 24;
+	
+
 	/**
 	 * SSO单点登录配置对象 
 	 */
@ -352,6 +358,22 @@ public class SaTokenConfig implements Serializable {
 		return this;
 	}

+	/**
+	 * @return Id-Token的有效期 (单位: 秒)
+	 */
+	public long getIdTokenTimeout() {
+		return idTokenTimeout;
+	}
+
+	/**
+	 * @param idTokenTimeout Id-Token的有效期 (单位: 秒)
+	 * @return 对象自身
+	 */
+	public SaTokenConfig setIdTokenTimeout(long idTokenTimeout) {
+		this.idTokenTimeout = idTokenTimeout;
+		return this;
+	}
+	
 	/**
 	 * @return SSO单点登录配置对象 
 	 */
@ -359,7 +381,6 @@ public class SaTokenConfig implements Serializable {
 		return sso;
 	}
 	
-
 	/**
 	 * @param sso SSO单点登录配置对象 
 	 */
@ -367,19 +388,15 @@ public class SaTokenConfig implements Serializable {
 		this.sso = sso;
 	}
 	
-
-	/**
-	 * toString() 
-	 */
 	@Override
 	public String toString() {
 		return "SaTokenConfig [tokenName=" + tokenName + ", timeout=" + timeout + ", activityTimeout=" + activityTimeout
-				+ ", isConcurrent=" + isConcurrent + ", isShare=" + isShare + ", isReadBody="
-				+ isReadBody + ", isReadHead=" + isReadHead + ", isReadCookie=" + isReadCookie + ", tokenStyle="
-				+ tokenStyle + ", dataRefreshPeriod=" + dataRefreshPeriod + ", tokenSessionCheckLogin="
-				+ tokenSessionCheckLogin + ", autoRenew=" + autoRenew + ", cookieDomain=" + cookieDomain
-				+ ", tokenPrefix=" + tokenPrefix + ", isPrint=" + isPrint + ", isLog=" + isLog + ", jwtSecretKey="
-				+ jwtSecretKey + ", sso=" + sso + "]";
+				+ ", isConcurrent=" + isConcurrent + ", isShare=" + isShare + ", isReadBody=" + isReadBody
+				+ ", isReadHead=" + isReadHead + ", isReadCookie=" + isReadCookie + ", tokenStyle=" + tokenStyle
+				+ ", dataRefreshPeriod=" + dataRefreshPeriod + ", tokenSessionCheckLogin=" + tokenSessionCheckLogin
+				+ ", autoRenew=" + autoRenew + ", cookieDomain=" + cookieDomain + ", tokenPrefix=" + tokenPrefix
+				+ ", isPrint=" + isPrint + ", isLog=" + isLog + ", jwtSecretKey=" + jwtSecretKey + ", idTokenTimeout="
+				+ idTokenTimeout + ", sso=" + sso + "]";
 	}
 	

--- a/sa-token-core/src/main/java/cn/dev33/satoken/exception/IdTokenInvalidException.java
+++ b/sa-token-core/src/main/java/cn/dev33/satoken/exception/IdTokenInvalidException.java
@ -0,0 +1,22 @@
+package cn.dev33.satoken.exception;
+
+/**
+ * 一个异常：代表提供的 Id-Token 无效 
+ * 
+ * @author kong
+ */
+public class IdTokenInvalidException extends SaTokenException {
+
+	/**
+	 * 序列化版本号
+	 */
+	private static final long serialVersionUID = 6806129545290130144L;
+	
+	/**
+	 * 一个异常：代表提供的 Id-Token 无效 
+	 */
+	public IdTokenInvalidException(String message) {
+		super(message);
+	}
+
+}
--- a/sa-token-core/src/main/java/cn/dev33/satoken/id/SaIdTemplate.java
+++ b/sa-token-core/src/main/java/cn/dev33/satoken/id/SaIdTemplate.java
@ -0,0 +1,172 @@
+package cn.dev33.satoken.id;
+
+import cn.dev33.satoken.SaManager;
+import cn.dev33.satoken.context.SaHolder;
+import cn.dev33.satoken.exception.IdTokenInvalidException;
+import cn.dev33.satoken.util.SaFoxUtil;
+
+/**
+ * Sa-Token-Id 身份凭证模块 
+ * <p> 身份凭证的获取与校验，可用于微服务内部调用鉴权 
+ * @author kong 
+ *
+ */
+public class SaIdTemplate {
+
+	/**
+	 * 在 Request 上储存 Id-Token 时建议使用的key 
+	 */
+	 public static final String ID_TOKEN = "SA_ID_TOKEN";
+	
+	// -------------------- 获取 & 校验 
+	
+	/**
+	 * 获取当前Id-Token, 如果不存在，则立即创建并返回 
+	 * @return 当前token
+	 */
+	public String getToken() {
+		String currentToken = getTokenNh(); 
+		if(SaFoxUtil.isEmpty(currentToken)) {
+			// 注意这里的自刷新不能做到高并发可用 
+			currentToken = refreshToken();
+		}
+		return currentToken;
+	}
+
+	/**
+	 * 判断一个Id-Token是否有效 
+	 * @param token 要验证的token
+	 * @return 这个token是否有效 
+	 */
+	public boolean isValid(String token) {
+		// 1、 如果传入的token未空，立即返回false 
+		if(SaFoxUtil.isEmpty(token)) {
+			return false;
+		}
+		
+		// 2、 验证当前 Id-Token 及 Past-Id-Token 
+		return token.equals(getToken()) || token.equals(getPastTokenNh());
+	}
+
+	/**
+	 * 校验一个Id-Token是否有效 (如果无效则抛出异常) 
+	 * @param token 要验证的token
+	 */
+	public void checkToken(String token) {
+		if(isValid(token) == false) {
+			token = (token == null ? "" : token);
+			throw new IdTokenInvalidException("无效Id-Token：" + token);
+		}
+	}
+
+	/**
+	 * 校验当前Request提供的Id-Token是否有效 (如果无效则抛出异常) 
+	 */
+	public void checkCurrentRequestToken() {
+		checkToken(SaHolder.getRequest().getHeader(ID_TOKEN));
+	}
+	
+	/**
+	 * 刷新一次Id-Token (注意集群环境中不要多个服务重复调用) 
+	 * @return 新Token 
+	 */
+	public String refreshToken() {
+		
+		// 1. 先将当前 Id-Token 写入到 Past-Id-Token 中 
+		String idToken = getTokenNh(); 
+		if(SaFoxUtil.isEmpty(idToken) == false) {
+			savePastToken(idToken, getTokenTimeout());
+		}
+		
+		// 2. 再刷新当前Id-Token 
+		String newIdToken = createToken();
+		saveToken(newIdToken);
+		
+		// 3. 返回新的 Id-Token 
+		return newIdToken;
+	}
+
+	
+	// ------------------------------ 保存Token 
+	
+	/**
+	 * 保存Id-Token
+	 * @param token
+	 */
+	public void saveToken(String token) {
+		if(SaFoxUtil.isEmpty(token)) {
+			return;
+		}
+		SaManager.getSaTokenDao().set(splicingTokenSaveKey(), token, SaManager.getConfig().getIdTokenTimeout());
+	}
+	
+	/**
+	 * 保存Past-Id-Token
+	 * @param token token
+	 * @param timeout 有效期（单位：秒）
+	 */
+	public void savePastToken(String token, long timeout){
+		if(SaFoxUtil.isEmpty(token)) {
+			return;
+		}
+		SaManager.getSaTokenDao().set(splicingPastTokenSaveKey(), token, timeout);
+	}
+	
+	
+	// -------------------- 获取Token 
+	
+	/**
+	 * 获取Id-Token，不做任何处理 
+	 * @return token 
+	 */
+	public String getTokenNh() {
+		return SaManager.getSaTokenDao().get(splicingTokenSaveKey());
+	}
+	
+	/**
+	 * 获取Past-Id-Token，不做任何处理 
+	 * @return token 
+	 */
+	public String getPastTokenNh() {
+		return SaManager.getSaTokenDao().get(splicingPastTokenSaveKey());
+	}
+
+	/**
+	 * 获取Id-Token的剩余有效期 (单位：秒) 
+	 * @return token 
+	 */
+	public long getTokenTimeout() {
+		return SaManager.getSaTokenDao().getTimeout(splicingTokenSaveKey());
+	}
+	
+
+	// -------------------- 创建Token 
+	
+	/**
+	 * 创建一个Id-Token 
+	 * @return Token 
+	 */
+	public String createToken() {
+		return SaFoxUtil.getRandomString(60);
+	}
+
+
+	// -------------------- 拼接key 
+
+	/** 
+	 * 拼接key：Id-Token的存储key
+	 * @return key
+	 */
+	public String splicingTokenSaveKey() {
+		return SaManager.getConfig().getTokenName() + ":var:id-token";
+	}
+
+	/** 
+	 * 拼接key：Id-Token的存储key
+	 * @return key
+	 */
+	public String splicingPastTokenSaveKey() {
+		return SaManager.getConfig().getTokenName() + ":var:past-id-token";
+	}
+
+}
--- a/sa-token-core/src/main/java/cn/dev33/satoken/id/SaIdUtil.java
+++ b/sa-token-core/src/main/java/cn/dev33/satoken/id/SaIdUtil.java
@ -0,0 +1,81 @@
+package cn.dev33.satoken.id;
+
+/**
+ * Sa-Token-Id 身份凭证模块-工具类 
+ * @author kong
+ *
+ */
+public class SaIdUtil {
+
+	/**
+	 * 在 Request 上储存 Id-Token 时建议使用的key 
+	 */
+	public static final String ID_TOKEN = SaIdTemplate.ID_TOKEN;
+
+	/**
+	 * 底层 SaIdTemplate 对象 
+	 */
+	public static SaIdTemplate saIdTemplate = new SaIdTemplate();
+	
+	// -------------------- 获取 & 校验 
+	
+	/**
+	 * 获取当前Id-Token, 如果不存在，则立即创建并返回 
+	 * @return 当前token
+	 */
+	public static String getToken() {
+		return saIdTemplate.getToken();
+	}
+
+	/**
+	 * 判断一个Id-Token是否有效 
+	 * @param token 要验证的token
+	 * @return 这个token是否有效 
+	 */
+	public static boolean isValid(String token) {
+		return saIdTemplate.isValid(token);
+	}
+
+	/**
+	 * 校验一个Id-Token是否有效 (如果无效则抛出异常) 
+	 * @param token 要验证的token
+	 */
+	public static void checkToken(String token) {
+		saIdTemplate.checkToken(token);
+	}
+
+	/**
+	 * 校验当前Request提供的Id-Token是否有效 (如果无效则抛出异常) 
+	 */
+	public static void checkCurrentRequestToken() {
+		saIdTemplate.checkCurrentRequestToken();
+	}
+	
+	/**
+	 * 刷新一次Id-Token (注意集群环境中不要多个服务重复调用)
+	 * @return 新Token 
+	 */
+	public static String refreshToken() {
+		return saIdTemplate.refreshToken();
+	}
+
+	
+	// -------------------- 获取Token 
+	
+	/**
+	 * 获取Id-Token，不做任何处理 
+	 * @return token 
+	 */
+	public static String getTokenNh() {
+		return saIdTemplate.getTokenNh();
+	}
+	
+	/**
+	 * 获取Past-Id-Token，不做任何处理 
+	 * @return token 
+	 */
+	public static String getPastTokenNh() {
+		return saIdTemplate.getPastTokenNh();
+	}
+
+}
--- a/sa-token-core/src/main/java/cn/dev33/satoken/sso/SaSsoTemplate.java
+++ b/sa-token-core/src/main/java/cn/dev33/satoken/sso/SaSsoTemplate.java
@ -13,7 +13,7 @@ import cn.dev33.satoken.stp.StpLogic;
 import cn.dev33.satoken.util.SaFoxUtil;

 /**
- * Sa-Token-SSO 单点登录接口 
+ * Sa-Token-SSO 单点登录模块
 * @author kong
 *
 */
--- a/sa-token-doc/doc/README.md
+++ b/sa-token-doc/doc/README.md
@ -195,6 +195,8 @@ Sa-Token秉承着开放的思想，欢迎大家为框架添砖加瓦：

 [**[ 小诺快速开发平台 ]** 基于SpringBoot2 + AntDesignVue全新快速开发平台，同时拥有三个版本](https://xiaonuo.vip/index#pricing)

+[**[ Jpom ]** 简而轻的低侵入式在线构建、自动部署、日常运维、项目监控软件](https://gitee.com/dromara/Jpom)
+

 ## 交流群
 QQ交流群：1002350610 [点击加入](https://jq.qq.com/?_wv=1027&k=45H977HM)
--- a/sa-token-doc/doc/_sidebar.md
+++ b/sa-token-doc/doc/_sidebar.md
@ -43,8 +43,11 @@
 	- [OAuth2-Server搭建](/oauth2/oauth2-server)
 	- [OAuth2-API列表](/oauth2/oauth2-api)

-<!-- - **微服务** -->
-
+- **微服务**
+	- [分布式Session会话](/micro/dcs-session)
+	- [网关统一鉴权](/micro/gateway-auth)
+	- [内部服务调用鉴权](/micro/id-token)
+	- [依赖引入说明](/micro/import-intro)

 - **插件**
 	- [AOP注解鉴权](/plugin/aop-at)
--- a/sa-token-doc/doc/micro/dcs-session.md
+++ b/sa-token-doc/doc/micro/dcs-session.md
@ -0,0 +1,52 @@
+# 微服务 - 分布式Session会话
+
+--- 
+
+### 需求场景 
+
+微服务架构下的第一个难题便是数据同步，单机版的`Session`在分布式环境下一般不能正常工作，为此我们需要对框架做一些特定的处理。
+
+首先我们要明白，分布式环境下为什么`Session`会失效？因为用户在一个节点对会话做出的更改无法实时同步到其它的节点，
+这就导致一个很严重的问题：如果用户在节点一上已经登录成功，那么当下一次的请求落在节点二上时，对节点二来讲，此用户仍然是未登录状态。
+
+### 解决方案 
+
+要怎么解决这个问题呢？目前的主流方案有四种：
+1. **Session同步**：只要一个节点的数据发生了改变，就强制同步到其它所有节点 
+2. **Session粘滞**：通过一定的算法，保证一个用户的所有请求都稳定的落在一个节点之上，对这个用户来讲，就好像还是在访问一个单机版的服务
+3. **建立会话中心**：将Session存储在专业的缓存中间件上，使每个节点都变成了无状态服务，例如：`Redis`
+4. **颁发无状态token**：放弃Session机制，将用户数据直接写入到令牌本身上，使会话数据做到令牌自解释，例如：`jwt`
+
+
+### 方案选择
+
+该如何选择一个合适的方案？
+- 方案一：性能消耗太大，不太考虑
+- 方案二：需要从网关处动手，与框架无关
+- 方案三：Sa-Token 整合`Redis`非常简单，详见章节：[集成 Redis](/up/integ-redis)
+- 方案四：详见官方仓库中 Sa-Token 整合`jwt`的示例
+
+由于`jwt`模式不在服务端存储数据，对于比较复杂的业务可能会功能受限，因此更加推荐使用方案三
+
+``` xml
+<!-- Sa-Token 整合 Redis (使用jackson序列化方式) -->
+<dependency>
+    <groupId>cn.dev33</groupId>
+    <artifactId>sa-token-dao-redis-jackson</artifactId>
+    <version>${sa.top.version}</version>
+</dependency>
+<dependency>
+    <groupId>org.apache.commons</groupId>
+    <artifactId>commons-pool2</artifactId>
+</dependency>
+```
+详细参考：[集成 Redis](/up/integ-redis)
+
+
+
+
+
+
+
+
+
--- a/sa-token-doc/doc/micro/gateway-auth.md
+++ b/sa-token-doc/doc/micro/gateway-auth.md
@ -0,0 +1,112 @@
+# 微服务 - 网关统一鉴权
+
+微服务架构下的鉴权一般分为两种：
+1. 每个服务各自鉴权
+2. 网关统一鉴权 
+
+方案一和传统单体鉴权差别不大，不再过多赘述，本篇介绍方案二的整合步骤：
+
+--- 
+
+
+
+### 1、引入依赖 
+
+首先，根据 [依赖引入说明](/micro/import-intro) 引入正确的依赖，以`[SpringCloud Gateway]`为例：
+
+``` xml
+<!-- Sa-Token 权限认证（Reactor响应式集成）, 在线文档：http://sa-token.dev33.cn/ -->
+<dependency>
+    <groupId>cn.dev33</groupId>
+    <artifactId>sa-token-reactor-spring-boot-starter</artifactId>
+    <version>${sa.top.version}</version>
+</dependency>
+<!-- Sa-Token 整合 Redis (使用jackson序列化方式) -->
+<dependency>
+    <groupId>cn.dev33</groupId>
+    <artifactId>sa-token-dao-redis-jackson</artifactId>
+    <version>${sa.top.version}</version>
+</dependency>
+<dependency>
+    <groupId>org.apache.commons</groupId>
+    <artifactId>commons-pool2</artifactId>
+</dependency>
+```
+注：Redis包是必须的，因为我们需要和各个服务通过Redis来同步数据 
+
+### 2、实现鉴权接口
+``` java
+/**
+ * 自定义权限验证接口扩展 
+ */
+@Component   
+public class StpInterfaceImpl implements StpInterface {
+
+    @Override
+    public List<String> getPermissionList(Object loginId, String loginType) {
+        // 返回此 loginId 拥有的权限列表 
+        return ...;
+    }
+
+    @Override
+    public List<String> getRoleList(Object loginId, String loginType) {
+        // 返回此 loginId 拥有的角色列表
+        return ...;
+    }
+
+}
+
+```
+关于数据的获取，建议以下方案三选一：
+1. 在网关处集成ORM框架，直接从数据库查询数据
+2. 先从Redis中获取数据，获取不到时走ORM框架查询数据库 
+3. 先从Redis中获取缓存数据，获取不到时走RPC调用子服务 (专门的权限数据提供服务) 获取
+
+
+### 3、注册全局过滤器 
+然后在网关处注册全局过滤器进行鉴权操作 
+
+``` java
+/**
+ * [Sa-Token 权限认证] 配置类 
+ * @author kong
+ */
+@Configuration
+public class SaTokenConfigure {
+	// 注册 Sa-Token全局过滤器 
+    @Bean
+    public SaReactorFilter getSaReactorFilter() {
+        return new SaReactorFilter()
+			// 拦截地址 
+			.addInclude("/**")
+			// 开放地址 
+			.addExclude("/favicon.ico")
+			// 鉴权方法：每次访问进入 
+			.setAuth(r -> {
+				// 登录验证 -- 拦截所有路由，并排除/user/doLogin 用于开放登录 
+				SaRouter.match("/**", "/user/doLogin", () -> StpUtil.checkLogin());
+				
+				// 权限认证 -- 不同模块, 校验不同权限 
+				SaRouter.match("/user/**", () -> StpUtil.checkPermission("user"));
+				SaRouter.match("/admin/**", () -> StpUtil.checkPermission("admin"));
+				SaRouter.match("/goods/**", () -> StpUtil.checkPermission("goods"));
+				SaRouter.match("/orders/**", () -> StpUtil.checkPermission("orders"));
+				
+				// ... 
+			})
+			// 异常处理方法：每次setAuth函数出现异常时进入 
+			.setError(e -> {
+				return SaResult.error(e.getMessage());
+			})
+			;
+    }
+}
+```
+
+详细操作参考：[路由拦截鉴权](/use/route-check)
+
+
+
+
+
+
--- a/sa-token-doc/doc/micro/id-token.md
+++ b/sa-token-doc/doc/micro/id-token.md
@ -0,0 +1,228 @@
+# 微服务 - 内部服务调用鉴权 
+
+--- 
+
+
+### 一、需求场景  
+
+我们的子服务一般不能通过外网直接访问，必须通过网关转发才是一个合法的请求，这种子服务与外网的隔离一般分为两种：
+
+1. 物理隔离：子服务部署在指定的内网环境中，只有网关对外网开放 
+2. 逻辑隔离：子服务与网关同时暴露在外网，但是子服务会有一个权限拦截层保证只接受网关发送来的请求，绕过网关直接访问子服务会被提示：无效请求 
+
+这种鉴权需求牵扯到两个环节：网关转发鉴权、内部服务调用鉴权 
+
+Sa-Token提供两种解决方案：
+1. 使用 OAuth2.0 模式的凭证式，将 Client-Token 用作各个服务的身份凭证进行权限校验
+2. 使用 Id-Token 模块提供的身份校验能力，完成服务间的权限认证
+
+本篇主要讲解方案二 `Id-Token` 模块的整合步骤，其鉴权流程与 OAuth2.0 类似，不过使用方式上更加简洁（希望使用方案一的同学可参考Sa-OAuth2模块，此处不再赘述）
+
+### 二、网关转发鉴权 
+
+##### 1、引入依赖
+
+在网关处引入的依赖为（此处以 SpringCloud Gateway 为例）：
+``` xml
+<!-- Sa-Token 权限认证（Reactor响应式集成）, 在线文档：http://sa-token.dev33.cn/ -->
+<dependency>
+    <groupId>cn.dev33</groupId>
+    <artifactId>sa-token-reactor-spring-boot-starter</artifactId>
+    <version>${sa.top.version}</version>
+</dependency>
+<!-- Sa-Token 整合 Redis (使用jackson序列化方式) -->
+<dependency>
+    <groupId>cn.dev33</groupId>
+    <artifactId>sa-token-dao-redis-jackson</artifactId>
+    <version>${sa.top.version}</version>
+</dependency>
+<dependency>
+    <groupId>org.apache.commons</groupId>
+    <artifactId>commons-pool2</artifactId>
+</dependency>
+```
+
+在子服务引入的依赖为：
+``` xml
+<!-- Sa-Token 权限认证, 在线文档：http://sa-token.dev33.cn/ -->
+<dependency>
+    <groupId>cn.dev33</groupId>
+    <artifactId>sa-token-spring-boot-starter</artifactId>
+    <version>${sa.top.version}</version>
+</dependency>
+<!-- Sa-Token 整合 Redis (使用jackson序列化方式) -->
+<dependency>
+    <groupId>cn.dev33</groupId>
+    <artifactId>sa-token-dao-redis-jackson</artifactId>
+    <version>${sa.top.version}</version>
+</dependency>
+<dependency>
+    <groupId>org.apache.commons</groupId>
+    <artifactId>commons-pool2</artifactId>
+</dependency>
+```
+
+##### 2、网关处添加Id-Token
+
+为网关添加全局过滤器：
+``` java
+/**
+ * 全局过滤器，为请求添加 Id-Token 
+ */
+@Component
+public class ForwardAuthFilter implements GlobalFilter {
+	@Override
+	public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
+		ServerHttpRequest newRequest = exchange
+				.getRequest()
+				.mutate()
+				// 为请求追加 Id-Token 参数 
+				.header(SaIdUtil.ID_TOKEN, SaIdUtil.getToken())
+				.build();
+        ServerWebExchange newExchange = exchange.mutate().request(newRequest).build();
+        return chain.filter(newExchange);
+	}
+}
+```
+此过滤器会为 Request 请求头追加 `Id-Token` 参数，这个参数会被转发到子服务 
+
+
+##### 3、在子服务里校验参数 
+
+在子服务添加过滤器校验参数 
+``` java
+/**
+ * Sa-Token 权限认证 配置类 
+ */
+@Configuration
+public class SaTokenConfigure implements WebMvcConfigurer {
+	// 注册 Sa-Token 全局过滤器 
+    @Bean
+    public SaServletFilter getSaServletFilter() {
+        return new SaServletFilter()
+        		.addInclude("/**")
+        		.addExclude("/favicon.ico")
+        		.setAuth(r -> {
+        			// 校验 Id-Token 身份凭证 	—— 以下两句代码可简化为：SaIdUtil.checkCurrentRequestToken(); 
+        			String token = SaHolder.getRequest().getHeader(SaIdUtil.ID_TOKEN);
+        			SaIdUtil.checkToken(token);
+        		})
+        		.setError(e -> {
+        			return SaResult.error(e.getMessage());
+        		})
+        		;
+    }
+}
+```
+
+启动网关与子服务，访问测试：
+
+> 如果通过网关转发，可以正常访问，直接访问子服务会提示：`无效Id-Token：xxx`
+
+
+### 三、内部服务调用鉴权 
+
+有时候我们需要在一个服务调用另一个服务的接口，这也是需要添加`Id-Token`作为身份凭证的
+
+在服务里添加 Id-Token 流程与网关类似，我们以RPC框架 `Feign` 为例：
+
+##### 1、首先在调用方添加 FeignInterceptor
+``` java
+/**
+ * feign拦截器, 在feign请求发出之前，加入一些操作 
+ */
+@Component
+public class FeignInterceptor implements RequestInterceptor {
+	// 为 Feign 的 RCP调用 添加请求头Id-Token 
+	@Override
+	public void apply(RequestTemplate requestTemplate) {
+		requestTemplate.header(SaIdUtil.ID_TOKEN, SaIdUtil.getToken());
+	}
+}
+```
+
+##### 2、在调用接口里使用此 Interceptor 
+``` java
+/**
+ * 服务调用 
+ */
+@FeignClient(
+		name = "sp-home", 				// 服务名称 
+		configuration = FeignInterceptor.class,		// 请求拦截器 （关键代码）
+		fallbackFactory = SpCfgInterfaceFallback.class	// 服务降级处理 
+		)	
+public interface SpCfgInterface {
+
+	// 获取server端指定配置信息 
+	@RequestMapping("/SpConfig/getConfig")
+	public String getConfig(@RequestParam("key")String key);
+	
+}
+```
+
+被调用方的代码无需更改（按照网关转发鉴权处的代码注册全局过滤器），保持启动测试即可 
+
+
+### 四、Id-Token 模块详解 
+
+Id-Token —— 专门解决身份凭证问题的一个模块，它的作用不仅局限于微服务调用场景
+
+基本使用流程为：服务调用方获取Token，提交到请求中，被调用方取出Token进行校验：Token一致则校验通过，否则拒绝服务
+
+首先我们预览一下此模块的相关API：
+``` java
+// 获取当前Id-Token
+SaIdUtil.getToken();
+
+// 判断一个Id-Token是否有效
+SaIdUtil.isValid(token);
+
+// 校验一个Id-Token是否有效 (如果无效则抛出异常)
+SaIdUtil.checkToken(token);
+
+// 校验当前Request提供的Id-Token是否有效 (如果无效则抛出异常)
+SaIdUtil.checkCurrentRequestToken();
+
+// 刷新一次Id-Token (注意集群环境中不要多个服务重复调用) 
+SaIdUtil.refreshToken();
+
+// 在 Request 上储存 Id-Token 时建议使用的key
+SaIdUtil.ID_TOKEN;
+```
+
+##### 1、疑问：这个Token保存在什么地方？有没有泄露的风险？Token为永久有效还是临时有效？
+Id-Token 默认随 Sa-Token 数据一起保存在Redis中，理论上不会存在泄露的风险，每个Token默认有效期只有一天
+
+##### 2、如何主动刷新Id-Token，例如：五分钟、两小时刷新一次？
+Id-Token 刷新间隔越短，其安全性越高，每个Token的默认有效期为一天，在一天后再次获取会自动产生一个新的Token
+
+!> 需要注意的一点是：Id-Token默认的自刷新机制，并不能做到高并发可用，多个服务一起触发Token刷新可能会造成毫秒级的短暂服务失效，其只能适用于 项目开发阶段 或 低并发业务场景 
+
+因此在微服务架构下，我们需要有专门的机制主动刷新Id-Token，保证其高可用
+
+例如，我们可以专门起一个服务，使用定时任务来刷新Id-Token 
+``` java
+/**
+ * Id-Token，定时刷新
+ */
+@Configuration
+public class SaIdTokenRefreshTask {
+	// 从 0 分钟开始 每隔 5 分钟执行一次 Id-Token  
+	@Scheduled(cron = "0 0/5 * * * ? ")
+	public void refreshToken(){
+		SaIdUtil.refreshToken();
+	}
+}
+```
+
+以上的cron表达式刷新间隔可以配置为`五分钟`、`十分钟` 或 `两小时`，只要低于Id-Token的有效期（默认为一天）即可。
+
+##### 3、如果网关携带token转发的请求在落到子服务的节点上时，恰好刷新了token，导致鉴权未通过怎么办？
+Id-Token 模块在设计时，充分考虑到了这一点，在每次刷新 Token 时，旧 Token 会被作为次级 Token 存储起来，
+只要网关携带的 Token 符合新旧 Token 其一即可通过认证，直至下一次刷新，新 Token 再次作为次级 Token 将此替换掉 
+
+
+
+
+
+
--- a/sa-token-doc/doc/micro/import-intro.md
+++ b/sa-token-doc/doc/micro/import-intro.md
@ -0,0 +1,62 @@
+
+# 微服务中使用Sa-Token 依赖引入说明 
+
+--- 
+
+虽然在 [开始] 章节已经说明了依赖引入规则，但是交流群里不少小伙伴提出bug解决到最后发现都是因为依赖引入错误导致的，此处再次重点强调一下：
+
+> **在微服务架构中使用Sa-Token时，网关和内部服务要分开引入Sa-Token依赖（不要直接在顶级父pom中引入Sa-Token）**
+
+总体来讲，我们需要关注的依赖就是两个：`sa-token-spring-boot-starter` 和 `sa-token-reactor-spring-boot-starter`，
+
+``` xml
+<!-- Sa-Token 权限认证, 在线文档：http://sa-token.dev33.cn/ -->
+<dependency>
+    <groupId>cn.dev33</groupId>
+    <artifactId>sa-token-spring-boot-starter</artifactId>
+    <version>${sa.top.version}</version>
+</dependency>
+```
+
+``` xml
+<!-- Sa-Token 权限认证（Reactor响应式集成）, 在线文档：http://sa-token.dev33.cn/ -->
+<dependency>
+    <groupId>cn.dev33</groupId>
+    <artifactId>sa-token-reactor-spring-boot-starter</artifactId>
+    <version>${sa.top.version}</version>
+</dependency>
+```
+
+
+至于怎么分辨我们需要引入哪个呢？这个要看你使用的基础框架：
+
+对于内部基础服务来讲，我们一般都是使用SpringBoot默认的web模块：SpringMVC，
+因为这个SpringMVC是基于Servlet模型的，在这里我们需要引入的是`sa-token-spring-boot-starter`
+
+对于网关服务，大体来讲分为两种：
+- 一种是基于Servlet模型的，如：Zuul，我们需要引入的是：`sa-token-spring-boot-starter`，详细戳：[在SpringBoot环境集成](/start/example)
+- 一种是基于Reactor模型的，如：SpringCloud Gateway、ShenYu、Fizz Gateway 等等，我们需要引入的是：`sa-token-reactor-spring-boot-starter`，**并且注册全局过滤器！**，详细戳：[在WebFlux环境集成](/start/webflux-example)
+
+注：切不可直接在一个项目里同时引入这两个依赖，否则会造成项目无法启动
+
+另外，我们需要引入Redis集成包，因为我们的网关和子服务主要通过Redis来同步数据 
+``` xml
+<!-- Sa-Token 整合 Redis (使用jackson序列化方式) -->
+<dependency>
+    <groupId>cn.dev33</groupId>
+    <artifactId>sa-token-dao-redis-jackson</artifactId>
+    <version>${sa.top.version}</version>
+</dependency>
+<dependency>
+    <groupId>org.apache.commons</groupId>
+    <artifactId>commons-pool2</artifactId>
+</dependency>
+```
+详细参考：[集成 Redis](/up/integ-redis)
+
+
+
+
+
+
+
--- a/sa-token-doc/doc/up/global-filter.md
+++ b/sa-token-doc/doc/up/global-filter.md
@ -75,7 +75,7 @@ public class SaTokenConfigure {
 ```

 ##### 注意事项：
- 在`[认证函数]`里，你可以写和拦截器里一致的代码，进行路由匹配鉴权，参考：[路由拦截式鉴权](/use/route-check)
+- 在`[认证函数]`里，你可以写和拦截器里一致的代码，进行路由匹配鉴权，参考：[路由拦截鉴权](/use/route-check)
 - 由于过滤器中抛出的异常不进入全局异常处理，所以你必须提供`[异常处理函数]`来处理`[认证函数]`里抛出的异常
 - 在`[异常处理函数]`里的返回值，将作为字符串输出到前端，如果需要定制化返回数据，请注意其中的格式转换