Sa-Token框架配置详解：从入门到精通

一、Sa-Token配置概述

Sa-Token作为一款轻量级Java权限认证框架，提供了灵活的配置方式，开发者可以根据项目需求进行个性化定制。框架支持零配置启动，同时也提供了丰富的配置选项来满足不同场景下的权限控制需求。

二、配置方式详解

1. 配置文件方式

Sa-Token支持通过标准的Spring Boot配置文件进行配置，包括YAML和Properties两种格式：

YAML配置示例

sa-token:
  token-name: satoken
  timeout: 2592000
  active-timeout: -1
  is-concurrent: true
  is-share: false
  token-style: uuid
  is-log: true

Properties配置示例

sa-token.token-name=satoken
sa-token.timeout=2592000
sa-token.active-timeout=-1
sa-token.is-concurrent=true
sa-token.is-share=false
sa-token.token-style=uuid
sa-token.is-log=true

2. 代码配置方式

对于需要动态配置的场景，Sa-Token提供了两种代码配置模式：

模式1：覆盖式配置

@Configuration
public class SaTokenConfigure {
    @Bean
    @Primary
    public SaTokenConfig getSaTokenConfigPrimary() {
        SaTokenConfig config = new SaTokenConfig();
        config.setTokenName("satoken");
        config.setTimeout(30 * 24 * 60 * 60);
        // 其他配置...
        return config;
    }
}

模式2：合并式配置

@Configuration
public class SaTokenConfigure {
    @Autowired
    public void configSaToken(SaTokenConfig config) {
        config.setTokenName("satoken");
        config.setTimeout(30 * 24 * 60 * 60);
        // 其他配置...
    }
}

两种模式的区别：

• 模式1会完全覆盖配置文件中的配置
• 模式2会与配置文件中的配置合并（代码配置优先）

三、核心配置项解析

1. 基础认证配置

配置项	说明	默认值
token-name	Token名称（也是Cookie名称）	satoken
timeout	Token有效期（秒），-1表示永久	2592000（30天）
active-timeout	Token活跃有效期（秒），超时未访问会被冻结	-1（不限制）
is-concurrent	是否允许同一账号多地同时登录	true
is-share	多人登录同一账号时是否共享Token	false
token-style	Token生成风格（uuid/simple-uuid等）	uuid

2. Cookie相关配置

sa-token:
  cookie:
    domain: stp.com
    path: /
    secure: false
    httpOnly: true
    sameSite: Lax
    extraAttrs:
      Priority: Medium
      Partitioned: ""

3. API签名配置

sa-token:
  sign:
    secret-key: kQwIOrYvnXmSDkwEiFngrKidMcdrgKor
    timestampDisparity: 900000
    digestAlgo: md5

4. API Key配置

sa-token:
  api-key:
    prefix: AK-
    timeout: 2592000
    is-record-index: true

四、单点登录(SSO)配置

1. SSO-Server端配置

sa-token:
  sso-server:
    ticket-timeout: 300
    home-route: /home
    is-slo: true
    clients:
      sso-client1:
        client: sso-client1
        allow-url: "*"
        secret-key: SSO-C1-kQwIOrYvnXmSDkwEiFngrKidMcdrgKor

2. SSO-Client端配置

sa-token:
  sso-client:
    server-url: http://sa-sso-server.com:9000
    is-slo: true

五、OAuth2.0配置

1. 服务端配置

sa-token:
  oauth2-server:
    enableAuthorizationCode: true
    enableImplicit: true
    codeTimeout: 300
    accessTokenTimeout: 7200
    refreshTokenTimeout: 2592000

六、配置最佳实践

1. 生产环境建议：

   • 务必设置合理的token有效期
   • 开启日志记录方便排查问题
   • 对于敏感操作开启签名校验

2. 开发环境建议：

   • 可以缩短token有效期方便测试
   • 可以关闭部分安全校验简化开发流程

3. 性能优化建议：

   • 根据并发量调整maxLoginCount
   • 合理设置dataRefreshPeriod减少清理频率

通过以上配置，开发者可以灵活地调整Sa-Token框架的行为，满足各种复杂的业务场景需求。建议在实际项目中根据具体需求选择合适的配置组合，并在不同环境中进行充分测试。