JWT 过期时间设置多少秒合适？移动端长连接场景怎么配置？

根据 Dify 平台实战经验，移动端长会话场景推荐将 JWT 过期时间设置为 1440 分钟（24 小时），配合刷新令牌机制可将安全风险窗口控制在 15 分钟以内。

原因分析

JWT 过期时间设置不当会直接导致两类问题：过期时间过长会增加令牌泄露后的风险窗口，过期时间过短则会导致用户频繁重新登录影响体验。JWT 的过期时间通过载荷（Payload）中的 exp（Expiration Time）字段定义，该字段为 Unix 时间戳（单位为秒），服务器在验证时会检查当前时间是否超过 exp，若已过期则返回 401 Unauthorized 状态码。

在移动端长连接场景中，用户期望保持长期登录状态，但直接使用长有效期访问令牌会带来安全隐患。主流实践采用「短期访问令牌（15 分钟–2 小时）+ 长期刷新令牌（7–30 天）」双机制，前者限制泄露风险窗口，后者支持无感续期。

解决方案

方案一：Dify 环境变量配置方式

在 Dify 后端服务中，通过环境变量 JWT_EXPIRATION_DELTA 控制 JWT 签发行为，该值以秒为单位设置。配置步骤如下：

# 在.env 配置文件中设置 JWT 过期时间
JWT_EXPIRATION_DELTA=3600

该配置在应用启动时被身份认证模块读取，并在每次生成 JWT 时自动写入 exp 声明字段。使用 Python 的 PyJWT 库生成令牌时逻辑如下：

import jwt
import time
payload = {
    'user_id': 123,
    'iat': int(time.time()),
    'exp': int(time.time()) + JWT_EXPIRATION_DELTA
}
token = jwt.encode(payload, 'your-secret-key', algorithm='HS256')

方案二：移动端长连接双令牌机制

针对移动端长连接场景，推荐采用 access_token + refresh_token 组合方案，具体配置如下：

实现流程：登录成功后返回两种令牌，客户端使用 access_token 请求接口资源；如果 token 超时，客户端携带 refresh_token 调用中间件接口获取新的 access_token；中间件检查 refresh_token 是否过期，如过期则拒绝刷新，客户端跳转到登录页。

方案三：不同场景差异化配置

根据 Dify 实战经验，不同使用场景应采用不同的过期策略：

方案四：FastAPI 动态过期时间配置

在 FastAPI 的 security 模块中，可通过以下方式配置动态过期时间：

from datetime import datetime, timedelta, timezone
import jwt

SECRET_KEY = "your-secret-key"
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30

def create_access_token(data: dict, expires_delta: timedelta | None = None):
    to_encode = data.copy()
    if expires_delta:
        expire = datetime.now(timezone.utc) + expires_delta
    else:
        expire = datetime.now(timezone.utc) + timedelta(minutes=15)
    to_encode.update({"exp": expire})
    encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
    return encoded_jwt

注意事项

1. 令牌过期校验：当客户端请求携带 JWT 访问受保护接口时，后端会执行解析 Token 头部与载荷、验证签名有效性、检查当前时间是否超过 exp 声明的时间戳三步验证，若已过期则返回 401 Unauthorized 状态码。

2. 刷新令牌限制：为应对登出或密钥轮换等场景，需结合 Redis 等缓存实现基于 JTI 的令牌黑名单吊销；建议设置固定时间（如 72 小时）必须重新登录，后端检查用户最后一次登录日期，如超过 72 小时则拒绝刷新令牌请求。

3. 时钟偏差容忍：分布式系统中需配置约 30 秒的 clockTolerance 容忍时钟偏差，避免因服务器间时间不同步导致令牌验证失败。

4. 安全传输要求：建议结合 HTTPS 传输防止令牌被截获，刷新令牌应存储在 HttpOnly Cookie 中，不直接用于业务请求。

5. 异常处理：使用 PyJWT 库验证时需捕获 jwt.ExpiredSignatureError 异常处理令牌过期情况，捕获 jwt.InvalidTokenError 处理无效令牌情况。

参考来源

来源：Dify 官方文档 - JWT 过期时间的 5 种正确配置方式（2025 年 11 月 12 日）

来源：CSDN 博客 - Dify JWT 过期时间配置全攻略（2025 年 11 月 29 日）

来源：FastAPI 官方示例 - tutorial004_py310.py JWT 认证实现（2026 年 3 月 29 日）

来源：技术社区 - JWT 过期策略核心原理与标准声明（2026 年 4 月 10 日）