363045841 的博客

Appearance

好的，我已理解您的要求。以下是对 SPCC 智慧港口通关系统完整架构的纯文字描述，不含任何表格或框线。

一、系统概述 ​

SPCC（Smart Port Clearance Control）是一套完整的智慧港口通关管理系统，核心功能是通过 RFID 技术实现车辆、集装箱、司机的自动识别、权限验证和通行控制，并额外提供 AI 智能问答功能，用于对通行记录进行自然语言查询与分析。

二、系统架构 ​

系统整体采用分层架构，从下至上依次为：

  • 设备模拟层：使用 Go 语言开发的 rfidmocker 服务，模拟 RFID 读卡器，通过 MQTT 协议持续生成测试数据。
  • 网关层：rfid-gateway 服务（Go 语言）订阅 MQTT 消息，对数据进行校验、添加元数据后，通过 RabbitMQ 转发至后端。
  • 后端服务层：spcc_backend（Spring Boot + PostgreSQL）负责所有业务逻辑，包括档案管理、权限验证、规则引擎执行和通行记录存储。
  • AI 服务层：ai 服务（FastAPI + LangChain）对接智谱 AI 大模型，为前端提供智能问答能力。
  • 用户层：front-end-smart-port（Vue 3 + Element Plus）提供前端界面，包含档案管理、通行记录查询、AI 问答等模块。

数据流自下而上，模拟器产生的 RFID 读卡数据经过网关和后端处理，最终存入数据库；前端通过 REST API 与后端交互，AI 问答则通过单独的服务与后端和大模型通信。

三、各子项目详解 ​

1. rfidmocker - RFID 数据模拟器 ​

  • 技术栈：Go 1.24，使用 paho. mqtt. golang 库。
  • 功能：模拟多个 RFID 读卡器，以可配置的频率（默认每秒一条）向 MQTT 主题 port/rfid/data 发布测试数据。
  • 数据格式：包含终端 ID（TID）、标签编码（EPC）、时间戳（TS）和位置（LOC）。
  • 模拟策略：约 80% 的数据对应已注册的标签（模拟正常通行），20% 为未注册标签（模拟拦截场景）。

2. rfid-gateway - RFID 网关 ​

  • 技术栈：Go 1.24，集成 MQTT 客户端与 RabbitMQ 客户端（amqp）。
  • 功能：
    • 订阅 port/rfid/data 主题，接收模拟器发来的数据。
    • 对 JSON 数据进行校验（如字段完整性）。
    • 在消息中添加网关 ID 和处理时间戳。
    • 将处理后的数据发布到 RabbitMQ 的 rfid_processed_data 队列，供后端消费。
  • 输出格式：在原数据基础上封装了 GatewayID 和 Timestamp 字段。

3. spcc_backend - 核心后端服务 ​

  • 技术栈：Spring Boot 4.0.4 + Java 25，使用 Spring Data JPA 和 Hibernate 作为 ORM，数据库为 PostgreSQL，通过 RabbitMQ 消费消息，并提供 OpenAPI（Swagger）文档。

数据库 Schema 设计

数据库按业务领域划分为多个 schema：

  • archive：存储档案类数据，包括公司、车辆、集装箱、司机、RFID 标签、闸口、终端等基础信息。
  • permission：存储权限相关数据，如黑白名单、通行权限、业务规则等。
  • pass：存储通行记录，按时间进行分区，以支持大数据量和高性能查询。
  • anomaly：存储异常事件和 AI 分析报告。
  • system：存储系统用户、审计日志和性能监控数据。

核心业务模块

  • 档案管理：管理公司、车辆、集装箱、司机、RFID 标签等基础档案，支持标签与车辆/集装箱/司机的绑定。
  • 设备管理：管理闸口（入口/出口/地磅）和 RFID 终端设备，终端关联到具体闸口。
  • 访问控制：
    • 黑白名单：分为 WHITELIST（快速放行）、BLACKLIST（直接拦截）、GRAYLIST（灰名单观察）。
    • 通行权限：支持时间窗口、通行次数限制、允许通行的闸口等精细控制。
    • 业务规则引擎：支持自定义规则（PASS/BLOCK/ALERT），规则可组合复杂条件（AND/OR），支持 EQ/NEQ/GT/LT/IN 等多种操作符，并按优先级排序执行。
  • 通行处理服务：核心处理流程为：消费 RabbitMQ 消息 → 解析标签 → 黑名单检查 → 白名单检查 → 规则引擎执行 → 通行权限验证 → 记录通行结果。验证优先级为黑名单最高，白名单次之，随后是规则引擎和通行权限。
  • 通行记录：使用分区表存储，完整记录每次通行的闸口、终端、目标、结果和耗时等信息，并提供多条件分页查询接口。

4. front-end-smart-port - 前端系统 ​

  • 技术栈：Vue 3.4 + TypeScript，Element Plus 作为 UI 库，ECharts 用于图表可视化，Vue Router 管理路由，Vite 作为构建工具。
  • 页面模块：系统包含多个功能页面，包括：
    • 仪表盘（Home）：展示系统概览，包含档案统计、异常事件、图表等。
    • 档案管理类：车辆、集装箱、司机、公司、RFID 标签等。
    • 设备管理类：闸口管理、终端管理。
    • 权限控制类：通行权限、黑白名单、业务规则配置。
    • 记录查询类：通行记录查询。
    • 系统管理类：用户管理。
    • AI 问答（AiQA）：提供自然语言对话界面，支持会话上下文，能够以 Markdown 格式渲染 AI 回复，用户可提问如“查询最后一次通行记录”等自然语言问题。

5. ai - AI 智能问答服务 ​

  • 技术栈：FastAPI（Python Web 框架）、LangChain（Agent 框架）、智谱 AI GLM-4.5-air 大语言模型，支持 SSE（Server-Sent Events）流式输出。
  • 核心功能：
    • 接收前端传来的自然语言问题。
    • 通过 LangChain 定义的 Tool（如 get_pass_records）自动判断是否需要调用后端 API 获取通行记录数据。
    • 将数据与问题结合，交由大模型进行智能分析和总结。
    • 支持同步返回和流式输出两种响应模式。
  • 工具定义：get_pass_records 工具封装了对后端通行记录查询接口的调用，可接受闸口 ID、时间范围、分页参数等。
  • API 接口：提供 /api/ai/chat（流式对话）和 /api/ai/chat/sync（同步对话）两个主要接口，以及健康检查接口。

四、数据流向 ​

系统数据流向清晰，主要分为两条路径：

  1. RFID 数据流：

    • rfidmocker 模拟器通过 MQTT 发布数据到 port/rfid/data。
    • rfid-gateway 订阅该主题，处理并转发至 RabbitMQ 队列 rfid_processed_data。
    • spcc_backend 消费队列中的消息，执行通行处理流程，并将结果写入 PostgreSQL。

  2. 用户交互与 AI 问答流：

    • 用户通过 front-end-smart-port 操作界面，发起 REST API 请求到 spcc_backend（如档案增删改查）。
    • 用户在 AI 问答界面输入自然语言问题，请求发送到 ai 服务。
    • ai 服务判断是否需要查询数据，如需则调用 spcc_backend 的 API 获取通行记录。
    • ai 服务将获取的数据与问题一并提交给智谱 AI 大模型，获取回答后返回给前端。

五、部署架构 ​

各服务部署在独立节点或容器中，关键服务及端口如下：

  • rfidmocker：无固定端口，部署于测试环境。
  • rfid-gateway：部署于边缘节点，与 MQTT Broker 和 RabbitMQ 通信。
  • spcc_backend：部署于应用服务器，对外提供 REST API，端口 8082。
  • ai 服务：部署于应用服务器，对外提供 AI 问答接口，端口 5000。
  • PostgreSQL：数据库服务器，端口 5432。
  • RabbitMQ：消息服务器，端口 5672。
  • MQTT Broker：边缘网关，端口 1883。

六、项目亮点 ​

  • 完整的物联网数据链路：从 RFID 模拟、MQTT 传输、网关协议转换、RabbitMQ 异步解耦，到后端业务处理，形成闭环。
  • 灵活的规则引擎：支持 JSON 配置复杂业务规则，可灵活扩展通行控制策略。
  • AI 赋能：通过自然语言即可查询和分析通行记录，降低了数据使用门槛。
  • 多 Schema 数据库设计：按业务域划分 schema，结构清晰，便于维护和扩展。
  • 分区表：通行记录采用时间分区表，支撑海量数据存储与高效查询。
  • 软删除：所有实体支持逻辑删除，保证数据可追溯性。
  • 完善的权限控制：黑白名单、时间窗口、通行次数等多维度权限验证机制，保障通关安全。