182 lines
7.9 KiB
Markdown
182 lines
7.9 KiB
Markdown
# Skins 业务后端
|
||
|
||
|
||
基于 **若依（RuoYi）4.8.2** 扩展的多模块 Java 后端，集成 CSGO/饰品相关业务（用户、玩法、第三方支付与回调、定时任务、推广后台等）。仓库同时包含两套管理端前端工程。
|
||
|
||
克隆后请在项目根目录执行 `mvn -v` 确认 JDK 21 与 Maven 可用，再按下文完成数据库与中间件初始化。
|
||
|
||
---
|
||
|
||
## 技术栈概览
|
||
|
||
| 层级 | 技术 |
|
||
|------|------|
|
||
| 运行时 | Java **21** |
|
||
| 框架 | Spring Boot **4.0.3**（启用虚拟线程 `spring.threads.virtual.enabled`） |
|
||
| Web 与安全 | **Spring Security 6**（无状态会话）、JWT（`Authorization` 请求头）、若依式菜单/权限模型 |
|
||
| 持久层 | MyBatis / MyBatis-Plus、PageHelper、Druid（含多数据源扩展） |
|
||
| 数据库 | MySQL |
|
||
| 缓存 | Redis（Spring Data Redis + Lettuce） |
|
||
| 消息 | RabbitMQ（业务侧配置虚拟主机等，详见各 profile） |
|
||
| 实时 | WebSocket（如 `/ws/**` 等路径，与安全放行配置保持一致） |
|
||
| API 文档 | **Springfox 3.x**（主用，Swagger / OAS3 分组）；另引入 **springdoc-openapi** Starter，可与 Springfox 并行存在 |
|
||
|
||
---
|
||
|
||
## 仓库结构
|
||
|
||
```
|
||
chengdu-backend/
|
||
├── ruoyi-admin/ # Web 入口（Spring Boot 启动模块）
|
||
├── ruoyi-framework/ # 安全、过滤器、资源配置等封装
|
||
├── ruoyi-system/ # 系统管理（用户、角色、菜单等）
|
||
├── ruoyi-common/ # 通用工具、常量、MQ 配置等
|
||
├── ruoyi-quartz/ # 定时任务（若依 Quartz 集成）
|
||
├── ruoyi-generator/ # 代码生成
|
||
├── skins-model/ # 业务领域模型（实体等）
|
||
├── skins-service/ # 业务服务聚合 POM（子模块见下）
|
||
│ ├── service-admin/ # 运营管理侧接口
|
||
│ ├── service-user/ # 用户侧接口
|
||
│ ├── service-playingmethod/ # 玩法相关
|
||
│ ├── service-thirdparty/ # 第三方对接
|
||
│ └── service-task/ # 任务与调度配合
|
||
├── skins-promo/ # 推广后台 API（路径前缀多为 /promo）
|
||
├── ruoyi-ui/ # 管理端 Vue2 + Element UI（若依经典前端）
|
||
├── promo-ui2/ # 推广/运营后台 Vue3 + Element Plus + Vite
|
||
└── docker/ # MySQL / Redis / RabbitMQ 编排
|
||
```
|
||
|
||
### 启动类
|
||
|
||
后端入口：`ruoyi-admin` 模块中的 `com.ruoyi.RuoYiApplication`。使用 `@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class })` 排除 Spring Boot 默认数据源自动配置（Spring Boot 4 下为 `org.springframework.boot.jdbc.autoconfigure.DataSourceAutoConfiguration`），由若依多数据源与 Druid 配置接管。
|
||
|
||
---
|
||
|
||
## 运行环境与配置
|
||
|
||
### 必备依赖
|
||
|
||
- JDK **21**
|
||
- Maven **3.6+**
|
||
- MySQL **8.x**（库名与账号见各 profile；本地可参考 `docker/docker-compose.yml`）
|
||
- Redis
|
||
- RabbitMQ（若启用了 MQ 监听或相关消费者则需可用）
|
||
|
||
根 `pom.xml` 已配置 **阿里云 Maven 公共仓库**，便于国内环境拉取依赖。
|
||
|
||
### Spring Profile
|
||
|
||
`ruoyi-admin/src/main/resources/application.yml` 中通过 `spring.profiles.active` 切换环境，配套文件：
|
||
|
||
- `application-dev.yml` — 本地/开发
|
||
- `application-test.yml` — 测试
|
||
- `application-pro.yml` — 生产
|
||
|
||
**重要：** 上述 profile 文件中常含数据库口令、第三方支付与短信密钥等敏感信息。**勿将真实密钥提交到公开仓库**；上线请改用环境变量、密钥管理系统或独立于仓库的配置挂载。
|
||
|
||
### 默认服务端口与上下文
|
||
|
||
- HTTP 端口：**28081**（见根配置 `ruoyi-admin/src/main/resources/application.yml` 中的 `server.port`；各环境可被 profile 或部署参数覆盖，默认绑定 `0.0.0.0`）
|
||
- 上下文路径：`/`（与管理端、`VUE_APP_BASE_API` 及反向代理前缀需一致）
|
||
|
||
### 对外匿名接口（简述）
|
||
|
||
与安全配置对齐的常见分类包括：`/login`、`/register`、`/captchaImage`，以及业务侧的 `/api/**`、`/admin/**`、WebSocket、部分 Swagger 与 Druid 监控路径等。具体请以 `ruoyi-framework` 中 **SecurityFilterChain** 与白名单配置为准。
|
||
|
||
---
|
||
|
||
## 本地启动后端
|
||
|
||
**方式一：先打包再在启动模块运行**
|
||
|
||
在项目根目录执行：
|
||
|
||
```bash
|
||
mvn clean package -DskipTests
|
||
cd ruoyi-admin
|
||
mvn spring-boot:run
|
||
```
|
||
|
||
**方式二：根目录一键拉起（会解析 `ruoyi-admin` 所需模块依赖）**
|
||
|
||
```bash
|
||
mvn -pl ruoyi-admin -am spring-boot:run -DskipTests
|
||
```
|
||
|
||
也可在 IDE 中直接运行 `RuoYiApplication`。
|
||
|
||
首次运行前请：
|
||
|
||
1. 创建 MySQL 库并完成若依及业务所需的 SQL 初始化（以团队提供的脚本为准）。
|
||
2. 按所选 profile 修改数据源、Redis、RabbitMQ 等连接信息。
|
||
|
||
---
|
||
|
||
## Docker 基础设施
|
||
|
||
目录：`docker/`
|
||
|
||
- `docker-compose.yml`：MySQL（含自定义镜像）、Redis、RabbitMQ（管理端口及初始化示例）。
|
||
- `docker/docker-cn/`：面向大陆镜像拉取环境的编排变体。
|
||
|
||
常用操作见 **`docker/readme.md`**（如单独重建某个服务等）。
|
||
|
||
---
|
||
|
||
## 前端工程
|
||
|
||
### ruoyi-ui（Vue 2）
|
||
|
||
- 技术栈：Vue CLI、Element UI（`package.json` 声明 Node `>=8.9`，实际开发建议 Node **16 LTS** 或 **18 LTS**，并按需开启 OpenSSL 兼容）。
|
||
- 脚本见 `ruoyi-ui/package.json`（Windows 脚本含 `set NODE_OPTIONS=--openssl-legacy-provider`；在 macOS/Linux 上需 `export NODE_OPTIONS=...` 或使用等价脚本）。
|
||
- 开发与打包：`npm run dev`、`npm run build:prod` 等。
|
||
- 系统工具内「Swagger」页当前 iframe 指向 **`/doc.html`**；若后端未部署对应聚合页，请改为与下文 **API 文档** 中实际地址一致（例如 `/swagger-ui.html`）。
|
||
|
||
### promo-ui2（Vue 3）
|
||
|
||
- 技术栈：Vue 3、Vite、TypeScript、Element Plus（基于 vue-element-plus-admin 演进）；要求 **Node ≥ 18**、`pnpm ≥ 8.1`（以 `promo-ui2/package.json` 中 `engines` 为准）。
|
||
- 推荐使用 **pnpm**：`pnpm install`、`pnpm dev`、`pnpm build:pro` 等。
|
||
- 详细说明见 `promo-ui2/README.zh-CN.md`。
|
||
|
||
前端请求的接口基地址需指向本后端；若经 Nginx 网关，注意与团队约定的前缀（如 `/prod-api`）一致。
|
||
|
||
---
|
||
|
||
## 业务模块说明（简述）
|
||
|
||
| 模块 | 职责 |
|
||
|------|------|
|
||
| **skins-model** | 共享实体与领域常量 |
|
||
| **service-user** | 用户相关业务 |
|
||
| **service-admin** | 运营管理侧业务 |
|
||
| **service-playingmethod** | 玩法相关逻辑 |
|
||
| **service-thirdparty** | 第三方对接（支付、交易平台回调等，密钥在各 profile 中） |
|
||
| **service-task** | 异步任务 / 与 Quartz 等协同 |
|
||
| **skins-promo** | 推广后台：登录注册、流水与佣金、充值卡等（REST 前缀示例：`/promo`） |
|
||
|
||
---
|
||
|
||
## API 文档
|
||
|
||
- **Springfox（当前主要使用）**：启动后访问（端口与 `server.port` 一致，仓库默认 **28081**）
|
||
`http://localhost:28081/swagger-ui.html`
|
||
在页面右上角切换分组（如 `user`、`thirdParty`、`playingMethod`、`task`、`promo` 等；与 `SwaggerConfig` 中 Docket 一致）。OpenAPI JSON 路径形如 `/<group>/api-docs`（Spring Security 已对 `/*/api-docs` 等放行，以实际配置为准）。
|
||
- **springdoc-openapi**：`ruoyi-admin` 已引入依赖；若单独启用 SpringDoc UI，需确保 **Security** 对 `/swagger-ui/**`、`/v3/api-docs` 等路径放行，避免 401。
|
||
|
||
---
|
||
|
||
## 版本信息
|
||
|
||
- 父 POM：`com.ruoyi:ruoyi:4.8.2`（`spring-boot.version` **4.0.3**，`springdoc.version` **3.0.2**，`swagger` / Springfox **3.0.0**）
|
||
- 若依官网参考：<http://www.ruoyi.vip>
|
||
|
||
---
|
||
|
||
## 安全建议
|
||
|
||
1. 轮换并私有化所有第三方（支付宝、聚合支付、短信等）密钥；生产环境勿使用仓库内示例明文。
|
||
2. 修改 JWT `token.secret` 与 Druid 监控口令等非默认值。
|
||
3. 按需收紧 Druid、`/actuator`（若启用）及 Swagger 相关路径的访问范围。
|
||
|
||
如有与本说明不一致之处，以当前仓库代码及团队部署文档为准。
|