JWT+Passport.js身份验证实现完整步骤

flowchart LR
    A[用户] -->|1. 注册| B[提交账号密码]
    B --> C{验证合法性
（用户名唯一等）}
    C -->|合法| D[创建用户记录
（密码加密存储）]
    A -->|2. 登录| E[提交账号密码]
    E --> F{验证账号密码
（与数据库比对）}
    F -->|通过| G[生成JWT令牌
（包含用户ID等信息）]
    A -->|3. 访问受保护接口| H[请求头携带JWT]
    H --> I[Passport拦截请求]
    I --> J[JWT策略验证令牌]
    J -->|有效| K[解析用户信息
（附在req.user）]
    K --> L[接口处理逻辑]
    J -->|无效| M[返回401未授权]

# 核心依赖：Passport本地策略、JWT策略、Nest集成包、加密
pnpm add @nestjs/passport passport passport-local @nestjs/jwt passport-jwt bcryptjs
# 类型定义（开发依赖）
pnpm add -D @types/passport-local @types/passport-jwt @types/bcryptjs

// src/auth/auth.controller.ts
import { Controller, Post, Body, HttpException } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { genSalt, hash } from 'bcryptjs';
import { User } from '../users/entities/user.entity'; // 用户实体（含id/username/password/role）

@Controller('auth')
export class AuthController {
  constructor(
    @InjectRepository(User) private userRepo: Repository<User>,
  ) {}

  // 注册接口
  @Post('register')
  async register(
    @Body() dto: { username: string; password: string },
  ) {
    // 1. 验证用户名是否已存在（防重复注册）
    const existUser = await this.userRepo.findOne({
      where: { username: dto.username },
    });
    if (existUser) {
      throw new HttpException('用户名已存在', 400);
    }

    // 2. 密码加密（核心！bcrypt自动加盐，无需手动处理）
    const salt = await genSalt(10); // 生成盐值（复杂度10）
    const hashedPassword = await hash(dto.password, salt);

    // 3. 创建用户记录（存入数据库，角色默认为普通用户）
    await this.userRepo.save({
      username: dto.username,
      password: hashedPassword, // 存储加密后的密码
      role: 'user', // 初始角色（后续可通过管理员修改）
    });

    return { message: '注册成功，请登录' };
  }
}

// src/auth/local.strategy.ts
import { BadRequestException } from '@nestjs/common';
import { PassportStrategy } from '@nestjs/passport';
import { InjectRepository } from '@nestjs/typeorm';
import { compareSync } from 'bcryptjs'; // 密码比对（bcrypt加密）
import { Strategy } from 'passport-local';
import { Repository } from 'typeorm';
import { User } from '../users/entities/user.entity'; // 用户实体

// 继承PassportStrategy，指定策略类型为local
export class LocalStrategy extends PassportStrategy(Strategy) {
  constructor(
    @InjectRepository(User) private userRepo: Repository<User>,
  ) {
    super({
      usernameField: 'username', // 对应请求体中的“用户名”字段
      passwordField: 'password', // 对应请求体中的“密码”字段
    });
  }

  // 验证逻辑：Passport会自动调用该方法
  async validate(username: string, password: string) {
    // 1. 根据用户名查用户（需额外查询密码，默认不返回）
    const user = await this.userRepo
      .createQueryBuilder('user')
      .addSelect('user.password') // 显式查询密码
      .where('user.username = :username', { username })
      .getOne();

    // 2. 校验用户是否存在、密码是否匹配
    if (!user || !compareSync(password, user.password)) {
      throw new BadRequestException('用户名或密码错误');
    }

    // 3. 返回用户信息（后续会被注入到req.user中）
    return user;
  }
}

// src/auth/auth.module.ts
import { Module } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { JwtModule } from '@nestjs/jwt';
import { PassportModule } from '@nestjs/passport';
import { TypeOrmModule } from '@nestjs/typeorm';
import { User } from '../users/entities/user.entity';
import { AuthService } from './auth.service';
import { LocalStrategy } from './local.strategy';
import { JwtStrategy } from './jwt.strategy';

// 异步配置JWT（从环境变量读取密钥）
const jwtModule = JwtModule.registerAsync({
  inject: [ConfigService],
  useFactory: (config: ConfigService) => ({
    secret: config.get('JWT_SECRET', 'dev-secret-123'), // 密钥（生产环境需复杂）
    signOptions: { expiresIn: '4h' }, // JWT过期时间（4小时）
  }),
});

@Module({
  imports: [
    TypeOrmModule.forFeature([User]), // 导入用户Repository
    PassportModule,
    jwtModule, // 注册JWT模块
  ],
  providers: [AuthService, LocalStrategy, JwtStrategy], // 注入服务和策略
  exports: [AuthService, JwtModule], // 导出JWT模块，供其他模块使用
})
export class AuthModule {}

// src/auth/auth.service.ts
import { Injectable } from '@nestjs/common';
import { JwtService } from '@nestjs/jwt';
import { User } from '../users/entities/user.entity';

@Injectable()
export class AuthService {
  constructor(private jwtService: JwtService) {}

  // 生成JWT（登录成功后调用）
  login(user: Partial<User>) {
    // Payload：存储用户核心信息（避免敏感数据，如密码）
    const payload = { 
      id: user.id, 
      username: user.username, 
      role: user.role // 角色信息，后续RBAC权限控制用
    };
    // 签名生成JWT令牌
    const token = this.jwtService.sign(payload);
    return { token }; // 返回给客户端
  }
}

// src/auth/auth.controller.ts
import { Controller, Post, Req, UseGuards } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';
import { AuthService } from './auth.service';

@Controller('auth')
export class AuthController {
  constructor(private authService: AuthService) {}

  // 登录接口：使用local策略验证
  @UseGuards(AuthGuard('local'))
  @Post('login')
  login(@Req() req) {
    // req.user由LocalStrategy的validate方法返回
    return this.authService.login(req.user);
  }
}

// src/auth/jwt.strategy.ts
import { UnauthorizedException } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { PassportStrategy } from '@nestjs/passport';
import { ExtractJwt, Strategy } from 'passport-jwt';
import { User } from '../users/entities/user.entity';
import { AuthService } from './auth.service';

export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor(
    private config: ConfigService,
    private authService: AuthService,
  ) {
    super({
      // 从请求头的Authorization: Bearer <JWT>中提取令牌
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      secretOrKey: config.get('JWT_SECRET'), // 用相同密钥解密
      ignoreExpiration: false, // 不忽略过期（过期则返回401）
    });
  }

  // 验证JWT有效性（解密后调用）
  async validate(payload: Partial<User>) {
    // 可额外校验用户状态（如是否被禁用）
    const user = await this.authService.findUserById(payload.id);
    if (!user) {
      throw new UnauthorizedException('令牌无效或用户不存在');
    }
    return user; // 返回用户信息，注入到req.user
  }
}

// src/auth/jwt-auth.guard.ts
import { Injectable, UnauthorizedException } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';

@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
  // 处理验证结果
  handleRequest(err: any, user: any) {
    if (err || !user) {
      throw new UnauthorizedException('请先登录');
    }
    return user;
  }
}

// src/users/users.controller.ts
import { Controller, Get, Req, UseGuards } from '@nestjs/common';
import { JwtAuthGuard } from '../auth/jwt-auth.guard';

@Controller('users')
export class UsersController {
  // 需登录才能访问的接口：获取当前用户信息
  @UseGuards(JwtAuthGuard)
  @Get('info')
  getUserInfo(@Req() req) {
    // req.user由JwtStrategy的validate方法返回
    return req.user;
  }
}

// src/auth/roles.guard.ts
import { Injectable, CanActivate, ExecutionContext, ForbiddenException } from '@nestjs/common';

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private requiredRoles: string[]) {} // 接收需要的角色列表

  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest();
    const user = request.user; // 从req.user中获取用户角色（JWT验证后注入）

    // 校验用户角色是否在允许的列表中
    const hasPermission = this.requiredRoles.some(role => user.role === role);
    if (!hasPermission) {
      throw new ForbiddenException('无权限访问，需管理员权限');
    }
    return true;
  }
}

// 自定义装饰器：简化角色配置（如@Roles('admin')）
import { SetMetadata } from '@nestjs/common';
export const Roles = (...roles: string[]) => SetMetadata('roles', roles);

// src/admin/admin.controller.ts
import { Controller, Get, UseGuards } from '@nestjs/common';
import { JwtAuthGuard } from '../auth/jwt-auth.guard';
import { RolesGuard, Roles } from '../auth/roles.guard';

@Controller('admin')
@UseGuards(JwtAuthGuard) // 先验证登录状态
export class AdminController {
  // 仅角色为admin的用户可访问：查询所有用户（管理员权限）
  @Get('all-users')
  @Roles('admin') // 指定需要的角色
  @UseGuards(new RolesGuard(['admin'])) // 应用角色守卫
  getAllUsers() {
    // 业务逻辑：查询数据库所有用户信息
    return { data: [], message: '所有用户列表' };
  }
}

// src/auth/auth.service.ts（新增刷新令牌逻辑）
import { InjectRedis } from '@nestjs-modules/ioredis';
import { Redis } from 'ioredis';
import { v4 as uuidv4 } from 'uuid'; // 生成唯一刷新令牌

@Injectable()
export class AuthService {
  // ... 其他代码 ...

  // 登录时生成双令牌
  async loginWithDoubleToken(user: Partial<User>) {
    // 1. 生成访问令牌（短有效期）
    const accessToken = this.jwtService.sign(
      { sub: user.id, username: user.username, role: user.role },
      { expiresIn: '30m' },
    );

    // 2. 生成刷新令牌（唯一ID，长有效期）
    const refreshToken = uuidv4();
    const refreshTokenExpire = 7 * 24 * 60 * 60; // 7天（秒）

    // 3. 刷新令牌存储到Redis（支持主动作废）
    await this.redis.set(
      `refresh_token:${refreshToken}`,
      user.id,
      'EX',
      refreshTokenExpire,
    );

    return {
      accessToken,
      refreshToken,
      expiresIn: 30 * 60, // 访问令牌有效期（秒）
    };
  }

  // 刷新访问令牌
  async refreshToken(refreshToken: string) {
    // 1. 验证刷新令牌是否存在于Redis
    const userId = await this.redis.get(`refresh_token:${refreshToken}`);
    if (!userId) {
      throw new UnauthorizedException('刷新令牌无效或已过期');
    }

    // 2. 查询用户信息
    const user = await this.findUserById(Number(userId));
    if (!user) {
      throw new UnauthorizedException('用户不存在');
    }

    // 3. 生成新的访问令牌
    const newAccessToken = this.jwtService.sign(
      { sub: user.id, username: user.username, role: user.role },
      { expiresIn: '30m' },
    );

    return { accessToken: newAccessToken, expiresIn: 30 * 60 };
  }

  // 登出：删除Redis中的刷新令牌（主动作废）
  async logout(refreshToken: string) {
    await this.redis.del(`refresh_token:${refreshToken}`);
    return { message: '登出成功' };
  }
}