在Redis的众多配置项中，timeout是一个经常被忽视但又与连接稳定性息息相关的参数。它控制的是服务器端主动关闭空闲客户端连接的阈值时间。所谓空闲连接，指的是在这个时间段内客户端没有向服务器发送任何命令请求的连接。很多线上出现的“连接莫名断开”“JedisConnectionException间歇性爆发”等问题，追根溯源都和这个参数的配置不当有关。本文将系统讲解timeout的工作机制、配置方法以及与客户端侧超时的配合策略。
timeout参数的工作机制与底层逻辑
Redis的timeout参数以秒为单位，默认值为0。当设置为0时，服务器永远不会主动关闭空闲的客户端连接，无论这个连接空闲多久都会一直保留。当设置为一个正整数时，比如120，那么一旦某个客户端连接超过120秒没有执行任何命令，Redis服务器就会关闭这个连接。
理解这个机制有几个关键细节需要注意。第一，这里判断的是“读写空闲”，即客户端没有发送命令请求，而不仅仅是客户端没有接收数据。第二，Redis只有在非阻塞模式下关闭连接。如果客户端正在执行阻塞操作（比如执行了BLPOP正在等待列表数据，或者处于SUBSCRIBE订阅状态），timeout规则不会生效，这类连接不会被当作空闲连接关闭。这一点非常重要，因为很多消息订阅类应用依赖长连接，如果不了解这个特性，可能会误以为timeout会切断订阅连接。
第三，timeout关闭连接时客户端不会收到任何预告。服务器直接关闭TCP连接，客户端在下一次发送命令时才发现连接已断，通常会抛出连接异常。这就是为什么timeout设置过小时，应用日志里会周期性地出现连接错误的原因。
timeout的配置方法与动态修改
timeout的配置有两种主要方式。第一种是静态配置，直接修改redis.conf配置文件，在文件中找到timeout配置项进行修改：
# redis.conf 中的配置 # 关闭空闲连接的超时时间，0表示禁用 timeout 120 # 修改后需要重启Redis服务才能生效 redis-server /etc/redis/redis.conf
第二种是动态修改，通过CONFIG SET命令在线生效，不需要重启服务：
# 在线查看当前timeout配置 redis-cli CONFIG GET timeout # 返回结果示例：timeout 120 # 动态修改为300秒 redis-cli CONFIG SET timeout 300 # 如果想永久保存到配置文件，可以执行 redis-cli CONFIG REWRITE
建议在低峰期执行动态修改。需要注意，动态修改只影响之后的空闲判断，已经在空闲中的连接会按新的阈值重新计算。如果使用的是云上托管Redis（如阿里云、腾讯云），部分实例可能限制了CONFIG SET权限，需要在控制台修改参数。
timeout与TCP keepalive的区别与配合
很多初学者会把timeout和tcp-keepalive搞混。两者的作用完全不同：timeout针对的是应用层的“命令空闲”，关闭的是活着的但长期不工作的连接；tcp-keepalive针对的是TCP层的存活探测，用来清理那些对端已经崩溃、变成“僵尸”的半开连接，比如客户端进程被强杀、机器断电等场景下，服务器端会残留一个TCP连接，对端永远不会再响应，keepalive探测失败后才会清理。
Redis从3.2版本开始，tcp-keepalive默认值为300秒，这是一个比较合理的默认值，一般不需要修改。两者配合使用的推荐策略是：timeout负责清理“活着但空闲”的连接，tcp-keepalive负责清理“已经死了”的连接。如果timeout设为0（永不关闭空闲连接），那么服务器必须依赖tcp-keepalive来防止僵尸连接无限堆积。
# 查看keepalive配置 redis-cli CONFIG GET tcp-keepalive # 1.tcp-keepalive # 300
不同业务场景下的推荐取值与实践建议
timeout没有一个放之四海而皆准的最优值，需要结合业务特征来定。对于普通的Web应用连接池场景，一般建议设置在300到600秒之间。因为连接池本身会有空闲回收机制，服务端的timeout只是最后一道防线，设置得比客户端连接池的空闲回收时间稍长一些比较稳妥，避免客户端刚想复用连接时发现已被服务端关闭。
对于连接数有限、需要严格控制资源的场景，比如单机部署了多个应用实例、maxclients设置不高的情况，可以将timeout调小到120秒甚至60秒，加快空闲连接的回收速度，防止连接数被耗尽。而对于长连接推送、发布订阅场景，由于阻塞类连接不受timeout影响，可以放心保持一个中等值，比如300秒。
最重要的实践原则是：客户端侧必须有配套的超时和重连机制。以Java的Lettuce或Jedis客户端为例，连接池需要配置testWhileIdle、minEvictableIdleTimeMillis等参数，并开启空闲检测，确保借出连接前验证连接可用性。这样即使服务端关闭了连接，客户端也能自动重建，业务无感知。
如何排查timeout导致的连接断开问题
如果怀疑连接被timeout误杀，可以通过几个命令来排查。首先用CLIENT LIST查看当前所有客户端连接的idle字段，该字段表示连接已空闲的秒数：
# 查看所有连接，重点关注 idle 和 age 字段 redis-cli CLIENT LIST # id=15 addr=192.168.1.100:52341 age=3600 idle=350 db=0 ... # idle=350 说明该连接已空闲350秒 # 查看已关闭连接的统计信息 redis-cli INFO stats | grep expired # expired_connections 字段记录了因timeout被关闭的连接数
INFO stats中的expired_connections计数器统计了因空闲超时被关闭的连接总数。如果在应用运行期间这个数字持续快速增长，同时客户端日志中出现大量连接重置错误，基本可以断定timeout设置过小，需要适当调大，或者优化客户端连接池的空闲回收策略，让客户端先于服务端回收空闲连接。
总结一下配置思路：timeout默认0适合客户端管理规范、连接可控的环境；设为正整数适合开放环境或连接来源复杂的场景，取值需要大于客户端连接池的最大空闲时间，并确保客户端具备完善的断线重连能力。通过CLIENT LIST和INFO stats持续观察连接状态，才能让这套配置真正稳定运行。
Redis timeout空闲连接超时Redis连接配置修改时间：2026-08-31 06:03:05