张翔
276 lines
7.4 KiB
Markdown
276 lines
7.4 KiB
Markdown
# 双应用架构文档
|
|
|
|
## 架构概述
|
|
|
|
本项目采用双应用架构，将客户端应用和后台管理应用分离，通过网关统一路由，实现独立部署和运维。
|
|
|
|
## 架构图
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ 客户端/浏览器 │
|
|
└──────────────────────┬──────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ Gateway │ 8080
|
|
│ (网关) │
|
|
└────────┬────────┘
|
|
│
|
|
┌────────────┴────────────┐
|
|
│ │
|
|
▼ ▼
|
|
┌──────────────────┐ ┌──────────────────┐
|
|
│ Client App │ │ Admin App │ 8082
|
|
│ (客户端应用) │ │ (后台管理应用) │
|
|
│ 8081 │ │ │
|
|
└────────┬─────────┘ └────────┬─────────┘
|
|
│ │
|
|
└────────────┬───────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ PostgreSQL │
|
|
│ (数据库) │
|
|
└─────────────────┘
|
|
```
|
|
|
|
## 模块说明
|
|
|
|
### 1. 网关模块 (everything-is-suitable-gateway)
|
|
- **端口**: 8080
|
|
- **职责**:
|
|
- 统一入口，路由请求到对应的应用
|
|
- JWT 认证和 RBAC 权限验证
|
|
- 负载均衡和熔断降级
|
|
- **路由规则**:
|
|
- `/api/client/**` → Client App (8081)
|
|
- `/api/admin/**` → Admin App (8082)
|
|
- `/api/auth/**` → Client App (8081)
|
|
- `/api/fortune/**` → Client App (8081)
|
|
|
|
### 2. 客户端应用 (everything-is-suitable-client-app)
|
|
- **端口**: 8081
|
|
- **职责**:
|
|
- 处理客户端用户请求
|
|
- 提供命理查询服务
|
|
- 用户认证和授权
|
|
- **依赖**:
|
|
- everything-is-suitable-client-api (接口层)
|
|
- everything-is-suitable-biz (业务逻辑)
|
|
- everything-is-suitable-common (公共组件)
|
|
|
|
### 3. 后台管理应用 (everything-is-suitable-admin-app)
|
|
- **端口**: 8082
|
|
- **职责**:
|
|
- 处理后台管理请求
|
|
- 用户管理和权限控制
|
|
- 统计数据查询
|
|
- **依赖**:
|
|
- everything-is-suitable-admin-api (接口层)
|
|
- everything-is-suitable-sys (系统管理)
|
|
- everything-is-suitable-statistics (统计分析)
|
|
|
|
### 4. 客户端接口层 (everything-is-suitable-client-api)
|
|
- **职责**:
|
|
- 定义客户端 API 路由
|
|
- 实现 Handler 处理请求
|
|
- 参数验证和响应封装
|
|
|
|
### 5. 后台管理接口层 (everything-is-suitable-admin-api)
|
|
- **职责**:
|
|
- 定义后台管理 API 路由
|
|
- 实现 Handler 处理请求
|
|
- RBAC 权限控制
|
|
|
|
### 6. 公共模块 (everything-is-suitable-common)
|
|
- **职责**:
|
|
- 提供通用工具类
|
|
- JWT 认证工具类
|
|
- JWT 认证过滤器
|
|
- RBAC 权限过滤器
|
|
|
|
### 7. 业务模块 (everything-is-suitable-biz)
|
|
- **职责**:
|
|
- 命理分析业务逻辑
|
|
- 数据访问层
|
|
- 业务规则实现
|
|
|
|
## 认证和授权
|
|
|
|
### JWT 认证
|
|
- **实现**: `JwtTokenProvider`
|
|
- **功能**:
|
|
- 生成 JWT Token
|
|
- 验证 JWT Token
|
|
- 解析 JWT Token
|
|
- **过滤器**: `JwtAuthenticationFilter`
|
|
- 自动提取和验证 JWT Token
|
|
- 将用户信息添加到请求头
|
|
|
|
### RBAC 权限控制
|
|
- **实现**: `RbacAuthorizationFilter`
|
|
- **角色定义**:
|
|
- **ADMIN**: 管理员，拥有所有权限
|
|
- **MANAGER**: 经理，拥有读取权限
|
|
- **OPERATOR**: 操作员，拥有基础权限
|
|
- **权限映射**:
|
|
- `users:read`, `users:write`, `users:delete`
|
|
- `statistics:read`
|
|
- `fortune:read`, `fortune:write`
|
|
- `settings:read`, `settings:write`
|
|
|
|
## 缓存策略
|
|
|
|
### Caffeine 本地缓存
|
|
- **用户信息**: 缓存 5 分钟
|
|
- **命理结果**: 缓存 10 分钟
|
|
- **统计数据**: 缓存 1 分钟
|
|
- **配置**:
|
|
```yaml
|
|
spring:
|
|
cache:
|
|
type: caffeine
|
|
caffeine:
|
|
spec: maximumSize=1000,expireAfterWrite=5m
|
|
```
|
|
|
|
## 部署方案
|
|
|
|
### Docker 部署
|
|
- **容器化**: 所有应用使用 Docker 容器部署
|
|
- **编排**: 使用 Docker Compose 编排服务
|
|
- **网络**: 使用 bridge 网络连接服务
|
|
|
|
### 部署命令
|
|
```bash
|
|
# 构建和部署
|
|
./build-and-deploy.sh
|
|
|
|
# 停止服务
|
|
./stop-services.sh
|
|
|
|
# 使用 Docker Compose
|
|
docker-compose up -d
|
|
docker-compose down
|
|
```
|
|
|
|
### 环境变量
|
|
- `JWT_SECRET`: JWT 密钥
|
|
- `JWT_EXPIRATION`: JWT 过期时间
|
|
- `SPRING_PROFILES_ACTIVE`: Spring Profile
|
|
- `SPRING_DATASOURCE_URL`: 数据库连接 URL
|
|
- `SPRING_DATASOURCE_USERNAME`: 数据库用户名
|
|
- `SPRING_DATASOURCE_PASSWORD`: 数据库密码
|
|
|
|
## 监控和运维
|
|
|
|
### Actuator 端点
|
|
- `/actuator/health`: 健康检查
|
|
- `/actuator/metrics`: 性能指标
|
|
- `/actuator/prometheus`: Prometheus 指标
|
|
|
|
### 日志管理
|
|
- 使用 SLF4J + Logback
|
|
- 日志级别可配置
|
|
- 支持结构化日志输出
|
|
|
|
## 性能优化
|
|
|
|
### JVM 优化
|
|
- 堆内存: `-Xms512m -Xmx1024m`
|
|
- GC 策略: `-XX:+UseG1GC -XX:MaxGCPauseMillis=200`
|
|
- 其他优化: `-XX:+UseStringDeduplication`
|
|
|
|
### 数据库优化
|
|
- 连接池配置
|
|
- 查询优化和索引
|
|
- 使用 R2DBC 非阻塞访问
|
|
|
|
### 响应式优化
|
|
- 使用 WebFlux 非阻塞特性
|
|
- 背压处理
|
|
- 避免阻塞操作
|
|
|
|
## 安全考虑
|
|
|
|
### 认证安全
|
|
- JWT Token 过期机制
|
|
- Token 刷新机制
|
|
- 密钥安全管理
|
|
|
|
### 授权安全
|
|
- RBAC 权限控制
|
|
- 路径级别的权限验证
|
|
- HTTP 方法级别的权限控制
|
|
|
|
### 数据安全
|
|
- 敏感数据加密
|
|
- SQL 注入防护
|
|
- XSS 防护
|
|
|
|
## 扩展性
|
|
|
|
### 水平扩展
|
|
- 可独立扩展客户端应用
|
|
- 可独立扩展后台管理应用
|
|
- 网关支持负载均衡
|
|
|
|
### 垂直扩展
|
|
- 增加 JVM 堆内存
|
|
- 优化数据库连接池
|
|
- 增加缓存容量
|
|
|
|
## 迁移指南
|
|
|
|
### 从单体应用迁移
|
|
1. 创建新的应用模块
|
|
2. 迁移 Handler 到接口层
|
|
3. 配置网关路由
|
|
4. 更新客户端调用地址
|
|
5. 验证功能完整性
|
|
6. 逐步切换流量
|
|
|
|
### 数据迁移
|
|
- 数据库结构保持不变
|
|
- 共享数据库连接
|
|
- 使用 Flyway 管理迁移
|
|
|
|
## 故障排查
|
|
|
|
### 常见问题
|
|
1. **网关无法连接后端服务**
|
|
- 检查服务是否启动
|
|
- 检查网络连接
|
|
- 检查端口配置
|
|
|
|
2. **JWT 认证失败**
|
|
- 检查 JWT 密钥配置
|
|
- 检查 Token 过期时间
|
|
- 检查 Token 格式
|
|
|
|
3. **权限验证失败**
|
|
- 检查角色配置
|
|
- 检查权限映射
|
|
- 检查请求头传递
|
|
|
|
### 日志查看
|
|
```bash
|
|
# 查看网关日志
|
|
docker logs everything-is-suitable-gateway
|
|
|
|
# 查看客户端应用日志
|
|
docker logs everything-is-suitable-client-app
|
|
|
|
# 查看后台管理应用日志
|
|
docker logs everything-is-suitable-admin-app
|
|
```
|
|
|
|
## 总结
|
|
|
|
双应用架构通过分离客户端和后台管理应用，实现了：
|
|
- ✅ 独立部署和运维
|
|
- ✅ 灵活的扩展能力
|
|
- ✅ 统一的认证和授权
|
|
- ✅ 高性能的响应式架构
|
|
- ✅ 完善的监控和日志 |