From 013c08187db7b03f83f7a2fd99e01b35f923bee5 Mon Sep 17 00:00:00 2001 From: click33 <2393584716@qq.com> Date: Thu, 30 Jun 2022 09:35:56 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96=E6=96=87=E6=A1=A3=EF=BC=9A?= =?UTF-8?q?=E6=A1=86=E6=9E=B6=E9=85=8D=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- sa-token-doc/doc/use/config.md | 62 ++++++++++++++++++++++++++++------ 1 file changed, 52 insertions(+), 10 deletions(-) diff --git a/sa-token-doc/doc/use/config.md b/sa-token-doc/doc/use/config.md index 0f736806..7144d9e6 100644 --- a/sa-token-doc/doc/use/config.md +++ b/sa-token-doc/doc/use/config.md @@ -72,20 +72,23 @@ PS：两者的区别在于：**`模式1会覆盖yml中的配置，模式2会与y --- ### 所有可配置项 + +你不必立刻掌握整个表格，只需要在用到某个功能时再详细查阅它即可 + | 参数名称 | 类型 | 默认值 | 说明 | | :-------- | :-------- | :-------- | :-------- | -| 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) | -| isConcurrent | Boolean | true | 是否允许同一账号并发登录 (为true时允许一起登录, 为false时新登录挤掉旧登录) | -| isShare | Boolean | true | 在多人登录同一账号时，是否共用一个token (为true时所有登录共用一个token, 为false时每次登录新建一个token) | -| maxLoginCount | int | 12 | 同一账号最大登录数量，-1代表不限 （只有在 isConcurrent=true, isShare=false 时此配置才有效） | +| 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) | +| 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) | | isReadBody | Boolean | true | 是否尝试从 请求体 里读取 Token | | isReadHead | Boolean | true | 是否尝试从 header 里读取 Token | -| isReadCookie | Boolean | true | 是否尝试从 cookie 里读取 Token | -| tokenStyle | String | uuid | token风格, [参考：自定义Token风格](/up/token-style) | -| dataRefreshPeriod | int | 30 | 默认dao层实现类中，每次清理过期数据间隔的时间 (单位: 秒) ，默认值30秒，设置为-1代表不启动定时清理 | -| tokenSessionCheckLogin | Boolean | true | 获取 `Token-Session` 时是否必须登录 (如果配置为true，会在每次获取 `Token-Session` 时校验是否登录) | +| isReadCookie | Boolean | true | 是否尝试从 cookie 里读取 Token，此值为 false 后，`StpUtil.login(id)` 登录时也不会再往前端注入Cookie | +| 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()` 时进行一次过期检查与续签操作) | | tokenPrefix | String | null | token前缀, 例如填写 `Bearer` 实际传参 `satoken: Bearer xxxx-xxxx-xxxx-xxxx` [参考：自定义Token前缀](/up/token-prefix) | | isPrint | Boolean | true | 是否在初始化配置时打印版本字符画 | @@ -194,3 +197,42 @@ sa-token: | pastClientTokenTimeout | long | 取全局配置 | 单独配置此Client：`Past-Client-Token` 保存的时间（单位：秒） [默认取全局配置] | + +### 部分配置项详解 + +对部分配置项做一下详解 + +#### maxLoginCount + +配置含义：同一账号最大登录数量。 + +在配置 `isConcurrent=true`, `isShare=false` 时，Sa-Token 将允许同一账号并发登录，且每次登录都会产生一个新Token， +这些 Token 都会以 `TokenSign` 的形式记录在其 `User-Session` 之上，这就造成一个问题： + +随着同一账号登录的次数越来越多，TokenSign 的列表也会越来越大，极端情况下，列表长度可能达到成百上千以上，严重拖慢数据处理速度， +为此 Sa-Token 对这个 TokenSign 列表的大小设定一个上限值，也就是 `maxLoginCount`，默认值=12。 + +假设一个账号的登录数量超过 `maxLoginCount` 后，将会主动注销第一个登录的会话（先进先出），以此保证队列中的有效会话数量始终 `<= maxLoginCount` 值。 + + +#### tokenSessionCheckLogin +配置含义：获取 `Token-Session` 时是否必须登录 （如果配置为true，会在每次获取 `Token-Session` 时校验是否登录）。 + +主要用法：在调用 `StpUtil.login(id)` 登录后， + +- 调用 `StpUtil.getSession()` 可以获取这个会话的 `User-Session` 对象。 +- 调用 `StpUtil.getTokenSession()` 可以获取这个会话 `Token-Session` 对象。 + +关于两种 Session 有何区别，可以参考这篇：[Session模型详解](/fun/session-model)，此处暂不赘述。 + +从设计上讲，无论会话是否已经登录，只要前端提供了Token，我们就可以找到这个 Token 的专属 `Token-Session` 对象，**这非常灵活但不安全**， +因为前端提交的 Token 可能是任意伪造的。 + +为了解决这个问题，`StpUtil.getTokenSession()` 方法在获取 `Token-Session` 时，会率先检测一下这个 Token 是否是一个有效Token： +- 如果是有效Token，正常返回 `Token-Session` 对象 +- 如果是无效Token，则 + + + + +