# 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) - 对象存储配置说明