From 4dbd6f075f4ac31e886a4fceb83646f7f76ac720 Mon Sep 17 00:00:00 2001 From: hailin Date: Thu, 22 Jan 2026 23:05:41 -0800 Subject: [PATCH] docs: reorganize documentation and add architecture document MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Changes: - Create docs/ directory for centralized documentation - Move DEVELOPMENT_GUIDE.md from root to docs/ - Add comprehensive ARCHITECTURE.md with: - System overview and architecture diagrams (ASCII) - Microservices responsibilities (6 services) - Technology stack details - Data flow diagrams (user conversation, admin evolution) - Production deployment architecture - Kong API routing table - Port mapping reference - Database schema overview (PostgreSQL, Neo4j, MinIO) - Security design notes - Update README.md with documentation index table Documentation structure: docs/ ├── ARCHITECTURE.md - System architecture reference └── DEVELOPMENT_GUIDE.md - Development guide and code examples Co-Authored-By: Claude Opus 4.5 --- README.md | 8 +- docs/ARCHITECTURE.md | 442 ++++++++++++++++++ .../DEVELOPMENT_GUIDE.md | 0 3 files changed, 448 insertions(+), 2 deletions(-) create mode 100644 docs/ARCHITECTURE.md rename DEVELOPMENT_GUIDE.md => docs/DEVELOPMENT_GUIDE.md (100%) diff --git a/README.md b/README.md index 08098c1..247e003 100644 --- a/README.md +++ b/README.md @@ -138,9 +138,13 @@ WECHAT_APP_ID=xxx 完整配置请参考 `.env.example` -## 开发指南 +## 文档 -详细的开发指导请参考 [DEVELOPMENT_GUIDE.md](./DEVELOPMENT_GUIDE.md) +| 文档 | 说明 | +|------|------| +| [架构文档](./docs/ARCHITECTURE.md) | 系统整体架构、服务职责、数据流、部署配置 | +| [开发指南](./docs/DEVELOPMENT_GUIDE.md) | 详细开发指导、代码示例、API 设计 | +| [MinIO 配置](./infrastructure/minio/README.md) | 对象存储配置说明 | ## 开发进度 diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..229c4fe --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,442 @@ +# 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) - 对象存储配置说明 diff --git a/DEVELOPMENT_GUIDE.md b/docs/DEVELOPMENT_GUIDE.md similarity index 100% rename from DEVELOPMENT_GUIDE.md rename to docs/DEVELOPMENT_GUIDE.md