iConsulting 系统架构文档
目录
系统概述
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 图模型
(: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/ # 导出文件
安全设计
认证机制
- 用户认证: 匿名 fingerprint → JWT
- 管理员认证: 用户名密码 → bcrypt 验证 → JWT
- API 认证: JWT Bearer Token
安全措施
- HTTPS (SSL/TLS)
- CORS 白名单
- 请求限流
- SQL 注入防护 (TypeORM 参数化)
- XSS 防护 (React 自动转义)
- 文件类型验证
- MinIO 预签名 URL (临时访问)
扩展性设计
水平扩展
- 微服务无状态设计，支持多实例部署
- Redis 分布式会话
- Kong 负载均衡
垂直扩展
- 数据库读写分离（预留）
- 消息队列（Kafka 已预留）
- 缓存分层
相关文档