# bytech-cloud

**Repository Path**: ningbo-boyu/bytech-cloud

## Basic Information

- **Project Name**: bytech-cloud
- **Description**: No description available
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-23
- **Last Updated**: 2026-07-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# javatech-cloud

基于 Spring Cloud 微服务架构的 **SaaS 多租户平台**，支持微服务 / 单体一键切换部署。

<br>

## 核心功能

| 功能 | 说明 |
|------|------|
| **双系统登录切换** | 平台管理员 + 租户用户两套身份体系，前端任意切换互不冲突 |
| **多租户数据隔离** | 基于 MySQL Schema（`USE database`）的轻量级隔离，每个租户独立库 |
| **微服务/单体双模式** | `monolith` Profile 一键聚合，单体模式下 Feign 接口零网络开销 |
| **RBAC 权限模型** | 平台/租户两套 RBAC 体系，`@PreAuth` 方法级权限 + 前端路由守卫 |
| **操作审计日志** | 等保三级合规的 `@OperLog` + `@DataChangeLog` + HTTP 访问日志 |
| **文件服务** | 文件上传下载 / OSS 适配 / 断点续传 |
| **IP 黑名单** | 支持 API / Gateway 两级拦截 |
| **代码生成器** | MyBatis-Plus 代码生成，一键生成 Controller/Service/Mapper/Entity |

<br>

## 技术选型

| 类别 | 技术 | 版本 |
|------|------|------|
| 基础框架 | Spring Boot + Spring Cloud + Spring Cloud Alibaba | 3.2.5 / 2023.0.1 |
| 注册/配置 | Nacos | 2.3.2 |
| 网关 | Spring Cloud Gateway (WebFlux) | 4.1.x |
| 数据库 | MySQL | 8.0 |
| 连接池 | Druid | 1.2.20 |
| ORM | MyBatis-Plus + dynamic-datasource | 3.5.5 / 4.2.0 |
| 安全认证 | Sa-Token（双 StpLogic）+ JWT | 1.37.0 |
| 远程调用 | OpenFeign + LoadBalancer | 4.1.1 |
| 缓存 | Redis + Redisson | 7.x |
| API 文档 | Knife4j (OpenAPI 3.0) | 4.4.0 |
| 对象转换 | MapStruct | 1.5.5 |
| 工具库 | Hutool | 5.8.24 |
| IP 定位 | ip2region（离线） | 3.3.7 |
| Java | JDK 17 | - |

<br>

## 模块结构

```
javatech-cloud
├── bytech-common                    公共模块聚合
│   ├── bytech-common-core           核心：R<T>、异常、常量、TenantContextHolder
│   ├── bytech-common-security-core  安全核心：白名单、IP黑名单（无 Web 依赖）
│   ├── bytech-common-security       安全：@PreAuth、LoginUser、Sa-Token 双 StpLogic
│   ├── bytech-common-log            日志：@OperLog / @DataChangeLog / 访问日志
│   ├── bytech-common-web            Web：全局异常处理、Jackson、Knife4j
│   ├── bytech-common-redis          Redis：序列化、缓存、分布式锁
│   ├── bytech-common-mybatis        MyBatis：分页、自动填充、动态数据源、Druid
│   └── bytech-common-tenant         多租户：Schema 拦截器、Header 提取、Feign 透传
├── bytech-feign-api                  Feign API 聚合
│   ├── bytech-feign-api-system      系统服务 API
│   └── bytech-feign-api-platform    平台服务 API
├── bytech-gateway                    Spring Cloud Gateway 网关
├── bytech-auth                      认证服务（登录/登出/权限加载）
├── bytech-modules                   业务模块聚合
│   ├── bytech-system                租户系统（用户/角色/菜单/部门/字典/日志/配置）
│   ├── bytech-platform              平台管理（租户CRUD/套餐/平台RBAC）
│   └── bytech-file                  文件服务（上传下载/OSS/断点续传）
└── bytech-boot                      单体启动聚合模块
```

<br>

## 双系统登录切换

平台管理员和租户用户拥有**完全独立的身份体系**，共享同一前端、同时在线、自由切换。

```
┌─────────────────────────────────────────────────────┐
│  平台管理员 (loginType="platform")                    │
│  路径: /platform/*     StpLogic: platformStpLogic     │
│  Token Redis Key:  platform:token:xxx                │
│  数据库: bytech_platform （全局唯一）                  │
├─────────────────────────────────────────────────────┤
│  租户用户 (loginType="auth")                         │
│  路径: /system/*       StpLogic: stpLogic (主)       │
│  Token Redis Key:  auth:token:xxx                    │
│  数据库: bytech_system_{tenantCode}（每个租户独立库）  │
└─────────────────────────────────────────────────────┘
```

- 两套 `StpLogic` 共享同一个 Redis 连接，通过不同 `loginType` 实现 Key 隔离，**可同时在线互不覆盖**
- 前端双 Token 并存于 `localStorage`，`currentLoginType` 存于 `sessionStorage`（多 Tab 独立）
- 退出时自动切换到另一已登录身份

> 详细文档：[docs/双系统同时登录机制.md](docs/双系统同时登录机制.md)

<br>

## 多租户数据隔离

采用 **Schema 级隔离**（每个租户独立 MySQL 库），轻量且高效。

```
HTTP 请求 (Authorization: Bearer {token})
  │
  ├─ Gateway AuthFilter
  │    └─ 从 Redis TokenSession 读取 LoginUser → tenantCode
  │    └─ 写入可信 Tenant-Code Header（先清除外部伪造头）
  │
  ├─ TenantHeaderInterceptor（Servlet Filter）
  │    └─ Header → TenantContextHolder (TransmittableThreadLocal)
  │
  └─ TenantSchemaInterceptor（MyBatis Plugin）
       └─ SQL 执行前 USE bytech_system_{tenantCode}
       └─ 无 tenantCode → 降级 USE bytech_system
```

| 组件 | 路径 | 功能 |
|------|------|------|
| `TenantContextHolder` | `bytech-common-core/.../holder/` | TransmittableThreadLocal 线程安全传递 |
| `TenantHeaderInterceptor` | `bytech-common-tenant/.../interceptor/` | 从 Header 提取并设置上下文 |
| `TenantSchemaInterceptor` | `bytech-common-tenant/.../interceptor/` | MyBatis Plugin，SQL 前动态 USE |
| `TenantFeignInterceptor` | `bytech-common-tenant/.../interceptor/` | Feign 调用时透传租户信息 |
| `TenantCodeResolver` | `bytech-common-security/.../utils/` | 从 Token 或 Session 解析 tenantCode |

**数据源设计**：
- `tenant` 数据源（primary）：共享连接池，`USE` 动态切换，零额外开销
- `platform` 数据源：`@DS("platform")` 注解切换，固定连接 `bytech_platform`

**可拔插**：不引入 `bytech-common-tenant` 时，多租户完全不激活。

<br>

## 微服务 / 单体双模式

通过 `monolith` Profile 一键切换，单体模式直接注入 Controller Bean 替代 Feign HTTP 调用。

| 模式 | Profile | Nacos | Feign | 启动方式 |
|------|---------|-------|-------|---------|
| **微服务** | `dev`/`prod` | ✅ 启用 | ✅ HTTP 代理 | 分别启动各服务 |
| **单体** | `monolith` | ❌ 禁用 | ❌ 本地注入 | 启动 bytech-boot 即可 |

```bash
# 单体模式（一键启动）
mvn clean package -pl bytech-boot -DskipTests
java -jar bytech-boot/target/bytech-boot-exec.jar --spring.profiles.active=monolith

# 微服务模式（需先启动 Nacos）
# 依次启动 gateway → auth → system → platform → file
```

**单体模式核心设计**：
- `bytech-boot` 聚合所有业务模块，`@ComponentScan("com.bytech")` 全量扫描
- `SecurityConfig`（`@Profile("monolith")`）：Servlet 拦截器链（安全配置不依赖 Gateway）
- Controller `implements FeignClient` 接口，单体模式下 `@Autowired` 直接注入本地 Bean，零网络开销

> 详细文档：[docs/API_CALLING_CONVENTION.md](docs/API_CALLING_CONVENTION.md)

<br>

## 审计日志体系

等保三级合规的完整审计方案，三种维度覆盖：

| 类型 | 注解/采集 | 存储表 | 说明 |
|------|-----------|--------|------|
| **操作日志** | `@OperLog` | `sys_oper_log` / `platform_oper_log` | 记录增删改查等业务操作 |
| **数据变更** | `@DataChangeLog` | `sys_data_change_log` | 新旧值 diff 对比 |
| **访问日志** | 全局拦截器自动采集 | `sys_access_log` / `platform_access_log` | HTTP 请求全量审计 |

**访问日志架构**：

```
单体模式:  AccessLogInterceptor (Servlet) → AsyncLogService → Feign → Controller → DB
微服务:    AccessLogGatewayFilter (Gateway) → WebClient POST → Controller → DB
```

日志表通过数据库触发器禁止 UPDATE/DELETE，等保合规不可篡改。

<br>

## 路线图 (TODO)

下一阶段计划实现的功能模块：

### 文件服务

| 功能 | 说明 |
|------|------|
| 本地存储 / OSS 多云适配 | 支持本地磁盘、阿里云 OSS、腾讯云 COS、MinIO 等，配置切换 |
| 断点续传 | 大文件分片上传，支持暂停/恢复 |
| 文件预览 | 图片、PDF、Office 文档在线预览 |
| 文件水印 | 图片/PDF 动态水印，防盗溯源 |

### 系统监控

| 功能 | 说明 |
|------|------|
| 在线用户 | 实时查看在线用户列表，支持强退 |
| 定时任务 | 基于 XXL-JOB 的分布式任务调度管理 |
| 服务监控 | Spring Boot Admin，查看各服务 CPU/内存/JVM/GC 指标 |
| Redis 监控 | Redis 连接数、命中率、内存使用量等实时监控 |

### 开发工具

| 功能 | 说明 |
|------|------|
| 开放接口 | Swagger / Knife4j 在线调试，自动生成 API 文档 |
| 代码生成 | 支持在线生成 Controller / Service / Mapper / Entity / Vue 页面 |
| 在线表单 | 可视化拖拽表单设计器，动态生成 CRUD 页面 |
| 流程控制 | 集成 Flowable 工作流引擎，支持可视化流程设计 |

### AI 功能

| 功能 | 说明 |
|------|------|
| 智能助手 | 接入大语言模型，自然语言查询数据、生成报表 |
| 代码审查 | AI 辅助代码 Review，自动检测规范和安全问题 |
| 智能日志分析 | 异常日志自动聚类、告警、给出修复建议 |
| 合规检查 | AI 自动审计操作日志，识别异常行为 |

### IP 地理位置

集成 ip2region 3.x 离线数据库，无需联网，微秒级解析。

**开启方式**：将 `ip2region_v4.xdb` / `ip2region_v6.xdb` 放入 `bytech-common/bytech-common-core/src/main/resources/ipdb/`

下载地址：[ip2region data](https://github.com/lionsoul2014/ip2region/tree/master/data)

<br>

## 快速开始

### 环境要求

- JDK 17+
- MySQL 8.0+
- Redis 7.x
- Nacos 2.x（微服务模式）
- Maven 3.8+

### 1. 初始化数据库

```sql
-- 创建公共库
CREATE DATABASE bytech_platform DEFAULT CHARACTER SET utf8mb4;
CREATE DATABASE bytech_system DEFAULT CHARACTER SET utf8mb4;

-- 导入表结构
source sql/bytech_platform.sql;
source sql/bytech_system.sql;
```

### 2. 单体模式（快速体验）

```bash
mvn clean package -pl bytech-boot -DskipTests
java -jar bytech-boot/target/bytech-boot-exec.jar --spring.profiles.active=monolith
```

访问 `http://localhost:8080`，默认账号 `admin` / `admin123`。

### 3. 微服务模式

3.1 启动 Nacos + Redis + MySQL

3.2 导入 Nacos 配置（`nacos-configs/dev/` 目录）

3.3 依次启动：
```bash
# Gateway
mvn spring-boot:run -pl bytech-gateway -Dspring.profiles.active=dev
# Auth
mvn spring-boot:run -pl bytech-auth -Dspring.profiles.active=dev
# System
mvn spring-boot:run -pl bytech-modules/bytech-system -Dspring.profiles.active=dev
# Platform
mvn spring-boot:run -pl bytech-modules/bytech-platform -Dspring.profiles.active=dev
# File
mvn spring-boot:run -pl bytech-modules/bytech-file -Dspring.profiles.active=dev
```

<br>

## 项目文档

| 文档 | 说明 |
|------|------|
| [双系统登录机制](docs/双系统同时登录机制.md) | 双 Token + currentLoginType 切换方案 |
| [多租户数据隔离](docs/multi-tenant-design.md) | Schema 级别隔离设计 |
| [API 调用规范](docs/API_CALLING_CONVENTION.md) | Controller implements FeignClient 双模约定 |
| [RBAC 权限模型](docs/RBAC数据库设计与逻辑说明.md) | 平台 + 租户两套 RBAC |
| [前端登录逻辑](docs/前端登录两种系统类型逻辑分析.md) | 前端双系统登录状态管理 |
| [登录逻辑说明](docs/login-logic.md) | 认证流程详解 |
| [数据库规范](docs/database-specification.md) | 建表与命名规范 |
| [系统配置设计](docs/sys_config_design.md) | 参数配置模块设计 |

<br>

## License

MIT