登录与鉴权

设备 ID 标识请求环境,登录凭证证明身份,权限决定能做什么。

设备 ID

首次访问时,网页向服务端登记设备,将返回的 ID 存入 localStorage.device_id,后续业务请求通过 K-Device-ID 请求头携带。

服务端保存对应设备记录,并用它校验账户会话和游客凭证的设备绑定。设备 ID 本身不代表已登录。

浏览器账户登录

登录会话180 天固定上限,刷新不延长
刷新令牌30 天一次性,换发后重新计时
访问令牌10 分钟用于业务请求

登录成功后建立登录会话,关联账户和设备,两种令牌都属于该会话。不同设备可独立登录,互不覆盖。

访问令牌只存页面内存,刷新令牌存 HttpOnly Cookie。两者均为安全随机字符串;后端保存哈希、账户与设备关联、有效期、撤销状态及轮换记录,不保存令牌原文。

“记住我”决定关闭浏览器后是否保留刷新令牌,不改变访问令牌的内存存储方式和登录会话的固定期限。

业务请求通过 Authorization: Bearer 携带访问令牌,通过 K-Device-ID 携带设备 ID;当前角色存于页面内存,通过 K-Character-ID 指定。后端按令牌哈希查询,校验状态、角色归属和权限。

刷新页面或访问令牌过期时,网页调用续期接口,浏览器自动携带刷新令牌 Cookie。成功后得到新的访问令牌和刷新令牌,分别更新页面内存和 Cookie。

旧刷新令牌立即失效,旧访问令牌到期前仍可用。因此,同一登录会话只有最新的刷新令牌可用,但可有多个有效的访问令牌;轮换不新建会话。

新刷新令牌重新计算 30 天,但不能超过登录会话的 180 天上限。连续 30 天未续期需重新登录;会话到期或退出时,其下所有令牌失效,其他设备的会话不受影响。退出还会清除本机内存中的访问令牌和刷新令牌 Cookie。

“记住我”有什么区别?

勾选时,刷新令牌使用持久 Cookie,关闭浏览器后仍可恢复登录;每次换发后重新保存,最长 30 天,且不能超过登录会话的 180 天上限。

不勾选时使用临时 Cookie,通常随浏览器会话结束而清除,再次打开需重新登录;浏览器的会话恢复功能可能保留它。刷新页面不等于关闭浏览器,只要 Cookie 仍有效,就能取得新的访问令牌。

多个窗口同时刷新时怎么办?

同一窗口的请求共用一次续期;多个窗口通过 Web Locks 协调,并用 BroadcastChannel 共享新的访问令牌,避免同时使用旧刷新令牌。

后端用事务和行锁保证旧令牌只消费一次,并为正常并发或网络重试设置短暂宽限期,安全复用同一次换发结果,不重复签发,也不立即撤销授权;超过宽限期再按重放处理。

游客登录

游客有两种凭证:浏览器日常使用的游客身份凭证,以及换浏览器或恢复身份时使用的游客身份授权码。

创建游客角色后,游客身份凭证保存在 HttpOnly Cookie k_guest_credential 中;后端保存凭证标识、秘密的哈希、所属角色、绑定设备和撤销状态,不保存秘密原文。请求自动携带该 Cookie 和 K-Device-ID,后端查找凭证记录、校验秘密与设备绑定,并确认凭证未被撤销后识别游客身份。

Cookie k_guest_active=1 表示当前正在使用游客身份,它只是登录状态,不是身份证明。游客身份凭证有效、该值为 1 且没有正式账户会话时,才以游客角色操作。

退出游客登录只清除 k_guest_active,保留游客身份凭证,下次点击游客登录即可继续使用原角色。

在原浏览器导出游客身份授权码并自行保存;在目标浏览器导入后,为同一游客角色取得绑定目标设备的新凭证,原设备已有凭证仍可使用。游客身份授权码没有到期时间,未使用且未被撤销时永久有效,但只能成功使用一次,再次复制时需重新生成;重新生成也会使旧的未使用游客身份授权码失效。

后端保存游客身份授权码的标识、秘密哈希、所属角色、使用与撤销状态,不保存秘密原文,也不设置到期时间。导入时核对秘密并检查是否已使用或撤销;成功后记录已使用,并关联目标设备新取得的游客身份凭证。游客身份授权码可以取得游客身份,应妥善保存,不要交给他人。

游客凭证保存多久?

游客身份凭证 Cookie 保存 365 天,每次凭证验证成功后重新延长到 365 天。关闭浏览器或退出游客登录不会删除它,但清除站点数据可能使它与设备 ID 一起丢失。

凭证与授权码有什么关联?

游客身份授权码由原设备的游客身份凭证生成,使用后为目标设备产生同一角色的新凭证,后端记录来源和目标关联。后续登录只使用新凭证,不再需要授权码;原凭证仍可使用。