NestJS 快速开始
当你第一次拉取项目、或准备把它跑起来与前端联调时，从这里开始。
本指南帮助你在 5 分钟内 完成后端服务 youlai-nest（Node/NestJS）的启动与验证，你将完成：
- 导入数据库初始化脚本
- 配置本地 MySQL / Redis
- 启动服务并访问
/api-docs - 使用默认账号完成一次登录验证
环境要求
| 工具 | 版本 | 用途 |
|---|---|---|
| Node.js | >= 20.17 LTS | 运行时 |
| pnpm | >= 8.0 | 包管理器 |
| MySQL | 5.7+ 或 8.x | 数据库 |
| Redis | 7.x | 缓存/Session |
项目结构
text
youlai-nest/
├── sql/ # 数据库脚本
│ └── mysql/
│ └── youlai_admin.sql # 初始化脚本
├── src/ # 源代码
│ ├── main.ts # 应用入口
│ ├── app.module.ts # 根模块
│ ├── auth/ # 认证与鉴权模块
│ ├── system/ # 系统核心模块（用户/角色/菜单/部门/字典/通知/日志）
│ ├── codegen/ # 代码生成模块
│ ├── file/ # 文件管理模块
│ ├── message/ # SSE 实时通信
│ ├── common/ # 公共能力（守卫/拦截器/过滤器/常量/枚举/异常/工具类等）
│ ├── config/ # 配置文件
│ └── types/ # 类型定义
├── docker/ # Docker 编排
├── .env # 基础配置
├── .env.dev # 开发环境配置
├── .env.prod # 生产环境配置
└── package.json # 项目脚本与依赖启动步骤
1. 克隆代码
bash
git clone https://gitee.com/youlaiorg/youlai-nest.git
cd youlai-nest2. 安装依赖
bash
pnpm install3. 数据库初始化
执行数据库脚本：
bash
mysql -u root -p < sql/mysql/youlai_admin.sql或通过数据库管理工具导入 sql/mysql/youlai_admin.sql。
4. 配置环境变量
修改 .env.dev（或新建本地副本并按需覆盖），配置 MySQL/Redis/JWT：
env
# 会话类型：jwt | redis-token
SESSION_TYPE=jwt
# MySQL
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=123456
MYSQL_DB=youlai_admin
# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=
# JWT（生产环境务必更换强密钥）
JWT_SECRET_KEY=change-me
JWT_EXPIRES_IN=7200
JWT_ISSUER=youlai-nest常用配置项：
APP_PORT：服务端口（默认8000）TYPEORM_LOGGING：是否输出 SQL 日志（开发环境建议true）
5. 启动服务
bash
# 开发模式（热重载）
pnpm run start:dev启动成功后访问：
| 服务 | 地址 |
|---|---|
| API 文档 (Swagger) | http://localhost:8000/api-docs |
| 健康检查 | http://localhost:8000/api/v1/health |
快速验证
接口文档
访问 Swagger 文档：
text
http://localhost:8000/api-docs登录测试
使用 Swagger 或 curl 测试登录接口：
bash
curl -X POST http://localhost:8000/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"123456"}'前端联调
配置后端地址
在前端项目 .env.development 设置后端地址：
env
VITE_APP_API_URL=http://localhost:8000默认账号
- 用户名：
admin - 密码：
123456
常见问题
端口冲突
排查：确认 APP_PORT 未被占用。
解决：修改 .env.dev 的 APP_PORT，并同步前端 VITE_APP_API_URL。
数据库连接失败
排查：
- MySQL 服务是否启动
.env.dev中MYSQL_HOST/MYSQL_PORT/MYSQL_USER/MYSQL_PASSWORD- 数据库
youlai_admin是否已导入脚本
Redis 连接失败
排查：
- Redis 服务是否启动
.env.dev中REDIS_HOST/REDIS_PORT/REDIS_PASSWORD
Docker 一键启动
bash
docker compose up -d --build下一步：