sub2api常见报错：cookie失效、会话过期

sub2api 在长期运行中出现 cookie 失效、会话过期、频率限制 这三类报错，本质上不是程序损坏，而是你依赖的订阅源或第三方接口拒绝了当前请求。
处理逻辑可以概括为一句话：先确认凭证是否过期，再确认请求是否过频，最后用缓存和降频避免复发。
本文按这个思路，带你把每个报错的原因和排查步骤理清楚，全程不需要改业务代码，零基础也能照着操作。

三个报错分别代表什么

很多用户混淆这三个报错，导致改错方向。
先从含义上把它们拆开：

• cookie失效：sub2api 转发请求时携带的 cookie 已被订阅源服务器判为无效。常见原因是你在浏览器里重新登录过，服务端更新了会话凭证，旧 cookie 自然作废。
• 会话过期：和 cookie 失效类似，但更偏向 token 或 session 的时效问题。比如 Surge、Mihomo 或部分机场面板签发的短期 token 到期，sub2api 仍然沿用旧值。
• 频率限制：订阅源接口对同一 IP 或同一账号的请求次数做了限制。通常在短时间内部署多个客户端、反复刷新订阅时触发，返回 429 或类似提示。

判断方法很简单：看报错文案里有没有出现 401、403、429 这类的 HTTP 状态码，也可直接查看 sub2api 的日志文件定位是哪一层抛出的异常。

先处理 cookie 失效与会话过期

cookie 失效和会话过期属于同一类凭证问题，处理顺序基本一致。

第一步：从源站重新获取最新凭证。

打开你订阅的机场面板或服务商网站，退出登录后重新登录，在开发者工具的 Network 面板中找到任意一个 API 请求，复制请求头里的 cookie 或 Authorization 字段。
不要直接在旧 cookie 上做局部修改，服务端校验的往往是一整段签名值。

第二步：更新 sub2api 的配置。

找到 sub2api 的配置文件，把重新获取的 cookie 填入对应位置。
常见的配置方式是在环境变量或 .env 文件中定义：

SUB2API_COOKIE="你的新cookie值"
SUB2API_TOKEN="你的新token值"

填好后重启服务，使配置生效：

# Docker Compose 部署方式
sudo docker compose restart sub2api

# systemd 部署方式
sudo systemctl restart sub2api

第三步：验证凭证是否生效。

直接请求一个需要鉴权的订阅接口，看是否还返回 401：

curl -I "http://127.0.0.1:12000/sub?token=你的token"

返回 200 OK 说明凭证已更新。
若仍然报错，检查系统时间和服务器时间是否同步，时间偏差超过几分钟会导致 JWT 类 token 校验失败，可通过 NTP 同步校正：

sudo timedatectl set-ntp true

再看频率限制的触发链路

如果凭证没问题，报错仍出现，重点转向频率限制。
sub2api 触发限频通常是这几种情况：

• 机场面板对单账号短时间内的订阅请求次数设限；
• 多个客户端共用同一个 sub2api 地址，请求量被放大；
• 定时任务或客户端自动刷新间隔设置过短。

处理逻辑依次有三种：

1. 减少直接请求次数。把客户端订阅自动更新时间从每 6 小时改为每天一次，降低触发 429 的概率。
2. 在 sub2api 和上游接口之间加缓存层。Sub-Store 本身支持缓存机制，优先开启它，让相同内容的请求命中缓存而不是打到上游。
3. 给不同客户端分配独立的 sub2api 路径，避免共用一个地址时互相挤占限额。

同时检查 sub2api 是否自带限流配置，若部署在反向代理（如 Nginx）后面，还需确认代理层有没有额外做请求频率控制：

# 在 Nginx 站点配置中查看是否存在 limit_req 相关指令
limit_req zone=mylimit burst=5 nodelay;

如果设置了过小的 burst 或过快的速率，建议先注释掉再测试，排除代理层误伤。

避坑清单

以下问题最容易让人走弯路，提前避开能省不少时间：

• 不要只在报错后更新 cookie。很多服务商的 cookie 有效期很短，建议把“重新获取 cookie”写进周期维护计划，比如每月一次。
• 更新配置后务必重启服务。部分部署方式不会热加载新配置，不重启会导致旧 cookie 继续被使用。
• 别忽略时间和时区。服务器时区混乱会让 token 校验提前失败，建议统一设置为 Asia/Shanghai 或 UTC，不要混合使用。
• 日志保留周期调长。sub2api 报错往往是间歇性的，保留至少 7 天日志，方便在再次报错时回溯是凭证问题还是限频问题。

验证处理结果是否稳定

处理完不要只看一次请求是否成功，建议连续验证一段时间：

# 连续请求 10 次，观察是否存在 401、403、429
for i in $(seq 1 10); do
  curl -o /dev/null -s -w "%{http_code}\n" "http://127.0.0.1:12000/sub?token=你的token"
  sleep 2
done

输出的状态码应全部为 200 或 304，一旦出现 429，说明频率问题还没解决；
出现 401，则说明凭证仍有问题，需要回到第二步重新检查。

同时观察 sub2api 的日志，确认最近一小时内没有新增 cookie 失效或会话过期的异常记录：

journalctl -u sub2api --since "1 hour ago" | grep -E "cookie|expire|limit"

如果长时间运行后再次遇到 sub2api 的 cookie 失效、会话过期或频率限制报错，优先按本文顺序排查，不要急于重装服务或修改业务代码；
多数情况下，更新凭证和调整请求频率就能稳定恢复。