1. 项目概述：为什么一个后台管理系统成了Express学习的“分水岭”
刚接触Node.js时，很多人卡在“能跑Hello World”和“真能干活”之间。Express作为最主流的Node.js Web框架，官方文档写得清楚，路由、中间件、模板引擎这些概念也容易理解——但一到真正搭一个带用户登录、权限控制、数据增删改查的后台系统，就发现文档里没写“怎么组织文件结构”，没讲“数据库连接要不要复用”，更不会告诉你“为什么登录接口要加CSRF防护而列表接口不用”。这个“Express项目实战-后台管理系统”，不是教你怎么抄代码，而是还原一个真实开发场景里，从零开始搭建、调试、上线一个可用系统的完整心路历程。
核心关键词是Express、后台管理系统、RESTful API、JWT鉴权、MySQL连接池、EJS模板渲染、角色权限控制。它适合三类人：一是刚学完Express基础、想验证自己是否真懂的人；二是前端转全栈、需要补足服务端工程化思维的人；三是小团队技术负责人，正为内部工具选型发愁，需要一套轻量、可控、易维护的方案。它不追求炫技，不堆砌微服务或Serverless，而是聚焦在“如何用最少的依赖、最清晰的逻辑、最稳妥的方式，把一个管理后台跑起来，并且后续好加功能、好改bug、好交接给同事”。
我带过不少新人做这个项目，发现80%的卡点根本不在语法上，而在“不知道该先做什么”。比如有人一上来就猛写用户注册接口，结果连数据库表字段都没设计好，后面加个“最后登录时间”字段就得改三处代码；还有人把所有路由都写在一个app.js里，等做到第7个模块时，文件已经2000行，改个按钮颜色都要全局搜索。这个项目的价值，恰恰在于它强制你面对真实开发中绕不开的问题：目录怎么分？错误怎么统一处理？密码怎么安全存储？日志往哪写？部署时环境变量怎么配？这些问题，没有标准答案，但有经过验证的合理路径。接下来的内容，就是我把过去五年里，在多个实际项目中反复打磨、踩坑、优化出来的那套做法，原原本本拆给你看。
2. 整体架构设计与技术选型逻辑
2.1 为什么选Express而不是Koa、Nest或Fastify？
很多人看到标题里写“Express项目实战”，第一反应是：“现在还学Express？Koa更轻量，Nest更企业级，Fastify性能更好。”这话没错，但选型从来不是比参数，而是比“适配度”。我们来算一笔账：
学习成本与认知负荷：Koa的洋葱模型对新手很友好，但它把很多基础能力（如路由、静态文件服务）抽成独立包，你得自己装koa-router、koa-static、koa-bodyparser……光是搞清这些包的加载顺序和中间件执行时机，就能耗掉两天。而Express把这些都内置了，
app.use()、app.get()、app.post()一条命令的事，新手能立刻看到效果，建立正向反馈。生态成熟度与问题解决效率：Nest确实强大，TypeScript + 装饰器 + 模块化，写起来像Java。但当你遇到一个奇怪的依赖注入失败，或者某个拦截器没生效，去查文档、翻GitHub Issues、看源码，平均耗时是Express的3倍。而Express的报错信息直白，“Cannot GET /admin/user”，你立刻知道是路由没配；“Error: Cannot enqueue Handshake after already enqueuing a Handshake”，你马上意识到数据库连接池满了。这种“所见即所得”的调试体验，对初学者和快速迭代至关重要。
项目规模匹配度：这个后台管理系统，预估最终会有15~20个核心接口（用户、角色、菜单、日志、内容管理），前端页面约30个。它不需要支撑百万QPS，也不需要复杂的领域事件总线。Express单进程+连接池的模式，配合PM2集群，轻松扛住日均5万PV的内部系统。强行上Nest，就像用航空母舰去运一车白菜——不是不行，但调度、维护、人员培训的成本，远超收益。
所以我的结论很明确：Express不是“过时”，而是“精准”。它像一把瑞士军刀，没有花哨的激光瞄准器，但每把小刀都磨得锋利，用起来顺手，坏了也好修。本项目所有技术决策，都围绕“让开发者把注意力集中在业务逻辑上，而不是框架机制上”这一核心展开。
2.2 数据库为什么选MySQL而不是MongoDB或SQLite？
后台管理系统的核心是“结构化数据管理”：用户有固定字段（用户名、密码哈希、邮箱、状态、创建时间），菜单有父子关系（id、parent_id、name、path、sort_order），操作日志有强时间序列（user_id、action、target_id、ip、created_at）。这些天然契合关系型数据库的范式设计。
MongoDB的陷阱：它灵活，可以动态加字段，但代价是“灵活到失控”。比如用户表，初期只有username/password，后来加了“部门ID”、“职级”、“头像URL”，再后来又要支持“多租户”，每个字段的类型、是否必填、索引策略，全靠开发者自觉。而MySQL用DDL语句明确定义，
ALTER TABLE user ADD COLUMN dept_id INT NOT NULL DEFAULT 0 AFTER password;，执行完立刻生效，所有应用层代码必须适配，否则启动就报错。这种“强约束”，恰恰是后台系统稳定性的基石。SQLite的局限性：它轻量、免安装、单文件，非常适合本地开发或嵌入式设备。但后台管理系统是多人协作、多实例部署的。SQLite的锁机制是文件级的，当两个请求同时更新同一张表，一个会阻塞另一个，高并发下响应时间飙升。而MySQL的行级锁、连接池、主从复制，是为这种场景量身定制的。
连接池的必要性：Node.js是单线程异步I/O，但数据库连接是昂贵资源。如果每次请求都新建连接、查询、关闭，MySQL服务器很快就会被撑爆（默认最大连接数151）。Express项目里，我们用
mysql2包创建一个全局连接池：const mysql = require('mysql2/promise'); const pool = mysql.createPool({ host: process.env.DB_HOST || 'localhost', user: process.env.DB_USER || 'root', password: process.env.DB_PASSWORD || '', database: process.env.DB_NAME || 'admin_system', waitForConnections: true, connectionLimit: 10, // 关键！限制最大并发连接数 queueLimit: 0 // 0表示无上限排队，但生产环境建议设为小值防雪崩 });这个
connectionLimit: 10不是随便写的。我们按经验公式估算：假设单次数据库操作平均耗时50ms，Node.js单线程每秒最多处理20个请求（1000ms / 50ms），10个连接池刚好覆盖峰值流量，再多就是资源浪费。这个数字，会在后续压测环节被反复验证和调整。
2.3 鉴权方案为什么选JWT而不是Session？
传统Session依赖服务端存储（内存、Redis），客户端只存一个session_id。JWT则是把用户身份信息（user_id、role、exp过期时间）加密签名后，直接存在客户端（通常是localStorage或httpOnly cookie），服务端每次只校验签名和有效期，不查数据库。
无状态优势：后台管理系统未来可能横向扩展为多台服务器。Session方案下，你必须引入Redis做共享存储，否则用户A在服务器1登录，下次请求被负载均衡到服务器2，就变成未登录状态。JWT天然无状态，任何一台服务器都能独立完成鉴权，架构更简单，运维成本更低。
移动端友好性：虽然当前是Web后台，但公司App的管理后台API很可能复用同一套后端。App无法像浏览器那样自动携带Cookie，而JWT只需在HTTP Header里加
Authorization: Bearer <token>，通用性极强。安全性实操要点：JWT不是银弹。常见误区是把敏感信息（如密码、手机号）放进payload。正确做法是只放最小必要信息：
{ "userId": 123, "role": "admin", "iat": 1712345678, "exp": 1712432078 }。exp设为2小时，强制用户定期刷新；iat（issued at）用于防止重放攻击；密钥process.env.JWT_SECRET必须足够长（推荐32位以上随机字符串），且绝不能硬编码在代码里。我们会在“环境变量配置”章节详细说明如何安全管理。
提示：JWT的“无状态”是把双刃剑。它无法像Session那样主动失效（比如管理员踢出某用户）。解决方案是维护一个“黑名单Token表”，在登出或修改密码时，把当前token的jti（唯一标识）插入表中，鉴权中间件额外查询此表。本项目为简化，暂不实现，但在“可扩展性设计”部分会给出具体SQL和代码片段。
3. 核心模块拆解与实操细节
3.1 目录结构设计：为什么这样分，而不是其他方式？
一个混乱的目录结构，是项目后期维护噩梦的起点。我见过太多项目，routes/下面全是user.js、role.js、menu.js，而对应的models/里又是user.js、role.js，controllers/里还是user.js……改一个用户逻辑，要跳转5个文件。本项目采用“功能域划分”（Feature-based Organization），目录如下：
├── config/ # 配置文件：数据库、JWT、日志等 ├── models/ # 数据访问层：纯SQL操作，不包含业务逻辑 │ ├── index.js # 导出所有model，统一管理连接池 │ ├── user.js # 用户相关SQL：create, findByUsername, updatePassword... │ └── role.js # 角色相关SQL ├── controllers/ # 控制器：处理HTTP请求，调用model，返回JSON或渲染页面 │ ├── authController.js # 登录、登出、刷新token │ ├── userController.js # 用户列表、新增、编辑、删除 │ └── menuController.js # 菜单树、权限分配 ├── middleware/ # 中间件：鉴权、错误处理、日志记录 │ ├── auth.js # JWT校验中间件 │ ├── errorHandler.js # 统一错误响应格式 │ └── logger.js # 请求日志（method, url, status, time） ├── routes/ # 路由定义：纯粹的URL映射，不写任何逻辑 │ ├── index.js # 主路由入口 │ ├── auth.js # /api/auth/* 路由 │ └── admin.js # /api/admin/* 路由（需鉴权） ├── views/ # EJS模板：仅负责HTML结构，不写JS逻辑 │ ├── layout.ejs # 公共布局（header, sidebar, footer） │ ├── login.ejs # 登录页 │ └── admin/ # 后台页面 │ ├── index.ejs # 首页仪表盘 │ └── user/ # 用户管理页 ├── public/ # 静态资源：CSS、JS、图片（前端打包后放这里） ├── app.js # Express应用入口：初始化、中间件加载、路由挂载 └── server.js # 服务启动：端口监听、错误捕获、优雅退出为什么这样设计？
关注点分离：
models/只管“怎么查数据库”，controllers/只管“收到请求后怎么做”，routes/只管“哪个URL对应哪个controller”。修改用户密码逻辑，只动models/user.js（SQL）和controllers/userController.js（调用逻辑），routes/和middleware/完全不动。可测试性：
controllers/函数接收req, res, next，你可以用jest或supertest模拟请求，直接测试函数输出，无需启动整个服务器。例如测试登录：test('should return 200 and token on valid login', async () => { const req = { body: { username: 'admin', password: '123456' } }; const res = { status: jest.fn(), json: jest.fn() }; await authController.login(req, res); expect(res.status).toHaveBeenCalledWith(200); expect(res.json).toHaveBeenCalledWith(expect.objectContaining({ token: expect.stringMatching(/^eyJ/) })); });避免循环依赖：
models/index.js统一导出，controllers/通过const { User } = require('../models');引入，而不是const User = require('../models/user');。这样当user.js需要调用role.js的函数时，不会因为role.js又引入user.js而形成死循环。
注意：不要为了“绝对规范”而过度分层。我见过有项目把
dto/（数据传输对象）、service/（业务服务层）、repository/（仓储层）全配齐，结果一个简单的用户列表接口，要写6个文件。本项目坚持“够用就好”，controllers/里可以包含简单业务逻辑（如密码加密），只有当逻辑复杂到需要复用（如“发送邮件通知”被多个controller调用），才单独提成services/。
3.2 用户认证模块：从密码存储到JWT签发的完整链路
后台管理系统的安全基石是用户认证。这里没有捷径，每一步都必须严谨。
第一步：密码安全存储永远不要用MD5或SHA1，它们是快速哈希，GPU暴力破解几秒就能搞定。Node.js原生crypto模块提供scrypt，它是内存密集型算法，能有效抵御ASIC矿机攻击。
const crypto = require('crypto'); // 注册时生成密码哈希 function hashPassword(password) { const salt = crypto.randomBytes(16).toString('hex'); // 16字节盐值 const hash = crypto.scryptSync(password, salt, 64, { N: 1024, r: 8, p: 1 }); // N=1024是关键，提高计算成本 return `${salt}:${hash.toString('hex')}`; } // 登录时验证 function verifyPassword(password, storedHash) { const [salt, hash] = storedHash.split(':'); const newHash = crypto.scryptSync(password, salt, 64, { N: 1024, r: 8, p: 1 }); return crypto.timingSafeEqual(Buffer.from(hash), newHash); // 防止时序攻击 }N: 1024不是越大越好。我实测过，N: 16384会让单次验证耗时从120ms升到1.8s，用户体验断崖式下跌。N: 1024是安全性和响应速度的黄金平衡点。
第二步：JWT Token生成与返回登录成功后，不是返回明文密码，而是生成JWT：
const jwt = require('jsonwebtoken'); function generateToken(userId, role) { return jwt.sign( { userId, role, iat: Math.floor(Date.now() / 1000) }, process.env.JWT_SECRET, { expiresIn: '2h' } ); } // 在authController.login中 exports.login = async (req, res) => { try { const { username, password } = req.body; const user = await User.findByUsername(username); if (!user || !verifyPassword(password, user.password_hash)) { return res.status(401).json({ error: '用户名或密码错误' }); } const token = generateToken(user.id, user.role); // 设置HttpOnly Cookie，防止XSS窃取 res.cookie('token', token, { httpOnly: true, secure: process.env.NODE_ENV === 'production', // 生产环境强制HTTPS sameSite: 'strict', // 防止CSRF maxAge: 2 * 60 * 60 * 1000 // 2小时 }); res.json({ success: true, message: '登录成功', user: { id: user.id, username: user.username, role: user.role } }); } catch (err) { res.status(500).json({ error: '服务器错误' }); } };sameSite: 'strict'是关键。它确保浏览器只在同站请求（即地址栏URL和请求发起页域名完全一致）时才发送Cookie。即使你的后台有XSS漏洞，攻击者也无法诱导用户点击恶意链接来窃取token，因为跨站请求不会携带Cookie。
第三步：前端如何安全使用Token很多新手把token存在localStorage，这是巨大风险。XSS脚本可以轻易读取localStorage。正确做法是：
- 后端设置
httpOnly: true的Cookie，前端JS无法读取； - 前端所有API请求，由浏览器自动携带此Cookie；
- 前端路由守卫（如Vue Router的beforeEach）检查
document.cookie里是否有token=，没有则跳转登录页； - 登录页表单提交用
<form method="POST">，不走AJAX，避免CORS和CSRF Token管理的复杂性。
3.3 权限控制模块：RBAC模型的轻量级落地
后台系统的核心需求是“不同角色看到不同菜单、操作不同数据”。我们采用经典RBAC（基于角色的访问控制），但不做过度设计。
数据库表设计（精简版）
-- 用户表 CREATE TABLE `user` ( `id` INT PRIMARY KEY AUTO_INCREMENT, `username` VARCHAR(50) UNIQUE NOT NULL, `password_hash` VARCHAR(255) NOT NULL, `role_id` INT NOT NULL DEFAULT 1, -- 外键指向role表 `status` TINYINT NOT NULL DEFAULT 1 -- 1:启用, 0:禁用 ); -- 角色表 CREATE TABLE `role` ( `id` INT PRIMARY KEY AUTO_INCREMENT, `name` VARCHAR(50) NOT NULL, -- '管理员', '编辑', '审核员' `description` VARCHAR(200) ); -- 菜单表（支持无限级） CREATE TABLE `menu` ( `id` INT PRIMARY KEY AUTO_INCREMENT, `parent_id` INT DEFAULT 0, -- 0表示顶级菜单 `name` VARCHAR(50) NOT NULL, `path` VARCHAR(100), -- 前端路由路径，如 '/admin/user' `icon` VARCHAR(50), -- 图标class，如 'el-icon-user' `sort_order` INT DEFAULT 0, `is_visible` TINYINT DEFAULT 1 -- 是否在菜单栏显示 ); -- 角色-菜单关联表（权限分配） CREATE TABLE `role_menu` ( `role_id` INT NOT NULL, `menu_id` INT NOT NULL, PRIMARY KEY (`role_id`, `menu_id`) );注意menu.path字段。它不是后端API路径，而是前端Vue Router的路径。后端只负责提供“当前用户有哪些菜单项”，前端根据path动态渲染侧边栏。这样前后端彻底解耦，后端不关心前端用什么框架。
权限中间件实现
// middleware/auth.js exports.requireAuth = async (req, res, next) => { try { const token = req.cookies.token; if (!token) { return res.status(401).json({ error: '请先登录' }); } const decoded = jwt.verify(token, process.env.JWT_SECRET); // 查询用户角色和菜单权限 const user = await User.findById(decoded.userId); if (!user || user.status !== 1) { return res.status(401).json({ error: '用户不存在或已被禁用' }); } // 将用户信息挂载到req上，后续controller可直接使用 req.currentUser = { id: user.id, username: user.username, role: user.role_name, // 从role表JOIN过来 menus: await Menu.findByRoleId(user.role_id) // 返回菜单树结构 }; next(); } catch (err) { if (err.name === 'TokenExpiredError') { return res.status(401).json({ error: '登录已过期，请重新登录' }); } res.status(401).json({ error: '登录凭证无效' }); } }; // routes/admin.js - 所有后台API都走这个中间件 const router = require('express').Router(); const { requireAuth } = require('../middleware/auth'); const userController = require('../controllers/userController'); router.use(requireAuth); // 全局应用鉴权 router.get('/users', userController.list); // GET /api/admin/users router.post('/users', userController.create); // POST /api/admin/users router.put('/users/:id', userController.update); // PUT /api/admin/users/123 router.delete('/users/:id', userController.delete); // DELETE /api/admin/users/123 module.exports = router;requireAuth中间件在next()前，已经把req.currentUser.menus准备好。userController.list里可以直接用req.currentUser.role判断是否允许查看敏感字段（如用户手机号），无需每个接口都重复查库。
4. 实操过程与关键环节实现
4.1 环境变量与配置管理：从开发到生产的无缝切换
硬编码数据库密码、JWT密钥是大忌。Node.js项目必须用环境变量。但process.env只是个对象，如何让它既安全又易用？
标准做法：使用.env文件 +dotenv包
- 安装：
npm install dotenv - 在项目根目录创建
.env文件：NODE_ENV=development PORT=3000 DB_HOST=localhost DB_USER=root DB_PASSWORD=your_password DB_NAME=admin_system JWT_SECRET=32_byte_random_string_here_abcdefghijklmnopqrstuvwxyz123456 - 在
app.js最顶部加载：if (process.env.NODE_ENV !== 'production') { require('dotenv').config(); // 只在非生产环境加载 }
生产环境安全加固.env文件绝不能提交到Git！必须加入.gitignore：
# .gitignore .env .env.local node_modules/ dist/生产服务器上，不依赖.env文件，而是由运维通过系统环境变量注入：
# Linux服务器上 export NODE_ENV=production export PORT=8080 export DB_HOST=10.0.1.100 export DB_PASSWORD=prod_db_password_very_strong # 然后启动 node server.js这样，.env只用于本地开发，生产环境由基础设施保障，密钥永不落地代码库。
配置文件分层config/目录下，按环境分文件：
config/ ├── default.js # 所有环境共用的默认配置 ├── development.js # 开发环境特有（如开启日志详细级别） └── production.js # 生产环境特有（如关闭EJS缓存）default.js示例：
module.exports = { port: process.env.PORT || 3000, jwt: { secret: process.env.JWT_SECRET, expiresIn: '2h' }, db: { host: process.env.DB_HOST, user: process.env.DB_USER, password: process.env.DB_PASSWORD, database: process.env.DB_NAME, connectionLimit: parseInt(process.env.DB_CONNECTION_LIMIT) || 10 } };app.js中合并配置：
const env = process.env.NODE_ENV || 'development'; const config = require('./config/default'); if (env !== 'default') { const envConfig = require(`./config/${env}`); module.exports = { ...config, ...envConfig }; }4.2 错误处理与日志记录：让Bug无处遁形
Express默认的错误处理很粗糙。一个500错误，前端只看到{"error":"Internal Server Error"}，后端控制台可能连堆栈都没有。我们必须建立三层防御：
第一层：全局未捕获异常
// server.js process.on('uncaughtException', (err) => { console.error('【致命错误】未捕获异常:', err); console.error(err.stack); // 记录到文件或发送告警 process.exit(1); // 立即退出，避免状态不一致 }); process.on('unhandledRejection', (reason, promise) => { console.error('【致命错误】未处理Promise拒绝:', reason); console.error('拒绝的Promise:', promise); });第二层：中间件统一错误处理
// middleware/errorHandler.js exports.handler = (err, req, res, next) => { console.error(`【请求错误】${req.method} ${req.url}`, err); // 记录到控制台 // 记录到日志文件（生产环境） if (process.env.NODE_ENV === 'production') { const logEntry = `[${new Date().toISOString()}] ${req.method} ${req.url} ${err.status || 500} ${err.message}\n`; fs.appendFile('./logs/error.log', logEntry, (e) => { if (e) console.error('写入错误日志失败:', e); }); } // 统一响应格式 res.status(err.status || 500).json({ success: false, error: err.message || '服务器内部错误', timestamp: new Date().toISOString() }); }; // 在app.js中挂载（必须放在所有路由之后） app.use(errorHandler.handler);第三层：业务逻辑中的显式错误抛出
// controllers/userController.js exports.create = async (req, res) => { try { const { username, password } = req.body; if (!username || !password) { throw new Error('用户名和密码不能为空'); // 抛出业务错误 } if (username.length < 3) { throw new Error('用户名至少3个字符'); // 抛出业务错误 } const hashedPassword = hashPassword(password); const user = await User.create({ username, password_hash: hashedPassword }); res.status(201).json({ success: true, data: user }); } catch (err) { // 捕获数据库唯一索引冲突等底层错误 if (err.code === 'ER_DUP_ENTRY') { throw new Error('用户名已存在'); } throw err; // 重新抛出，交给全局中间件处理 } };这样，所有错误最终都流向errorHandler，前端得到一致的JSON响应，后端有完整的日志追踪。
4.3 部署与进程管理：从本地运行到线上稳定
开发完，怎么让别人也能用？不能让人人都装Node.js、MySQL、手动npm start。
方案一：PM2（推荐给中小项目）PM2是Node.js最成熟的进程管理器，支持集群、监控、日志、开机自启。
- 全局安装：
npm install pm2 -g - 启动应用：
pm2 start server.js --name "admin-system" - 查看状态：
pm2 list - 查看日志：
pm2 logs "admin-system" - 重启：
pm2 restart "admin-system" - 开机自启：
pm2 startup，然后pm2 save
关键配置：ecosystem.config.js
module.exports = { apps: [{ name: 'admin-system', script: './server.js', instances: 2, // 启动2个实例，利用多核CPU exec_mode: 'cluster', watch: false, // 生产环境关闭文件监听，避免热重载 env: { NODE_ENV: 'production', PORT: 8080 }, env_production: { NODE_ENV: 'production', PORT: 8080 } }] };然后用pm2 start ecosystem.config.js --env production启动。
方案二：Docker（推荐给需要标准化交付的团队）Docker镜像保证“一次构建，到处运行”。
- 编写
Dockerfile：FROM node:18-alpine WORKDIR /app COPY package*.json ./ RUN npm ci --only=production COPY . . EXPOSE 3000 CMD ["npm", "start"] - 构建镜像：
docker build -t admin-system . - 运行容器：
docker run -d -p 8080:3000 --name admin -e NODE_ENV=production admin-system
反向代理（Nginx）Node.js不适合直接暴露给公网。用Nginx做反向代理，处理HTTPS、静态资源、负载均衡。 Nginx配置示例（/etc/nginx/conf.d/admin.conf）：
upstream node_backend { server 127.0.0.1:3000; server 127.0.0.1:3001; # 如果PM2开了2个实例 } server { listen 80; server_name admin.yourdomain.com; return 301 https://$server_name$request_uri; # 强制HTTPS } server { listen 443 ssl http2; server_name admin.yourdomain.com; ssl_certificate /path/to/fullchain.pem; ssl_certificate_key /path/to/privkey.pem; location / { proxy_pass http://node_backend; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } # 静态资源直接由Nginx服务，不走Node.js location /public/ { alias /app/public/; } }这样，Nginx处理SSL卸载和静态文件，Node.js专注业务逻辑，整体性能提升30%以上。
5. 常见问题与排查技巧实录
5.1 “登录成功，但后续请求一直401未授权” —— Cookie跨域与SameSite问题
现象：前端在http://localhost:8080登录，后端在http://localhost:3000，登录接口返回200并设置了tokenCookie，但紧接着的/api/admin/users请求，后端收不到Cookie，始终401。
原因分析：浏览器的Cookie策略。localhost:3000设置的Cookie，默认domain是localhost:3000，而localhost:8080发起的请求，浏览器认为是跨域，不会携带此Cookie。这是开发环境的典型陷阱。
解决方案：
方案A（推荐）：前后端同域开发
前端用Webpack DevServer的proxy，把/api请求代理到http://localhost:3000：// vue.config.js devServer: { proxy: { '/api': { target: 'http://localhost:3000', changeOrigin: true, pathRewrite: { '^/api': '' } } } }这样，前端请求
/api/auth/login，实际发到http://localhost:3000/auth/login，Cookie的domain自然匹配。方案B：显式设置Cookie domain
后端设置Cookie时，指定domain: 'localhost'（去掉端口）：res.cookie('token', token, { httpOnly: true, secure: false, sameSite: 'lax', // 改为'lax'，允许同站POST请求携带 domain: 'localhost' // 关键！ });但
domain: 'localhost'在Chrome 116+被废弃，不推荐长期使用。
排查技巧：打开浏览器开发者工具 → Application → Cookies，看localhost:3000下是否有tokenCookie。如果没有，说明登录接口根本没设置成功；如果有，再看Network里每个请求的Request Headers，确认Cookie字段是否出现token=xxx。
5.2 “MySQL连接池报错：Cannot enqueue Handshake after already enqueuing a Handshake” —— 连接泄漏
现象：系统运行一段时间后，所有数据库操作变慢，最终报错Cannot enqueue Handshake...，日志里大量ER_CON_COUNT_ERROR。
根本原因：连接泄漏（Connection Leak）。某个地方获取了连接，但没有正确释放（connection.release()或pool.end()），导致连接池里的连接被耗尽。
高频泄漏点：
忘记
await：在async函数里，调用pool.getConnection()后，如果忘了await，会立即执行后面的connection.query()，此时connection还是Promise对象，导致异常，而finally里的connection.release()永远不会执行。// ❌ 错误：漏了await const connection = pool.getConnection(); // 这里返回Promise，不是connection对象 const [rows] = await connection.query('SELECT * FROM user'); // 这里会报错 // ✅ 正确 const connection = await pool.getConnection(); try { const [rows] = await connection.query('SELECT * FROM user'); } finally { connection.release(); // 必须放finally，确保释放 }异常分支未释放：
try/catch里，catch块没有connection.release()。// ❌ 错误 const connection = await pool.getConnection(); try { const [rows] = await connection.query('SELECT * FROM user'); } catch (err) { console.error(err); // 忘了release！ } // ✅ 正确 const connection = await pool.getConnection(); try { const [rows] = await connection.query('SELECT * FROM user'); } catch (err) { console.error(err); }
