new-api 用户鉴权与登录会话架构全解：Access Token、Refresh Cookie 与多节点安全控制面-北京尧图网络

new-api 用户鉴权与登录会话架构全解Access Token、Refresh Cookie 与多节点安全控制面【免费下载链接】new-apiA unified AI model hub for aggregation distribution. It supports cross-converting various LLMs into OpenAI-compatible, Claude-compatible, or Gemini-compatible formats. A centralized gateway for personal and enterprise model management.项目地址: https://gitcode.com/gh_mirrors/ne/new-api导读本文以 docs/authentication.md 为骨架系统讲解 new-api 面板的现代鉴权体系短期 JWT Access Token、HttpOnly Refresh Cookie、服务端登录会话控制面user_sessions三者的协同关系以及 Redis 多节点拓扑下的撤销传播语义、浏览器端冷启动与会话接口契约、Session 签发限额、Origin 校验、可信代理与 IP 限流、PAT 调用契约、临时鉴权流程与 Security Proof 二次验证。读完本文你将掌握 new-api 面板登录态从签发、刷新、撤销到清理的全链路原理并能在本地开发与生产 HTTPS 多节点部署中正确配置SESSION_SECRET、SESSION_COOKIE_SECURE、SESSION_COOKIE_TRUSTED_URL、TRUSTED_PROXIES、SYNC_FREQUENCY等关键环境变量。鉴权模型三层协同的登录态设计new-api 面板不再依赖 Gin session也不再要求New-Api-User请求头。当前面板鉴权由短期 Access Token HttpOnly Refresh Cookie 服务端登录会话控制面组合而成Access Token有效期 15 分钟的 JWT只保存在浏览器内存中通过Authorization: Bearer token发送。源码中 service/auth_token.go 定义了AccessTokenTTL 15 * time.MinuteJWT 载荷包含token_use、sid会话 ID、uv用户鉴权版本、sv会话版本等声明见 authClaims并使用基于SESSION_SECRET派生的独立用途密钥签名authSigningKey。Refresh Token随机不透明值有效期最长 30 天源码LoginSessionTTL 30 * 24 * time.Hour。浏览器只通过HttpOnly、SameSiteStrictCookie 持有它服务端仅保存 HMAC 摘要并在每次刷新时轮换PreviousRefreshHash用于容错窗口内的确定性轮换恢复。user_sessions登录会话控制面记录设备、IP、登录方式、最后活跃时间、到期时间和撤销状态。模型定义见 model/user_session.go数据库中的 Session 状态是最终权威撤销传播速度取决于 Redis 拓扑。auth_version版本栅栏用户密码、状态、角色或安全因子发生安全相关变化时递增使旧登录会话失效订阅带来的分组升降级只刷新授权缓存不会退出任何登录设备。Redis 缓存保存用户鉴权快照和登录会话快照。版本栅栏和撤销 tombstone 防止旧缓存重新授权Session 快照使用跟随SYNC_FREQUENCY的短 TTLcommon/init.go 中SyncFrequency默认 60 秒缓存未命中或未启用 Redis 时回退到数据库校验。SESSION_SECRET与密钥派生SESSION_SECRET用于派生 Access Token、Security Proof、Refresh Token 摘要和 AuthFlow 摘要的不同用途密钥。生产环境及多节点部署必须在所有节点配置相同的高强度随机值更换该值会使现有登录、临时鉴权流程和 Security Proof 全部失效。启动时若检测到默认值会输出告警并拒绝启动见 common/init.go。多节点 Redis 拓扑与撤销传播语义多节点部署必须共用同一主数据库。登录 Session、账户级活跃 Session 上限和签发窗口计数都以数据库为权威因此这些限制在应用节点间全局生效。Redis 中的 Session Hash包含revoking/revokedtombstone只是缓存其 TTL 为 Session 剩余寿命与有效SYNC_FREQUENCY中的较小值读取缓存不会续期过期后会按 SID 回源数据库。延迟完成的 active 缓存回写只能使用其数据库观察窗口尚未消耗的 TTL不能在撤销 tombstone 到期后重新启动一个完整缓存周期。Redis 部署方式Session 状态传播限流语义所有节点共享 Redis正常撤销和版本发布通过同一缓存即时传播Redis 限流额度在所有节点间共享每个节点使用独立 Redis最迟在该节点 Session 缓存 TTL 到期后回源收敛即不超过有效SYNC_FREQUENCY版本轮换期间新 Token 在持有旧缓存的节点上可能短暂返回 401每个节点独立计数集群总额度最坏约为单节点阈值乘以节点数不使用 Redis每次 Session 校验直接读取数据库使用各节点的内存限流器额度同样按节点独立SYNC_FREQUENCY越大独立 Redis 部署的陈旧窗口越长值越小每个活跃 SID 在每个节点上回源数据库的频率越高。默认配置下持续活跃的 Session 每个节点最多约每 60 秒增加一次数据库主键点查。共享 Redis 时撤销 tombstone 和版本发布仍保持即时传播。关键约束所有节点必须使用相同的SESSION_SECRET当多个节点连接同一个 Redis 时还必须使用相同的CRYPTO_SECRET否则节点生成的缓存键摘要不一致无法正确共享缓存。上述保证只覆盖登录 Session 鉴权的有界陈旧语义限流额度及其他 Redis 缓存仍会受到 Redis 拓扑影响。浏览器接口登录返回契约与会话管理 API登录成功后密码登录、2FA、Passkey、OAuth、WeChat 和 Telegram 登录均返回统一数据AuthBundle结构见 service/auth_session.go{ success: true, data: { access_token: ..., token_type: Bearer, access_expires_at: 1730000000, user: {}, session: { sid: ..., current: true, login_method: password, ip: ..., user_agent: ..., created_at: 1730000000, last_active_at: 1730000000, expires_at: 1732592000 } } }会话相关接口如下处理器实现见 controller/auth_session.go接口鉴权用途POST /api/user/auth/refreshRefresh CookieSecure 模式附加 Origin 校验轮换 Refresh Token 并签发新的 Access TokenPOST /api/user/auth/logoutRefresh CookieSecure 模式附加 Origin 校验可同时携带 Bearer撤销当前登录会话并清除 CookieGET /api/user/sessionsBearer查看当前鉴权版本的有效登录会话当前会话优先最多 100 条DELETE /api/user/sessions/:sidBearer撤销指定登录会话包括当前会话POST /api/user/sessions/revoke-othersBearer保留当前会话并撤销其他会话X-Auth-Session与多标签页一致性客户端内存中已有会话时应在 refresh/logout 请求中发送X-Auth-Session: sid。Refresh Cookie 与该 SID 不一致时两个端点都返回409 AUTH_SESSION_MISMATCH且不会轮换、撤销或清除任何会话源码见 service/auth_session.go客户端先通过 refresh 清除本标签页的旧 SID、恢复 Cookie 当前对应的会话再重试 logout。冷启动尚无内存会话时可以省略该请求头。并发使用同一个 Refresh Token 时服务端通过确定性轮换恢复同一个后继 TokenPreviousRefreshHashRefreshReplayWindow见 service/auth_token.go多个浏览器标签页不会因丢失胜者响应而被迫退出。最近一代 Refresh Token 在短暂容错窗口结束后再次出现会撤销对应会话无法识别的更早代或随机 Token 只会被拒绝不会允许攻击者凭猜测踢掉会话。会话提示 Cookienew_api_has_sessionnew_api_has_session是 Refresh Cookie 的会话提示常量定义见 service/auth_session.go值恒为1Path/、非HttpOnly与 Refresh Cookie 同时写入、同时清除、同一过期时间。它只声明曾签发过 Refresh Cookie不含任何凭据也不参与任何鉴权判定伪造它唯一的效果是自费一次注定失败的 refresh。它存在的原因是 Refresh Cookie 被HttpOnly和Path/api/user/auth双重限制/上的页面无法判断自己是否匿名否则每次冷启动都要发一次注定 401 的 refresh而该请求还会占用按 IP 计数的CriticalRateLimit配额common/init.go 中默认 20 次/20 分钟。前端web/src/lib/session-hint.ts将冷启动状态与登录状态分开管理网络或服务端临时故障允许后续导航重试 refresh服务端确认 Refresh Cookie 无效时才进入已完成的匿名状态。内存 SID 与 Cookie SID 不一致时客户端清除旧内存身份并在不携带旧 SID 的情况下重试一次。公开页面的冷启动会先读new_api_has_session提示不存在且内存中没有任何身份时跳过 refresh直接按匿名渲染且不把这次跳过记为已完成的匿名判定——跳过只是延后不是服务端结论。会依据鉴权结果做跳转的位置受保护路由与登录页不看提示内存为空时一律回源。因此提示缺失但 Refresh Cookie 有效的用户会在公开页显示为匿名并在进入上述任一位置时自动恢复登录态不需要重新输入密码。提示因服务端撤销而过期时那次 refresh 返回 401 并在同一响应里清除提示浪费的请求只发生一次。前端还使用 Web Locks 串行化同一浏览器配置文件中的刷新并通过 BroadcastChannel不支持时回退到storage事件仅同步会话标识和登录/退出事件Access Token 与 Refresh Token 都不会通过跨标签页消息传递或持久化到 Web Storage。Session 签发限额与保留策略服务端在所有登录方式的统一 Session 签发出口createLoginSession见 service/auth_session.go执行两级账户限制环境变量解析见 common/init.goUSER_SESSION_ACTIVE_LIMIT默认50单用户未过期且状态为 active 的 Session 上限。达到上限时新登录返回409 AUTH_SESSION_LIMIT。USER_SESSION_ISSUANCE_LIMIT默认100和USER_SESSION_ISSUANCE_WINDOW_SECONDS默认86400统计窗口内该用户创建的所有 Session包含已撤销和旧鉴权版本的记录。达到上限时返回429 AUTH_SESSION_ISSUANCE_LIMIT。这两次计数与插入不加跨数据库锁极端并发登录可能出现少量超额但计数失败会拒绝签发不会降级放行。升级时已经超过活跃上限的账户不会被自动下线或挤掉旧会话限制只作用于后续的新 Session 签发。USER_SESSION_REVOKED_RETENTION_DAYS默认7控制 revoked 行的审计保留期。签发计数依赖窗口内的行仍存在因此签发窗口不得超过 revoked 保留期。如果配置超出启动时会记录告警并将实际窗口钳制到保留期initUserSessionSettings中的钳制逻辑避免提前删除 revoked 行导致限流计数被低估。定时清理即使发现expires_at已过期也不会删除created_at仍落在实际签发窗口内的行尚未达到 revoked 保留期的撤销记录同样会继续保留。活跃数量会计入状态仍为 active 但user_auth_version已过期的异常残留行而设备列表只展示当前鉴权版本。因此遇到AUTH_SESSION_LIMIT时应优先在仍已登录的设备上执行撤销其他会话该操作会同时清理不可见的旧版本 active 行没有可用设备时可使用密码重置撤销所有会话。密码重置不会清空签发窗口计数。仅 master 节点每小时分批删除过期 Session 和超过保留期的 revoked Session。USER_SESSION_HOURLY_ALERT_THRESHOLD默认5000只在最近一小时全局签发量异常时记录告警不会形成可被滥用的全站登录拒绝开关。Refresh/Logout 的 Origin 校验与 Cookie 安全模式refresh/logout 的 Origin 防护与 Refresh Cookie 的 Secure 模式绑定初始化逻辑见 common/session_cookie.go中间件见 middleware/auth_origin.go未配置SESSION_COOKIE_SECURE或显式设为false时Refresh Cookie 可用于本地 HTTPrefresh/logout 的 OriginGuard 关闭并且不得配置SESSION_COOKIE_TRUSTED_URL配置了会直接报错。这使http://localhost上不同端口的 Rsbuild/Vite 开发代理可以正常转发请求。该模式仅用于可信的本地开发环境不应暴露到公网。SESSION_COOKIE_SECUREtrue时Refresh Cookie 仅通过 HTTPS 发送同时启用严格 OriginGuard。POST /api/user/auth/refresh和POST /api/user/auth/logout会校验浏览器的Origin缺少Origin时只接受合法的单一Referer作为回退。允许来源包括请求自身的精确 Origin以及SESSION_COOKIE_TRUSTED_URL中配置的精确 Origin。校验失败返回403 AUTH_ORIGIN_FORBIDDEN。Secure 模式的 Origin 校验不信任客户端直接发送的X-Forwarded-Protomiddleware/auth_origin_test.go 有对应测试用例。TLS 在反向代理终止时应将面板的公开 HTTPS Origin 明确写入SESSION_COOKIE_TRUSTED_URL。SESSION_COOKIE_TRUSTED_URL的明确语义SESSION_COOKIE_TRUSTED_URL是 refresh/logout Cookie 端点的可信 Origin 列表不是 CORS 白名单。配置规则如下仅在SESSION_COOKIE_SECUREtrue时配置多个值用英文逗号分隔。每项必须是精确的 HTTPS Origin例如https://panel.example.com或https://panel.example.com:8443。不接受通配符、路径、查询参数、用户信息或域名后缀匹配NormalizeOrigin会做规范化校验见 common/session_cookie.go。不会修改 relay、旧 billing dashboard、/api/usage/token或/api/log/token的 CORS 行为。浏览器使用sk-key 直连 relay 的场景保持不变。本地 HTTP 开发示例OriginGuard 关闭SESSION_SECRETlocal-random-value SESSION_COOKIE_SECUREfalse # SESSION_COOKIE_TRUSTED_URL 不得设置生产 HTTPS 示例OriginGuard 开启SESSION_SECREThigh-entropy-random-value SESSION_COOKIE_SECUREtrue SESSION_COOKIE_TRUSTED_URLhttps://panel.example.com,https://admin.example.com可信代理与 IP 限流Gin 默认会信任所有代理提供的客户端 IP 请求头。本项目改为兼顾常见反代拓扑和公网直连安全的三态配置TRUSTED_PROXIES未配置、空字符串或纯空白的TRUSTED_PROXIES默认信任127.0.0.0/8、::1、10.0.0.0/8、172.16.0.0/12、192.168.0.0/16和fc00::/7并输出启动告警。该默认值覆盖同机 Nginx、Docker Compose 和常见内网反代公网直连地址不在列表中其伪造的X-Forwarded-For会被忽略。TRUSTED_PROXIESnone大小写不敏感且必须单独使用启用严格直连模式不信任任何代理ClientIP()只使用 TCP 直连地址。其他非空值按英文逗号解析为代理 IP/CIDR并完全替代默认列表。应填写反向代理自身的地址而不是客户端网段非法 CIDR、空列表或将none与其他值混用都会阻止服务启动。Gin 只在请求的直连来源属于可信代理时解析客户端 IP 请求头并从转发链右侧向左寻找首个非可信地址。因此常见 Nginx$proxy_add_x_forwarded_for链中的公网客户端地址会阻止更左侧的伪造前缀生效。默认信任私网的残余风险是能够从同一私网直接访问应用的其他机器或容器仍可伪造这些请求头需要消除此风险时应使用none或配置精确代理地址。Redis 限流使用原子 Lua 固定窗口替代旧的近似滑动窗口 List 实现Lua 脚本见 common/limiter/lua/rate_limit.lua。这是有意的语义变化窗口边界两侧可分别打满一次极短时间内通过量最高约为配置值的两倍。例如20 次/20 分钟在边界可通过约 40 次。帐户级 Session 上限和签发窗口继续控制数据库增长如未来需要严格抑制边界突发需单独迁移为 ZSET 滑动窗口。用户级模型成功请求限流仍使用原有 Redis List 近似滑动窗口但列表时间戳统一写为 UTC。滚动升级期间旧节点写入的本地时间字符串和新节点写入的 UTC 字符串无法从格式上区分可能在一个模型限流窗口内临时误放行或误拒绝。所有节点升级完成并经过一个完整窗口后会自然收敛本次升级不会切换 Key 或主动删除现有列表。开放注册仍会受 Critical IP 限流保护但分布式 IP 多账号攻击不能仅靠 IP 限流阻止。公网开放注册的部署应同时启用 Turnstile 和邮箱验证更强的设备或多维风控需作为独立安全项目设计。PAT 调用契约外部脚本的简化User.AccessToken面板 PAT继续支持Authorization: Bearer pat也兼容原有的单值Authorization: pat。New-Api-User不再参与鉴权外部脚本不需要再发送 Bearer 与用户 ID 双请求头。这是有意的调用契约简化旧 PAT 本身无需重新生成。PAT 不是浏览器登录会话不能调用登录会话管理接口也不能签发绑定具体登录会话的 Security Proof。临时鉴权流程与二次验证OAuth state、2FA pending、Passkey ceremony、Telegram bind 等临时状态存放在auth_flows。客户端只持有随机flow_token数据库仅保存 HMAC 摘要流程具有用途、provider、intent、用户和登录会话绑定并且只能原子消费一次。OAuth 注册的 affiliate code 也随登录 AuthFlow 保存。标准 OAuth 绑定回调由 popup 通过同源postMessage交给 opener只有 opener 使用自身内存中的 Bearer 调用后端绑定接口。Telegram 绑定先由已登录前端创建绑定 AuthFlow再让 widget 回调携带路径中的flow_token回调时会重新确认原登录会话仍有效。Telegram 的已签名 widget assertion 也会登记为一次性凭据重复回放会被拒绝。敏感操作使用有效期 5 分钟的X-Security-ProofSecurityProofTTL time.Minute即 5 分钟见 service/auth_token.gochannel.key.read查看渠道密钥passkey.register注册 Passkeypasskey.delete删除 Passkey。Proof 同时绑定用户、登录会话、用户鉴权版本、会话版本和 scope不能跨用户、跨会话或跨用途复用。启用了 2FA 的用户注册 Passkey 时register begin 与 finish 都必须携带有效的passkey.registerProoffinish 会在消费一次性 AuthFlow 之前重新验证 Proof。未启用 2FA 的首次 Passkey 注册不要求该请求头。升级注意事项从旧版本升级到该鉴权体系时需注意旧sessionCookie 不再使用升级后现有面板登录会失效用户需要重新登录。数据库迁移会新增user_sessions、auth_flows、external_identity_claims和users.auth_version并为已有用户初始化鉴权版本、回填 Telegram 账号唯一归属若历史数据中同一 Telegram ID 已绑定多个用户迁移会拒绝继续启动需先消除歧义。数据库迁移会为 Session 签发计数和分批清理新增索引已有user_sessions很大时应为首次启动预留维护窗口。user_sessions.previous_refresh_hash会从定长char(64)迁移为varchar(64)。应用会兼容读取历史定长字段留下的空格填充模型AfterFind中strings.TrimSpace迁移后的目标结构必须保持幂等连续启动不应反复执行列类型变更。仅 master 节点定时清理过期登录会话、超过配置保留期的 revoked 会话和已过保留期的 AuthFlow。未配置TRUSTED_PROXIES时会兼容信任回环和常见私网代理使用公网负载均衡器、100.64.0.0/10、链路本地地址或自定义 CNI 网段的部署仍需显式配置。需要严格忽略所有转发头时设置为none。Redis 限流从近似滑动窗口改为原子固定窗口存在明确的边界双倍突发语义。用户级模型成功请求限流的 UTC 时间戳在滚动升级期间存在一个窗口的混合格式过渡期间可能临时误放行或误拒绝。自建客户端应按新的 AuthBundle、flow_token和 Security Proof 契约升级PAT 客户端可直接移除New-Api-User。关键源码索引会话模型与表结构model/user_session.go会话签发、校验与撤销逻辑service/auth_session.goAccess Token / Security Proof 签发与解析service/auth_token.go会话管理 API 控制器controller/auth_session.goOrigin 校验中间件及测试middleware/auth_origin.go、middleware/auth_origin_test.goCookie 安全模式初始化common/session_cookie.go环境变量解析与钳制common/init.goRedis Lua 固定窗口限流脚本common/limiter/lua/rate_limit.lua前端会话提示逻辑web/src/lib/session-hint.ts【免费下载链接】new-apiA unified AI model hub for aggregation distribution. It supports cross-converting various LLMs into OpenAI-compatible, Claude-compatible, or Gemini-compatible formats. A centralized gateway for personal and enterprise model management.项目地址: https://gitcode.com/gh_mirrors/ne/new-api创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

new-api 用户鉴权与登录会话架构全解：Access Token、Refresh Cookie 与多节点安全控制面

相关推荐

Gatsby Build Caching 构建缓存 API 实战指南：跨构建持久化数据，为插件与站点开发提速

Jekyll 版本升级全指南：从 0.x 迁移到 4.x 的路线图与源码级避坑手册

【软件测试】接口自动化测试

更多资讯

OpenProject 版本管理（Versions）完全指南：创建、共享、生命周期与 Roadmap 联动

仿生蝴蝶扑翼无人机：低雷诺数气动优化与FOC驱动动态调参

BabelDOC：PDF文档翻译3分钟上手，公式和版式都能保住

蓝屏代码0xc000021a与UNEXPECTED_STORE_EXCEPTION排查指南

CSS入门与实战：从选择器、盒模型到现代布局指南

new-api 用户鉴权与登录会话架构全解：Access Token、Refresh Cookie 与多节点安全控制面

今日更新

AReaL 调试指南：从 Agent Workflow 验证到分布式训练死锁诊断

MATLAB实现GPS L1 C/A信号仿真与二维捕获验证

彻底搞懂ASCII、Unicode与UTF-8：从乱码根源到编码实战

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？