# campus-carbon-cloud

**Repository Path**: 965756692/campus-carbon-cloud

## Basic Information

- **Project Name**: campus-carbon-cloud
- **Description**: 一个通用的用户管理平台
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-24
- **Last Updated**: 2026-05-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 能碳平台 (Campus Carbon Cloud)

> 能碳平台 - 用户权限管理系统，基于 Spring Cloud 微服务架构构建的企业级能碳排放管理云平台。

## 技术栈

### 后端

| 技术 | 版本 | 说明 |
|------|------|------|
| Spring Boot | 3.3.7 | 基础框架 |
| Spring Cloud | 2023.0.5 | 微服务治理 |
| Spring Cloud Alibaba | 2023.0.3.4 | Nacos 注册/配置中心 |
| Spring Cloud Gateway | - | API 网关 |
| MyBatis-Plus | 3.5.9 | ORM 框架 |
| Spring Data Redis + Lettuce | - | 缓存中间件 |
| JetCache | 2.7.5 | 多级缓存（可选启用） |
| OpenFeign | - | 服务间调用 |
| RocketMQ | 2.3.2 | 消息队列 |
| XXL-JOB | 2.4.1 | 分布式任务调度 |
| JWT (JJWT) | 0.12.6 | 认证令牌 |
| Knife4j | 4.5.0 | API 文档 |
| EasyExcel | 4.0.3 | Excel 导入导出 |
| MySQL | - | 关系型数据库 |
| Nacos | 2.x | 注册中心 & 配置中心 |

### 前端

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.5.x | 前端框架 |
| Vite | 6.x | 构建工具 |
| Element Plus | 2.9.x | UI 组件库 |
| Pinia | 2.3.x | 状态管理 |
| Vue Router | 4.5.x | 路由管理 |
| Vue I18n | 9.x | 国际化 |
| Axios | 1.7.x | HTTP 客户端 |
| ECharts | 5.5.x | 图表可视化 |
| Globe.gl | 2.45.x | 3D 地球可视化 |
| TopoJSON Client | 3.1.x | 地理数据解析 |
| Crypto-JS | 4.2.x | 加密验证工具 |
| NProgress | 0.2.x | 页面加载进度条 |
| TypeScript | 5.6.x | 类型支持 |

## 系统架构

```
┌─────────────┐
│   前端 (Vue3)  │
└──────┬──────┘
       │
┌──────▼──────┐
│  API Gateway │  :9090  路由 / 鉴权 / 限流 / 签名校验
└──┬───────┬──┘
   │       │
┌──▼──┐ ┌──▼──┐
│ Auth │ │System│  认证服务 :9091  /  系统服务 :9092
└──┬──┘ └──┬──┘
   │       │
┌──▼───────▼──┐
│  Nacos 注册中心 & 配置中心  :8848
├─────────────┤
│  Redis 缓存  :6379
├─────────────┤
│  MySQL 数据库  :3306
├─────────────┤
│  RocketMQ 消息队列  :9876
├─────────────┤
│  XXL-JOB 任务调度  :8080
└─────────────┘
```

## 项目结构

```
campus-carbon-cloud
├── campus-carbon-gateway          # API 网关 (端口:9090)
│   ├── filter/                    # 过滤器链（认证、限流、安全、签名、监控）
│   ├── ratelimit/                 # 令牌桶限流（Redis + Lua）
│   └── config/                    # 网关配置
│
├── campus-carbon-auth             # 认证服务 (端口:9091)
│   ├── controller/                # 认证接口（登录/注册/登出/验证码）
│   ├── service/                   # 认证业务（Token管理/验证码/忘记密码）
│   ├── strategy/                  # 登录策略（密码/短信/邮箱 - 工厂模式）
│   ├── config/                    # 验证码配置管理
│   └── form/                      # 请求/响应表单
│
├── campus-carbon-modules
│   └── campus-carbon-system       # 系统管理服务 (端口:9092)
│       ├── controller/            # 用户/角色/菜单/部门/字典/日志/岗位/会话/验证码配置
│       ├── service/               # 业务逻辑
│       └── domain/                # 实体与表单
│
├── campus-carbon-common           # 公共模块
│   ├── campus-carbon-common-core       # 核心工具（异常/上下文/工具类/常量）
│   ├── campus-carbon-common-redis      # Redis 服务 + 分布式锁 + JetCache
│   ├── campus-carbon-common-mybatis    # MyBatis-Plus 配置（分页/乐观锁/软删除/审计填充）
│   ├── campus-carbon-common-security   # 安全配置（Feign拦截器/上下文传递）
│   ├── campus-carbon-common-log        # 操作日志（AOP切面 + RocketMQ异步）
│   ├── campus-carbon-common-rocketmq   # RocketMQ 配置
│   ├── campus-carbon-common-xxljob     # XXL-JOB 分布式任务调度配置
│   └── campus-carbon-common-swagger    # Knife4j API 文档配置
│
├── campus-carbon-api              # Feign 远程调用接口
│   ├── campus-carbon-api-system         # 系统服务接口（用户/会话/日志/验证码配置）
│   └── campus-carbon-api-auth           # 认证服务接口
│
├── campus-carbon-ui              # 前端项目 (Vue3 + Vite)
│   ├── src/views/                 # 页面（登录/仪表盘/大屏/用户/角色/菜单/部门/字典等）
│   ├── src/components/            # 组件（验证码滑块/项目设置）
│   ├── src/stores/                # Pinia 状态管理
│   ├── src/router/                # 路由配置
│   ├── src/i18n/                  # 国际化（中文/英文）
│   ├── src/utils/                 # 工具（请求封装/加密验证/主题色）
│   └── src/composables/           # 组合式函数
│
├── sql                            # 数据库初始化脚本
│   └── init.sql
└── docs                           # 项目文档
```

## 核心功能

### 认证与安全
- **多方式登录** - 用户名密码 / 短信验证码 / 邮箱验证码（工厂策略模式）
- **JWT 令牌管理** - Access Token + Refresh Token 轮换机制
- **会话策略** - 支持单端登录(SINGLE)和多端登录(MULTI)，可配置最大会话数
- **登录安全** - 失败重试计数 + 自动锁定 + BCrypt 密码加密
- **忘记密码** - 手机/邮箱验证身份 → 发送验证码 → 重置密码
- **分布式锁** - 验证码频率控制 / 注册唯一性 / 会话管理 / 令牌刷新

### 网关能力
- **统一鉴权** - JWT 解析与校验，白名单放行
- **令牌桶限流** - Redis + Lua 脚本，支持 API/用户/IP 多维度
- **安全过滤** - 路径过滤、跨域处理、防重放攻击、防重复提交

### 系统管理
- **用户管理** - CRUD / 状态管理 / 密码重置 / 角色分配 / 部门分配 / Excel 导出
- **角色管理** - CRUD / 权限分配 / 数据权限
- **菜单管理** - 树形菜单 / 按钮级权限
- **部门管理** - 树形组织架构
- **字典管理** - 数据字典维护
- **日志管理** - 操作日志 + 登录日志
- **岗位管理** - 岗位信息维护
- **会话管理** - 在线会话查看 / 强制下线 / 会话策略调整

### 定时任务与调度
- **XXL-JOB 集成** - 分布式任务调度平台，支持定时任务、分片广播、故障转移等
- **自动配置** - 基于条件装配，按需启用（`xxl-job.enabled=true`）
- **执行器管理** - 各服务独立执行器端口（Auth:9901, System:9902）
- **日志管理** - 任务执行日志自动记录，支持日志保留天数配置

### 前端特性
- **现代简约 UI** - Element Plus 组件库 + 自定义主题色
- **国际化** - 中文/英文切换 (Vue I18n)
- **权限控制** - 路由守卫 + 按钮级权限指令 + 业务服务权限校验
- **验证码** - AJ-Captcha 滑块验证
- **响应式布局** - 侧边栏 + 标签页 + 工具栏
- **数据大屏** - 碳足迹仪表盘 + 3D 地球地图协同可视化

## 快速开始

### 环境要求

| 依赖 | 版本要求 |
|------|---------|
| JDK | 17+ |
| Maven | 3.8+ |
| Node.js | 18+ |
| MySQL | 8.0+ |
| Redis | 7.0+ |
| Nacos | 2.x |
| RocketMQ | 5.x |
| XXL-JOB | 2.4.0+ |

### 1. 初始化数据库

```bash
# 创建数据库并执行初始化脚本
mysql -u root -p -e "CREATE DATABASE campus_carbon DEFAULT CHARACTER SET utf8mb4;"
mysql -u root -p campus_carbon < sql/init.sql
```

### 2. 启动中间件

```bash
# Redis
redis-server

# Nacos (单机模式)
sh startup.sh -m standalone

# RocketMQ
nohup sh mqnamesrv &
nohup sh mqbroker -n localhost:9876 &

# XXL-JOB Admin (可选，按需启动)
# 下载地址：https://github.com/xuxueli/xxl-job
# 启动前需初始化数据库并修改配置文件
```

### 3. 启动后端服务

```bash
# 编译整个项目
mvn clean package -DskipTests

# 按顺序启动服务
# 1. 网关服务
java -jar campus-carbon-gateway/target/campus-carbon-gateway-1.0.0.jar

# 2. 认证服务
java -jar campus-carbon-auth/target/campus-carbon-auth-1.0.0.jar

# 3. 系统管理服务
java -jar campus-carbon-modules/campus-carbon-system/target/campus-carbon-system-1.0.0.jar
```

### 4. 启动前端

```bash
cd campus-carbon-ui
npm install
npm run dev
```

### 访问地址

| 服务 | 地址 |
|------|------|
| 前端页面 | http://localhost:5173 |
| API 网关 | http://localhost:9090 |
| 认证服务 | http://localhost:9091 |
| 系统管理服务 | http://localhost:9092 |
| Nacos 控制台 | http://localhost:8848/nacos |
| API 文档 (Auth) | http://localhost:9091/doc.html |
| API 文档 (System) | http://localhost:9092/doc.html |
| XXL-JOB Admin | http://localhost:8080/xxl-job-admin |

### 默认账号

| 账号 | 密码 | 角色 |
|------|------|------|
| admin | admin123 | 超级管理员 |

## 配置说明

### 环境切换

各服务通过 `spring.profiles.active` 切换环境配置：

- `dev` - 开发环境（Redis 单机模式，本地中间件）
- `prod` - 生产环境（Redis 集群模式，环境变量覆盖）

### 关键配置项

```yaml
# 认证配置
auth:
  token-expire-minutes: 30       # Access Token 有效期（分钟）
  refresh-token-expire-days: 14  # Refresh Token 有效期（天）
  session-policy: MULTI          # 会话策略（SINGLE/MULTI）
  max-session: 3                 # 最大同时在线会话数
  login-retry-limit: 5           # 登录失败重试上限
  lock-duration-minutes: 30      # 账号锁定时长（分钟）

# 验证码配置
verification-code:
  sms-code-length: 6             # 短信验证码长度
  email-code-length: 6           # 邮箱验证码长度
  code-ttl: 300                  # 验证码有效期（秒）
  send-interval: 60              # 发送间隔限制（秒）
  daily-limit: 10                # 每日发送上限

# JetCache 配置（默认关闭）
jetcache:
  enable: false                  # 设为 true 启用多级缓存

# XXL-JOB 配置（默认关闭）
xxl-job:
  enabled: false                 # 设为 true 启用分布式任务调度
```

### 环境变量覆盖

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `NACOS_ADDR` | 127.0.0.1:8848 | Nacos 地址 |
| `NACOS_NAMESPACE` | ${spring.profiles.active} | Nacos 命名空间 |
| `REDIS_HOST` | 127.0.0.1 | Redis 地址 |
| `REDIS_PORT` | 6379 | Redis 端口 |
| `REDIS_PASSWORD` | (空) | Redis 密码 |
| `MYSQL_HOST` | 127.0.0.1 | MySQL 地址 |
| `MYSQL_PORT` | 3306 | MySQL 端口 |
| `XXL_JOB_ADMIN_ADDRESSES` | http://127.0.0.1:8080/xxl-job-admin | XXL-JOB Admin 地址 |
| `XXL_JOB_EXECUTOR_PORT` | 9901/9902 | XXL-JOB 执行器端口 |

## 分布式锁

项目基于 `DistributedLockUtil`（Redis SETNX + Lua 脚本）实现了轻量级分布式锁，已应用于以下关键场景：

| 场景 | 锁粒度 | 防护目标 |
|------|--------|---------|
| 验证码发送 | 手机号/邮箱 | 防止并发绕过频率限制 |
| 验证码校验 | 手机号/邮箱 | 防止验证码被重复使用 |
| 用户注册 | 用户名 | 防止并发注册重复用户名 |
| 忘记密码发送验证码 | 验证目标 | 防止并发发送 |
| 忘记密码重置 | 用户名 | 防止验证码被重复使用 |
| 会话管理 | 用户ID | 防止并发登录超出会话数 |
| Refresh Token 刷新 | refreshToken | 防止并发刷新同一令牌 |

## 分布式任务调度

项目已集成 **XXL-JOB** 分布式任务调度平台，提供强大的定时任务管理能力：

### 架构设计
- **调度中心** - XXL-JOB Admin 提供统一管理界面，负责任务调度、监控、报警等
- **执行器** - 各微服务作为执行器，接收调度中心指令并执行具体任务
- **自动装配** - 基于 Spring Boot 条件装配，通过 `xxl-job.enabled` 控制启用状态
- **模块隔离** - 独立的 `campus-carbon-common-xxljob` 模块，避免耦合

### 核心特性
- **定时策略** - 支持 CRON 表达式、固定间隔、固定延迟等多种调度策略
- **分片广播** - 支持任务分片执行，提高大数据量处理效率
- **故障转移** - 执行器故障时自动转移任务至其他可用节点
- **失败重试** - 支持任务失败自动重试，可配置重试次数和间隔
- **日志追踪** - 完整的任务执行日志，支持在线查看和下载
- **报警机制** - 支持邮件、Webhook 等多种报警方式

### 配置说明
```yaml
# 各服务独立配置（以 auth 服务为例）
xxl-job:
  enabled: false                 # 是否启用，默认 false
  admin:
    addresses: http://127.0.0.1:8080/xxl-job-admin  # 调度中心地址
  executor:
    appname: campus-carbon-auth  # 执行器 AppName
    port: 9901                   # 执行器端口，各服务需不同
    logpath: ./logs/xxl-job/campus-carbon-auth  # 日志路径
    logretentiondays: 30         # 日志保留天数
    accessToken:                 # 访问令牌（可选）
```

### 使用示例
```java
// 在业务代码中使用 @XxlJob 注解定义任务处理器
@Component
public class SampleTask {
    
    @XxlJob("demoTaskHandler")
    public void demoTaskHandler() throws Exception {
        XxlJobHelper.log("执行定时任务...");
        // 业务逻辑
    }
}
```

### 启用步骤
1. 部署 XXL-JOB Admin 调度中心（参考官方文档）
2. 初始化 XXL-JOB 数据库表结构
3. 在各服务配置文件中设置 `xxl-job.enabled=true`
4. 配置正确的 `admin.addresses` 和各服务独立的 `executor.port`
5. 在 XXL-JOB Admin 控制台注册执行器并配置任务

## 许可证

私有项目，未经授权禁止使用。