Sa-Token 详细配置指南：从入门到生产环境最佳实践！

视频看了几百小时还迷糊？关注我，几分钟让你秒懂！

Sa-Token 是一个轻量级 Java 权限认证框架，开箱即用、零侵入、API 极简。但很多开发者在集成后发现：

• 登录后 token 没生效？
• 会话无法跨服务共享？
• 用户登出不彻底？
• 权限校验总是失败？

其实，这些问题大多源于 配置不当！

本文将带你 全面掌握 Sa-Token 的核心配置项，涵盖 基础设置、Redis 集成、安全加固、生产调优，并附上 完整 Spring Boot 示例 + 反例避坑指南，小白也能一次配对！

🧩 一、Sa-Token 配置方式

Sa-Token 支持两种配置方式：

我们以 application.yml 为主，这是最常用的方式。

🔧 二、完整配置示例（含注释）

sa-token:
# 【必看】核心配置项说明 ↓↓↓

# Token 名称（前端请求头中携带的字段名）
token-name: Authorization # 默认: satoken

# Token 有效期（单位：秒），-1 表示永不过期
timeout: 2592000 # 默认: 2592000 (30天)

# Token 最低活跃时间（单位：秒）
# 用户在 timeout 时间内至少访问一次，token 才会续期
active-timeout: 1800 # 默认: 0（不启用）

# 是否允许同一账号多地登录（true=允许，false=新登录踢掉旧会话）
is-concurrent: false # 默认: true

# 在多人登录同一账号时，是否共用一个 token（true=共用，false=独立）
is-share: false # 默认: false

# Token 风格（可选：uuid / simple-uuid / random-32 / random-64 / tiktok-uuid）
token-style: uuid # 默认: uuid

# 是否输出 Sa-Token 日志（用于调试）
is-log: true # 默认: false

# 【重要】是否在 Cookie 中写入 token（Web 项目可开启）
is-write-header: true # 默认: true（写入响应头）
is-read-cookie: false # 默认: false（不从 Cookie 读）

# 【分布式必备】Session 存储方式（默认内存，生产必须改 Redis！）
# 注意：只要引入 spring-boot-starter-data-redis，Sa-Token 会自动使用 Redis！

✅ 只需添加以上配置，即可满足 90% 场景！

🌐 三、生产环境关键配置详解

1. Token 名称（token-name）

• 前端需在请求头中携带此字段：

  GET /api/user
  Authorization: xxx-xxx-xxx

• 如果你用的是 satoken（默认值），前端就要传 satoken: xxx；
• 建议改为 Authorization，符合 RESTful 规范，也方便网关统一处理。

2. 会话有效期（timeout & active-timeout）

💡 推荐组合：

• 普通系统：timeout=86400（1天），active-timeout=1800（30分钟）
• 金融/支付系统：timeout=1800，active-timeout=300

3. 并发控制（is-concurrent）

• is-concurrent: false → 单点登录（SSO）效果
  用户在 A 设备登录后，B 设备再登录，A 设备自动失效。
• is-concurrent: true → 允许多地同时在线（如 Web + App）

✅ 大多数后台管理系统应设为 false，提升安全性！

4. Token 风格（token-style）

🔥 生产推荐：tiktok-uuid，既保证唯一性，又便于日志追踪和数据库索引优化。

🚀 四、集成 Redis（分布式会话必备）

1. 添加依赖

<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>

2. 配置 Redis 连接（application.yml）

spring:
redis:
host: localhost
port: 6379
password:
database: 0
timeout: 2000ms

✅ 无需任何额外代码！ Sa-Token 检测到 Redis 后，自动将会话存储到 Redis，支持集群、重启不丢失！

⚠️ 五、反例：错误配置导致的安全问题

❌ 反例1：生产环境未配 Redis

# 什么都没配，默认用内存存储

后果：

• 服务重启 → 所有用户掉线；
• 多实例部署 → 会话不共享，登录状态混乱。

❌ 反例2：token-name 与前端不一致

sa-token:
token-name: satoken

但前端传的是：

axios.defaults.headers.common['Authorization'] = token;

后果：Sa-Token 找不到 token，所有请求返回 401！

✅ 解决：统一命名，或让前端按 satoken 字段传。

❌ 反例3：is-concurrent=true + 敏感系统

银行后台允许多地登录，黑客盗取 token 后可长期潜伏。

✅ 解决：敏感系统设 is-concurrent: false，新登录踢旧会话。

🛠 六、Java Config 方式（动态配置）

如果需要运行时动态调整配置（如从数据库读），可用 Java 方式：

@Configuration
public class SaTokenConfig {

@Bean
public SaTokenConfig config() {
return new SaTokenConfig()
.setTimeout(86400)
.setTokenName("Authorization")
.setIsConcurrent(false)
.setTokenStyle("tiktok-uuid")
.setIsLog(true);
}
}

⚠️ 注意：YAML 和 Java Config 不能同时生效，优先级：Java > YAML。

✅ 七、验证配置是否生效

1. 调用登录接口

POST /login
username=admin&password=123456

响应：

{ "token": "xxxx-xxxx-xxxx" }

2. 携带 Token 访问受保护接口

GET /user/info
Authorization: xxxx-xxxx-xxxx

✅ 返回用户信息 → 配置成功！

3. 查看 Redis（如有）

redis-cli
KEYS *satoken*

你会看到类似：

satoken:account:10001
satoken:token:xxxx-xxxx

说明会话已持久化！

🎯 总结：生产环境推荐配置

sa-token:
token-name: Authorization
timeout: 86400 # 1天
active-timeout: 1800 # 30分钟无操作则过期
is-concurrent: false # 单点登录
is-share: false
token-style: tiktok-uuid
is-log: false # 生产关闭日志

• 引入 Redis 依赖
• 前端统一使用 Authorization 请求头
• 敏感操作加二次验证（StpUtil.openSafe()）

视频看了几百小时还迷糊？关注我，几分钟让你秒懂！