186 lines
8.6 KiB
Markdown
186 lines
8.6 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 / springdoc，仓库内无 Swagger UI 与 OpenAPI 端点） |
|
||
|
||
---
|
||
|
||
## 仓库结构
|
||
|
||
```
|
||
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、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 页已随接口文档一并删除（`views/tool/swagger/index.vue`），若侧边栏仍有该菜单，执行 `DELETE FROM sys_menu WHERE component = 'tool/swagger/index';` 后重新登录。
|
||
|
||
### 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（`springfox-boot-starter`）、springdoc-openapi 依赖、`SwaggerConfig` 与源码中的 `@Api` / `@ApiOperation` / `@ApiModelProperty` 等注解，`SecurityConfig` 与 `ResourcesConfig` 里对应的放行与静态映射也已去掉。
|
||
- 因此 `/swagger-ui.html`、`/v3/api-docs`、`/*/api-docs`、`/doc.html` 均不再对外提供服务（未认证访问会直接落到 401）。
|
||
|
||
---
|
||
|
||
## 版本信息
|
||
|
||
- 父 POM：`com.ruoyi:ruoyi:4.8.2`（`spring-boot.version` **4.0.3**）
|
||
- 若依官网参考：<http://www.ruoyi.vip>
|
||
|
||
---
|
||
|
||
## 安全建议
|
||
|
||
1. 轮换并私有化所有第三方（支付宝、聚合支付、短信等）密钥；生产环境勿使用仓库内示例明文。
|
||
2. 修改 JWT `token.secret` 等非默认值。
|
||
3. Druid 监控台：生产已关闭（`application-pro.yml` 的 `statViewServlet.enabled=false`，`/druid/**` 是匿名放行的，开着等于把全部 SQL 与连接信息暴露到公网）；
|
||
开发环境已限制 `allow: 127.0.0.1` 并改用非默认口令。临时排障如需开启，务必保持白名单 + 改口令，用完立即关回。
|
||
4. **三端 token 互不通用**（游戏管理后台 / 推广后台 / 玩家端）：三个端共用同一套 JWT 与会话存储，
|
||
靠 `LoginUser.loginScope`（`admin` / `promo` / `player`）区分，判定在 `ruoyi-framework` 的 `SecurityConfig`：
|
||
`/admin|/system|/monitor|/tool|/test` 只认后台账号、`/promo/**` 只认推广端签发的 token、`/api/**` 只认玩家端签发的 token。
|
||
标记由 `ApiUserDetailsServiceImpl` 按登录账号前缀（`api_` / `promo_` / `promo_user_` / 无前缀）写入，随会话缓存在 Redis。
|
||
**注意**：升级到该版本后，不带端标记的旧 token 会被拒绝，推广后台与玩家端需要重新登录一次（后台账号不受影响）。
|
||
|
||
如有与本说明不一致之处，以当前仓库代码及团队部署文档为准。
|