aiotagro/jiebanke

Fork 0

Files

ylweng e767d1ab27 refactor(backend): 更新数据库配置并迁移至MySQL，优化文档和技术栈描述

2025-09-01 01:07:12 +08:00

27 KiB

Raw Blame History

结伴客系统架构文档

1. 系统架构概览

1.1 架构图

graph TB
    subgraph "客户端层"
        A[微信小程序 uni-app]
        B[后台管理系统 Vue 3 + Ant Design]
        C[官网系统 HTML5 + Bootstrap]
    end
    
    subgraph "接入层"
        D[Express API Gateway]
    end
    
    subgraph "应用服务层"
        E[认证服务]
        F[用户服务]
        G[旅行服务]
        H[动物服务]
        I[订单服务]
        J[管理员服务]
    end
    
    subgraph "基础设施层"
        K[MySQL 数据库]
        L[Redis 缓存]
        M[RabbitMQ 消息队列]
        N[文件存储]
    end
    
    subgraph "监控运维层"
        O[Swagger API 文档]
        P[Winston 日志系统]
        Q[健康检查监控]
    end
    
    A --> D
    B --> D
    C --> D
    D --> E
    D --> F
    D --> G
    D --> H
    D --> I
    D --> J
    
    E --> K
    F --> K
    G --> K
    H --> K
    I --> K
    J --> K
    
    E --> L
    F --> L
    G --> L
    
    I --> M
    
    E --> N
    F --> N
    H --> N
    
    D --> O
    D --> P
    D --> Q

系统架构层次说明：

1. 客户端层

微信小程序: 基于uni-app开发，提供用户端功能
后台管理系统: 基于Vue.js 3 + TypeScript + Ant Design Vue + Pinia开发，提供管理功能
官网系统: 基于HTML5 + Bootstrap开发，提供企业宣传功能

2. 接入层

API网关: 基于Express.js框架，提供统一的API接入、路由分发、安全防护和请求处理，所有API路径前缀为/api/v1

3. 应用服务层

认证服务: 用户身份认证、JWT令牌管理和权限控制
用户服务: 用户信息管理、个人中心功能和用户统计
旅行服务: 旅行计划创建、查询、匹配和管理功能
动物服务: 动物信息管理、认领流程和动物统计
订单服务: 订单创建、支付处理和交易管理
管理员服务: 管理员权限管理和系统配置

4. 基础设施层

MySQL数据库: 单实例架构，存储核心业务数据，使用连接池优化性能（测试环境: 192.168.0.240:3306，生产环境: 129.211.213.226:9527）
Redis缓存: 单实例模式，提供会话管理和数据缓存服务
RabbitMQ消息队列: 异步消息处理和解耦（待实现）
文件存储: 本地文件系统，存储用户上传的图片和文件资源

5. 监控运维层

Swagger API文档: 自动生成的API接口文档
Winston日志系统: 结构化日志记录和分析
健康检查监控: 系统状态监控和性能统计

架构连接关系：

所有客户端通过API网关访问后端服务
应用服务层各服务独立部署，通过API网关统一暴露接口
认证服务、用户服务、旅行服务、动物服务、商家服务连接MySQL数据库和Redis缓存
支付服务和推广服务连接MySQL数据库和RabbitMQ消息队列
认证服务、用户服务、动物服务、商家服务连接对象存储
监控系统、日志系统、CI/CD系统监控所有应用服务

2. 项目结构

结伴客项目 (根目录)
├── mini-program                // 微信小程序 (uni-app)
│   ├── pages
│   │   ├── user                    // 用户相关页面
│   │   │   ├── login               // 登录页面
│   │   │   ├── register            // 注册页面
│   │   │   ├── profile             // 个人主页
│   │   │   └── settings            // 设置页面
│   │   ├── merchant                // 商家相关页面
│   │   │   ├── register            // 商家注册
│   │   │   ├── profile             // 商家主页
│   │   │   └── dashboard           // 商家控制台
│   │   ├── travel                  // 旅行结伴页面
│   │   │   ├── plan                // 旅行计划
│   │   │   ├── search              // 搜索结伴
│   │   │   └── activities          // 其他活动
│   │   ├── animal                  // 动物认领页面
│   │   │   ├── list                // 动物列表
│   │   │   ├── detail              // 动物详情
│   │   │   └── claim               // 认领流程
│   │   ├── social                  // 社交互动页面
│   │   │   ├── messages            // 消息聊天
│   │   │   └── feed                // 动态分享
│   │   ├── flower                  // 送花服务页面
│   │   │   ├── products            // 鲜花产品
│   │   │   └── orders              // 订单管理
│   │   └── promotion               // 推广奖励页面
│   │       ├── invite              // 邀请推广
│   │       └── rewards             // 奖励中心
│   ├── components                  // 可复用组件
│   │   ├── common                  // 通用组件
│   │   ├── user                    // 用户相关组件
│   │   ├── travel                  // 旅行相关组件
│   │   ├── animal                  // 动物相关组件
│   │   ├── social                  // 社交相关组件
│   │   ├── merchant                // 商家相关组件
│   │   └── flower                  // 鲜花相关组件
│   ├── utils                       // 工具函数
│   │   ├── request                 // 网络请求封装
│   │   ├── auth                    // 认证相关工具
│   │   ├── storage                 // 存储相关工具
│   │   └── helpers                 // 辅助函数
│   ├── static                      // 静态资源
│   │   ├── images                  // 图片资源
│   │   └── styles                  // 样式文件
│   └── store                       // 状态管理
│       ├── modules                 // 模块化状态
│       │   ├── user                // 用户状态
│       │   ├── travel              // 旅行状态
│       │   ├── animal              // 动物状态
│       │   ├── social              // 社交状态
│       │   ├── merchant            // 商家状态
│       │   ├── flower              // 鲜花状态
│       │   └── promotion           // 推广状态
│       └── index.js                // 状态管理入口
├── admin-system                    // 后台管理系统 (Vue.js 3 + TypeScript + Ant Design Vue + Pinia)
│   ├── public                      // 静态资源
│   ├── src
│   │   ├── api                     // API接口 (TypeScript类型定义)
│   │   │   ├── user                // 用户相关接口
│   │   │   ├── merchant            // 商家相关接口
│   │   │   ├── travel              // 旅行相关接口
│   │   │   ├── animal              // 动物相关接口
│   │   │   ├── order               // 订单相关接口
│   │   │   ├── promotion           // 推广相关接口
│   │   │   └── system              // 系统管理接口
│   │   ├── assets                  // 静态资源
│   │   ├── components              // 公共组件 (Vue 3 Composition API)
│   │   │   ├── layout              // 布局组件
│   │   │   ├── common              // 通用组件
│   │   │   ├── user                // 用户相关组件
│   │   │   ├── merchant            // 商家相关组件
│   │   │   ├── travel              // 旅行相关组件
│   │   │   ├── animal              // 动物相关组件
│   │   │   ├── order               // 订单相关组件
│   │   │   ├── promotion           // 推广相关组件
│   │   │   └── dashboard           // 仪表板组件
│   │   ├── composables             // 组合式函数 (Vue 3 Composition API)
│   │   ├── directives              // 自定义指令
│   │   ├── layouts                 // 页面布局
│   │   │   ├── default.vue         // 默认布局
│   │   │   ├── auth.vue            // 认证布局
│   │   │   └── empty.vue           // 空白布局
│   │   ├── locales                 // 国际化资源
│   │   │   ├── zh-CN.json          // 中文语言包
│   │   │   └── en-US.json          // 英文语言包
│   │   ├── pages                   // 页面视图 (Vue 3 + TypeScript)
│   │   │   ├── dashboard           // 仪表板页面
│   │   │   ├── user                // 用户管理页面
│   │   │   ├── merchant            // 商家管理页面
│   │   │   ├── travel              // 旅行管理页面
│   │   │   ├── animal              // 动物管理页面
│   │   │   ├── order               // 订单管理页面
│   │   │   ├── promotion           // 推广管理页面
│   │   │   ├── system              // 系统管理页面
│   │   │   ├── login.vue           // 登录页面
│   │   │   └── register.vue        // 注册页面
│   │   ├── plugins                 // 插件
│   │   ├── router                  // 路由配置 (Vue Router 4 + TypeScript)
│   │   │   ├── modules             // 模块路由
│   │   │   │   ├── user.ts         // 用户路由
│   │   │   │   ├── merchant.ts     // 商家路由
│   │   │   │   ├── travel.ts       // 旅行路由
│   │   │   │   ├── animal.ts       // 动物路由
│   │   │   │   ├── order.ts        // 订单路由
│   │   │   │   ├── promotion.ts    // 推广路由
│   │   │   │   └── system.ts       // 系统路由
│   │   │   └── index.ts            // 路由入口
│   │   ├── stores                  // 状态管理 (Pinia 2 + TypeScript)
│   │   │   ├── modules             // 模块状态
│   │   │   │   ├── user.ts         // 用户状态
│   │   │   │   ├── merchant.ts     // 商家状态
│   │   │   │   ├── travel.ts       // 旅行状态
│   │   │   │   ├── animal.ts       // 动物状态
│   │   │   │   ├── order.ts        // 订单状态
│   │   │   │   ├── promotion.ts    // 推广状态
│   │   │   │   └── system.ts       // 系统状态
│   │   │   └── index.ts            // 状态管理入口
│   │   ├── styles                  // 样式文件
│   │   ├── types                   // TypeScript类型定义
│   │   ├── utils                   // 工具函数 (TypeScript)
│   │   │   ├── request.ts          // 请求封装 (Axios + TypeScript)
│   │   │   ├── auth.ts             // 认证工具
│   │   │   ├── storage.ts          // 存储工具
│   │   │   ├── format.ts           // 格式化工具
│   │   │   └── validate.ts         // 验证工具
│   │   └── App.vue                 // 根组件 (Vue 3 + TypeScript)
│   │   └── main.ts                 // 入口文件 (Vue 3 + TypeScript + Pinia + Ant Design Vue)
│   ├── tests                       // 测试目录 (Vitest + Vue Test Utils)
│   ├── .env                        // 环境配置
│   ├── .env.development            // 开发环境配置
│   ├── .env.production             // 生产环境配置
│   ├── index.html                  // HTML模板
│   ├── tsconfig.json               // TypeScript配置 (严格模式)
│   ├── vite.config.ts              // 构建配置 (Vite 4 + TypeScript)
│   └── package.json                // 依赖配置 (Vue 3 + TypeScript + Ant Design Vue + Pinia)
├── website                         // 官网系统 (HTML5 + Bootstrap)
│   ├── index.html                  // 首页
│   ├── about.html                  // 关于我们
│   ├── contact.html                // 联系我们
│   ├── merchant                    // 商家合作页面
│   │   ├── index.html              // 商家合作首页
│   │   ├── policy.html             // 合作政策
│   │   └── apply.html              // 入驻申请
│   ├── case.html                   // 案例展示
│   ├── css                         // 样式文件
│   │   ├── bootstrap.min.css       // Bootstrap样式
│   │   └── custom.css              // 自定义样式
│   ├── js                          // JavaScript文件
│   │   ├── bootstrap.min.js        // Bootstrap脚本
│   │   └── custom.js               // 自定义脚本
│   ├── images                      // 图片资源
│   └── vendor                      // 第三方库
├── backend                         // 后端接口服务 (Node.js + Express)
│   ├── src
│   │   ├── controllers             // 控制器层
│   │   │   ├── user                // 用户控制器
│   │   │   ├── merchant            // 商家控制器
│   │   │   ├── travel              // 旅行控制器
│   │   │   ├── animal              // 动物控制器
│   │   │   ├── social              // 社交控制器
│   │   │   ├── flower              // 鲜花控制器
│   │   │   ├── promotion           // 推广控制器
│   │   │   └── auth                // 认证控制器
│   │   ├── services                // 业务逻辑层
│   │   │   ├── user                // 用户服务
│   │   │   ├── merchant            // 商家服务
│   │   │   ├── travel              // 旅行服务
│   │   │   ├── animal              // 动物服务
│   │   │   ├── social              // 社交服务
│   │   │   ├── flower              // 鲜花服务
│   │   │   ├── promotion           // 推广服务
│   │   │   └── auth                // 认证服务
│   │   ├── models                  // 数据模型层
│   │   │   ├── user.js             // 用户模型
│   │   │   ├── merchant.js         // 商家模型
│   │   │   ├── travelPlan.js       // 旅行计划模型
│   │   │   ├── animal.js           // 动物模型
│   │   │   ├── claim.js            // 认领模型
│   │   │   ├── message.js          // 消息模型
│   │   │   ├── activity.js         // 活动模型
│   │   │   ├── product.js          // 商品模型
│   │   │   ├── order.js            // 订单模型
│   │   │   ├── review.js           // 评价模型
│   │   │   └── reward.js           // 奖励模型
│   │   ├── routes                  // 路由定义
│   │   │   ├── api                 // API路由
│   │   │   │   ├── v1              // v1版本API
│   │   │   │   │   ├── user.js     // 用户相关API
│   │   │   │   │   ├── merchant.js // 商家相关API
│   │   │   │   │   ├── travel.js   // 旅行相关API
│   │   │   │   │   ├── animal.js   // 动物相关API
│   │   │   │   │   ├── social.js   // 社交相关API
│   │   │   │   │   ├── flower.js   // 鲜花相关API
│   │   │   │   │   └── promotion.js // 推广相关API
│   │   │   │   └── index.js        // API路由入口
│   │   │   └── web                 // Web路由(管理后台)
│   │   ├── middleware              // 中间件
│   │   │   ├── auth                // 认证中间件
│   │   │   ├── validation          // 验证中间件
│   │   │   ├── rateLimit           // 限流中间件
│   │   │   └── error               // 错误处理中间件
│   │   ├── utils                   // 工具函数
│   │   │   ├── database            // 数据库工具
│   │   │   ├── logger              // 日志工具
│   │   │   ├── helpers             // 辅助函数
│   │   │   └── constants           // 常量定义
│   │   ├── config                  // 配置文件
│   │   │   ├── database.js         // 数据库配置
│   │   │   ├── redis.js            // Redis配置
│   │   │   ├── rabbitmq.js         // RabbitMQ配置
│   │   │   └── app.js              // 应用配置
│   │   └── app.js                  // 应用入口
│   ├── tests                       // 测试目录
│   │   ├── unit                    // 单元测试
│   │   └── integration             // 集成测试
│   ├── docs                        // 文档目录
│   └── package.json                // 依赖配置
└── docs                            // 项目文档
    ├── requirements.md             // 需求文档
    ├── architecture.md             // 架构文档
    ├── detailed_design.md          // 详细设计文档
    └── development_plan.md         // 开发计划文档

2. 技术栈选型

2.1 后端技术栈

技术组件	版本	用途	选型理由
Node.js	>=16.0.0	运行时环境	高性能、异步I/O、丰富的生态系统
Express.js	^4.18.2	Web框架	轻量级、灵活、中间件生态丰富
MySQL2	^3.14.3	数据库驱动	支持Promise、连接池、性能优化
JWT	^9.0.2	身份认证	无状态、安全、易于分布式部署
bcryptjs	^2.4.3	密码加密	安全性高、性能适中
Redis	^5.8.2	缓存/会话	内存存储、高性能、支持数据结构
RabbitMQ	^0.10.9	消息队列	异步处理、系统解耦（待实现）
Swagger	^6.2.8	API文档	自动化文档、接口测试
Winston	^3.11.0	日志系统	结构化日志、多传输方式

2.2 安全防护

安全组件	版本	防护类型
Helmet	^7.1.0	安全头部
express-rate-limit	^7.1.5	请求限流
xss-clean	^0.1.4	XSS防护
hpp	^0.2.3	参数污染防护
express-mongo-sanitize	^2.2.0	NoSQL注入防护

2.3 前端技术栈

项目	技术栈	状态
微信小程序	uni-app + Vue 2	开发中
后台管理系统	Vue 3 + TypeScript + Ant Design Vue + Pinia	开发中
官网系统	HTML5 + Bootstrap + JavaScript	待开发

2.6 选型理由与对比分析

后端技术栈选型理由

Node.js (TypeScript) + Express.js

优势：
- 高性能：Node.js基于事件驱动和非阻塞I/O模型，适合高并发场景
- 生态丰富：npm生态系统庞大，可快速集成各种第三方库
- 全栈统一：前后端均可使用JavaScript/TypeScript，降低开发成本
- 轻量级：Express.js是一个轻量级的Web框架，灵活性高
- RBAC支持：完善的权限管理中间件生态，支持JWT和RBAC权限控制
劣势：
- CPU密集型任务处理能力较弱
- 回调地狱问题（TypeScript可有效缓解）

前端技术栈选型理由

uni-app

优势：
- 一套代码多端运行：可同时发布到iOS、Android、H5、以及各种小程序平台
- 开发生态：基于Vue.js，学习成本低，社区活跃
- 性能优化：接近原生应用的性能体验
劣势：
- 平台限制：某些平台特定功能需要特殊处理
- 复杂度：多端兼容可能带来额外的复杂性

后台管理系统 (Vue.js 3 + TypeScript + Ant Design Vue + Pinia)

优势：
- 类型安全: TypeScript提供编译时类型检查，减少运行时错误
- 开发体验: Vue 3 Composition API + <script setup>语法提供更好的代码组织和复用
- 企业级UI: Ant Design Vue提供专业的企业级UI组件和设计规范
- 状态管理: Pinia提供轻量级、类型安全的状态管理方案，替代Vuex
- 构建性能: Vite构建工具提供极快的开发服务器启动和热重载
- 代码质量: ESLint + Prettier确保代码风格统一和质量
- 测试覆盖: Vitest + Vue Test Utils支持完整的单元测试和组件测试
劣势：
- 学习曲线: TypeScript和新的Composition API需要一定的学习成本
- 包体积: 类型系统和完整工具链会增加最终的包体积

官网技术栈选型理由

HTML5 + Bootstrap

优势：
- 简单易用：技术门槛低，开发效率高
- 兼容性好：Bootstrap提供了良好的浏览器兼容性
- 响应式设计：Bootstrap内置响应式布局，适配各种设备
- 社区活跃：Bootstrap拥有庞大的社区和丰富的组件
劣势：
- 定制性相对较弱：需要额外工作来实现独特的设计效果
- 文件体积：Bootstrap框架本身会增加页面加载体积

数据库选型理由

MySQL 5.7

优势：
- 成熟稳定：关系型数据库，事务支持完善
- 生态丰富：社区活跃，文档齐全
- 广泛兼容：MySQL 5.7在生产环境中广泛使用，兼容性好
劣势：
- 水平扩展性相对较弱
- 复杂查询性能可能不如专门的分析型数据库
- 缺少MySQL 8.0的一些新特性

缓存选型理由

Redis Cluster

优势：
- 高性能：内存数据库，读写速度极快
- 分布式支持：Redis Cluster提供高可用和水平扩展能力
- 丰富数据结构：支持字符串、哈希、列表、集合等多种数据结构
劣势：
- 内存成本：数据存储在内存中，成本较高
- 持久化性能：持久化操作可能影响性能

消息队列选型理由

RabbitMQ

优势：
- 成熟稳定：经过多年发展，稳定性好
- 协议支持：支持多种消息协议
- 灵活路由：支持多种消息路由模式
劣势：
- 吞吐量：相比Kafka等大数据消息队列，吞吐量较低
- Erlang语言：维护和调优需要掌握Erlang语言

WebSocket

优势：
- 实时性：全双工通信，实时性好
- 节省资源：相比轮询，节省网络资源
劣势：
- 连接管理：需要处理连接断开重连等问题
- 浏览器兼容性：老旧浏览器支持不好

3. 部署视图

外网:
  ├── uni-app前端用户 --- HTTPS --> API网关
  ├── 官网用户 --- HTTPS --> Nginx反向代理 --> 官网系统
  ├── 后台管理系统用户 --- HTTPS --> API网关 (Vue 3 + TypeScript + Ant Design Vue + Pinia)
  └── 第三方支付平台 <-- 支付回调 --- 后端服务

腾讯云服务器:
  ├── Nginx反向代理 --> 官网系统
  │   ├── 静态资源服务
  │   └── SSR渲染服务 (Nuxt.js)
  ├── API网关 --> 后端服务
  │   ├── 用户端API服务 (小程序接口)
  │   ├── 管理端API服务 (后台管理接口 - Vue 3 + TypeScript + Ant Design Vue + Pinia)
  │   └── 公共服务 (认证、权限等)
  ├── 后端服务 --> MySQL数据库 (包含RBAC权限表)
  ├── 后端服务 --> Redis缓存 (会话和权限缓存)
  ├── 后端服务 --> RabbitMQ消息队列
  └── 后端服务 --监控--> Prometheus监控 --> Grafana
                                      |--> ELK Stack

3.1 部署环境

云服务提供商：腾讯云
服务器配置：4台4核8GB服务器组成Kubernetes集群
负载均衡：腾讯云负载均衡CLB
SSL证书：腾讯云SSL证书服务
域名解析：腾讯云DNS解析
对象存储：腾讯云COS（用于存储图片、视频等静态资源）
CDN加速：腾讯云CDN（用于加速静态资源访问）
反向代理：Nginx
静态资源服务器：Nginx

3.2 部署流程

代码提交到Git仓库触发CI/CD流水线
通过Docker构建服务镜像并推送到镜像仓库
Kubernetes从镜像仓库拉取镜像并部署服务
配置健康检查和自动扩缩容策略
配置监控和日志收集系统
配置域名解析和SSL证书
配置Nginx反向代理和静态资源服务器

3.3 备份与灾备

数据库每日自动备份到COS
关键服务配置文件版本化管理
多可用区部署实现高可用

4. 风险分析与应对策略

4.1 技术风险

系统性能瓶颈

风险描述：随着用户量增长，系统可能面临性能瓶颈，特别是在高并发场景下。
应对策略：
- 使用Redis缓存热点数据，减少数据库访问压力
- 对数据库进行读写分离和分库分表
- 使用CDN加速静态资源访问
- 实施自动扩缩容策略，根据负载动态调整服务实例数量

数据安全风险

风险描述: 系统涉及用户个人信息、支付信息等敏感数据，存在数据泄露风险。管理员后台权限控制不当可能导致数据泄露。
应对策略:
- 对敏感数据进行加密存储（AES/RSA算法）
- 实施严格的访问控制和身份认证机制
- 采用RBAC权限模型，严格控制管理员操作权限
- 定期进行安全审计和渗透测试
- 遵循GDPR等数据保护法规要求
- 管理员操作日志记录和审计

4.2 业务风险

用户增长压力

风险描述：产品上线后可能面临用户快速增长的压力，对系统稳定性提出挑战。
应对策略：
- 提前进行压力测试，评估系统承载能力
- 设计可水平扩展的架构，支持快速扩容
- 制定限流和降级策略，保证核心功能稳定运行

商家服务质量风险

风险描述: 商家用户提供的服务质量和用户体验直接影响平台声誉。管理员审核不严可能导致低质量商家入驻。
应对策略:
- 建立商家资质审核机制
- 实施用户评价体系，公开服务评价
- 建立投诉处理机制，及时处理用户反馈
- 对低质量商家实施警告、限流或清退措施
- 管理员审核流程标准化和权限分级

4.3 运维风险

系统监控不足

风险描述：缺乏有效的监控可能导致问题发现不及时，影响用户体验。
应对策略：
- 建立全方位监控体系，包括基础设施、应用性能、业务指标等
- 设置合理的告警阈值和通知机制
- 定期审查和优化监控策略

故障恢复能力

风险描述：系统故障可能导致服务中断，影响业务连续性。
应对策略：
- 制定详细的应急预案和故障恢复流程
- 定期进行故障演练，验证恢复能力
- 实施多可用区部署，提高容灾能力
- 建立数据库备份和恢复机制

27 KiB Raw Blame History Unescape Escape