# 琥歌瑞 Hugray

琥歌瑞（Hugray）是一个多端业务平台，采用「一后端 + 三前端」的单体仓库（Monorepo）管理，后端为 Spring Cloud 微服务架构。

## 目录结构

```
Hugray/
├── hugray-server/          Java 微服务后端（网关 / 认证 / 系统 / 文件 / 任务 / 生成 / 监控）
├── hugray-admin/           管理后台前端（Web 端，供运营与管理人员使用）
├── hugray-user-miniapp/    用户小程序（面向 C 端用户）
├── hugray-partner-miniapp/ 服务商小程序（面向服务商 / 入驻方）
├── LICENSE
└── README.md
```

## 各端简介

| 端 | 目录 | 技术栈 | 说明 |
| --- | --- | --- | --- |
| 管理后台 | [hugray-admin](file:///d:/work/Hugray/hugray-admin) | Vue 3.5 + Vite 6 + Element Plus 2.13 + Pinia + Vue Router 4 | 浏览器访问的运营管理后台 |
| 用户小程序 | [hugray-user-miniapp](file:///d:/work/Hugray/hugray-user-miniapp) | uni-app（Vue 3） | 可编译到微信 / 支付宝 / 百度 / 抖音等小程序 |
| 服务商小程序 | [hugray-partner-miniapp](file:///d:/work/Hugray/hugray-partner-miniapp) | uni-app（Vue 3） | 面向服务商 / 入驻方的小程序 |
| 后端服务 | [hugray-server](file:///d:/work/Hugray/hugray-server) | Java 17 + Spring Cloud 微服务 | 统一为三个端提供接口 |

## 后端 hugray-server

### 技术栈

| 分类 | 技术 | 版本 |
| --- | --- | --- |
| 运行环境 | Java | 17 |
| 基础框架 | Spring Boot | 4.1.0 |
| 微服务框架 | Spring Cloud | 2025.1.2 |
| 微服务框架 | Spring Cloud Alibaba | 2025.1.0.0 |
| 注册 / 配置中心 | Nacos | 3.0.2 |
| 流量防护 | Sentinel | 随 Spring Cloud Alibaba |
| 监控 | Spring Boot Admin | 4.1.2 |
| 持久层 | MyBatis + PageHelper + Druid | - |
| 数据库 | MySQL | 5.7+ |
| 缓存 | Redis | - |
| 认证 | JWT | 0.9.1 |
| 接口文档 | SpringDoc OpenAPI | 3.1.0 |
| 对象存储 | MinIO | 8.2.2 |

### 服务模块与端口

| 模块 | 目录 | 说明 | 端口 |
| --- | --- | --- | --- |
| 网关 | `ruoyi-gateway` | 统一入口、路由转发、鉴权与限流 | 8080 |
| 认证服务 | `ruoyi-auth` | 登录、注册、令牌签发 | 9200 |
| 系统服务 | `ruoyi-modules/ruoyi-system` | 用户 / 角色 / 菜单 / 部门 / 字典 / 日志等 | 9201 |
| 代码生成 | `ruoyi-modules/ruoyi-gen` | 前后端代码一键生成 | 9202 |
| 定时任务 | `ruoyi-modules/ruoyi-job` | Quartz 任务调度 | 9203 |
| 文件服务 | `ruoyi-modules/ruoyi-file` | 本地 / MinIO 文件上传下载 | 9300 |
| 监控服务 | `ruoyi-visual/ruoyi-monitor` | Spring Boot Admin 服务监控 | 9100 |

### 公共依赖模块

- `ruoyi-common-core`：核心工具与公共模型
- `ruoyi-common-security`：鉴权与安全
- `ruoyi-common-redis`：缓存服务
- `ruoyi-common-datasource`：多数据源
- `ruoyi-common-datascope`：数据权限
- `ruoyi-common-sensitive`：数据脱敏
- `ruoyi-common-log`：操作日志
- `ruoyi-common-seata`：分布式事务
- `ruoyi-common-swagger`：接口文档
- `ruoyi-api/ruoyi-api-system`：系统服务对外接口定义

### docker 与部署脚本

- `docker/`：Nacos、MySQL、Redis、Nginx 及各服务的容器化配置，编排文件为 `docker/docker-compose.yml`
- `docker/deploy.sh`、`docker/copy.sh`：一键部署与拷贝脚本
- `bin/`：各服务的本地启动脚本（`run-gateway.bat`、`run-auth.bat`、`run-modules-*.bat`、`run-monitor.bat`）
- `sql/`：初始化脚本
    - `ry_20260417.sql`：业务库（`ry-cloud`）
    - `ry_config_20260918.sql`：Nacos 配置库
    - `quartz.sql`：定时任务表
    - `ry_seata_20210128.sql`：Seata 事务表

## 环境要求

| 组件 | 版本要求 |
| --- | --- |
| JDK | 17+ |
| Maven | 3.8+ |
| Node.js | 18+（建议 20 LTS） |
| MySQL | 5.7+ |
| Redis | 5.0+ |
| Nacos | 3.x（8848） |
| Docker | 可选，用于一键启动中间件 |

## 快速开始

### 1. 启动中间件

推荐使用 Docker 一键启动 Nacos、MySQL、Redis、Nginx：

```bash
cd hugray-server/docker
docker-compose up -d
```

也可自行安装上述组件，默认连接地址均为 `127.0.0.1`。

### 2. 初始化数据库与配置

1. 创建业务库 `ry-cloud`，执行 `hugray-server/sql/ry_20260417.sql`、`quartz.sql`；
2. 在 Nacos 配置库中执行 `hugray-server/sql/ry_config_20260918.sql`，导入各服务的配置；
3. 如有分布式事务需求，执行 `hugray-server/sql/ry_seata_20210128.sql`。

### 3. 启动后端

先启动 Nacos，再按依赖顺序启动各服务（也可直接运行 `hugray-server/bin/` 下的脚本）：

```
ruoyi-gateway → ruoyi-auth → ruoyi-modules/ruoyi-system → ... → ruoyi-visual/ruoyi-monitor
```

### 4. 启动管理后台前端

```bash
cd hugray-admin
npm install
npm run dev        # 开发环境，默认 http://localhost:80
npm run build:prod # 生产打包，产物在 dist/
```

### 5. 启动小程序

用 HBuilderX 打开 `hugray-user-miniapp` 或 `hugray-partner-miniapp`，运行到对应小程序平台（微信小程序需先在 `manifest.json` 中配置 AppID）。

## 端口一览

| 服务 | 端口 |
| --- | --- |
| 管理后台前端（开发） | 80 |
| 网关 ruoyi-gateway | 8080 |
| 认证 ruoyi-auth | 9200 |
| 系统 ruoyi-system | 9201 |
| 代码生成 ruoyi-gen | 9202 |
| 定时任务 ruoyi-job | 9203 |
| 文件服务 ruoyi-file | 9300 |
| 监控 ruoyi-monitor | 9100 |
| Nacos | 8848 / 9848 / 9849 |
| Sentinel 控制台 | 8718 |
| MySQL | 3306 |
| Redis | 6379 |
| Nginx | 80 |

> 说明：管理后台开发端口（80）与容器 Nginx（80）不冲突，生产环境前端产物由 Nginx 托管。

## 开源说明

后端基于开源项目 [RuoYi-Cloud](https://gitee.com/y_project/RuoYi-Cloud)（v3.6.8）二次开发，遵循其原始开源协议（MIT）；使用时请保留原作者版权声明。