# lingxi-admin

**Repository Path**: ma-qiangwei/lingxi-admin

## Basic Information

- **Project Name**: lingxi-admin
- **Description**: 一个nestjs搭建的管理后台
- **Primary Language**: TypeScript
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-02-02
- **Last Updated**: 2026-09-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

NestJS 开源项目 README 模板（含定制功能）
直接复制到你的项目 `README.md` 即可使用，**专业、完整、GitHub 标准格式**，包含所有开源项目必备模块，已添加完善的日志系统、PM2部署、配置文件配置、核心模块集成测试等功能。

# 项目名称

✨ 基于 NestJS 构建的企业级后端服务框架

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen.svg)](https://nodejs.org/)
[![NestJS Version](https://img.shields.io/badge/nestjs-%5E10.0.0-red.svg)](https://nestjs.com/)
[![PM2 Version](https://img.shields.io/badge/pm2-%5E5.0.0-orange.svg)](https://pm2.keymetrics.io/)

## 📖 项目简介

本项目是一款基于 **NestJS + TypeScript** 开发的**现代化、模块化、高可用**后端服务模板。
遵循企业级开发规范，开箱即用，帮助开发者快速搭建稳定、可扩展、易维护的服务端应用，内置完善的日志系统、PM2部署支持、灵活配置及完整集成测试，降低开发与部署成本。

## ✨ 核心特性

- ✅ 完全使用 **TypeScript** 开发，类型安全
- ✅ 模块化架构，代码结构清晰，易于扩展
- ✅ 内置依赖注入（DI），松耦合、高复用
- ✅ 支持 RESTful API 标准接口设计
- ✅ 集成数据库 / ORM / 事务管理
- ✅ 完整的权限控制、路由守卫、全局拦截
- ✅ 统一响应格式 + 全局异常处理
- ✅ 完善的日志系统（分级日志、文件归档、异常日志追溯）
- ✅ 支持配置文件配置基础参数（环境、数据库、端口等，灵活适配多环境）
- ✅ 支持 PM2 部署（进程守护、自动重启、日志管理）
- ✅ 核心模块有完整的集成测试（保障模块稳定性，降低迭代风险）
- ✅ 环境变量配置、接口文档
- ✅ 支持开发/生产环境一键切换
- ✅ 代码规范 + 提交规范 + 自动化脚本

## 🚀 快速开始

### 环境要求

- Node.js >= 16.x
- 建议使用 pnpm
- 数据库（MySQL/PostgreSQL 等）
- PM2 >= 5.0.0（用于生产环境部署）

### 安装依赖

```bash
pnpm install
# 全局安装PM2（生产环境必备）
pnpm install pm2 -g
# 全局安装 PM2 日志切割插件
pnpm install pm2-logrotate -g
# 配置每天分割 + 最大100M + 保留30天 + 上海时区
pm2 set pm2-logrotate:rotateInterval "0 0 * * *"
pm2 set pm2-logrotate:max_size 100M
pm2 set pm2-logrotate:retain 30
pm2 set pm2-logrotate:timezone "Asia/Shanghai"
```

### 环境配置

#### 1. 配置文件配置基础参数

项目支持通过配置文件灵活配置基础参数，无需修改代码即可适配不同环境：

- 核心配置文件路径：[lingxi.config.yaml](lingxi.config.yaml)（包含数据库、端口、日志、跨域等基础参数）
- 复制环境配置文件并修改对应参数：

### 启动项目

```bash
# 开发模式
pnpm start:dev

# 生产模式（直接启动）
pnpm build
pnpm start:prod

# 生产模式（PM2部署，推荐）
pnpm build
pm2 start ecosystem.config.js     # 启动并命名进程
pm2 logs                          # 查看PM2日志
pm2 restart ecosystem.config.js   # 重启进程
pm2 stop ecosystem.config.js      # 停止进程
pm2 delete ecosystem.config.js    # 删除进程
```

### 访问项目

- API 地址：http://localhost:3000（端口可在配置文件中修改）
- 接口文档：http://localhost:3000/api-docs
- 日志查看：开发环境日志输出至控制台，生产环境PM2部署日志归档至 `logs/` 目录（可在配置文件[ecosystem.config.js](ecosystem.config.js)中修改日志路径和级别）

## 📚 项目结构

```
src/
├── common/        # 公共模块（过滤器、拦截器、装饰器等）
├── config/        # 配置文件（基础参数配置、日志配置等）
├── modules/       # 业务模块（各模块均包含集成测试用例）
├── core/          # 核心模块（完整集成测试覆盖，保障核心功能稳定）
├── utils/         # 工具函数
├── test/          # 测试目录（核心模块集成测试、单元测试用例）
├── app.module.ts  # 根模块
└── main.ts        # 入口文件
```

## 🧩 内置模块

- 用户认证与授权（JWT）
- 角色权限管理
- 完善的日志系统（分级输出、文件归档、异常追溯）
- 全局异常处理
- 请求参数校验
- 接口文档自动生成
- 数据库 CRUD 封装
- 配置文件管理（支持基础参数灵活配置）
- PM2 部署适配（进程守护、日志集成）
- 核心模块集成测试（test目录下，可直接运行测试）
- 定时任务（可选）
- 文件上传（可选）

## 🧪 集成测试

核心模块已实现完整的集成测试，保障模块功能稳定性，降低迭代风险：

```bash
# 运行所有集成测试
npm run test:integration

# 运行指定模块集成测试
npm run test:integration -- --testNamePattern=模块名称
```

踩坑说明

- 文档完善使用工厂模式，VO类只能通过 `ApiOkResponse` 完善Swagger文档，并不能在代码里当作类型使用（不推荐）。

测试用例位于 `test/` 目录下，与核心模块一一对应，可根据业务扩展测试场景。

## 📝 开发规范

- 遵循 RESTful API 设计规范
- 使用 TypeScript 强类型约束
- 统一错误码与响应格式
- 模块化、单一职责设计
- Git 提交信息规范化
- 核心模块新增/修改后，需补充对应的集成测试用例

## 📄 许可证

本项目基于 [MIT License](LICENSE) 开源，可自由使用、修改、分发。

## 🤝 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/xxx`)
3. 提交修改（核心模块修改需补充集成测试，`git commit -m 'feat: add xxx'`）
4. 推送到分支 (`git push origin feature/xxx`)
5. 提交 Pull Request（将自动触发集成测试，测试通过后方可合并）

## 💡 联系方式

如有问题或建议，欢迎提交 Issue 或邮件联系。

---

⭐ 如果本项目对你有帮助，欢迎 Star 支持一下！

### 替换说明（仅需修改4处，快速适配你的项目）

1. 项目名称：替换文档中所有「项目名称」为你的实际项目名
2. 项目简介：修改为你的项目具体用途（如“用户管理系统后端”“API网关服务”等）
3. 内置模块：删除/补充你项目实际拥有的功能，保留新增的4个定制功能即可
4. 配置文件/日志路径：若你的项目配置文件、日志目录路径不同，修改对应描述即可

## 支持使用openapi-generator-cli、openapi-typescript-codegen生成接口对应的请求代码

```bash
## 生成请求代码-合并模板代码-合并到前端目录。可以换-d参数为自己项目的路径。
C:\Users\developer\Desktop\lingxi-front\app\common\api
### typescript/openapi-typescript-codegen 工具
#### 生成TypeScript版本
npx openapi-typescript-codegen --input openapi/swagger.json --output openapi/temp/openapi-typescript-codegen --client axios --useOptions; # 生成到临时目录
node scripts/merge-directories.js -s openapi/template/openapi-typescript-codegen -d openapi/temp/openapi-typescript-codegen; # 模板代码合并到临时目录
node scripts/merge-directories.js -s openapi/temp/openapi-typescript-codegen -d ../lingxi-front/app/common/api -i core; # 合并到前端目录

### java/openapi-generator-cli 工具
#### 生成Dart版本
java -jar openapi-generator-cli-7.9.0.jar generate -i openapi/swagger.json -g dart-dio -o ./openapi/temp/openapi-dart --skip-validate-spec; # 生成到临时目录
node scripts/merge-directories.js -s openapi/template/openapi-dart -d openapi/temp/openapi-dart; # 模板代码合并到临时目录
node scripts/merge-directories.js -s openapi/temp/openapi-dart -d ../lingxi-front/app/common/api -c; # 合并到前端目录

#### 生成TypeScript Fetch版本
java -jar openapi-generator-cli-7.9.0.jar generate -i openapi/swagger.json -g typescript-fetch -o ./openapi/temp/typescript-fetch --skip-validate-spec; # 生成到临时目录
node scripts/merge-directories.js -s openapi/template/typescript-fetch -d openapi/temp/typescript-fetch; # 模板代码合并到临时目录
node scripts/merge-directories.js -s openapi/temp/typescript-fetch -d ../lingxi-front/app/common/api -c; # 合并到前端目录

#### 生成TypeScript Axios版本
java -jar openapi-generator-cli-7.9.0.jar generate -i openapi/swagger.json -g typescript-axios -o ./openapi/temp/typescript-axios --skip-validate-spec; # 生成到临时目录
node scripts/merge-directories.js -s openapi/template/typescript-axios -d openapi/temp/typescript-axios; # 模板代码合并到临时目录
node scripts/merge-directories.js -s openapi/temp/typescript-axios -d ../lingxi-front/app/common/api -c; # 合并到前端目录

#### 生成Java版本
java -jar openapi-generator-cli-7.9.0.jar generate -i openapi/swagger.json -g java -o ./openapi/temp/openapi-java --skip-validate-spec; # 生成到临时目录
node scripts/merge-directories.js -s openapi/template/openapi-java -d openapi/temp/openapi-java; # 模板代码合并到临时目录
node scripts/merge-directories.js -s openapi/temp/openapi-java -d ../lingxi-front/app/common/api -c; # 合并到前端目录
```

<!-- java -jar openapi-generator-cli-7.9.0.jar generate -i openapi/swagger.json -g typescript-fetch -o openapi/temp/openapi-typescript --skip-validate-spec -->

## 部署脚本

```bash
node scripts/deploy.js -H 47.100.227.40 -u root -p ****** -d "/opt"
```