## 一、认证方案选型

Web应用的认证方案有很多，每种各有适用场景：

| 方案 | 原理 | 优势 | 劣势 | 适用场景 |
|------|------|------|------|---------|
| **Session+Cookie** | 服务端存session，浏览器带Cookie | 简单直接 | 不适合分布式/跨域 | 传统服务端渲染 |
| **JWT（JSON Web Token）** | 服务端签发令牌，客户端每次请求携带 | 无状态、跨域友好、移动端兼容 | 令牌无法主动失效 | 前后端分离SPA |
| **OAuth2.0** | 第三方授权登录 | 用户无需记密码 | 流程复杂、需第三方接入 | 社交登录集成 |
| **SSO单点登录** | 多系统共享认证状态 | 一次登录处处通行 | 架构复杂 | 企业多系统 |

### 选择 JWT 的理由

我们的平台是**前后端分离的单页应用**，且需要从校外公网访问——这意味着：
1. 前端和API可能不在同一域名下（内网穿透后的域名问题）
2. 需要支持未来可能的移动端H5访问
3. NAS上跑Redis做Session存储太重了

**JWT完美匹配这些需求**：无状态（服务端不存session）、自包含（用户信息编码在token里）、跨域友好（放在Authorization头而非Cookie里）。

## 二、完整认证流程

```
┌─────────┐                    ┌──────────┐
│  浏览器   │                    │ Express   │
│ (Vue 3) │                    │ 后端      │
└────┬────┘                    └────┬─────┘
     │                              │
     │  ① POST /api/auth/login      │
     │  { username, password }      │
     │ ──────────────────────────> │
     │                              │
     │                    ② bcrypt.compare(输入密码, DB哈希)
     │                              │
     │  ③ { code:200, data:{ token, user } } │
     │ <────────────────────────── │
     │                              │
     │  ④ localStorage.setItem('token', token)
     │    跳转到首页                  │
     │                              │
     │  ⑤ GET /api/resources (带 Authorization: Bearer xxx)
     │ ──────────────────────────> │
     │                              │
     │              ⑥ jwt.verify(token, secret) → 解析出userId/roleLevel
     │              ⑦ 查DB获取完整用户信息 → 挂到 req.user
     │              ⑧ 返回资源列表数据
     │  ⑨ { code:200, data:[...] }  │
     │ <────────────────────────── │
```

## 三、核心代码实现

### 3.1 密码注册（bcrypt哈希）

```javascript
// routes/auth.js — 注册接口
const bcrypt = require('bcryptjs');
const db = require('../db');

router.post('/register', async (req, res) => {
    const { username, password, realName } = req.body;

    // 1. 校验输入
    if (!username || !password || password.length < 6) {
        return res.status(400).json({
            code: 400,
            message: '用户名不能为空，密码至少6位'
        });
    }

    // 2. 检查用户名是否已存在
    const existing = db.prepare(
        'SELECT id FROM users WHERE username = ?'
    ).get(username);

    if (existing) {
        return res.status(409).json({
            code: 409,
            message: '该用户名已被注册'
        });
    }

    // 3. 密码bcrypt哈希（cost=10，约100ms）
    const hashedPassword = await bcrypt.hash(password, 10);

    // 4. 写入数据库
    const result = db.prepare(`
        INSERT INTO users (username, password, real_name, role_id)
        VALUES (?, ?, ?, 1)
    `).run(username, hashedPassword, realName);  // 默认角色=teacher

    res.json({
        code: 200,
        data: { userId: result.lastInsertRowid },
        message: '注册成功'
    });
});
```

**为什么用 bcrypt 而不是 MD5/SHA256？**

MD5和SHA256是**快速哈希算法**——一秒能算几十亿次。如果数据库泄露，攻击者可以用彩虹表在几分钟内破解所有密码。而bcrypt是**专门为密码存储设计的慢哈希**，`cost=10`意味着要做2^10次（1024轮）迭代运算，每个密码需要约100ms。这对合法用户几乎无感（注册时多等0.1秒），但对暴力破解者来说，每秒只能试10个密码——破解成本提升了几个数量级。

### 3.2 登录鉴权（JWT签发）

```javascript
// routes/auth.js — 登录接口
const jwt = require('jsonwebtoken');

// JWT密钥（生产环境应从环境变量读取）
const JWT_SECRET = process.env.JWT_SECRET || 'your-secret-key-at-least-32-chars';
const JWT_EXPIRES = '24h';  // 令牌有效期24小时

router.post('/login', (req, res) => {
    const { username, password } = req.body;

    // 1. 查找用户
    const user = db.prepare(
        'SELECT u.*, r.name AS role_name, r.level AS role_level ' +
        'FROM users u JOIN roles r ON u.role_id = r.id ' +
        'WHERE u.username = ? AND u.status = 1'
    ).get(username);

    if (!user) {
        return res.status(401).json({
            code: 401,
            message: '用户名或密码错误'
        });
    }

    // 2. 对比密码
    const valid = bcrypt.compareSync(password, user.password);
    if (!valid) {
        return res.status(401).json({
            code: 401,
            message: '用户名或密码错误'
        });
    }

    // 3. 签发JWT（payload只放非敏感信息）
    const token = jwt.sign(
        {
            userId: user.id,
            username: user.username,
            roleLevel: user.role_level,    // 权限等级（给RBAC中间件用）
            roleName: user.role_name       // 角色名称（前端展示用）
        },
        JWT_SECRET,
        { expiresIn: JWT_EXPIRES }
    );

    // 4. 返回令牌和用户信息
    res.json({
        code: 200,
        data: {
            token,
            user: {
                id: user.id,
                username: user.username,
                realName: user.real_name,
                roleLevel: user.role_level,
                roleName: user.role_name
            }
        },
        message: '登录成功'
    });
});
```

**JWT Payload 设计原则**：
- ✅ 只放**必要的非敏感信息**（ID、角色等级）
- ❌ 绝不放密码哈希、手机号、真实姓名等隐私数据
- ❌ 不放权限矩阵（权限可能变更，但token在有效期内不会变）

> 💡 **安全提醒**：JWT_SECRET 至少32个随机字符。不要写死在代码里，要用环境变量`process.env.JWT_SECRET`读取。我在开发阶段为了方便硬编码了，但部署时已改为从Docker的环境变量注入。

### 3.3 认证中间件（请求拦截）

这是整个认证链路中最关键的环节——**也是我踩过最深的坑**：**JWT 认证那个坑，我一个人至少得卡两天。WorkBuddy 帮我顺着调用链快速定位到 auth 中间件导出方式的隐蔽 bug，半小时就通了。它不只是给代码，更给思路，这是我最看重的。**

```javascript
// middleware/auth.js — JWT验证中间件
const jwt = require('jsonwebtoken');

const JWT_SECRET = process.env.JWT_SECRET || 'your-secret-key-at-least-32-chars';

function authMiddleware(req, res, next) {
    // 1. 获取 Authorization 头
    const authHeader = req.headers.authorization;
    if (!authHeader || !authHeader.startsWith('Bearer ')) {
        return res.status(401).json({ code: 401, message: '未提供认证令牌' });
    }

    const token = authHeader.split(' ')[1];

    try {
        // 2. 验证令牌并解码
        const decoded = jwt.verify(token, JWT_SECRET);

        // 3. 将用户信息挂到req上，供后续路由/中间件使用
        req.user = {
            userId: decoded.userId,
            username: decoded.username,
            roleLevel: decoded.roleLevel,
            roleName: decoded.roleName
        };

        next();  // 验证通过，继续执行下一个中间件/路由
    } catch (err) {
        if (err.name === 'TokenExpiredError') {
            return res.status(401).json({ code: 401, message: '令牌已过期，请重新登录' });
        }
        return res.status(401).json({ code: 401, message: '无效的认证令牌' });
    }
}

// ⚠️ 导出方式：导出函数本身，不要导出对象！
module.exports = authMiddleware;
```

![screenshot_04_jwt_login_clean.png](https://developer.qcloudimg.com/http-save/yehe-12595092/4234c4e3ef5ad7a5f938927da6ce73ef.png)

![screenshot_06_homepage_loggedin_clean.png](https://developer.qcloudimg.com/http-save/yehe-12595092/8619eca8b5ed43a8589cef9bf16f5a41.png)


![screenshot_11_admin_users_clean.png](https://developer.qcloudimg.com/http-save/yehe-12595092/bf2cb263c126edd76cc0e041446de10c.png)

## 四、⚠️ 最大坑点：auth.js 导出方式

这是我整个项目里**排错时间最长的一个bug**，值得单独拿出来讲。

### 错误现象

```javascript
// ❌ 错误写法（解构导入）
const { authMiddleware } = require('./middleware/auth');

router.get('/resources', authMiddleware, (req, res) => {
    console.log(req.user);  // → undefined！！
    res.json({ code: 200, data: [] });
});
```

运行后`req.user`始终是`undefined`，中间件好像没执行一样。控制台也不报错——因为代码本身没有语法错误。

### 正确写法

```javascript
// ✅ 正确写法（整体导入函数）
const auth = require('./middleware/auth');

router.get('/resources', auth, (req, res) => {
    console.log(req.user);  // → { userId: 3, username: 'zhangsan', ... }
    res.json({ code: 200, data: [] });
});
```

### 根因分析

```javascript
// middleware/auth.js 的两种导出对比：

// 方式A：module.exports = authMiddleware;
// → require() 拿到的是函数本身
// → const auth = require(...) → auth 是一个 function
// → router.get('/', auth, handler) → auth(req,res,next) ✅ 正确调用

// 方式B：module.exports = { authMiddleware };
// → require() 拿到的是对象 { authMiddleware: [Function] }
// → const { auth } = require(...) → auth 是一个 function
// → 但如果写成 const auth = require(...) → auth 是 { authMiddleware: fn }
// → router.get('/', auth, handler) → 把对象当中间件用了 ❌ 报错或静默失败
```

**教训**：在一个项目里统一一种风格。我的规范是：**auth中间件永远用`module.exports = authMiddleware`（导出函数），路由端永远用`const auth = require(...)`（整体导入）**。这个规则写进了团队编码规范的铁律第一条。

## 五、前端认证逻辑

### 登录组件核心代码

```vue

<template>
  <div class="min-h-screen bg-gradient-to-b from-blue-50 to-white">
    <div class="max-w-sm mx-auto mt-20 bg-white rounded-xl shadow-lg p-8">
      <h2 class="text-xl font-bold text-center mb-6">用户登录</h2>
      <form @submit.prevent="handleLogin">
        <input v-model="form.username" placeholder="用户名" />
        <input v-model="form.password" type="password" placeholder="密码" />
        <button type="submit" :disabled="loading">登 录</button>
      </form>
      <p v-if="errorMsg" class="text-red-500 mt-4">{{ errorMsg }}</p>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { useRouter } from 'vue-router';
import api from '../services/api';

const router = useRouter();
const form = ref({ username: '', password: '' });
const loading = ref(false);
const errorMsg = ref('');

async function handleLogin() {
  if (!form.value.username || !form.value.password) {
    errorMsg.value = '请输入用户名和密码';
    return;
  }

  loading.value = true;
  errorMsg.value = '';

  try {
    const response = await api.post('/auth/login', form.value);
    const { token, user } = response.data.data;  // ⚠️ 注意嵌套层级！

    localStorage.setItem('token', token);
    localStorage.setItem('user', JSON.stringify(user));
    router.push('/');  // 跳转首页
  } catch (err: any) {
    errorMsg.value = err.response?.data?.message || '登录失败，请重试';
  } finally {
    loading.value = false;
  }
}
</script>
```

### Axios 请求拦截器（自动携带Token）

```javascript
// services/api.ts
import axios from 'axios';

const api = axios.create({
  baseURL: '/api',
  timeout: 30000,
});

// 请求拦截器：自动在每个请求头加入JWT
api.interceptors.request.use((config) => {
  const token = localStorage.getItem('token');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

// 响应拦截器：统一处理401（token过期跳登录）
api.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      localStorage.removeItem('token');
      localStorage.removeItem('user');
      window.location.href = '/login';  // 强制跳登录页
    }
    return Promise.reject(error);
  }
);

export default api;
```

## 六、安全加固清单

| 措施 | 实现方式 | 重要度 |
|------|---------|-------|
| 密码哈希 | bcrypt (cost≥10) | 🔴 必须 |
| JWT密钥 | 环境变量注入，≥32字符 | 🔴 必须 |
| Token有效期 | 24小时 | 🟡 推荐 |
| HTTPS传输 | frp + Caddy自签证书 | 🔴 必须 |
| 密码强度校验 | 前端+后端双重检查 | 🟡 推荐 |
| 登录限速 | express-rate-limit | 🟡 建议 |
| 敏感操作二次确认 | 删除/批量操作前弹窗确认 | 🟡 建议 |

## 七、本篇小结

认证模块虽然功能单一（注册+登录+鉴权），但它决定了整个系统的安全基线。三个关键决策：

1. **bcrypt 存密码**——永远不要明文存密码
2. **JWT 做会话**——无状态、前后端分离的最佳选择
3. **auth 中间件统一拦截**——但要注意导出方式的一致性

> 💡 **可复用经验**：这套认证模式（bcrypt + JWT + Axios拦截器）可以直接复制到任何前后端分离的项目中，改动量不超过20%。
>
> **下篇预告**：《从零搭建教学资源平台（五）：文件上传与存储方案》——multer配置、500MB大文件处理、中文文件名乱码修复，以及那个经典的坑：**multer必须在RBAC之前执行，否则req.body为空**。

**标签**：#WorkBuddy开发者分享季# #JWT# #认证授权# #Node.js# #安全# #前后端分离#

JWT完美匹配这些需求：无状态（服务端不存session）、自包含（用户信息编码在token里）、跨域友好（放在Authorization头而非Cookie里）。

# 从零搭建教学资源平台（四）：用户认证与JWT鉴权实战 #WorkBuddy开发者分享季#

系列导航：本文是系列第四篇。前一篇讲了六表E-R模型，本篇聚焦用户认证——从密码存储到JWT令牌的完整链路。

后端

编程语言

职业发展

JWT认证方案详解：前后端分离项目如何实现安全登录？本文对比Session、JWT、OAuth2.0等认证方案，重点解析JWT在跨域场景下的优势，提供完整的Node.js+Express实现代码，包括bcrypt密码哈希、JWT签发、认证中间件等核心模块，并分享常见坑点及安全加固措施。

单点登录

文件处理

代码解释

中间件

数据库

WorkBuddy 

路由

Redis

JSON

热销域名限时优惠，新客首年免费！


domain

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

# 从零搭建教学资源平台（四）：用户认证与JWT鉴权实战 #WorkBuddy开发者分享季#-腾讯云开发者社区-腾讯云

# 从零搭建教学资源平台（四）：用户认证与JWT鉴权实战 #WorkBuddy开发者分享季#

# 从零搭建教学资源平台（四）：用户认证与JWT鉴权实战 #WorkBuddy开发者分享季#

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐