# mynav

**Repository Path**: yzh_69/mynav

## Basic Information

- **Project Name**: mynav
- **Description**: No description available
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-01-30
- **Last Updated**: 2026-06-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MyNav 导航网站

一个功能完善、高性能的导航网站系统，采用前后端分离架构，包含完整的用户体系、网站管理与审核流程。

## 项目简介

MyNav 是一个现代化的导航网站系统，旨在为用户提供便捷的网站链接管理和分类浏览服务。系统支持用户注册登录、网站链接管理、分类管理、收藏功能、搜索功能、网站收录提交、站内消息通知以及访问统计等核心功能，前端采用 Tailwind CSS + DaisyUI 构建现代化 UI。

### 主要特点

- **完整的前后端分离架构**：后端基于 Spring Boot 3，前端基于 Vue 3 + TypeScript
- **现代化 UI 设计**：基于 Tailwind CSS 4 + DaisyUI 5 的响应式界面
- **丰富的功能模块**：用户管理、分类管理、网站链接管理、搜索、收藏、网站收录、站内消息、统计等
- **高性能设计**：Redis 缓存、Sa-Token Redis 存储、逻辑删除、合理索引
- **完善的权限控制**：基于 Sa-Token 的认证授权机制，支持角色权限分离
- **网站收录流程**：用户提交 → 管理员审核 → 自动创建网站，审核结果通过站内信通知
- **详细的 API 文档**：集成 SpringDoc OpenAPI (Swagger) 接口文档
- **Docker 一键部署**：提供完整的 docker-compose 编排方案

## 技术栈

### 后端技术

| 技术 | 版本 | 用途 |
|------|------|------|
| Spring Boot | 3.2.5 | 基础框架 |
| MyBatis Plus | 3.5.7 | ORM 框架 |
| MySQL | 8.0 | 数据库 |
| Redis | 7.0 | 缓存 & Sa-Token 存储 |
| Sa-Token | 1.39.0 | 认证授权框架 |
| Hutool | 5.8.25 | 工具库 |
| SpringDoc OpenAPI | 2.6.0 | API 文档 |
| Lombok | - | 代码简化 |

### 前端技术

| 技术 | 版本 | 用途 |
|------|------|------|
| Vue.js | 3.5 | 前端框架 |
| TypeScript | 5.9 | 类型系统 |
| Vite | 7.2 | 构建工具 |
| Vue Router | 4.6 | 路由管理 |
| Pinia | 3.0 | 状态管理（持久化） |
| Axios | 1.13 | HTTP 客户端 |
| Tailwind CSS | 4.1 | CSS 框架 |
| DaisyUI | 5.5 | UI 组件库 |
| GSAP | 3.14 | 动画库 |
| Phosphor Icons | 2.2 | 图标库 |
| 天爱验证码 (tianai-captcha) | 1.0 | 行为验证码组件 |

## 功能模块

### 1. 用户管理

- 用户注册/登录（含验证码）
- Sa-Token 认证授权（Redis 存储 Token）
- 用户信息管理（头像上传）
- 密码修改（BCrypt 加密）
- 角色权限控制（USER/ADMIN）

### 2. 分类管理

- 分类增删改查
- 分类树形结构
- 分类排序
- 父/子分类支持

### 3. 网站链接管理

- 网站链接增删改查
- 链接状态管理（待审核/已发布/已下架）
- 推荐网站设置
- 点击量统计
- 分类关联
- Favicon 自动获取

### 4. 搜索功能

- 多条件搜索（名称、描述、标签）
- 分类筛选
- 分页查询
- 热门网站推荐

### 5. 收藏功能

- 添加/取消收藏
- 收藏列表查询
- 收藏状态检查

### 6. 网站收录

- 用户提交网站收录申请
- 管理员审核（通过/拒绝）
- 审核通过自动创建网站
- 拒绝可填写原因
- 审核结果站内信通知

### 7. 站内消息

- 系统通知
- 审核结果通知
- 消息已读/未读管理
- 未读消息计数

### 8. 访问统计

- PV/UV 统计
- 热门网站排行
- 每小时访问趋势
- 仪表盘数据展示

### 9. 公告管理

- 公告发布/编辑/删除
- 公告类型（普通/重要/紧急）
- 公告置顶
- 定时发布（开始/结束时间）

### 10. 系统设置

- 网站名称、Logo、备案号等基本配置
- SEO 关键词/描述配置
- 配置支持缓存（5分钟过期），修改后自动刷新

### 11. 操作日志

- 基于 AOP 切面 + 自定义注解 `@OperLog` 自动记录
- 记录操作模块、业务类型、请求参数、响应结果、耗时、IP 等
- 敏感参数（密码/token 等）自动脱敏
- 支持按用户名、模块、业务类型、状态筛选
- 可定期清理历史日志

### 12. 导入导出

- 网站链接 Excel 导入/导出
- 网站链接 JSON 导入/导出
- 导入支持增量添加和去重

### 13. 管理后台

- 管理仪表盘（数据概览）
- 用户管理
- 网站管理
- 分类管理
- 公告管理
- 网站收录审核
- 站内消息管理
- 系统设置
- 操作日志

### 14. 限流保护

- 基于 Redis + Lua 脚本的分布式限流
- 支持注解式限流配置（`@RateLimit`）
- 限流触发时显示友好提示（含倒计时）
- 适用于验证码、登录等敏感接口

## 项目结构

### 后端结构

```
src/main/java/com/mynav/mynav/
├── annotation/          # 自定义注解（@OperLog 等）
├── aspect/              # AOP 切面（操作日志切面等）
├── common/              # 通用组件
│   ├── constant/        # 常量定义
│   ├── exception/       # 异常处理
│   └── result/          # 返回结果封装
├── config/              # 配置类
│   ├── CurrentUserArgumentResolver  # 当前用户参数解析
│   ├── FileUploadConfig             # 文件上传配置
│   ├── MyBatisPlusConfig            # MyBatis-Plus 配置
│   ├── OpenApiConfig                # OpenAPI 配置
│   ├── RedisConfig                  # Redis 配置
│   ├── SaTokenConfig                # Sa-Token 认证配置
│   ├── SaTokenPermissionConfig      # 权限配置
│   ├── SchedulingConfig             # 定时任务配置
│   ├── StpInterfaceImpl             # 权限/角色接口实现
│   └── WebMvcConfig                 # MVC 配置
├── controller/          # 控制器层
├── dto/                 # 数据传输对象
├── entity/              # 实体类
├── interceptor/         # 拦截器
├── job/                 # 定时任务
├── mapper/              # MyBatis Mapper
├── security/            # 安全相关
│   ├── CurrentUser                  # 当前用户注解
│   ├── CurrentUserInfo              # 当前用户信息
│   └── SaTokenUtil                  # Sa-Token 工具类
├── service/             # 业务逻辑层
├── util/                # 工具类
└── vo/                  # 视图对象

src/main/resources/
├── db/                  # 数据库脚本
│   └── schema.sql       # 完整建表及初始数据
├── mapper/              # MyBatis XML
└── application.yml      # 配置文件
```

### 前端结构

```
mynav-frontend/
├── public/              # 静态资源
├── src/
│   ├── assets/          # 资源文件
│   ├── components/      # 组件
│   │   ├── common/      # 通用组件
│   │   ├── layout/      # 布局组件
│   │   └── navigation/  # 导航相关组件
│   ├── layouts/         # 页面布局
│   ├── router/          # 路由配置
│   ├── services/        # API 服务
│   │   ├── api.ts             # Axios 基础配置
│   │   ├── auth.ts            # 认证 API
│   │   ├── user.ts            # 用户 API
│   │   ├── category.ts        # 分类 API
│   │   ├── website.ts         # 网站 API
│   │   ├── favorite.ts        # 收藏 API
│   │   ├── announcement.ts    # 公告 API
│   │   ├── statistics.ts      # 统计 API
│   │   ├── message.ts         # 消息 API
│   │   ├── websiteSubmission.ts # 网站收录 API
│   │   ├── avatar.ts          # 头像 API
│   │   ├── favicon.ts         # 图标 API
│   │   ├── systemConfig.ts    # 系统设置 API
│   │   └── operLog.ts         # 操作日志 API
│   ├── stores/          # 状态管理
│   ├── types/           # 类型定义
│   ├── utils/           # 工具函数
│   ├── views/           # 页面视图
│   │   ├── admin/       # 管理后台页面
│   │   ├── auth/        # 认证页面
│   │   ├── error/       # 错误页面
│   │   ├── home/        # 首页相关页面
│   │   └── user/        # 用户页面
│   ├── App.vue          # 根组件
│   ├── main.ts          # 入口文件
│   └── style.css        # 全局样式
├── package.json         # 项目配置
├── tsconfig.json        # TypeScript 配置
└── vite.config.ts       # Vite 配置
```

## 快速开始

### 环境要求

- **后端**：JDK 17+, MySQL 8.0+, Redis 7.0+, Maven 3.6+
- **前端**：Node.js 18+, npm 8+

### 后端启动步骤

1. **创建数据库**

```sql
CREATE DATABASE mynav CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

2. **导入初始数据**

执行 `src/main/resources/db/schema.sql` 完成建表和初始数据导入。

3. **配置数据库连接**

修改 `src/main/resources/application.yml` 中的数据库配置（或通过环境变量覆盖）：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mynav?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai
    username: root
    password: your_password
```

4. **配置 Redis**

```yaml
spring:
  data:
    redis:
      host: localhost
      port: 6379
      password:
```

5. **启动后端服务**

```bash
# 克隆项目
git clone https://gitee.com/yzh_69/mynav.git

# 进入项目目录
cd mynav

# 编译运行
./mvnw spring-boot:run

# 或使用 Maven
mvn spring-boot:run
```

6. **访问 API 文档**

启动后访问：http://localhost:8080/swagger-ui.html

### 前端启动步骤

1. **进入前端目录**

```bash
cd mynav-frontend
```

2. **安装依赖**

```bash
npm install
```

3. **配置环境变量**

修改 `.env` 文件中的 API 地址：

```
VITE_API_BASE_URL=http://localhost:8080/api
```

4. **启动前端服务**

```bash
npm run dev
```

5. **访问前端页面**

启动后访问：http://localhost:5173

### Docker 部署

使用 docker-compose 一键部署（包含 MySQL、Redis、后端、前端）：

1. **配置环境变量**

创建 `.env` 文件：

```env
# 端口配置
FRONTEND_PORT=80
BACKEND_PORT=8080
MYSQL_PORT=3306
REDIS_PORT=6379

# 数据库配置
MYSQL_ROOT_PASSWORD=your_root_password
MYSQL_DATABASE=mynav
MYSQL_USER=mynav
MYSQL_PASSWORD=your_password
SPRING_DATASOURCE_URL=jdbc:mysql://mysql:3306/mynav?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai
SPRING_DATASOURCE_USERNAME=mynav
SPRING_DATASOURCE_PASSWORD=your_password

# Redis 配置
SPRING_REDIS_HOST=redis
SPRING_REDIS_PORT=6379
SPRING_REDIS_PASSWORD=
```

2. **启动服务**

```bash
docker-compose up -d
```

## API 接口

### 认证接口

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | /api/auth/register | 用户注册 |
| POST | /api/auth/login | 用户登录 |
| POST | /api/auth/logout | 用户登出 |

### 验证码接口

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/captcha/gen | 生成行为验证码（滑块） |
| POST | /api/captcha/check | 验证行为验证码 |
| GET | /api/captcha/types | 获取支持的验证码类型 |

### 用户接口

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/users/me | 获取当前用户信息 |
| PUT | /api/users/me | 更新当前用户信息 |
| PUT | /api/users/me/password | 修改密码 |
| POST | /api/users/me/avatar | 上传头像 |

### 分类接口

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/categories | 获取所有分类 |
| GET | /api/categories/tree | 获取分类树 |
| POST | /api/categories | 创建分类（管理员） |
| PUT | /api/categories/{id} | 更新分类（管理员） |
| DELETE | /api/categories/{id} | 删除分类（管理员） |

### 网站接口

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/websites | 搜索网站 |
| GET | /api/websites/featured | 获取推荐网站 |
| GET | /api/websites/category/{categoryId} | 根据分类获取网站 |
| GET | /api/websites/{id} | 获取网站详情 |
| POST | /api/websites/{id}/visit | 访问网站 |
| POST | /api/websites | 创建网站（管理员） |
| PUT | /api/websites/{id} | 更新网站（管理员） |
| DELETE | /api/websites/{id} | 删除网站（管理员） |

### 收藏接口

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/favorites | 获取收藏列表 |
| POST | /api/favorites/{websiteId} | 添加收藏 |
| DELETE | /api/favorites/{websiteId} | 取消收藏 |
| GET | /api/favorites/{websiteId}/check | 检查是否已收藏 |

### 网站收录接口

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | /api/website-submissions | 提交网站收录 |
| GET | /api/website-submissions | 获取我的提交记录 |
| GET | /api/website-submissions/pending | 获取待审核列表（管理员） |
| PUT | /api/website-submissions/{id}/approve | 审核通过（管理员） |
| PUT | /api/website-submissions/{id}/reject | 审核拒绝（管理员） |

### 站内消息接口

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/messages | 获取消息列表 |
| GET | /api/messages/unread-count | 获取未读消息数 |
| PUT | /api/messages/{id}/read | 标记消息已读 |
| PUT | /api/messages/read-all | 全部标记已读 |

### 统计接口

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/statistics/dashboard | 获取仪表盘统计 |
| GET | /api/statistics/today/pv | 获取今日 PV |
| GET | /api/statistics/today/uv | 获取今日 UV |
| GET | /api/statistics/today/hot | 获取今日热门网站 |

### 公告接口

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/announcements | 获取公告列表 |
| POST | /api/announcements | 创建公告（管理员） |
| PUT | /api/announcements/{id} | 更新公告（管理员） |
| DELETE | /api/announcements/{id} | 删除公告（管理员） |

### 图标接口

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/favicon | 获取网站 Favicon |

### 系统设置接口

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/system-config/public | 获取公开配置 |
| GET | /api/system-config/list | 获取所有配置（管理员） |
| GET | /api/system-config/group/{group} | 按分组获取配置（管理员） |
| PUT | /api/system-config/batch | 批量更新配置（管理员） |

### 操作日志接口

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/oper-logs/page | 分页查询操作日志（管理员） |
| DELETE | /api/oper-logs/clean | 清理历史操作日志（管理员） |

### 导入导出接口

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | /api/websites/import/excel | Excel 导入网站（管理员） |
| GET | /api/websites/export/excel | Excel 导出网站（管理员） |
| POST | /api/websites/import/json | JSON 导入网站（管理员） |
| GET | /api/websites/export/json | JSON 导出网站（管理员） |

### 头像接口

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/avatar/{filename} | 获取头像文件 |

## 数据库设计

| 表名 | 说明 |
|------|------|
| t_user | 用户表 |
| t_category | 分类表 |
| t_website | 网站链接表 |
| t_favorite | 收藏表 |
| t_visit_log | 访问日志表 |
| t_statistics_daily | 每日统计表 |
| t_announcement | 公告表 |
| t_website_submission | 网站收录提交表 |
| t_user_message | 用户消息表（站内信） |
| t_oper_log | 操作日志表 |
| t_system_config | 系统配置表 |

所有表均支持逻辑删除（`deleted` 字段）。

## 默认账号

- **管理员账号**: `admin`
- **管理员密码**: `admin123`

## 性能优化

### 缓存策略

- Redis 缓存热点数据
- Sa-Token 会话存储于 Redis（alone-redis）
- 分类数据缓存
- 统计数据缓存

### 安全防护

- Sa-Token 认证授权（Bearer Token + Redis 存储）
- BCrypt 密码加密
- 接口权限控制（角色/权限分离）
- 验证码服务
- SQL 注入防护（MyBatis 参数化查询）
- XSS 防护
- 文件上传限制（单文件 10MB，请求 100MB）

### 数据库优化

- 合理的索引设计
- MyBatis Plus 分页插件
- 逻辑删除（避免物理删除导致的数据丢失）
- 全文索引（网站名称/描述/标签）

## 部署

### 后端部署

```bash
# 打包
mvn clean package -DskipTests

# 运行
java -jar target/mynav-0.0.1-SNAPSHOT.jar
```

### 前端部署

```bash
# 打包
npm run build

# 部署 dist 目录到静态文件服务器
```

### Docker 部署

```bash
# 一键启动所有服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down
```

## 开发指南

### 后端开发

1. 遵循 Spring Boot 开发规范
2. 使用 MyBatis Plus 进行数据库操作
3. 接口返回统一的 Result 格式
4. 异常处理使用 GlobalExceptionHandler
5. 使用 `@CurrentUser` 注解获取当前登录用户信息

### 前端开发

1. 遵循 Vue 3 组合式 API 规范
2. 使用 TypeScript 进行类型定义
3. 组件命名使用 PascalCase 规范
4. API 调用使用 services 目录下的服务
5. 使用 Pinia 进行状态管理（支持持久化）

## 许可证

本项目采用 **木兰宽松许可证，第 2 版** 开源协议。

## 贡献

欢迎各位开发者贡献代码，提交 Issue 和 Pull Request。

## 联系方式

- 项目地址: https://gitee.com/yzh_69/mynav
- 如有问题，请在 Gitee 上提交 Issue

---

**感谢使用 MyNav 导航网站系统！**