tian/kangda-robot-backend

Fork 0

Tian jianyong acf1f7c568 增加架构文档

2025-12-12 11:16:28 +08:00

10 KiB

Raw Blame History

康达机器人系统架构文档

1. 系统概述

康达机器人系统是一个集机器人控制、人脸识别、门禁管理、文档检索和智能对话于一体的综合性管理平台。系统采用前后端分离架构，集成了多种外部服务和AI能力，为用户提供全面的机器人管理和控制解决方案。

2. 系统架构图

flowchart TD
    subgraph 客户端层
        Web控制台["Web控制台\n(管理界面)"]
        Pad控制端["Pad控制端\n(现场操作)"]
    end

    subgraph 后端服务层
        FastAPI["FastAPI后端服务\n(核心业务逻辑)"]
        Redis["Redis缓存\n(会话、数据缓存)"]
        Database[("数据库\n(MySQL/PostgreSQL)")]
    end

    subgraph 外部服务层
        RAGFlow["RAGFlow\n(文档检索与智能对话)"]
        SearchAPI["搜索API\n(SerpAPI)"]
        Compreface["Compreface\n(人脸识别)"]
        HaiKang["海康平台\n(门禁控制)"]
    end

    subgraph 设备层
        Robot["机器人\n(执行动作、采集数据)"]
        Door["门禁设备\n(开关控制)"]
        Camera["摄像头\n(图像采集)"]
    end

    %% 连接关系
    Web控制台 -->|HTTP请求| FastAPI
    Pad控制端 -->|HTTP请求| FastAPI
    FastAPI -->|读写数据| Database
    FastAPI -->|缓存操作| Redis
    FastAPI -->|调用接口| RAGFlow
    FastAPI -->|搜索增强| SearchAPI
    FastAPI -->|人脸识别| Compreface
    FastAPI -->|门禁控制| HaiKang
    FastAPI -->|控制指令| Robot
    HaiKang -->|控制| Door
    Camera -->|图像数据| Compreface
    Robot -->|状态反馈| FastAPI
    Door -->|状态反馈| HaiKang
    HaiKang -->|状态更新| FastAPI

    %% 大模型服务
    RAGFlow -->|调用| LLM["大语言模型\n(云上服务)"]
    SearchAPI -->|调用| SearchEngine["搜索引擎\n(第三方)"]

3. 系统组件说明

3.1 客户端层

Web控制台

功能：提供系统管理、用户管理、角色管理、机器人配置、讲解内容管理等功能
技术：Vue.js + Element Plus
访问方式：浏览器访问

Pad控制端

功能：现场控制机器人、查看实时状态、处理识别记录
技术：Web应用（适配Pad设备）
访问方式：Pad浏览器或专用应用

3.2 后端服务层

FastAPI后端服务

核心功能：
- 提供RESTful API接口
- 处理业务逻辑
- 集成各种外部服务
- 权限管理与认证
- 系统监控与日志
主要模块：
- 用户管理模块
- 角色管理模块
- 机器人信息管理模块
- 机器人动作管理模块
- 门禁设备管理模块
- 识别记录管理模块
- RAGFlow文档管理模块
- 人脸识别管理模块
- 系统统计模块

Redis缓存

功能：
- 会话管理
- 数据缓存
- 分布式锁
- 消息队列（可选）

数据库

功能：存储系统配置、用户信息、机器人数据、识别记录等持久化数据
支持类型：MySQL、PostgreSQL

3.3 外部服务层

RAGFlow

功能：
- 文档检索与管理
- 智能对话（基于大语言模型）
- 知识库管理
集成方式：API调用

搜索API

功能：
- 增强智能对话的搜索能力
- 提供实时信息查询
技术：SerpAPI

Compreface

功能：
- 人脸识别
- 人脸比对
- 人脸检测
集成方式：API调用

海康平台

功能：
- 门禁设备管理
- 门禁状态查询
- 门禁控制（开关门）
- 门禁事件记录
集成方式：API调用

3.4 设备层

机器人

功能：
- 执行预设动作
- 采集环境数据
- 接收并执行控制指令
- 反馈执行状态

门禁设备

功能：
- 开关门控制
- 状态反馈
- 事件记录

摄像头

功能：
- 图像采集
- 视频监控
- 人脸数据采集

4. 核心工作流程

4.1 用户认证流程

sequenceDiagram
    participant 用户 as 用户
    participant Web as Web控制台/Pad控制端
    participant FastAPI as FastAPI后端
    participant Redis as Redis缓存
    participant DB as 数据库

    用户->>Web: 输入用户名密码
    Web->>FastAPI: POST /system/user/login
    FastAPI->>DB: 查询用户信息
    DB-->>FastAPI: 返回用户数据
    FastAPI->>FastAPI: 验证密码
    FastAPI->>Redis: 生成并存储token
    Redis-->>FastAPI: 返回token
    FastAPI-->>Web: 返回token和用户信息
    Web->>Web: 存储token

4.2 门禁控制流程

sequenceDiagram
    participant Pad as Pad控制端
    participant FastAPI as FastAPI后端
    participant HaiKang as 海康平台API
    participant Door as 门禁设备

    Pad->>FastAPI: POST /system/door/control_door
    FastAPI->>HaiKang: 请求门禁控制
    HaiKang->>Door: 发送开关指令
    Door-->>HaiKang: 执行结果
    HaiKang-->>FastAPI: 返回控制结果
    FastAPI-->>Pad: 返回操作状态

4.3 人脸识别流程

sequenceDiagram
    participant Camera as 摄像头
    participant Compreface as Compreface
    participant FastAPI as FastAPI后端
    participant DB as 数据库
    participant Robot as 机器人

    Camera->>Compreface: 上传人脸图像
    Compreface->>Compreface: 检测人脸
    Compreface->>Compreface: 提取特征
    Compreface->>FastAPI: 返回识别结果
    FastAPI->>DB: 保存识别记录
    FastAPI->>Robot: 发送响应指令
    Robot-->>FastAPI: 执行结果

4.4 智能对话流程

sequenceDiagram
    participant User as 用户
    participant Web as Web/Pad客户端
    participant FastAPI as FastAPI后端
    participant Redis as Redis缓存
    participant RAGFlow as RAGFlow
    participant Search as 搜索API
    participant LLM as 大语言模型

    User->>Web: 输入问题
    Web->>FastAPI: POST /system/ragflow/converse_with_chat_assistant
    FastAPI->>Redis: 检查缓存
    alt 缓存命中
        Redis-->>FastAPI: 返回缓存结果
    else 缓存未命中
        FastAPI->>RAGFlow: 发送对话请求
        RAGFlow->>Search: 检查是否需要搜索增强
        alt 需要搜索增强
            Search->>SearchEngine: 执行搜索
            SearchEngine-->>Search: 返回搜索结果
            Search-->>RAGFlow: 返回搜索内容
        end
        RAGFlow->>LLM: 调用大语言模型
        LLM-->>RAGFlow: 返回生成内容
        RAGFlow-->>FastAPI: 返回对话结果
        FastAPI->>Redis: 存储结果到缓存
    end
    FastAPI-->>Web: 返回对话结果
    Web->>User: 显示回答

5. 系统集成与依赖

5.1 内部依赖

依赖名称	用途	版本
FastAPI	后端框架	最新
SQLAlchemy	ORM框架	最新
Redis	缓存服务	最新
Pydantic	数据验证	最新
python-jose	JWT认证	最新

5.2 外部服务依赖

服务名称	用途	集成方式
RAGFlow	文档检索与智能对话	API调用
Compreface	人脸识别	API调用
海康平台	门禁控制	API调用
SerpAPI	搜索增强	API调用

6. 系统特性与优势

模块化设计：系统采用模块化架构，各功能模块独立，便于维护和扩展
前后端分离：前端使用Vue.js，后端使用FastAPI，提高开发效率和系统性能
多端支持：支持Web控制台和Pad控制端，满足不同场景的使用需求
AI能力集成：集成了人脸识别、智能对话和搜索增强等AI能力，提升系统智能化水平
丰富的外部接口：与门禁系统、机器人硬件等多种外部设备和服务进行集成
完善的权限管理：支持基于角色的权限控制，确保系统安全
实时监控与统计：提供系统统计和识别记录管理，便于数据分析和决策

7. 系统部署架构

flowchart TD
    subgraph 服务器集群
        LoadBalancer["负载均衡器\n(Nginx)"]
        Backend1["FastAPI节点1"]
        Backend2["FastAPI节点2"]
        Backend3["FastAPI节点3"]
    end

    subgraph 数据层
        DB[("主数据库\n(MySQL/PostgreSQL)")]
        DB2[("从数据库\n(MySQL/PostgreSQL)")]
        RedisCluster["Redis集群\n(主从架构)"]
    end

    subgraph 外部服务
        RAGFlow["RAGFlow服务"]
        Compreface["Compreface服务"]
        HaiKang["海康平台"]
    end

    用户["用户"] -->|HTTP请求| LoadBalancer
    LoadBalancer -->|分发请求| Backend1
    LoadBalancer -->|分发请求| Backend2
    LoadBalancer -->|分发请求| Backend3
    
    Backend1 -->|读写| DB
    Backend2 -->|读写| DB
    Backend3 -->|读写| DB
    DB -->|同步| DB2
    
    Backend1 -->|缓存操作| RedisCluster
    Backend2 -->|缓存操作| RedisCluster
    Backend3 -->|缓存操作| RedisCluster
    
    Backend1 -->|API调用| RAGFlow
    Backend2 -->|API调用| RAGFlow
    Backend3 -->|API调用| RAGFlow
    
    Backend1 -->|API调用| Compreface
    Backend2 -->|API调用| Compreface
    Backend3 -->|API调用| Compreface
    
    Backend1 -->|API调用| HaiKang
    Backend2 -->|API调用| HaiKang
    Backend3 -->|API调用| HaiKang

8. 系统扩展性设计

微服务架构支持：系统可扩展为微服务架构，将不同功能模块拆分为独立服务
插件化设计：支持通过插件方式扩展系统功能
API网关集成：可集成API网关，统一管理API访问
容器化部署：支持Docker容器化部署，便于水平扩展
云原生支持：支持在Kubernetes等容器编排平台上部署

9. 系统安全设计

身份认证与授权：采用JWT令牌机制，支持基于角色的访问控制
数据加密：敏感数据加密存储，传输过程使用HTTPS
接口安全：所有API接口均需认证，部分接口需额外权限验证
日志审计：记录所有用户操作和系统事件，便于审计和追踪
防SQL注入：使用ORM框架和参数化查询，防止SQL注入攻击
防XSS攻击：对输入输出进行过滤，防止跨站脚本攻击

10. 总结

康达机器人系统采用现代化的技术架构，集成了多种AI能力和外部服务，为用户提供全面的机器人管理和控制解决方案。系统具有良好的扩展性、安全性和可维护性，能够满足不同规模和场景的使用需求。

10 KiB Raw Blame History Unescape Escape