重构概念：临时有效期 -> token 最低活跃频率

2025-09-19 01:58:05 +08:00 · 2023-05-11 05:35:43 +08:00
parent def58b9101
commit facb7ca9b6
8 changed files with 129 additions and 126 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
@@ -19,12 +19,12 @@ public class SaTokenConfig implements Serializable {
 	/** token 名称 （同时也是： cookie 名称、提交 token 时参数的名称、存储 token 时的 key 前缀） */
 	private String tokenName = "satoken";

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

 	/**
-	 * token 临时有效期 [ 指定时间内无操作就视为 token 过期 ] （单位: 秒）, 默认-1 代表不限制
-	 * （例如可以设置为 1800 代表 30 分钟内无操作就过期）
+	 * token 最低活跃频率（单位：秒），如果 token 超过此时间没有访问系统就会被冻结，默认-1 代表不限制，永不冻结
+	 * （例如可以设置为 1800 代表 30 分钟内无操作就冻结）
 	 */
 	private long activityTimeout = -1;

@@ -34,7 +34,7 @@ public class SaTokenConfig implements Serializable {
 	private Boolean isConcurrent = true;

 	/**
-	 * 在多人登录同一账号时，是否共用一个token （为true时所有登录共用一个token, 为false时每次登录新建一个token）
+	 * 在多人登录同一账号时，是否共用一个 token （为 true 时所有登录共用一个 token, 为 false 时每次登录新建一个 token）
 	 */
 	private Boolean isShare = true;

@@ -171,14 +171,14 @@ public class SaTokenConfig implements Serializable {
 	}

 	/**
-	 * @return token 的长久有效期（单位:秒） 默认30天, -1代表永久
+	 * @return token 有效期（单位：秒） 默认30天，-1代表永久
 	 */
 	public long getTimeout() {
 		return timeout;
 	}

 	/**
-	 * @param timeout token 的长久有效期（单位:秒） 默认30天, -1代表永久
+	 * @param timeout token 有效期（单位：秒） 默认30天，-1代表永久
 	 * @return 对象自身
 	 */
 	public SaTokenConfig setTimeout(long timeout) {
@@ -187,16 +187,16 @@ public class SaTokenConfig implements Serializable {
 	}

 	/**
-	 * @return token 临时有效期 [ 指定时间内无操作就视为 token 过期 ] （单位: 秒）, 默认-1 代表不限制
-	 * （例如可以设置为 1800 代表 30 分钟内无操作就过期）
+	 * @return token 最低活跃频率（单位：秒），如果 token 超过此时间没有访问系统就会被冻结，默认-1 代表不限制，永不冻结
+	 * 							（例如可以设置为 1800 代表 30 分钟内无操作就冻结）
 	 */
 	public long getActivityTimeout() {
 		return activityTimeout;
 	}

 	/**
-	 * @param activityTimeout token 临时有效期 [ 指定时间内无操作就视为 token 过期 ] （单位: 秒）, 默认-1 代表不限制
-	 * 							（例如可以设置为 1800 代表 30 分钟内无操作就过期）
+	 * @param activityTimeout token 最低活跃频率（单位：秒），如果 token 超过此时间没有访问系统就会被冻结，默认-1 代表不限制，永不冻结
+	 * 								（例如可以设置为 1800 代表 30 分钟内无操作就冻结）
 	 * @return 对象自身
 	 */
 	public SaTokenConfig setActivityTimeout(long activityTimeout) {
--- a/sa-token-core/src/main/java/cn/dev33/satoken/error/SaErrorCode.java
+++ b/sa-token-core/src/main/java/cn/dev33/satoken/error/SaErrorCode.java
@@ -74,7 +74,7 @@ public interface SaErrorCode {
 	/** Token已被踢下线 */
 	int CODE_11015 = 11015;

-	/** Token已临时过期 */
+	/** Token已被冻结 */
 	int CODE_11016 = 11016;
 	
 	/** 在未集成 sa-token-jwt 插件时调用 getExtra() 抛出异常 */
--- a/sa-token-core/src/main/java/cn/dev33/satoken/stp/StpLogic.java
+++ b/sa-token-core/src/main/java/cn/dev33/satoken/stp/StpLogic.java
@@ -491,7 +491,7 @@ public class StpLogic {
 		SaStorage storage = SaHolder.getStorage();
 		storage.delete(splicingKeyJustCreatedSave());

- 		// 4、清除当前上下文的 [ 临时有效期 check 标记 ]
+ 		// 4、清除当前上下文的 [ 活跃度校验 check 标记 ]
 		storage.delete(SaTokenConsts.TOKEN_ACTIVITY_TIMEOUT_CHECKED_KEY);

 		// 5、清除这个 token 的其它相关信息
@@ -809,7 +809,7 @@ public class StpLogic {
 		}

 		// 7、检查此 token 的最后活跃时间是否已经超过了 activity-timeout 的限制，
-		//    如果是则代表其已经临时过期，需要抛出：token 已过期
+		//    如果是则代表其已被冻结，需要抛出：token 已过期
 	 	checkActivityTimeout(tokenValue);

 		// ------ 至此，loginId 已经是一个合法的值，代表当前会话是一个正常的登录状态了
@@ -868,7 +868,7 @@ public class StpLogic {
 			return null;
 		}

- 		// 4、如果根本获取不到这个 token 的最后活跃时间数据，则也视为其：已经临时过期，也返回 null
+ 		// 4、如果 token 已被冻结，也返回 null
 		if(getTokenActivityTimeoutByToken(tokenValue) == SaTokenDao.NOT_VALUE_EXPIRE) {
 			return null;
 		}
@@ -1239,7 +1239,7 @@ public class StpLogic {
 	}


-	// ------------------- Activity-Timeout 临时有效期 验证相关 -------------------
+	// ------------------- Activity-Timeout token 最低活跃度 验证相关 -------------------

 	/**
 	 * 写入指定 token 的 [ 最后活跃时间 ] 为当前时间戳
@@ -1247,7 +1247,8 @@ public class StpLogic {
 	 * @param tokenValue 指定token 
 	 */
 	protected void setLastActivityToNow(String tokenValue) {
- 		// 如果提供的 token 或者 全局配置了 [ 永不过期 ], 则立即返回，无需操作
+
+ 		// 如果提供的 token 无效，或者配置没有打开 token 活跃度校验, 则立即返回，无需操作
 		if(SaFoxUtil.isEmpty(tokenValue) || ! isOpenActivityCheck() ) {
 			return;
 		}
@@ -1262,7 +1263,8 @@ public class StpLogic {
 	 * @param tokenValue 指定 token
 	 */
 	protected void clearLastActivity(String tokenValue) {
-		// 如果提供的 token 或者 全局配置了 [ 永不过期 ], 则立即返回，无需操作
+
+		// 如果提供的 token 无效，或者配置没有打开 token 活跃度校验, 则立即返回，无需操作
 		if(SaFoxUtil.isEmpty(tokenValue) || ! isOpenActivityCheck() ) {
 			return;
 		}
@@ -1272,13 +1274,13 @@ public class StpLogic {
 	}
 	
 	/**
- 	 * 检查指定token 是否已经 [ 临时过期 ]，如果已经过期则抛出异常
+ 	 * 检查指定 token 是否已被冻结，如果是则抛出异常
 	 *
- 	 * @param tokenValue 指定token
+ 	 * @param tokenValue 指定 token
 	 */
 	public void checkActivityTimeout(String tokenValue) {

-		// 如果提供的 token 或者 全局配置了 [ 永不过期 ], 则立即返回，无需操作
+		// 如果提供的 token 无效，或者配置没有打开 token 活跃度校验, 则立即返回，无需操作
 		if(SaFoxUtil.isEmpty(tokenValue) || ! isOpenActivityCheck() ) {
 			return;
 		}
@@ -1289,19 +1291,19 @@ public class StpLogic {
 			return;
 		}

- 		// ------------ 下面开始校验这个 token 是否已经 [ 临时过期 ]
+ 		// ------------ 下面开始校验这个 token 是否已被冻结

- 		// 1、获取这个 token 的临时剩余时间
+ 		// 1、获取这个 token 的剩余活跃有效期
 		long timeout = getTokenActivityTimeoutByToken(tokenValue);

-		// 2、值为 -1 代表此 token 已经被设置永不过期，无须继续验证
+		// 2、值为 -1 代表此 token 已经被设置永不冻结，无须继续验证
 		if(timeout == SaTokenDao.NEVER_EXPIRE) {
 			// 此句代码含义参考最下面
 			storage.set(SaTokenConsts.TOKEN_ACTIVITY_TIMEOUT_CHECKED_KEY, true);
 			return;
 		}

-		// 3、值为 -2 代表已临时过期，此时需要抛出异常
+		// 3、值为 -2 代表已被冻结，此时需要抛出异常
 		if(timeout == SaTokenDao.NOT_VALUE_EXPIRE) {
 			throw NotLoginException.newInstance(loginType, NotLoginException.TOKEN_TIMEOUT, tokenValue).setCode(SaErrorCode.CODE_11016);
 		}
@@ -1312,7 +1314,7 @@ public class StpLogic {
 	}

 	/**
- 	 * 检查当前 token 是否已经[临时过期]，如果已经过期则抛出异常
+ 	 * 检查当前 token 是否已被冻结，如果是则抛出异常
 	 */
 	public void checkActivityTimeout() {
 		checkActivityTimeout(getTokenValue());
@@ -1324,7 +1326,7 @@ public class StpLogic {
 	 * @param tokenValue 指定token 
 	 */
 	public void updateLastActivityToNow(String tokenValue) {
-		// 如果提供的 token 或者 全局配置了 [ 永不过期 ], 则立即返回，无需操作
+		// 如果提供的 token 无效，或者配置没有打开 token 活跃度校验, 则立即返回，无需操作
 		if(SaFoxUtil.isEmpty(tokenValue) || ! isOpenActivityCheck() ) {
 			return;
 		}
@@ -1336,8 +1338,8 @@ public class StpLogic {
 	/**
 	 * 续签当前 token：(将 [最后操作时间] 更新为当前时间戳)
 	 * <h2>
-	 * 		请注意: 即使 token 已经 [ 临时过期 ] 也可续签成功，
- 	 * 		如果此场景下需要提示续签失败，可在此之前调用 checkActivityTimeout() 强制检查是否过期即可
+	 * 		请注意: 即使 token 已被冻结 也可续签成功，
+ 	 * 		如果此场景下需要提示续签失败，可在此之前调用 checkActivityTimeout() 强制检查是否冻结即可
 	 * </h2>
 	 */
 	public void updateLastActivityToNow() {
@@ -1405,7 +1407,7 @@ public class StpLogic {
 	}

 	/**
- 	 * 获取当前 token [ 临时过期 ] 剩余有效时间（单位: 秒，返回 -1 代表永久有效，-2 代表没有这个值）
+ 	 * 获取当前 token 剩余活跃有效期：当前 token 距离被冻结还剩多少时间（单位: 秒，返回 -1 代表永不冻结，-2 代表没有这个值或 token 已被冻结了）
 	 *
 	 * @return /
 	 */
@@ -1414,23 +1416,23 @@ public class StpLogic {
 	}
 	
 	/**
- 	 * 获取指定 token [ 临时过期 ] 剩余有效时间（单位: 秒，返回 -1 代表永久有效，-2 代表没有这个值）
+ 	 * 获取指定 token 剩余活跃有效期：这个 token 距离被冻结还剩多少时间（单位: 秒，返回 -1 代表永不冻结，-2 代表没有这个值或 token 已被冻结了）
 	 *
 	 * @param tokenValue 指定 token
 	 * @return /
 	 */
 	public long getTokenActivityTimeoutByToken(String tokenValue) {

+		// 如果全局配置了永不冻结, 则返回 -1
+		if( ! isOpenActivityCheck() ) {
+			return SaTokenDao.NEVER_EXPIRE;
+		}
+
 		// 如果提供的 token 为 null，则返回 -2
 		if(SaFoxUtil.isEmpty(tokenValue)) {
 			return SaTokenDao.NOT_VALUE_EXPIRE;
 		}

- 		// 如果全局配置了永不过期, 则返回 -1
- 		if( ! isOpenActivityCheck() ) {
- 			return SaTokenDao.NEVER_EXPIRE;
- 		}
-
 		// ------ 开始查询

 		// 1、先获取这个 token 的最后活跃时间，13位时间戳
@@ -1448,12 +1450,12 @@ public class StpLogic {
 		long apartSecond = (System.currentTimeMillis() - lastActivityTime) / 1000;

 		// 4、校验这个时间差是否超过了允许的值
-		//    计算公式为: 允许的最大时间差 - 实际时间差，判断是否 < 0， 如果是则代表已经临时过期 ，返回-2
+		//    计算公式为: 允许的最大时间差 - 实际时间差，判断是否 < 0， 如果是则代表已经被冻结 ，返回-2
 		long timeout = getConfig().getActivityTimeout() - apartSecond;
 		if(timeout < 0) {
 			return SaTokenDao.NOT_VALUE_EXPIRE;
 		} else {
-			// 否则代表没过期，返回剩余有效时间
+			// 否则代表没冻结，返回剩余有效时间
 			return timeout;
 		}
 	}
@@ -2587,7 +2589,7 @@ public class StpLogic {
 	}

 	/**
- 	 * 返回全局配置是否开启了Token 活跃校验
+ 	 * 返回全局配置是否开启了 Token 活跃度校验，返回 true 代表已打开，返回 false 代表不打开，此时永不冻结 token
 	 *
 	 * @return / 
 	 */
--- a/sa-token-core/src/main/java/cn/dev33/satoken/stp/StpUtil.java
+++ b/sa-token-core/src/main/java/cn/dev33/satoken/stp/StpUtil.java
@@ -478,10 +478,10 @@ public class StpUtil {
 	}
 	

-	// ------------------- Activity-Timeout 临时有效期 验证相关 -------------------
+	// ------------------- Activity-Timeout token 最低活跃度 验证相关 -------------------

 	/**
-	 * 检查当前 token 是否已经[临时过期]，如果已经过期则抛出异常
+	 * 检查当前 token 是否已被冻结，如果是则抛出异常
 	 */
 	public static void checkActivityTimeout() {
 		stpLogic.checkActivityTimeout();
@@ -490,8 +490,8 @@ public class StpUtil {
 	/**
 	 * 续签当前 token：(将 [最后操作时间] 更新为当前时间戳)
 	 * <h2>
-	 * 		请注意: 即使 token 已经 [ 临时过期 ] 也可续签成功，
-	 * 		如果此场景下需要提示续签失败，可在此之前调用 checkActivityTimeout() 强制检查是否过期即可
+	 * 		请注意: 即使 token 已被冻结 也可续签成功，
+	 * 		如果此场景下需要提示续签失败，可在此之前调用 checkActivityTimeout() 强制检查是否冻结即可
 	 * </h2>
 	 */
 	public static void updateLastActivityToNow() {
@@ -529,7 +529,7 @@ public class StpUtil {
 	}

 	/**
-	 * 获取当前 token [ 临时过期 ] 剩余有效时间（单位: 秒，返回 -1 代表永久有效，-2 代表没有这个值）
+	 * 获取当前 token 剩余活跃有效期：当前 token 距离被冻结还剩多少时间（单位: 秒，返回 -1 代表永不冻结，-2 代表没有这个值或 token 已被冻结了）
 	 *
 	 * @return /
 	 */
--- a/sa-token-doc/fun/token-timeout.md
+++ b/sa-token-doc/fun/token-timeout.md
@@ -2,22 +2,22 @@

 <!-- 本篇介绍Token有效期的详细用法 -->

-Sa-Token 提供两种Token自动过期策略，分别是`timeout`与`activity-timeout`，配置方法如下：
+Sa-Token 提供两种 Token 自动过期策略，分别是 `timeout` 与 `activity-timeout`，配置方法如下：

 <!---------------------------- tabs:start ---------------------------->
 <!------------- tab:yaml 风格  ------------->
 ``` yaml
 sa-token: 
-    # Token 有效期，单位：秒，默认30天, -1代表永不过期 
-    timeout: 2592000
-    # Token 临时有效期 (指定时间内无操作就视为 Token 过期) 单位: 秒，-1代表不设限 
-    activity-timeout: -1
+	# token 有效期（单位：秒），默认30天，-1代表永不过期 
+	timeout: 2592000
+	# token 最低活跃频率（单位：秒），如果 token 超过此时间没有访问系统就会被冻结，默认-1 代表不限制，永不冻结
+	activity-timeout: -1
 ```
 <!------------- tab:properties 风格  ------------->
 ``` properties
-# Token 有效期，单位：秒，默认30天, -1代表永不过期 
+# token 有效期（单位：秒），默认30天，-1代表永不过期 
 sa-token.timeout=2592000
-# Token 临时有效期 (指定时间内无操作就视为 Token 过期) 单位: 秒，-1代表不设限 
+# token 最低活跃频率（单位：秒），如果 token 超过此时间没有访问系统就会被冻结，默认-1 代表不限制，永不冻结
 sa-token.activity-timeout=-1
 ```
 <!---------------------------- tabs:end ---------------------------->
@@ -29,41 +29,41 @@ sa-token.activity-timeout=-1
 > 2. 银行为你颁发一张储蓄卡（系统为你颁发一个Token），以后每次存取钱都要带上这张卡（后续每次访问系统都要提交 Token）。
 > 3. 银行为这张卡设定两个过期时间：
 > 	- 第一个是 `timeout`，代表这张卡的长久有效期，就是指这张卡最长能用多久，假设 `timeout=3年`，那么3年后此卡将被银行删除，想要继续来银行办理业务必须重新办卡（Token 过期后想要访问系统必须重新登录）。
-> 	- 第二个就是 `activity-timeout`，代表这张卡的临时有效期，就是指这张卡必须每隔多久来银行一次，假设 `activity-timeout=1月` ，你如果超过1月不来办一次业务，银行就将你的卡冻结，列为长期不动户（Token 长期不访问系统，被冻结，但不会被删除）。
+> 	- 第二个就是 `activity-timeout`，代表这张卡的最低活跃频率限制，就是指这张卡必须每隔多久来银行一次，假设 `activity-timeout=1月` ，你如果超过1月不来办一次业务，银行就将你的卡冻结，列为长期不动户（Token 长期不访问系统，被冻结，但不会被删除）。
 > 4. 两个过期策略可以单独配置，也可以同时配置，只要有其中一个有效期超出了范围，这张卡就会变得不可用（两个有效期只要有一个过期了，Token就无法成功访问系统了）。

 下面是对两个过期策略的详细解释：

 ### timeout
-1. `timeout`代表Token的长久有效期，单位/秒，例如将其配置为 2592000 (30天)，代表在30天后，Token必定过期，无法继续使用
+1. `timeout`代表 Token 的长久有效期，单位/秒，例如将其配置为 2592000 (30天)，代表在30天后，Token必定过期，无法继续使用。
 2. `timeout`~~无法续签，想要继续使用必须重新登录~~。v1.29.0+ 版本新增续期方法：`StpUtil.renewTimeout(100)`。
-3. `timeout`的值配置为-1后，代表永久有效，不会过期
+3. `timeout`的值配置为-1后，代表永久有效，不会过期。


 ### activity-timeout
-1. `activity-timeout`代表临时有效期，单位/秒，例如将其配置为 1800 (30分钟)，代表用户如果30分钟无操作，则此Token会立即过期
-2. 如果在30分钟内用户有操作，则会再次续签30分钟，用户如果一直操作则会一直续签，直到连续30分钟无操作，Token才会过期
-3. `activity-timeout`的值配置为-1后，代表永久有效，不会过期，此时也无需频繁续签
+1. `activity-timeout`代表最低活跃频率，单位/秒，例如将其配置为 1800 (30分钟)，代表用户如果30分钟无操作，则此Token会立即过期（被冻结，但不会删除掉）。
+2. 如果在30分钟内用户有操作，则会再次续签30分钟，用户如果一直操作则会一直续签，直到连续30分钟无操作，Token才会过期。
+3. `activity-timeout`的值配置为-1后，代表永久有效，不会过期，此时也无需频繁续签。


 ### 关于activity-timeout的续签
-如果`activity-timeout`配置了大于零的值，Sa-Token 会在登录时开始计时，在每次直接或间接调用`getLoginId()`时进行一次过期检查与续签操作。
+如果`activity-timeout`配置了大于零的值，Sa-Token 会在登录时开始计时，在每次直接或间接调用`getLoginId()`时进行一次冻结检查与续签操作。
 此时会有两种情况：
-1. 一种是会话无操作时间太长，Token已经过期，此时框架会抛出`NotLoginException`异常(场景值=-3)，
+1. 一种是会话无操作时间太长，Token已经被冻结，此时框架会抛出`NotLoginException`异常(场景值=-3)，
 2. 另一种则是会话在`activity-timeout`有效期内通过检查，此时Token可以成功续签 


-### 我可以手动续签吗？
+### 我可以手动续签 activity-timeout 吗？
 **可以！**
 如果框架的自动续签算法无法满足您的业务需求，你可以进行手动续签，Sa-Token 提供两个API供你操作：
-1. `StpUtil.checkActivityTimeout()`: 检查当前Token 是否已经[临时过期]，如果已经过期则抛出异常
+1. `StpUtil.checkActivityTimeout()`: 检查当前Token 是否已经被冻结，如果是则抛出异常
 2. `StpUtil.updateLastActivityToNow()`: 续签当前Token：(将 [最后操作时间] 更新为当前时间戳) 

-注意：在手动续签时，即使Token已经 [临时过期] 也可续签成功，如果此场景下需要提示续签失败，可采用先检查再续签的形式保证Token有效性 
+注意：在手动续签时，即使 Token 已经被冻结也可续签成功（解冻），如果此场景下需要提示续签失败，可采用先检查再续签的形式保证Token有效性 

 例如以下代码：
 ``` java
-// 先检查是否已过期
+// 先检查是否已被冻结
 StpUtil.checkActivityTimeout();
 // 检查通过后继续续签
 StpUtil.updateLastActivityToNow();
@@ -79,14 +79,15 @@ StpUtil.stpLogic.updateLastActivityToNow(tokenValue);
 ```


-### timeout与activity-timeout可以同时使用吗？
+### timeout 与 activity-timeout 可以同时使用吗？
 **可以同时使用！** 
 两者的认证逻辑彼此独立，互不干扰，可以同时使用。

-### StpUtil 类中哪些公开方法支持临时有效期自动续签? 
+
+### StpUtil 类中哪些公开方法支持临时有效期自动续签 activity-timeout? 
 > 直接或间接获取了当前用户id的方法 （间接调用过 StpLogic.getLoginId() 方法）

-| 支持自动续签的方法 |
+| 包括但不限于这些： |
 |---|
 | StpUtil.checkLogin() |
 | StpUtil.getLoginId() |
--- a/sa-token-doc/start/example.md
+++ b/sa-token-doc/start/example.md
@@ -55,17 +55,17 @@ server:
 	
 ############## Sa-Token 配置 (文档: https://sa-token.cc) ##############
 sa-token: 
-	# token名称 (同时也是cookie名称)
+	# token 名称（同时也是 cookie 名称）
 	token-name: satoken
-	# token有效期，单位s 默认30天, -1代表永不过期 
+	# token 有效期（单位：秒），默认30天，-1代表永不过期 
 	timeout: 2592000
-	# token临时有效期 (指定时间内无操作就视为token过期) 单位: 秒
+	# token 最低活跃频率（单位：秒），如果 token 超过此时间没有访问系统就会被冻结，默认-1 代表不限制，永不冻结
 	activity-timeout: -1
-	# 是否允许同一账号并发登录 (为true时允许一起登录, 为false时新登录挤掉旧登录) 
+	# 是否允许同一账号多地同时登录（为 true 时允许一起登录，为 false 时新登录挤掉旧登录）
 	is-concurrent: true
-	# 在多人登录同一账号时，是否共用一个token (为true时所有登录共用一个token, 为false时每次登录新建一个token) 
+	# 在多人登录同一账号时，是否共用一个 token （为 true 时所有登录共用一个 token，为 false 时每次登录新建一个 token）
 	is-share: true
-	# token风格
+	# token 风格
 	token-style: uuid
 	# 是否输出操作日志 
 	is-log: false
@@ -78,17 +78,17 @@ server.port=8081
 	
 ############## Sa-Token 配置 (文档: https://sa-token.cc) ##############

-# token名称 (同时也是cookie名称)
+# token名称（同时也是 cookie 名称）
 sa-token.token-name=satoken
-# token有效期，单位s 默认30天, -1代表永不过期 
+# token 有效期（单位：秒），默认30天，-1代表永不过期 
 sa-token.timeout=2592000
-# token临时有效期 (指定时间内无操作就视为token过期) 单位: 秒
+# token 最低活跃频率（单位：秒），如果 token 超过此时间没有访问系统就会被冻结，默认-1 代表不限制，永不冻结
 sa-token.activity-timeout=-1
-# 是否允许同一账号并发登录 (为true时允许一起登录, 为false时新登录挤掉旧登录) 
+# 是否允许同一账号多地同时登录（为 true 时允许一起登录，为 false 时新登录挤掉旧登录）
 sa-token.is-concurrent=true
-# 在多人登录同一账号时，是否共用一个token (为true时所有登录共用一个token, 为false时每次登录新建一个token) 
+# 在多人登录同一账号时，是否共用一个 token （为 true 时所有登录共用一个 token，为 false 时每次登录新建一个 token）
 sa-token.is-share=true
-# token风格
+# token 风格
 sa-token.token-style=uuid
 # 是否输出操作日志 
 sa-token.is-log=false
--- a/sa-token-doc/start/solon-example.md
+++ b/sa-token-doc/start/solon-example.md
@@ -60,20 +60,20 @@ server:
    
 ############## Sa-Token 配置 (文档: https://sa-token.cc) ##############
 sa-token: 
-    # token名称 (同时也是cookie名称)
-    token-name: satoken
-    # token有效期，单位s 默认30天, -1代表永不过期 
-    timeout: 2592000
-    # token临时有效期 (指定时间内无操作就视为token过期) 单位: 秒
-    activity-timeout: -1
-    # 是否允许同一账号并发登录 (为true时允许一起登录, 为false时新登录挤掉旧登录) 
-    is-concurrent: true
-    # 在多人登录同一账号时，是否共用一个token (为true时所有登录共用一个token, 为false时每次登录新建一个token) 
-    is-share: true
-    # token风格
-    token-style: uuid
-    # 是否输出操作日志 
-    is-log: false
+	# token 名称（同时也是 cookie 名称）
+	token-name: satoken
+	# token 有效期（单位：秒），默认30天，-1代表永不过期 
+	timeout: 2592000
+	# token 最低活跃频率（单位：秒），如果 token 超过此时间没有访问系统就会被冻结，默认-1 代表不限制，永不冻结
+	activity-timeout: -1
+	# 是否允许同一账号多地同时登录（为 true 时允许一起登录，为 false 时新登录挤掉旧登录）
+	is-concurrent: true
+	# 在多人登录同一账号时，是否共用一个 token （为 true 时所有登录共用一个 token，为 false 时每次登录新建一个 token）
+	is-share: true
+	# token 风格
+	token-style: uuid
+	# 是否输出操作日志 
+	is-log: false
 ```

 <!------------- tab:app.properties 风格  ------------->
@@ -83,17 +83,17 @@ server.port=8081
    
 ############## Sa-Token 配置 (文档: https://sa-token.cc) ##############

-# token名称 (同时也是cookie名称)
+# token名称（同时也是 cookie 名称）
 sa-token.token-name=satoken
-# token有效期，单位s 默认30天, -1代表永不过期 
+# token 有效期（单位：秒），默认30天，-1代表永不过期 
 sa-token.timeout=2592000
-# token临时有效期 (指定时间内无操作就视为token过期) 单位: 秒
+# token 最低活跃频率（单位：秒），如果 token 超过此时间没有访问系统就会被冻结，默认-1 代表不限制，永不冻结
 sa-token.activity-timeout=-1
-# 是否允许同一账号并发登录 (为true时允许一起登录, 为false时新登录挤掉旧登录) 
+# 是否允许同一账号多地同时登录（为 true 时允许一起登录，为 false 时新登录挤掉旧登录）
 sa-token.is-concurrent=true
-# 在多人登录同一账号时，是否共用一个token (为true时所有登录共用一个token, 为false时每次登录新建一个token) 
+# 在多人登录同一账号时，是否共用一个 token （为 true 时所有登录共用一个 token，为 false 时每次登录新建一个 token）
 sa-token.is-share=true
-# token风格
+# token 风格
 sa-token.token-style=uuid
 # 是否输出操作日志 
 sa-token.is-log=false
--- a/sa-token-doc/use/config.md
+++ b/sa-token-doc/use/config.md
@@ -12,17 +12,17 @@
 ``` yaml
 ############## Sa-Token 配置 (文档: https://sa-token.cc) ##############
 sa-token: 
-	# token名称 (同时也是cookie名称)
+	# token 名称（同时也是 cookie 名称）
 	token-name: satoken
-	# token有效期，单位s 默认30天, -1代表永不过期 
+	# token 有效期（单位：秒），默认30天，-1代表永不过期 
 	timeout: 2592000
-	# token临时有效期 (指定时间内无操作就视为token过期) 单位: 秒
+	# token 最低活跃频率（单位：秒），如果 token 超过此时间没有访问系统就会被冻结，默认-1 代表不限制，永不冻结
 	activity-timeout: -1
-	# 是否允许同一账号并发登录 (为true时允许一起登录, 为false时新登录挤掉旧登录) 
+	# 是否允许同一账号多地同时登录（为 true 时允许一起登录，为 false 时新登录挤掉旧登录）
 	is-concurrent: true
-	# 在多人登录同一账号时，是否共用一个token (为true时所有登录共用一个token, 为false时每次登录新建一个token) 
+	# 在多人登录同一账号时，是否共用一个 token （为 true 时所有登录共用一个 token，为 false 时每次登录新建一个 token）
 	is-share: true
-	# token风格
+	# token 风格
 	token-style: uuid
 	# 是否输出操作日志 
 	is-log: false
@@ -32,17 +32,17 @@ sa-token:
 ``` properties
 ############## Sa-Token 配置 (文档: https://sa-token.cc) ##############

-# token名称 (同时也是cookie名称)
+# token名称（同时也是 cookie 名称）
 sa-token.token-name=satoken
-# token有效期，单位s 默认30天, -1代表永不过期 
+# token 有效期（单位：秒），默认30天，-1代表永不过期 
 sa-token.timeout=2592000
-# token临时有效期 (指定时间内无操作就视为token过期) 单位: 秒
+# token 最低活跃频率（单位：秒），如果 token 超过此时间没有访问系统就会被冻结，默认-1 代表不限制，永不冻结
 sa-token.activity-timeout=-1
-# 是否允许同一账号并发登录 (为true时允许一起登录, 为false时新登录挤掉旧登录) 
+# 是否允许同一账号多地同时登录（为 true 时允许一起登录，为 false 时新登录挤掉旧登录）
 sa-token.is-concurrent=true
-# 在多人登录同一账号时，是否共用一个token (为true时所有登录共用一个token, 为false时每次登录新建一个token) 
+# 在多人登录同一账号时，是否共用一个 token （为 true 时所有登录共用一个 token，为 false 时每次登录新建一个 token）
 sa-token.is-share=true
-# token风格
+# token 风格
 sa-token.token-style=uuid
 # 是否输出操作日志 
 sa-token.is-log=false
@@ -68,12 +68,12 @@ public class SaTokenConfigure {
    @Primary
    public SaTokenConfig getSaTokenConfigPrimary() {
 		SaTokenConfig config = new SaTokenConfig();
-		config.setTokenName("satoken");             // token名称 (同时也是cookie名称)
-		config.setTimeout(30 * 24 * 60 * 60);       // token有效期，单位s 默认30天
-		config.setActivityTimeout(-1);              // token临时有效期 (指定时间内无操作就视为token过期) 单位: 秒
-		config.setIsConcurrent(true);               // 是否允许同一账号并发登录 (为true时允许一起登录, 为false时新登录挤掉旧登录) 
-		config.setIsShare(true);                    // 在多人登录同一账号时，是否共用一个token (为true时所有登录共用一个token, 为false时每次登录新建一个token) 
-		config.setTokenStyle("uuid");               // token风格 
+		config.setTokenName("satoken");             // token 名称（同时也是 cookie 名称）
+		config.setTimeout(30 * 24 * 60 * 60);       // token 有效期（单位：秒），默认30天，-1代表永不过期 
+		config.setActivityTimeout(-1);              // token 最低活跃频率（单位：秒），如果 token 超过此时间没有访问系统就会被冻结，默认-1 代表不限制，永不冻结
+		config.setIsConcurrent(true);               // 是否允许同一账号多地同时登录（为 true 时允许一起登录，为 false 时新登录挤掉旧登录）
+		config.setIsShare(true);                    // 在多人登录同一账号时，是否共用一个 token （为 true 时所有登录共用一个 token，为 false 时每次登录新建一个 token）
+		config.setTokenStyle("uuid");               // token 风格
 		config.setIsLog(false);                     // 是否输出操作日志 
 		return config;
 	}
@@ -90,12 +90,12 @@ public class SaTokenConfigure {
 	// 此配置会与 application.yml 中的配置合并 （代码配置优先）
 	@Autowired
 	public void configSaToken(SaTokenConfig config) {
-		config.setTokenName("satoken");             // token名称 (同时也是cookie名称)
-		config.setTimeout(30 * 24 * 60 * 60);       // token有效期，单位s 默认30天
-		config.setActivityTimeout(-1);              // token临时有效期 (指定时间内无操作就视为token过期) 单位: 秒
-		config.setIsConcurrent(true);               // 是否允许同一账号并发登录 (为true时允许一起登录, 为false时新登录挤掉旧登录) 
-		config.setIsShare(true);                    // 在多人登录同一账号时，是否共用一个token (为true时所有登录共用一个token, 为false时每次登录新建一个token) 
-		config.setTokenStyle("uuid");               // token风格 
+		config.setTokenName("satoken");             // token 名称（同时也是 cookie 名称）
+		config.setTimeout(30 * 24 * 60 * 60);       // token 有效期（单位：秒），默认30天，-1代表永不过期 
+		config.setActivityTimeout(-1);              // token 最低活跃频率（单位：秒），如果 token 超过此时间没有访问系统就会被冻结，默认-1 代表不限制，永不冻结
+		config.setIsConcurrent(true);               // 是否允许同一账号多地同时登录（为 true 时允许一起登录，为 false 时新登录挤掉旧登录）
+		config.setIsShare(true);                    // 在多人登录同一账号时，是否共用一个 token （为 true 时所有登录共用一个 token，为 false 时每次登录新建一个 token）
+		config.setTokenStyle("uuid");               // token 风格
 		config.setIsLog(false);                     // 是否输出操作日志 
 	}
 }
@@ -115,11 +115,11 @@ public class SaTokenConfigure {
 | 参数名称				| 类型		| 默认值		| 说明																				|
 | :--------				| :--------	| :--------	| :--------																			|
 | tokenName				| String	| satoken	| Token 名称 （同时也是 Cookie 名称、数据持久化前缀）													|
-| timeout				| long		| 2592000	| Token 有效期，单位/秒 默认30天，-1代表永久有效	[参考：token有效期详解](/fun/token-timeout)		|
-| activityTimeout		| long		| -1		| Token 临时有效期 （指定时间内无操作就视为token过期） 单位: 秒, 默认-1 代表不限制 （例如可以设置为1800代表30分钟内无操作就过期） 	[参考：token有效期详解](/fun/token-timeout)													|
+| timeout				| long		| 2592000	| Token 有效期（单位：秒），默认30天，-1代表永不过期 [参考：token有效期详解](/fun/token-timeout)		|
+| activityTimeout		| long		| -1		| Token 最低活跃频率（单位：秒），如果 token 超过此时间没有访问系统就会被冻结，默认-1 代表不限制，永不冻结（例如可以设置为1800代表30分钟内无操作就过期） 	[参考：token有效期详解](/fun/token-timeout)													|
 | isConcurrent			| Boolean	| true		| 是否允许同一账号并发登录 （为 true 时允许一起登录，为 false 时新登录挤掉旧登录）															|
-| isShare				| Boolean	| true		| 在多人登录同一账号时，是否共用一个token （为 true 时所有登录共用一个 token, 为 false 时每次登录新建一个 token） 	|
-| maxLoginCount			| int		| 12		| 同一账号最大登录数量，-1代表不限 （只有在 `isConcurrent=true`, `isShare=false` 时此配置才有效），[详解](/use/config?id=配置项详解：maxlogincount)	|
+| isShare				| Boolean	| true		| 在多人登录同一账号时，是否共用一个 token （为 true 时所有登录共用一个 token，为 false 时每次登录新建一个 token） 	|
+| maxLoginCount			| int		| 12		| 同一账号最大登录数量，-1代表不限 （只有在 `isConcurrent=true`，`isShare=false` 时此配置才有效），[详解](/use/config?id=配置项详解：maxlogincount)	|
 | maxTryTimes			| int		| 12		| 在每次创建 Token 时的最高循环次数，用于保证 Token 唯一性（-1=不循环重试，直接使用）			|
 | isReadBody			| Boolean	| true		| 是否尝试从 请求体 里读取 Token														|
 | isReadHeader			| Boolean	| true		| 是否尝试从 header 里读取 Token														|
@@ -128,7 +128,7 @@ public class SaTokenConfigure {
 | tokenStyle			| String	| uuid		| token风格， [参考：自定义Token风格](/up/token-style)										|
 | dataRefreshPeriod		| int		| 30		| 默认数据持久组件实现类中，每次清理过期数据间隔的时间 （单位: 秒） ，默认值30秒，设置为-1代表不启动定时清理 		|
 | tokenSessionCheckLogin	| Boolean	| true	| 获取 `Token-Session` 时是否必须登录 （如果配置为true，会在每次获取 `Token-Session` 时校验是否登录），[详解](/use/config?id=配置项详解：tokenSessionCheckLogin)		|
-| autoRenew				| Boolean	| true		| 是否打开自动续签 （如果此值为true, 框架会在每次直接或间接调用 `getLoginId()` 时进行一次过期检查与续签操作），[参考：token有效期详解](/fun/token-timeout)		|
+| autoRenew				| Boolean	| true		| 是否打开自动续签 （如果此值为true，框架会在每次直接或间接调用 `getLoginId()` 时进行一次过期检查与续签操作），[参考：token有效期详解](/fun/token-timeout)		|
 | tokenPrefix			| String	| null		| token前缀，例如填写 `Bearer` 实际传参 `satoken: Bearer xxxx-xxxx-xxxx-xxxx` 	[参考：自定义Token前缀](/up/token-prefix) 			|
 | isPrint				| Boolean	| true		| 是否在初始化配置时打印版本字符画													|
 | isLog					| Boolean	| false		| 是否打印操作日志																	|