# 天远 API 服务器 - 微服务架构文档 ## 项目概述 天远 API 服务器是一个基于 `go-zero` 框架构建的微服务架构系统，主要提供数据加密传输、用户管理、产品管理、支付等核心业务功能。整个系统采用微服务架构模式，每个服务独立部署，通过 gRPC 和 HTTP 进行通信。 ## 技术栈 - **微服务框架**: go-zero - **编程语言**: Go - **数据库**: MySQL - **缓存**: Redis - **消息队列**: Kafka (通过 kq) - **服务注册发现**: Etcd - **API 协议**: HTTP/REST + gRPC - **加密**: AES, MD5 - **第三方服务**: 阿里云短信、七牛云存储、百度 AI、支付宝支付 ## 整体架构图 ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ 客户端应用 │ │ 管理端应用 │ │ 第三方系统 │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ API 网关层 │ │ (gateway-api) │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 微服务集群 │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ API │ │ User │ │ Sentinel │ │ Admin │ │ │ │ Service │ │ Service │ │ Service │ │ Service │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ MQS │ │ Index │ │ WestDex │ │ 共享包 │ │ │ │ Service │ │ Service │ │ Module │ │ (pkg) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 基础设施层 │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ MySQL │ │ Redis │ │ Kafka │ │ Etcd │ │ │ │ Database │ │ Cache │ │MessageQueue │ │Service Disc │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ## 服务详细说明 ### 1. Gateway Service (网关服务) **路径**: `apps/gateway/` **功能**: - 统一入口网关，处理所有外部请求 - 用户认证与授权 - 企业认证管理 - 产品信息查询 - 用户产品管理 - 充值管理 - 白名单管理 **API 端点**: - `/api/console/auth/*` - 认证相关（登录、注册、验证码） - `/api/console/user/*` - 用户管理（用户信息、企业认证） - `/api/console/product/*` - 产品管理 - `/api/console/user-product/*` - 用户产品关联 - `/api/console/topup/*` - 充值管理 - `/api/console/whitelist/*` - 白名单管理 **依赖**: - UserRpc: 用户服务的 gRPC 客户端 - SentinelRpc: 哨兵服务的 gRPC 客户端 ### 2. API Service (核心 API 服务) **路径**: `apps/api/` **功能**: - 核心业务 API 处理 - 数据加密解密 - 第三方接口代理 - 业务逻辑处理 **业务模块**: - **IVYZ**: 数据查询服务 (7 个 API 端点) - **FLXG**: 风险评估服务 (12 个 API 端点) - **QYGL**: 企业管理服务 (6 个 API 端点) - **YYSY**: 应用系统服务 (7 个 API 端点) - **JRZQ**: 金融征信服务 (4 个 API 端点) - **COMB**: 组合业务服务 (1 个 API 端点) **特点**: - 所有 API 都需要通过 `ApiAuthInterceptor` 中间件认证 - 数据采用 AES 加密传输 - 集成了消息队列服务记录 API 调用 ### 3. User Service (用户服务) **路径**: `apps/user/` **功能**: - 用户注册、登录、认证 - 企业认证管理 - 钱包服务（余额、充值、扣款） - API 请求记录管理 **gRPC 服务**: - `Auth`: 用户认证服务 - `User`: 用户信息服务 - `WalletService`: 钱包服务 - `Enterprise`: 企业服务 - `ApiRequestService`: API 请求记录服务 **数据模型**: - 用户信息 - 企业认证信息 - 钱包余额 - 扣款记录 - 充值记录 - API 请求记录 ### 4. Sentinel Service (哨兵服务) **路径**: `apps/sentinel/` **功能**: - 产品管理 - 用户产品关联管理 - 白名单管理 - 密钥管理 - 支付管理 **gRPC 服务**: - `product`: 产品服务 - `userProduct`: 用户产品服务 - `whitelist`: 白名单服务 - `secret`: 密钥服务 - `topUp`: 充值服务 ### 5. Admin Service (管理端服务) **路径**: `apps/admin/` **功能**: - 管理员认证 - 企业审核管理 - 产品管理 - 用户管理 - 用户充值 **API 模块**: - `auth`: 管理员登录 - `review`: 企业审核 - `product`: 产品 CRUD 操作 - `user`: 用户管理和充值 ### 6. MQS Service (消息队列服务) **路径**: `apps/mqs/` **功能**: - 消息队列消费者服务 - API 请求记录处理 - 异步任务处理 **特点**: - 监听 Kafka 消息队列 - 处理 API 请求日志 - 支持分布式消息处理 ### 7. Index Service (索引服务) **路径**: `apps/index/` **功能**: - 产品索引服务 - 搜索功能支持 ### 8. WestDex Module (西部对接模块) **路径**: `westDex/` **功能**: - 第三方西部数据源对接 - 数据加密解密 - 独立运行的数据处理模块 ## 共享包 (pkg/) ### 1. crypto - AES 加密解密 - MD5 哈希 - 西部数据源专用加密 ### 2. errs - 统一错误处理 - API 错误码定义 ### 3. jwt - JWT 令牌生成和验证 ### 4. models - 消息队列数据模型 - 通用数据结构 ### 5. response - 统一响应格式 ### 6. generate - 支付相关生成器 ### 7. sqlutil - 数据库工具函数 ## 中间件系统 ### 1. AuthInterceptor - 用户身份认证 - JWT 令牌验证 - 用户上下文注入 ### 2. ApiAuthInterceptor - API 调用认证 - 签名验证 - 限流控制 ### 3. EntAuthInterceptor - 企业认证检查 - 企业用户权限验证 ### 4. ApiMqsInterceptor - API 调用记录 - 消息队列发送 ## 数据库设计 ### 主要数据表 - `users`: 用户基础信息 - `enterprises`: 企业认证信息 - `products`: 产品信息 - `user_products`: 用户产品关联 - `wallets`: 钱包信息 - `recharge_records`: 充值记录 - `deduction_records`: 扣款记录 - `api_requests`: API 请求记录 - `pay_orders`: 支付订单 - `whitelists`: 白名单 - `secrets`: 密钥管理 ## 配置管理 每个服务都支持多环境配置： - `etc/*.yaml`: 生产环境配置 - `etc/*.dev.yaml`: 开发环境配置 **主要配置项**: - 数据库连接 (MySQL) - 缓存配置 (Redis) - 服务发现 (Etcd) - 第三方服务 (阿里云、七牛云、百度 AI) - JWT 配置 - 消息队列配置 ## 部署架构 ### Docker 化部署 每个服务都有独立的 Dockerfile： - `apps/*/Dockerfile` ### 服务发现 - 使用 Etcd 作为服务注册中心 - gRPC 服务自动注册和发现 ### 负载均衡 - 通过 go-zero 内置的负载均衡机制 - 支持多种负载均衡策略 ## 安全机制 ### 1. 数据传输安全 - AES 加密传输 - HTTPS 协议 - 签名验证 ### 2. 身份认证 - JWT 令牌认证 - 多级权限控制 - 白名单机制 ### 3. 数据存储安全 - 数据库密码加密 - 敏感信息脱敏 - 访问日志记录 ## 监控与日志 ### 日志系统 - 结构化日志记录 - 分级日志管理 - 链路追踪支持 ### 监控指标 - API 调用统计 - 服务健康检查 - 性能指标监控 ## 扩展性设计 ### 水平扩展 - 无状态服务设计 - 数据库读写分离支持 - 缓存集群支持 ### 模块化设计 - 微服务独立部署 - 插件化业务模块 - 模板化代码生成 ## 开发规范 ### 代码结构 每个微服务遵循 go-zero 标准结构： ``` service/ ├── internal/ │ ├── config/ # 配置定义 │ ├── handler/ # HTTP处理器 │ ├── logic/ # 业务逻辑 │ ├── svc/ # 服务上下文 │ ├── types/ # 类型定义 │ └── middleware/ # 中间件 ├── etc/ # 配置文件 ├── *.api # API定义文件 ├── *.proto # protobuf定义 └── Dockerfile # 容器化配置 ``` ### API 设计规范 - RESTful API 设计 - 统一错误码 - 标准化响应格式 - 版本控制支持 ## 总结 天远 API 服务器采用了现代化的微服务架构，具备良好的可扩展性、可维护性和安全性。通过 go-zero 框架的支持，实现了高性能的服务间通信和统一的开发规范。整个系统支持多环境部署、监控告警、日志追踪等企业级特性，是一个完整的商业级 API 服务平台。