JWT 与滑动窗口续签——不让活跃用户被踢下线

JWT 认证流程

1. 用户向 /api/v1/auth/login 提交凭证
2. 服务器校验后返回 JWT——包含 token、tokenType: Bearer、expiresIn（默认 24 小时）
3. 之后所有请求在 Authorization header 里带这个 token
4. 服务器在每个请求上校验 token 的签名和过期时间

滑动窗口续签

MateClaw 实现了一个大多数 JWT 系统没有的特性：滑动窗口 token 续签。

• 当 token 剩余有效期在 25% 以内时（比如 24 小时的 token 剩不到 6 小时）
• 服务器在每次响应头里加上 X-New-Token——一个全新的、完整 24 小时有效期的 token
• 前端自动拿到新 token，替换本地存的旧 token，用新 token 做后续请求
• 用户完全感知不到

这意味着：活跃用户永远不会被踢下线。每次在 token 快过期前，只要再发一个请求（哪怕只是刷新一下页面），就自动续上了。

不活跃的会话（比如一周没登录），token 真的过期了——登录重新来。

手动调 API 时注意

如果你在写脚本用 curl/Postman 调 API，需要自己处理续签：

1. 每次发请求后检查响应头有没有 X-New-Token
2. 有的话，把你的 token 更新成这个新值
3. 下次请求用新 token

如果忘了处理，会在某个请求上突然收到 401。

生产环境配置

必须改默认 JWT secret——至少 32 字符。用环境变量 JWT_SECRET=... 设置，不要 commit 进仓库。可以配置的参数包括：token 有效期（毫秒）、是否启用滑动窗口续签。