# nova-stack **Repository Path**: shuai_dd/nova-stack ## Basic Information - **Project Name**: nova-stack - **Description**: NovaStack 致力于为开发者提供一套现代化、类型安全、可扩展的全栈开发解决方案，内置用户系统、权限管理、API 路由保护、国际化、代码规范等，适合企业级或个人项目快速起步。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-06-25 - **Last Updated**: 2026-02-22 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README
NovaStack Logo

Nuxt3 TypeScript MySQL TailwindCSS License

# NovaStack 基于 Nuxt3 + Vue 3 + TypeScript + Prisma 的现代化全栈应用框架，提供完整的 RBAC 权限管理、任务调度、文件上传等功能，适合中大型 Web 应用开发。 --- ## 项目简介 NovaStack 是一个企业级的全栈开发解决方案，采用现代化的技术栈，提供开箱即用的用户认证、权限管理、任务调度、文件管理等核心功能。项目遵循代码规范，注重类型安全，支持国际化、主题切换，通过 Docker 容器化部署，适合快速构建企业级应用。 ## 主要功能 ### 核心功能 - 🔐 用户认证系统（注册/登录/JWT令牌管理） - 🛡️ RBAC权限管理（角色/菜单/权限多维度控制） - 👥 多设备登录与会话管理 - 📁 文件上传与管理（支持多种文件类型） - ⏰ 任务调度系统（Cron定时任务） - 📧 邮件发送与验证（基于Nodemailer） - ⚙️ 系统配置管理（动态配置项） - 🌍 国际化支持（中英文） - 🌓 暗色/亮色主题切换 ### 技术特性 - 💎 TypeScript 全栈类型安全 - 🎨 Element Plus UI组件库 - 🎯 Prisma ORM 数据库管理 - 🚀 Redis 缓存支持（可选内置/外部） - 📦 MySQL 数据库持久化 - 📝 ESLint + Prettier 代码规范 - 🐳 Docker 容器化部署 - 🔄 自动化数据库迁移 ## 目录结构 ``` ├── pages/ # 前端页面 │ ├── index.vue # 首页 │ ├── login.vue # 登录页 │ ├── register.vue # 注册页 │ └── admin/ # 管理后台（17个子页面） │ ├── index.vue # 仪表盘 │ ├── users/ # 用户管理 │ ├── roles/ # 角色管理 │ ├── menus/ # 菜单管理 │ ├── tasks/ # 任务调度 │ └── ... ├── components/ # 组件 │ ├── layout/ # 布局组件 │ └── icons/ # 图标组件 ├── composables/ # 可复用逻辑（5个TS文件） │ ├── useAuth.ts # 认证逻辑 │ └── ... ├── server/ # 服务端（78个TS文件） │ ├── api/ # API路由 │ │ ├── admin/ # 管理后台API（21个） │ │ ├── auth/ # 认证API │ │ ├── config/ # 配置API │ │ ├── files/ # 文件API │ │ ├── tasks/ # 任务API（10个） │ │ └── ... │ ├── services/ # 业务服务层 │ │ ├── DbService.ts # 数据库服务 │ │ ├── AuthService.ts # 认证服务 │ │ ├── FileService.ts # 文件服务 │ │ ├── ConfigService.ts # 配置服务 │ │ └── emailSender.ts # 邮件服务 │ ├── utils/ # 工具函数 │ └── plugins/ # 服务端插件 ├── prisma/ # Prisma数据库 │ ├── schema.prisma # 数据模型定义 │ ├── migrations/ # 迁移文件（8个SQL） │ ├── seed.ts # 种子数据 │ └── db/ # 生成的Prisma Client ├── locales/ # 国际化资源（23个文件） ├── assets/ # 静态资源 │ └── css/ # CSS文件 ├── types/ # TypeScript类型定义 ├── layouts/ # 页面布局 ├── public/ # 公共静态资源（78个文件） ├── docs/ # 文档（17个MD文件） ├── scripts/ # 部署与构建脚本 ├── task/ # 任务脚本 ├── logs/ # 日志目录 ├── backups/ # 备份目录 ├── uploads/ # 上传文件目录 ├── redis-data/ # Redis数据目录 ├── nuxt.config.ts # Nuxt配置 ├── package.json # 依赖配置 ├── docker-compose.yml # Docker编排 └── Dockerfile # Docker镜像构建 ``` ## 数据库模型 项目使用 Prisma ORM 管理 MySQL 数据库，包含以下核心模型： ### 用户与权限 - **users** - 用户表（用户信息、邮箱验证、登录状态） - **roles** - 角色表（角色定义、系统角色标识） - **permissions** - 权限表（角色与菜单的权限关联） - **menus** - 菜单表（前端/后端/中控菜单、层级结构） - **user_roles** - 用户角色关联表 - **user_token** - 用户令牌表（多设备登录管理） ### 系统功能 - **task** - 任务表（定时任务配置、执行状态） - **files** - 文件表（上传文件记录、关联用户） - **system_configs** - 系统配置表（分组配置项管理） ## API 路由 ### 认证相关 - `POST /api/auth/register` - 用户注册 - `POST /api/auth/login` - 用户登录 - `POST /api/auth/logout` - 用户登出 - `GET /api/auth/user` - 获取当前用户信息 ### 管理后台API #### 用户管理 - `GET /api/admin/users` - 获取用户列表 - `POST /api/admin/users` - 创建用户 - `PUT /api/admin/users/:id` - 更新用户 - `DELETE /api/admin/users/:id` - 删除用户 #### 角色管理 - `GET /api/admin/roles` - 获取角色列表 - `POST /api/admin/roles` - 创建角色 - `PUT /api/admin/roles/:id` - 更新角色 - `DELETE /api/admin/roles/:id` - 删除角色 - `GET /api/admin/roles/:id/permissions` - 获取角色权限 #### 菜单管理 - `GET /api/admin/menus` - 获取菜单列表 - `POST /api/admin/menus` - 创建菜单 - `PUT /api/admin/menus/:id` - 更新菜单 - `DELETE /api/admin/menus/:id` - 删除菜单 #### 任务管理 - `GET /api/admin/tasks` - 获取任务列表 - `POST /api/admin/tasks` - 创建任务 - `PUT /api/admin/tasks/:id` - 更新任务 - `DELETE /api/admin/tasks/:id` - 删除任务 - `POST /api/admin/tasks/:id/run` - 手动执行任务 - `POST /api/admin/tasks/:id/start` - 启动任务 - `POST /api/admin/tasks/:id/stop` - 停止任务 ### 文件管理 - `POST /api/upload` - 上传文件 - `GET /api/files` - 获取文件列表 - `GET /api/files/:id` - 获取文件详情 - `DELETE /api/files/:id` - 删除文件 ### 配置管理 - `GET /api/config/:group` - 获取配置组 - `PUT /api/config/:group` - 更新配置组 - `GET /api/config/:group/:key` - 获取单个配置 ## 认证与安全 - ✅ 密码加密存储（bcryptjs） - ✅ JWT令牌生成与校验 - ✅ 多设备登录与会话管理 - ✅ 路由中间件保护（鉴权+权限验证） - ✅ 登录失败次数限制 - ✅ 邮箱验证机制 - ✅ RBAC权限控制 ## 管理后台 ### 页面 - `/admin` - 仪表盘（系统概览） - `/admin/users` - 用户管理（CRUD+角色分配） - `/admin/roles` - 角色管理（权限配置） - `/admin/menus` - 菜单管理（树形结构） - `/admin/tasks` - 任务调度（Cron配置） - `/admin/settings` - 系统设置 - `/admin/logs` - 系统日志 ### 权限控制 - 基于角色的访问控制（RBAC） - 菜单级权限过滤 - API操作权限验证 - 系统角色保护 ## 技术栈 ### 前端 - **框架**：Nuxt 3 + Vue 3 - **语言**：TypeScript - **UI库**：Element Plus - **样式**：TailwindCSS + 自定义CSS变量 - **图标**：@nuxt/icon (Lucide, Feather, UI8等) - **动画**：motion-v - **主题**：@nuxtjs/color-mode (暗色/亮色切换) - **国际化**：@nuxtjs/i18n - **图片**：@nuxt/image ### 后端 - **框架**：Nuxt 3 Server API - **ORM**：Prisma 6 - **数据库**：MySQL 8 - **缓存**：Redis (ioredis) - **认证**：JWT (jsonwebtoken) - **加密**：bcryptjs, crypto-js - **邮件**：Nodemailer - **日志**：Winston (带日志轮转) - **任务调度**：node-schedule ### 开发工具 - **包管理**：pnpm - **代码规范**：ESLint + Prettier - **提交规范**：Husky + commitlint + lint-staged - **文档**：VitePress - **类型检查**：TypeScript 5.6 ### 部署 - **容器化**：Docker + Docker Compose - **基础镜像**：node:22-slim (Debian) ## 开发命令 ```bash # 开发 npm run dev # 启动开发服务器（端口8080） npm run build # 构建生产版本 npm run preview # 预览生产构建 # 数据库 npm run migrate:dev # 开发环境迁移 npm run migrate:reset # 重置数据库 npm run migrate:deploy # 生产环境迁移 npm run seed # 生成种子数据 # Prisma npm run prisma:generate # 生成Prisma Client # 代码质量 npm run lint # ESLint检查 npm run lint:fix # ESLint自动修复 npm run format # Prettier格式化 npm run typecheck # TypeScript类型检查 # 文档 npm run docs:dev # 启动文档服务器 npm run docs:build # 构建文档 ``` ## 许可证 MIT --- > 本项目持续迭代中，欢迎关注与参与！ ## 代码规范 1. **代码风格** - 遵循ESLint和Prettier配置 - 使用2个空格缩进 - 单引号字符串 2. **类型安全** - 所有TS文件必须通过类型检查 - 避免使用`any`类型 - 为复杂类型定义接口 3. **文档注释** - 公共API必须包含JSDoc注释 - 遵循[JSDoc指南](./docs/JSDOC_GUIDE.md) - 为复杂逻辑添加注释说明 4. **提交规范** - 提交信息使用中英文描述 - 说明修改内容和原因 - 通过commitlint验证 ## 快速开始 ### 方式一：Docker 部署（推荐） #### 前置要求 - Docker 20.10+ - Docker Compose 2.0+ #### 快速部署 ```bash # 1. 克隆项目 git clone cd nova-stack # 2. 配置环境变量 cp .env.example .env # 编辑 .env 文件，配置数据库、Redis、JWT 等信息 # 3. 使用脚本启动服务 bash scripts/docker-build.sh start ``` #### Docker 脚本命令 项目提供了便捷的 Docker 部署脚本 `scripts/docker-build.sh`，支持以下命令： | 命令 | 说明 | |------|------| | `build` | 构建 Docker 镜像 | | `start` | 启动所有服务（包括应用和Redis） | | `stop` | 停止所有服务 | | `restart` | 重启服务 | | `logs` | 查看所有服务日志 | | `logs [服务]` | 查看指定服务日志（如 `logs app`） | | `init` | 初始化数据库（迁移+种子数据） | | `status` | 查看服务运行状态 | | `clean` | 清理所有容器和数据卷（⚠️ 会删除数据） | | `help` | 显示帮助信息 | **示例：** ```bash # 构建并启动服务 bash scripts/docker-build.sh build bash scripts/docker-build.sh start # 查看服务状态 bash scripts/docker-build.sh status # 查看应用日志 bash scripts/docker-build.sh logs app # 初始化数据库 bash scripts/docker-build.sh init # 重启服务 bash scripts/docker-build.sh restart ``` #### Dockerfile 优化说明 Dockerfile 采用**多阶段构建**（Multi-stage Build），基于 `node:22-slim` 镜像： **构建阶段（builder）**： - 安装所有依赖（包括开发依赖） - 生成 Prisma Client - 构建生产版本 **生产阶段**： - 只安装生产依赖（减少镜像体积） - 只复制构建产物和必要文件 - 最终镜像体积大幅减小 **优化效果**： - 📦 镜像体积减少约 50% - ⚡ 构建时间更快（层缓存优化） - 🔒 生产环境更安全（无开发工具） - 🐧 基于 Debian Slim，兼容性好 #### Docker Compose 配置 `docker-compose.yml` 配置了以下服务： - **app**: NovaStack 应用容器（Node.js 22 Slim + Nuxt 3 + 内置 Redis） - 端口映射: `${APP_PORT:-8080}:8080` - 外部 MySQL 数据库（通过环境变量配置） - **灵活的 Redis 配置**： - **内置 Redis**：设置 `REDIS_HOST=127.0.0.1` 使用容器内 Redis - **外部 Redis**：设置 `REDIS_HOST` 为外部 Redis 地址 - 数据持久化： - Redis 数据：`./redis-data` 挂载到容器 - 应用日志：`./logs` 挂载到容器 - 备份文件：`./backups` 挂载到容器 - 上传文件：`./uploads` 挂载到容器 - 日志轮转: 最多保留 3 个 10MB 的日志文件 #### Redis 配置说明 **使用内置 Redis（默认）**： ```env # .env 或 docker-compose.yml 中 REDIS_HOST=127.0.0.1 REDIS_PORT=6379 REDIS_PASSWORD=your_password REDIS_DB=0 ``` **使用外部 Redis**： ```env # .env 或 docker-compose.yml 中 REDIS_HOST=192.168.1.54 REDIS_PORT=26379 REDIS_PASSWORD=your_password REDIS_DB=0 ``` #### 服务访问 启动成功后，访问 http://localhost:8080 即可使用应用。 ### 方式二：本地开发环境 ### 1. 安装依赖 ```bash npm install ``` ### 2. 环境配置 1. 复制环境变量示例文件： ```bash cp .env.example .env ``` 2. 修改 `.env` 文件中的配置： ```env # 应用配置 APP_TITLE=NovaStack APP_NAMESPACE=nova_stack NODE_ENV=development PORT=8080 HOST=0.0.0.0 # 数据库配置（Prisma格式） DB_URL=mysql://username:password@host:port/database # Redis配置（可选：内置Redis或外部Redis） REDIS_HOST=127.0.0.1 # 使用内置Redis REDIS_PORT=6379 REDIS_PASSWORD=your_redis_password REDIS_DB=0 # 或使用外部Redis： # REDIS_HOST=192.168.1.54 # REDIS_PORT=26379 # JWT配置 JWT_SECRET=your-strong-random-key-at-least-32-characters ``` ### 3. 数据库迁移 运行数据库迁移命令创建必要的表： ```bash # 开发环境 npm run migrate:dev # 重置数据库（删除所有数据） npm run migrate:reset # 生成种子数据（可选） npm run seed ``` ### 4. 启动开发服务器 ```bash npm run dev ``` ### 5. 代码质量检查 ```bash npm run lint # 检查代码规范 npm run format # 格式化代码 npm run typecheck # 类型检查 ``` ## 开发指南 ### 添加新API路由 在 `server/api/` 目录下创建新的API端点，文件名自动映射为路由： ```typescript // server/api/example.get.ts export default defineEventHandler(async event => { return { code: 200, message: "成功", data: { example: "data" }, } }) ``` **路由命名规则**： - `example.get.ts` → GET /api/example - `users/[id].get.ts` → GET /api/users/:id - `admin/users.post.ts` → POST /api/admin/users ### 数据库操作 使用 Prisma Client 进行数据库操作： ```typescript // 在API或Service中使用 import { PrismaClient } from '~/prisma/db' const prisma = new PrismaClient() // 查询 const users = await prisma.users.findMany() // 创建 const user = await prisma.users.create({ data: { username: 'test', email: 'test@example.com', password: 'hash' } }) // 更新 await prisma.users.update({ where: { id: 1 }, data: { status: 2 } }) // 删除 await prisma.users.delete({ where: { id: 1 } }) ``` ### 使用服务层 推荐使用服务层封装业务逻辑： ```typescript // server/services/UserService.ts import { PrismaClient } from '~/prisma/db' const prisma = new PrismaClient() export class UserService { async getUserById(id: number) { return await prisma.users.findUnique({ where: { id }, select: { password: false, ... } // 排除敏感字段 }) } } ``` ### 添加新API 在 `server/api/` 目录下创建新的API端点： ```typescript // server/api/example.get.ts export default defineEventHandler(async event => { return { code: 200, message: "成功", data: { example: "data", }, } }) ``` ### 前端Composables 使用组合式函数复用逻辑： ```typescript // composables/useAuth.ts export const useAuth = () => { const user = useState('user', () => null) const token = useCookie('token') const login = async (email: string, password: string) => { const { data } = await $fetch('/api/auth/login', { method: 'POST', body: { email, password } }) user.value = data.user token.value = data.token } const logout = async () => { await $fetch('/api/auth/logout', { method: 'POST' }) user.value = null token.value = null } return { user, login, logout } } ``` ### 使用组件库 项目集成了 Element Plus 组件库： ```vue ``` ### 国际化使用 ```vue ``` ### 代码文档规范 所有公共API和组件必须包含JSDoc注释： ```typescript /** * 用户服务类 * @class * @description 提供用户相关的业务逻辑操作 */ class UserService { /** * 根据ID获取用户信息 * @param {number} id - 用户ID * @returns {Promise} 用户对象（不包含密码） * @throws {Error} 当用户不存在时抛出错误 * @example * const user = await userService.getUserById(1) */ async getUserById(id: number): Promise { // ... } } ``` 详细规范请参考: [JSDoc指南](./docs/JSDOC_GUIDE.md) ## 项目特色 ### 1. 内置Redis支持 Docker容器内置Redis服务，支持本地开发无依赖启动，也可配置为外部Redis。 ### 2. 完善的RBAC系统 基于角色-菜单-权限的三级权限控制，支持细粒度的API操作权限验证。 ### 3. 任务调度系统 内置Cron任务调度器，支持任务的创建、启动、停止、手动执行和状态监控。 ### 4. 文件管理 完整的文件上传、存储、管理功能，支持文件关联用户。 ### 5. 系统配置 分组化的配置管理系统，支持动态加载和更新系统配置。 ### 6. 邮件验证 支持邮箱验证功能，基于Nodemailer实现。 ### 7. 日志管理 基于Winston的日志系统，支持日志轮转和分类存储。 ## 贡献指南 1. Fork 本项目 2. 创建特性分支 (`git checkout -b feature/AmazingFeature`) 3. 提交更改 (`git commit -m 'feat: Add some AmazingFeature'`) 4. 推送到分支 (`git push origin feature/AmazingFeature`) 5. 提交 Pull Request ## 常见问题 ### Q: 如何切换内置Redis和外部Redis？ A: 在 `.env` 文件中设置 `REDIS_HOST`： - 使用内置Redis：`REDIS_HOST=127.0.0.1` - 使用外部Redis：`REDIS_HOST=your-redis-host` ### Q: 数据库迁移失败怎么办？ A: 检查数据库连接配置，确保数据库存在且用户有权限。可以尝试重置迁移：`npm run migrate:reset` ### Q: 如何重置管理员密码？ A: 运行种子数据会创建默认管理员账号，或直接在数据库中修改用户记录。 ### Q: Docker容器无法连接MySQL？ A: 确保 `.env` 中的 `DB_URL` 使用 `host.docker.internal` 或正确的Docker网络地址。 ## 联系方式 - 作者：2264505396@qq.com - 项目主页：[GitHub](https://gitee.com/shuai_dd/nova-stack/tree/v1.0/)