novalon/everything-is-suitable
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
everything-is-suitable/everything-is-suitable-api/docs/dual-app-architecture.md
T
张翔 08ea5fbe98 feat(admin): 添加用户管理相关文件 
添加用户管理视图、API和状态管理文件
2026-03-28 14:37:29 +08:00

7.4 KiB
Raw Permalink Blame History

双应用架构文档

架构概述

本项目采用双应用架构，将客户端应用和后台管理应用分离，通过网关统一路由，实现独立部署和运维。

架构图

┌─────────────────────────────────────────────────────────────────┐
│                     客户端/浏览器                         │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
              ┌─────────────────┐
              │    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 分钟
  • 配置: 
    spring:
  cache:
    type: caffeine
    caffeine:
      spec: maximumSize=1000,expireAfterWrite=5m

部署方案

Docker 部署

  • 容器化: 所有应用使用 Docker 容器部署
  • 编排: 使用 Docker Compose 编排服务
  • 网络: 使用 bridge 网络连接服务

部署命令

# 构建和部署
./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. 权限验证失败

    • 检查角色配置
    • 检查权限映射
    • 检查请求头传递

日志查看

# 查看网关日志
docker logs everything-is-suitable-gateway

# 查看客户端应用日志
docker logs everything-is-suitable-client-app

# 查看后台管理应用日志
docker logs everything-is-suitable-admin-app

总结

双应用架构通过分离客户端和后台管理应用，实现了：

  • ✅ 独立部署和运维
  • ✅ 灵活的扩展能力
  • ✅ 统一的认证和授权
  • ✅ 高性能的响应式架构
  • ✅ 完善的监控和日志
Reference in New Issue View Git Blame Copy Permalink