一、项目背景 + 项目介绍

背景的观点是，NestJS 鉴权常见痛点

在 NestJS 项目里做登录鉴权。很多人会遇到同一组问题：

• Guard + Session/JWT 各写一套顶号、踢人、活跃过期要自己拼 Redis 键。
• 多端登录语义绕不清PC 和 App 能不能同时在线？同端能不能顶号，
• 敏感操作只有一级登录，缺少「二次确认」机制
• 运维侧查在线使用者、强制下线、审计登录事件往往要重复造轮子

Java 环境有Sa-Token把这些问题封装成统一 API；Node 侧长期缺少一个NestJS 原生、语义对齐、可插拔的同类方案。

xlt-token 是一个面向 NestJS 的轻量 Token 鉴权库。灵感来自 Sa-Token，MIT 开源。

pnpm add xlt-token
// 如需多实例建议再加 redis
pnpm add redis

主要设计：

• 可插拔：Store、Token 策略均可替换。
• 双形态 API：{@link StpLogic} 依赖注入 + {@link StpUtil} 静态门面。
• 声明式开发：{@link XltIgnore}、{@link LoginId}、{@link XltCheckPermission} 等 Guard 与装饰器。
• 新能力全部 opt‑in，老项目升级不破坏现有 API。

二、项目如何使用

安装

pnpm add xlt-token # 推荐生产多实例加 pnpm add redis

注册模块 + 全局守卫

import { Module } from '@nestjs/common';import { APP_GUARD } from '@nestjs/core';import { XltTokenModule,XltTokenGuard } from 'xlt-token';@Module({
imports:,providers:,})
export class AppModule {}

登录 / 登出 / 获取当前使用者

import { Controller。Post,Body } from '@nestjs/common';老实说，import { StpUtil,XltIgnore。LoginId } from 'xlt-token';@Controller
export class AuthController {
@XltIgnore
@Post
async login dto: { username: string }) {
const token = await StpUtil.login;return { token };}
@Post
async logout token?: string) {
await StpUtil.logout;return { ok: true };}
@Post
me loginId?: string) {
return { loginId };}
}

默认 { defaultCheck:true } ：所有接口需登录 —公开路由加 @XltIgnore 即可。

客户端请求时带上 Header：

Authorization: Bearer 

更多配置、Redis 存储、异步 { forRootAsync } 见在线文档·快速开始。

三、本版本做了哪些内容

① 多端登录 PC / App 能否共存、同端能否顶号？device 参数，deviceConcurrent；设备列表与按端踢人，② 二级认证 + 临时 Token：敏感操作二次确认；邮件链接一次性授权 openSafe / @XltCheckSafe；createTempToken 系列。③ JWT Strategy：既要 JWT 验签，又要踢人/顶号/活跃过期内置 JwtStrategy + jti 黑名单。④ Hooks + 在线观测：在线使用者；强制下线，登录审计 keys 扫描 getOnlineLoginIds。

至于设计原则。

• 与 API 完全兼容，新字段/新 API 均为可选。
• 不传 device 时等价 device:'default'，旧 session 键可迁移。
• 不绑业务：权限数据仍由 StpInterface 实现，库不做 CRUD。

四、功能点 · 怎么用 · 完成了什么 **多端登录** **完成了什么**：

• Session 键升级为 `session:${loginId}:${device}` 并增加 `session-list`设备索引。
• 新增 `deviceConcurrent` 与 `isConcurrent`/`isShare` 控制互踢范围。话说回来，
• 提供 `getDeviceList` 、`kickoutByDevice` 、`kickoutByToken` 、 `forceLogout`。

**典型配置 — PC 与 App 相互独立**： ts XltTokenModule.forRoot({ config:{ deviceConcurrent:true。isConcurrent:true,isShare:false,},});**怎么用** ts // 登录时指定设备 const pcToken = await stp.login;const appToken= await stp.login;// 管理端查询设备并踢指定端 const devices = await stp.getDeviceList;await stp.kickoutByDevice;//仅踢 PC await stp.forceLogout;// 全端下线 📄详见文档·多端登录 --- ### 二级认证+ 临时 Token **完成了什么** * 存储键：`safe:${token}:${business}` 标记安全窗口；* `temp-token:${tempToken}` 存业务 payload；* 新增 `NotSafeException` 装饰器 `@XltCheckSafe`;* Guard 在 checkLogin 成功后自动消费 Safe 元数据。**二级认证 — 转账前验证码** ts // 第一步先验证通过后打开秒窗口 await stp.openSafe;// 接下来敏感接口 @XltCheckSafe @Post transfer{ /* 未 openSafe 则抛异常 */ } **临时 Token — 邮件重置密码** ts const tempToken = await stp.createTempToken;const link = `https://app.com/reset?t=${tempToken}`;说起来，// 使用者点链接后解析并一次性消费 const value = await stp.parseTempToken;await stp.deleteTempToken;📄详见文档·二级认证 --- ### 内置 JWT Strategy **完成了什么** * 新增 `` ：payload约定 `` + ``。不过，* 鉴权方法：本地 verifyToken + 查 `jwt-blacklist:${jti}`。按理说，* 保留 xlt-token 的语义：顶号、踢人、活跃过期仍由 Store 控制。**怎么用** ts import { XltTokenModule,JwtStrategy } from 'xlt-token';XltTokenModule.forRoot({ strategy:{ useClass : JwtStrategy }。config:{ jwt这方面，{ secret : process.env.JWT_SECRET!algorithm:'HS256'}。timeout : /*...*/,},});需自行安装 jsonwebtoken： pnpm add jsonwebtoken 📄详见文档·JWT 策略 --- ### Hooks + 在线观测 **完成了什么** * Store 接口 ``。* `` / `` 扫描 ``。* Hooks：onLogin / onKickout 等异常不影响主流程。**怎么用** ts XltTokenModule.forRoot({ hooks:{ onLogin:=>{ audit.log;},onKickout:=>{ websocket.notify;},},})，// 运维API const count=await stp.getOnlineCount;const users=await stp.getOnlineLoginIds;📄详见文档·Hooks 与观测性 --- ### 能力回顾

能力	用法要点
顶号/踢人	isConcurrent:false 顶号;kickout 返回 KICK_OUT 而非笼统401
活跃过期	activeTimeout+每次请求刷新 lastActive
权限/角色	@XltCheckPermission/@XltCheckRole 并实现SttInterface会话 SttUtil.getSession.set
自定义 Guard继承 X ltAbstractLoginGuard 重写 onAuthSuccess 加载 request.user

我们不为「能跑通 Demo」买单，每个 Milestone 都有对应单测/E2E。

---

测试规模

指标	数值
Total Cases:

功能与测试对应关系

本地一键验证

bash pnpm test # 单测 pnpm test:e2e # E2E pnpm test:cov # 覆盖率报告

文档站代码块已接入 Twoslash。悬停即可看类型，与测试一起保证「文档示例 ≠ 假代码」。

x lt-token 把 NestJS + Sa‑token 的语义打好基础；话说回来，补齐生产里最常需要的四个能力——多端、安全、高度集成的 JWT 与实时观测。

如果你也在 NestJS 中维护鉴权层，欢迎：

• 📖 文档 → xiaolangtou.github.io/xLT‑TOKEN/ • 💬 Issue 提反馈场景需求 一句 forRoot 让剩下交给库吧！说起来，​🌟​. \ "。style=" font-weight:bold;" class=" " id=" " />