Tomcat 9.0.118 分布式 Redis Session 配置指南
配置目标: 实现多台Tomcat集群部署的Session共享
一、Redis Session Manager 概述
1.1 功能特性
- ✅ Session共享: 多台Tomcat共享Redis中的Session，支持集群部署
- ✅ Session持久化: Session存储在Redis中，Tomcat重启不丢失
- ✅ 高可用: Redis故障时可配置降级策略
- ✅ 无侵入: 应用代码无需修改，Tomcat容器级配置
1.2 适用场景
- 多实例集群部署
- 负载均衡环境
- 需要Session共享
- 需要会话持久化
二、JAR包清单
2.1 核心JAR包
| JAR包名称 | 版本 | 大小 | 说明 |
|---|---|---|---|
tomcat-cluster-redis-session-manager-4.0.jar |
4.0 | 250KB | Tomcat Redis Session Manager核心包 |
下载地址:
bash
# GitHub官方下载
wget https://github.com/ran-jit/tomcat-cluster-redis-session-manager/releases/download/4.0/tomcat-cluster-redis-session-manager-4.0.jar安装位置 : $CATALINA_HOME/lib/
2.2 依赖JAR包
| JAR包名称 | 版本 | 说明 |
|---|---|---|
jedis-3.10.0.jar |
3.10.0 | Redis Java客户端 |
commons-pool2-2.11.1.jar |
2.11.1 | 连接池依赖 |
注意: Redis Session Manager 4.0 已经内置了这些依赖，无需额外下载。
2.3 Tomcat版本兼容性
| Tomcat版本 | Redis Session Manager版本 | JAR包名称 |
|---|---|---|
| Tomcat 8.5.x | 3.0 | tomcat-cluster-redis-session-manager-3.0.jar |
| Tomcat 9.0.x | 4.0 | tomcat-cluster-redis-session-manager-4.0.jar |
| Tomcat 10.0.x | 5.0+ | tomcat-cluster-redis-session-manager-5.0.jar |
当前项目 : Tomcat 9.0.118 → 使用 4.0版本
三、安装配置步骤
3.1 下载并安装JAR包
bash
# 1. 进入Tomcat lib目录
cd /path/to/tomcat/lib
# 2. 下载Redis Session Manager
wget https://github.com/ran-jit/tomcat-cluster-redis-session-manager/releases/download/4.0/tomcat-cluster-redis-session-manager-4.0.jar
# 3. 验证下载
ls -lh tomcat-cluster-redis-session-manager-4.0.jar
# 应显示: -rw-r--r-- 1 user user 250K ... tomcat-cluster-redis-session-manager-4.0.jar
# 4. 验证JAR包完整性
jar -tf tomcat-cluster-redis-session-manager-4.0.jar | head -103.2 配置context.xml
文件位置 : $CATALINA_HOME/conf/context.xml
xml
<?xml version="1.0" encoding="UTF-8"?>
<Context>
<!-- 默认监听资源 -->
<WatchedResource>WEB-INF/web.xml</WatchedResource>
<WatchedResource>WEB-INF/tomcat-web.xml</WatchedResource>
<WatchedResource>${catalina.base}/conf/web.xml</WatchedResource>
<!-- Redis Session Manager 配置 -->
<Valve className="tomcat.request.session.redis.SessionHandlerValve" />
<Manager className="tomcat.request.session.redis.SessionManager" />
</Context>配置说明:
SessionHandlerValve: 处理Session请求拦截SessionManager: 管理Session的存储和读取
3.3 创建Redis配置文件
文件位置 : $CATALINA_HOME/conf/redis-data-cache.properties
properties
# Redis主机地址（支持多个，逗号分隔）
redis.hosts=127.0.0.1:6379
# Redis密码
redis.password=123456
# 集群模式（默认false）
redis.cluster.enabled=false
# 哨兵模式（默认false）
redis.sentinel.enabled=false
# redis.sentinel.master=mymaster
# Redis数据库索引（建议使用专用database）
redis.database=4
# 负载均衡粘性会话（默认false）
# 如果启用了，必须在负载均衡器配置sticky session
lb.sticky-session.enabled=false
# Session持久化策略（默认DEFAULT）
# 可选值: DEFAULT, SAVE_ON_CHANGE, ALWAYS_SAVE_AFTER_REQUEST
session.persistent.policies=DEFAULT
# SSO会话超时时间（毫秒，0=永不过期）
redis.sso.timeout=0四、配置参数详解
4.1 Redis连接参数
| 参数 | 默认值 | 说明 |
|---|---|---|
redis.hosts |
- | Redis主机地址，多个用逗号分隔 |
redis.password |
- | Redis密码 |
redis.database |
0 | Redis数据库索引（0-15） |
redis.timeout |
2000ms | Redis连接超时时间 |
4.2 集群模式配置
单机模式（默认）
properties
redis.hosts=127.0.0.1:6379
redis.cluster.enabled=false
redis.sentinel.enabled=falseRedis Cluster集群模式（仅参考）
properties
redis.hosts=192.168.1.1:6379,192.168.1.2:6379,192.168.1.3:6379
redis.cluster.enabled=true
redis.sentinel.enabled=falseRedis Sentinel哨兵模式（仅参考）
properties
redis.hosts=192.168.1.1:26379,192.168.1.2:26379,192.168.1.3:26379
redis.cluster.enabled=false
redis.sentinel.enabled=true
redis.sentinel.master=mymaster4.3 Session持久化策略
| 策略 | 说明 | 性能影响 |
|---|---|---|
DEFAULT |
请求结束时保存Session | 低 |
SAVE_ON_CHANGE |
每次setAttribute/removeAttribute都保存 | 中 |
ALWAYS_SAVE_AFTER_REQUEST |
每次请求后强制保存 | 高 |
推荐 : 使用 DEFAULT 策略，性能最优。
4.4 粘性会话配置
不启用粘性会话（推荐）
properties
lb.sticky-session.enabled=false- Session在所有Tomcat实例间共享
- 负载均衡器无需特殊配置
启用粘性会话
properties
lb.sticky-session.enabled=true- 需要在负载均衡器配置sticky session
- Session值存储在本地JVM和Redis
- Redis故障时使用本地Session降级
五、多环境配置示例
5.1 开发环境配置
properties
# 单机Redis
redis.hosts=127.0.0.1:6379
redis.password=
redis.database=0
redis.cluster.enabled=false
redis.sentinel.enabled=false
lb.sticky-session.enabled=false
session.persistent.policies=DEFAULT5.2 测试环境配置
properties
# 单机Redis，使用专用database
redis.hosts=192.168.1.100:6379
redis.password=123456
redis.database=1
redis.cluster.enabled=false
redis.sentinel.enabled=false
lb.sticky-session.enabled=false
session.persistent.policies=DEFAULT5.3 生产环境配置（仅参考）
properties
# Redis Cluster集群
redis.hosts=192.168.1.1:6379,192.168.1.2:6379,192.168.1.3:6379
redis.password=123456
redis.database=4
redis.cluster.enabled=true
redis.sentinel.enabled=false
lb.sticky-session.enabled=false
session.persistent.policies=DEFAULT
redis.sso.timeout=05.4 高可用生产环境配置（仅参考）
properties
# Redis Sentinel哨兵集群
redis.hosts=192.168.1.1:26379,192.168.1.2:26379,192.168.1.3:26379
redis.password=123456
redis.database=4
redis.cluster.enabled=false
redis.sentinel.enabled=true
redis.sentinel.master=mymaster
lb.sticky-session.enabled=false
session.persistent.policies=DEFAULT
redis.sso.timeout=0六、配置验证
6.1 启动验证
成功日志:
INFO: Loaded Apache Tomcat Native library [1.3.x]
INFO: Redis Session Manager initialized successfully
INFO: Server startup in [xxxx] milliseconds失败日志:
SEVERE: Unable to load Redis Session Manager
SEVERE: Could not connect to Redis at 127.0.0.1:63796.2 功能验证
步骤1: 检查Redis连接
bash
redis-cli -h 127.0.0.1 -p 6379 -a 123456 ping
# 应返回: PONG步骤2: 检查Session存储
bash
# 访问应用，触发Session创建
curl http://localhost:8080/your-app/
# 查看Redis中的Session
redis-cli -h 127.0.0.1 -p 6379 -a 123456
SELECT 4
KEYS *
# 应显示类似: session:xxx-xxx-xxx-xxx步骤3: 验证Session共享
bash
# 部署两台Tomcat实例
# Tomcat1: http://192.168.1.10:8080/app/
# Tomcat2: http://192.168.1.11:8080/app/
# 在Tomcat1创建Session，在Tomcat2验证Session是否存在
redis-cli -h 127.0.0.1 -p 6379 -a 123456
SELECT 4
GET session:xxx七、常见问题排查
7.1 JAR包找不到
错误日志:
java.lang.ClassNotFoundException: tomcat.request.session.redis.SessionManager解决方案:
bash
# 检查jar包是否存在
ls -l $CATALINA_HOME/lib/tomcat-cluster-redis-session-manager-*.jar
# 如果不存在，重新下载
wget https://github.com/ran-jit/tomcat-cluster-redis-session-manager/releases/download/4.0/tomcat-cluster-redis-session-manager-4.0.jar
cp tomcat-cluster-redis-session-manager-4.0.jar $CATALINA_HOME/lib/7.2 JAR包版本不匹配
错误日志:
java.lang.NoSuchMethodError: org.apache.catalina.session.ManagerBase.xxx原因: Redis Session Manager版本与Tomcat版本不兼容
解决方案:
bash
# 检查Tomcat版本
./bin/catalina.sh version
# 根据Tomcat版本下载对应Redis Session Manager
# Tomcat 9.0.x → 使用 4.0版本7.3 Redis连接失败
错误日志:
Could not connect to Redis at 127.0.0.1:6379排查步骤:
bash
# 1. 检查Redis服务是否启动
systemctl status redis
# 或
ps aux | grep redis
# 2. 检查Redis端口是否监听
netstat -tlnp | grep 6379
# 3. 检查防火墙
firewall-cmd --list-ports
# 4. 测试连接
redis-cli -h 127.0.0.1 -p 6379 ping7.4 Session序列化失败
错误日志:
java.io.NotSerializableException: com.xxx.XXXClass解决方案:
java
// 确保Session中的对象实现了Serializable接口
public class UserSession implements Serializable {
private static final long serialVersionUID = 1L;
// ...
}7.5 Redis数据库冲突
问题描述: 多个应用使用同一个Redis数据库，Session数据冲突
解决方案:
properties
# 为不同应用分配不同的database
# 应用1: database=4
redis.database=4
# 应用2: database=5
redis.database=5八、性能优化建议
8.1 连接池优化
Redis Session Manager默认使用连接池，无需额外配置。
建议:
- 单机Redis: 默认配置即可
- 集群Redis: 适当增加连接池大小
8.2 Session超时配置
web.xml配置:
xml
<session-config>
<session-timeout>30</session-timeout> <!-- 30分钟 -->
</session-config>注意: Session超时由Tomcat管理，Redis中Session会自动过期删除。
8.3 Redis内存优化
查看Redis内存使用:
bash
redis-cli -h 127.0.0.1 -p 6379 -a 123456
INFO memory优化建议:
- 设置Redis最大内存:
maxmemory 2gb - 设置淘汰策略:
maxmemory-policy allkeys-lru
九、应用级依赖配置
9.1 pom.xml配置
如果应用代码中也需要使用Redis（业务缓存），需要在项目的 pom.xml 中添加：
xml
<!-- Redis客户端 -->
<dependency>
<groupId>redis.clients</groupId>
<artifactId>jedis</artifactId>
<version>3.10.0</version>
</dependency>
<!-- 连接池（Jedis 3.x需要） -->
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-pool2</artifactId>
<version>2.11.1</version>
</dependency>注意:
- Tomcat Session Manager 和应用业务可以共用同一个Redis服务
- Session Manager使用
database=4，业务数据建议使用database=1，避免冲突
十、配置检查清单
10.1 安装前检查
- Tomcat版本 >= 8.5
- JDK版本 >= 1.8
- Redis服务可用
- 网络连通性正常
10.2 配置检查
- jar包已复制到
$CATALINA_HOME/lib/ -
context.xml已配置SessionManager和SessionHandlerValve -
redis-data-cache.properties文件存在 - Redis主机地址正确
- Redis密码正确
- Redis数据库索引正确
10.3 启动验证
- Tomcat启动成功
- 日志无ERROR
- 应用可访问
- Session可创建
- Redis中存在Session数据
十一、参考资源
| 资源 | 链接 |
|---|---|
| Redis Session Manager 4.0下载 | https://github.com/ran-jit/tomcat-cluster-redis-session-manager/releases/download/4.0/tomcat-cluster-redis-session-manager-4.0.jar |
| Redis Session Manager GitHub | https://github.com/ran-jit/tomcat-cluster-redis-session-manager |
| Tomcat 9 文档 | https://tomcat.apache.org/tomcat-9.0-doc/ |
| Redis 官方文档 | https://redis.io/documentation |
| Redis Cluster教程 | https://redis.io/topics/cluster-tutorial |
| Redis Sentinel文档 | https://redis.io/topics/sentinel |
| Jedis GitHub | https://github.com/redis/jedis |
| Commons Pool2 | https://commons.apache.org/proper/commons-pool/ |