443 lines
20 KiB
Markdown
443 lines
20 KiB
Markdown
# iConsulting 系统架构文档
|
||
|
||
## 目录
|
||
|
||
- [系统概述](#系统概述)
|
||
- [整体架构](#整体架构)
|
||
- [服务架构](#服务架构)
|
||
- [技术栈](#技术栈)
|
||
- [数据流](#数据流)
|
||
- [部署架构](#部署架构)
|
||
- [API 路由](#api-路由)
|
||
- [数据存储](#数据存储)
|
||
|
||
---
|
||
|
||
## 系统概述
|
||
|
||
iConsulting 是一个基于 Claude AI 的香港移民智能咨询系统，采用微服务架构，支持：
|
||
|
||
- **智能对话**: 基于 Claude API 的多模态 AI 对话
|
||
- **知识增强**: RAG + Neo4j 知识图谱
|
||
- **自我进化**: 从对话中学习经验，持续优化
|
||
- **文件处理**: 支持图片、PDF 等文件上传与 AI 分析
|
||
|
||
---
|
||
|
||
## 整体架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ 客户端层 │
|
||
├─────────────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌─────────────────────┐ ┌─────────────────────┐ │
|
||
│ │ Web Client │ │ Admin Client │ │
|
||
│ │ (React + TS) │ │ (React + Ant) │ │
|
||
│ │ │ │ │ │
|
||
│ │ • 用户咨询界面 │ │ • 知识库管理 │ │
|
||
│ │ • 多模态文件上传 │ │ • 经验库管理 │ │
|
||
│ │ • 实时流式对话 │ │ • 系统配置 │ │
|
||
│ └─────────────────────┘ └─────────────────────┘ │
|
||
│ │ │ │
|
||
└────────────┼───────────────────────────────────┼────────────────────────────┘
|
||
│ │
|
||
▼ ▼
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ Nginx 反向代理 (SSL 终止) │
|
||
│ │
|
||
│ / → Web Client (SPA) │
|
||
│ /admin → Admin Client (SPA) │
|
||
│ /api/v1/* → Kong API Gateway │
|
||
│ /ws/* → WebSocket (Conversation Service) │
|
||
│ /storage/* → MinIO (文件存储) │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ Kong API Gateway (DB-less) │
|
||
│ │
|
||
│ • 请求路由 • CORS 处理 • 请求限流 │
|
||
│ • 超时控制 • 负载均衡 │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ 微服务层 │
|
||
├─────────────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ User Service │ │ Conversation │ │ Knowledge │ │ Payment │ │
|
||
│ │ :3001 │ │ Service │ │ Service │ │ Service │ │
|
||
│ │ │ │ :3004 │ │ :3003 │ │ :3002 │ │
|
||
│ │ • 匿名认证 │ │ • Claude AI │ │ • RAG 检索 │ │ • 支付宝 │ │
|
||
│ │ • JWT 管理 │ │ • 流式响应 │ │ • 向量搜索 │ │ • 微信支付 │ │
|
||
│ │ • 用户信息 │ │ • WebSocket │ │ • Neo4j 图谱 │ │ • Stripe │ │
|
||
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||
│ │
|
||
│ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ Evolution │ │ File │ │
|
||
│ │ Service │ │ Service │ │
|
||
│ │ :3005 │ │ :3006 │ │
|
||
│ │ │ │ │ │
|
||
│ │ • 经验提取 │ │ • 文件上传 │ │
|
||
│ │ • 管理员认证 │ │ • MinIO 存储 │ │
|
||
│ │ • 自我进化 │ │ • 缩略图生成 │ │
|
||
│ └──────────────┘ └──────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ 基础设施层 │
|
||
├─────────────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ PostgreSQL │ │ Redis │ │ Neo4j │ │ MinIO │ │
|
||
│ │ :5432 │ │ :6379 │ │ :7474/:7687 │ │ :9000/:9001 │ │
|
||
│ │ │ │ │ │ │ │ │ │
|
||
│ │ • 用户数据 │ │ • 会话缓存 │ │ • 知识图谱 │ │ • 文件存储 │ │
|
||
│ │ • 对话历史 │ │ • 限流计数 │ │ • 用户记忆 │ │ • 图片/PDF │ │
|
||
│ │ • 订单数据 │ │ • 分布式锁 │ │ • 关系网络 │ │ • 缩略图 │ │
|
||
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ 外部服务 │
|
||
├─────────────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ Claude API │ │ OpenAI API │ │ 支付网关 │ │
|
||
│ │ (Anthropic) │ │ (Embedding) │ │ │ │
|
||
│ │ │ │ │ │ • 支付宝 │ │
|
||
│ │ • 对话生成 │ │ • 向量化 │ │ • 微信支付 │ │
|
||
│ │ • 多模态理解 │ │ │ │ • Stripe │ │
|
||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 服务架构
|
||
|
||
### 服务职责
|
||
|
||
| 服务 | 端口 | 职责 |
|
||
|------|------|------|
|
||
| **user-service** | 3001 | 用户认证（匿名/手机）、JWT 管理、用户信息 |
|
||
| **payment-service** | 3002 | 订单管理、支付宝/微信/Stripe 支付集成 |
|
||
| **knowledge-service** | 3003 | RAG 检索、向量搜索、Neo4j 知识图谱 |
|
||
| **conversation-service** | 3004 | Claude AI 对话、WebSocket 实时通信、流式响应 |
|
||
| **evolution-service** | 3005 | 管理员认证、经验提取、系统进化、经验库管理 |
|
||
| **file-service** | 3006 | 文件上传/下载、MinIO 存储、缩略图生成 |
|
||
|
||
### 服务依赖关系
|
||
|
||
```
|
||
conversation-service
|
||
├── knowledge-service (RAG 检索)
|
||
├── file-service (多模态文件)
|
||
├── PostgreSQL (对话存储)
|
||
├── Redis (会话缓存)
|
||
└── Claude API (AI 生成)
|
||
|
||
evolution-service
|
||
├── conversation-service (经验来源)
|
||
├── PostgreSQL (经验存储)
|
||
└── Claude API (经验分析)
|
||
|
||
knowledge-service
|
||
├── PostgreSQL (文档存储)
|
||
├── Neo4j (知识图谱)
|
||
└── OpenAI API (向量化)
|
||
|
||
file-service
|
||
├── MinIO (对象存储)
|
||
└── PostgreSQL (文件元数据)
|
||
```
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
### 前端
|
||
|
||
| 技术 | 用途 |
|
||
|------|------|
|
||
| React 18 | UI 框架 |
|
||
| TypeScript | 类型安全 |
|
||
| TailwindCSS | 样式 |
|
||
| Zustand | 状态管理 |
|
||
| React Query | 数据获取 |
|
||
| Socket.IO Client | WebSocket |
|
||
| Ant Design | Admin UI 组件 |
|
||
|
||
### 后端
|
||
|
||
| 技术 | 用途 |
|
||
|------|------|
|
||
| NestJS | 微服务框架 |
|
||
| TypeORM | ORM |
|
||
| Socket.IO | WebSocket |
|
||
| Anthropic SDK | Claude API |
|
||
| bcrypt | 密码加密 |
|
||
| JWT | 认证令牌 |
|
||
|
||
### 基础设施
|
||
|
||
| 技术 | 用途 |
|
||
|------|------|
|
||
| PostgreSQL 15 | 主数据库 |
|
||
| Redis 7 | 缓存 |
|
||
| Neo4j 5 | 图数据库 |
|
||
| MinIO | 对象存储 |
|
||
| Kong | API 网关 |
|
||
| Nginx | 反向代理 |
|
||
| Docker Compose | 容器编排 |
|
||
|
||
---
|
||
|
||
## 数据流
|
||
|
||
### 用户对话流程
|
||
|
||
```
|
||
用户输入 (文本/图片/文件)
|
||
│
|
||
▼
|
||
┌─────────────────┐
|
||
│ Web Client │
|
||
│ (上传文件到 │
|
||
│ file-service) │
|
||
└────────┬────────┘
|
||
│
|
||
▼
|
||
┌─────────────────┐
|
||
│ Nginx │
|
||
│ (SSL + 路由) │
|
||
└────────┬────────┘
|
||
│
|
||
▼
|
||
┌─────────────────┐
|
||
│ Kong Gateway │
|
||
│ (认证 + 限流) │
|
||
└────────┬────────┘
|
||
│
|
||
▼
|
||
┌─────────────────┐ ┌─────────────────┐
|
||
│ Conversation │────────▶│ Knowledge │
|
||
│ Service │ RAG │ Service │
|
||
│ │ 检索 │ │
|
||
└────────┬────────┘ └─────────────────┘
|
||
│
|
||
│ 构建上下文 (系统提示 + RAG 结果 + 历史消息 + 文件)
|
||
▼
|
||
┌─────────────────┐
|
||
│ Claude API │
|
||
│ (流式响应) │
|
||
└────────┬────────┘
|
||
│
|
||
▼
|
||
┌─────────────────┐
|
||
│ WebSocket │
|
||
│ (实时推送) │
|
||
└────────┬────────┘
|
||
│
|
||
▼
|
||
用户看到回复
|
||
```
|
||
|
||
### 管理员进化流程
|
||
|
||
```
|
||
管理员指令
|
||
│
|
||
▼
|
||
┌─────────────────┐
|
||
│ Admin Client │
|
||
└────────┬────────┘
|
||
│
|
||
▼
|
||
┌─────────────────┐
|
||
│ Evolution │
|
||
│ Service │
|
||
│ │
|
||
│ 1. 分析历史对话 │
|
||
│ 2. 提取经验 │
|
||
│ 3. 更新知识库 │
|
||
│ 4. 调整系统提示 │
|
||
└────────┬────────┘
|
||
│
|
||
▼
|
||
┌─────────────────┐
|
||
│ Knowledge │
|
||
│ Service │
|
||
│ (更新 RAG) │
|
||
└─────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 部署架构
|
||
|
||
### 生产环境
|
||
|
||
```
|
||
┌───────────────────┐
|
||
│ 用户请求 │
|
||
│ iconsulting. │
|
||
│ szaiai.com │
|
||
└─────────┬─────────┘
|
||
│
|
||
┌─────────▼─────────┐
|
||
│ 系统 Nginx │
|
||
│ (SSL 终止) │
|
||
│ :443 → :8080 │
|
||
└─────────┬─────────┘
|
||
│
|
||
┌────────────────────┼────────────────────┐
|
||
│ │ │
|
||
┌─────────▼─────────┐ ┌───────▼───────┐ ┌─────────▼─────────┐
|
||
│ Docker Nginx │ │ Kong │ │ MinIO Console │
|
||
│ :8080 │ │ :8000 │ │ :9001 │
|
||
└───────────────────┘ └───────────────┘ └───────────────────┘
|
||
```
|
||
|
||
### 网络配置
|
||
|
||
- **对外网卡**: 14.215.128.96 (用户访问)
|
||
- **出口网卡**: 154.84.135.121 (Claude API 调用，绕过国内限制)
|
||
- **Docker 网络**: 172.20.0.0/16 (内部服务通信)
|
||
|
||
### 端口映射
|
||
|
||
| 服务 | 容器端口 | 宿主机端口 |
|
||
|------|----------|------------|
|
||
| PostgreSQL | 5432 | 5432 |
|
||
| Redis | 6379 | 6379 |
|
||
| Neo4j HTTP | 7474 | 7474 |
|
||
| Neo4j Bolt | 7687 | 7687 |
|
||
| MinIO API | 9000 | 9000 |
|
||
| MinIO Console | 9001 | 9001 |
|
||
| Kong Proxy | 8000 | 8000 |
|
||
| Kong Admin | 8001 | 8001 |
|
||
| Nginx | 80 | 8080 |
|
||
| user-service | 3001 | 3001 |
|
||
| payment-service | 3002 | 3002 |
|
||
| knowledge-service | 3003 | 3003 |
|
||
| conversation-service | 3004 | 3004 |
|
||
| evolution-service | 3005 | 3005 |
|
||
| file-service | 3006 | 3006 |
|
||
|
||
---
|
||
|
||
## API 路由
|
||
|
||
### Kong 路由配置
|
||
|
||
| 路径前缀 | 目标服务 | 说明 |
|
||
|----------|----------|------|
|
||
| `/api/v1/users`, `/api/v1/auth` | user-service:3001 | 用户认证 |
|
||
| `/api/v1/payments`, `/api/v1/orders` | payment-service:3002 | 支付订单 |
|
||
| `/api/v1/knowledge`, `/api/v1/memory` | knowledge-service:3003 | 知识库 |
|
||
| `/api/v1/conversations`, `/api/v1/messages` | conversation-service:3004 | 对话 |
|
||
| `/api/v1/evolution`, `/api/v1/admin` | evolution-service:3005 | 进化/管理 |
|
||
| `/api/v1/files` | file-service:3006 | 文件 |
|
||
|
||
### 前端路由
|
||
|
||
| 路径 | 说明 |
|
||
|------|------|
|
||
| `/` | 用户咨询界面 (web-client) |
|
||
| `/admin/` | 管理后台 (admin-client) |
|
||
| `/admin/login` | 管理员登录 |
|
||
| `/admin/knowledge` | 知识库管理 |
|
||
| `/admin/experience` | 经验库管理 |
|
||
|
||
---
|
||
|
||
## 数据存储
|
||
|
||
### PostgreSQL 主要表
|
||
|
||
| 表名 | 说明 |
|
||
|------|------|
|
||
| `users` | 用户信息（匿名/注册） |
|
||
| `conversations` | 对话会话 |
|
||
| `messages` | 对话消息 |
|
||
| `files` | 文件元数据 |
|
||
| `orders` | 支付订单 |
|
||
| `admins` | 管理员账户 |
|
||
| `experiences` | 提取的经验 |
|
||
| `knowledge_documents` | 知识文档 |
|
||
| `system_configs` | 系统配置 |
|
||
|
||
### Neo4j 图模型
|
||
|
||
```cypher
|
||
(:User)-[:HAS_MEMORY]->(:Memory)
|
||
(:User)-[:ASKED_ABOUT]->(:Knowledge)
|
||
(:Knowledge)-[:RELATED_TO]->(:Knowledge)
|
||
(:Experience)-[:DERIVED_FROM]->(:Conversation)
|
||
```
|
||
|
||
### MinIO Bucket 结构
|
||
|
||
```
|
||
iconsulting/
|
||
├── uploads/ # 用户上传
|
||
│ ├── images/
|
||
│ ├── documents/
|
||
│ └── temp/
|
||
├── processed/ # 处理后文件
|
||
│ ├── thumbnails/
|
||
│ └── extracted/
|
||
└── exports/ # 导出文件
|
||
```
|
||
|
||
---
|
||
|
||
## 安全设计
|
||
|
||
### 认证机制
|
||
|
||
1. **用户认证**: 匿名 fingerprint → JWT
|
||
2. **管理员认证**: 用户名密码 → bcrypt 验证 → JWT
|
||
3. **API 认证**: JWT Bearer Token
|
||
|
||
### 安全措施
|
||
|
||
- HTTPS (SSL/TLS)
|
||
- CORS 白名单
|
||
- 请求限流
|
||
- SQL 注入防护 (TypeORM 参数化)
|
||
- XSS 防护 (React 自动转义)
|
||
- 文件类型验证
|
||
- MinIO 预签名 URL (临时访问)
|
||
|
||
---
|
||
|
||
## 扩展性设计
|
||
|
||
### 水平扩展
|
||
|
||
- 微服务无状态设计，支持多实例部署
|
||
- Redis 分布式会话
|
||
- Kong 负载均衡
|
||
|
||
### 垂直扩展
|
||
|
||
- 数据库读写分离（预留）
|
||
- 消息队列（Kafka 已预留）
|
||
- 缓存分层
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- [开发指南](./DEVELOPMENT_GUIDE.md) - 详细的开发文档和代码示例
|
||
- [MinIO 配置](../infrastructure/minio/README.md) - 对象存储配置说明
|