# core

**Repository Path**: PunishWicked/core

## Basic Information

- **Project Name**: core
- **Description**: 核心上传服务
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-26
- **Last Updated**: 2025-11-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Core 项目说明（Ruichi NDT）

面向无损检测（NDT）业务的高性能消息与图像处理服务。项目以 ZeroMQ 作为数据接入层、Redis Stream 作为高吞吐消息队列、Netty 与并行线程池实现计算密集型任务调度，MinIO 进行对象存储，MySQL 作为业务数据支撑。整体侧重吞吐、低延迟与稳定性。

---

## 1. 项目目标
- 接收与处理外部设备推送的图像/消息数据。
- 使用 Redis Stream 进行可靠的生产-消费处理，并支持批量、回压与重试策略。
- 将结果图像/文件写入 MinIO，便于后续归档与检索。
- 通过 Netty、线程池与性能监控，维持稳定、高吞吐的服务运行。

---

## 2. 技术栈
- 应用框架：Spring Boot
- 消息队列：Redis Stream（Lettuce 客户端）
- 网络与并发：Netty、ForkJoinPool、可配置线程池
- 对象存储：MinIO（基于 OkHttp 的高性能客户端）
- 数据访问：Druid 数据源、MyBatis / MyBatis-Plus、PageHelper
- 消息接入：ZeroMQ（Jeromq）
- 图像/文件：TwelveMonkeys、OpenCV、dcm4che（医疗影像/DICOM）
- 其它：H2（测试）、Lombok、Spring Boot Starter Test

---

## 3. 目录结构（关键路径）
- `src/main/java/com/ruichi/ndt/zmq/` - 核心业务包
  - `config/` - 应用与性能相关配置（Netty、线程池、MinIO 客户端等）
  - `redis/` - Redis 相关模块
    - `ingest/RedisStreamImageConsumer` - Redis Stream 消费者（图像/消息消费）
    - `publisher/RedisImageStreamPublisher` - Redis Stream 生产者（写入消息）
  - `layer/` - ZeroMQ 接入层（请求应答、发布订阅）
  - `queue/` - 进程内队列（如 `ImageTaskQueue`）
  - `uploader/` - 上传与批处理组件（如 `ImageUploaderPool`）
  - `monitor/PerformanceMonitor` - 性能监控与指标上报
  - `util/ParallelProcessingUtil` - 并行处理工具类
  - `coordinator/ImageProcessingCoordinator` - 图像处理三层架构协调器
- `src/main/resources/application.yml` - 应用配置（端口、Redis、MinIO、线程池等）
- `pom.xml` - 构建与依赖管理
- `app.log` - 运行日志（按需开启/轮转）

> 注：具体类名来自代码与日志，实际包内可能包含更多辅助类与组件。

---

## 4. 核心模块说明

### 4.1 配置模块（`config/`）
- `NettyConfig`：创建 `EventLoopGroup`（boss/worker），配置网络与处理器，支持高并发。
- `ThreadPoolConfig`：统一管理异步、上传、自定义 ForkJoinPool 等线程池参数。
- `MinioPerformanceConfig`：构建高性能 `OkHttpClient` 与 `MinioClient`，控制连接池、超时与并发。

### 4.2 Redis 消息流（`redis/`）
- `RedisStreamImageConsumer`：
  - 保证 Stream 与 Consumer Group 就绪（初始化时检查/创建）。
  - 批量拉取与消费消息；在 BUSYGROUP（组已存在）等场景下进行容错处理。
  - 可配置 `poll-timeout-ms`、`batch-size`、`max-length` 等参数。
- `RedisImageStreamPublisher`：
  - 将外部/内部生成的消息写入 Redis Stream。
  - 控制消息键、分区策略与回压（基于 Stream 最长度）。

### 4.3 ZeroMQ 接入层（`layer/`）
- `ZmqImageProducer` / `ZmqServer`：
  - REP（请求应答）端口与 PUB（发布）端口管理。
  - 负责接入设备端数据流，完成初步验证与入队。

### 4.4 进程内队列与上传（`queue/`、`uploader/`）
- `ImageTaskQueue`：图像任务队列，支持容量限制、入队/出队超时、累计字节上限等。
- `ImageUploaderPool`：上传线程池，支持批处理、轮询间隔与错误重试。

### 4.5 协调与并发（`coordinator/`、`util/`）
- `ImageProcessingCoordinator`：三层架构启动/健康检查/统计报告，串联接入、处理、存储链路。
- `ParallelProcessingUtil`：封装常见并发处理模式（并行分发、批量处理等）。

### 4.6 性能与监控（`monitor/`）
- `PerformanceMonitor`：周期性采样与指标上报（吞吐、延迟、队列长度、线程池使用情况等）。

### 4.7 数据访问（`datasource/mapper` 等）
- `Druid` + `MyBatis(+Plus)`：数据库连接池与 ORM/Mapper；用于业务数据与处理记录。

---

## 5. 配置说明（`application.yml`）

> 以下为常用关键项说明，具体以实际配置为准。

- `server.port`：HTTP 服务端口（默认 8090）。
- `spring.datasource.*`：Druid 数据源与 MySQL 连接信息。
- `spring.redis.*`：Redis 地址、库、密码与 Lettuce 连接池参数。
- `image-processing.redis-stream.*`：
  - `key`：Stream 键（示例：`images:ingest`）
  - `group`：Consumer Group 名称（示例：`images:workers`）
  - `consumer-name`：消费者标识（示例：`worker-1`）
  - `poll-timeout-ms`：XREADGROUP 轮询超时
  - `batch-size`：批量消费大小
  - `max-length`：Stream 最大长度（用于回压与控制内存）
- `minio.*`：MinIO 端点、AccessKey/SecretKey、对象前缀等。
- `zeromq.*`：ZMQ REP/PUB 端口等接入层参数。
- `netty.*`：网络与线程模型优化项（例如 boss/worker 线程数）。
- `thread-pools.*`：异步任务池、上传池、自定义 ForkJoinPool 参数。

---

## 6. 工作流（数据与消息流）

1. 设备/外部系统 → ZeroMQ 接入层（REP/PUB）。
2. 接入层初步解析与校验 → 写入 Redis Stream（Publisher）。
3. 消费者从 Redis Stream 批量拉取 → 并行处理（Netty/线程池）。
4. 处理结果持久化：对象写 MinIO，业务数据入库（MySQL）。
5. 性能监控与健康检查持续运行，定期报告指标与异常。

---

## 7. 运行与测试

- 前置依赖：
  - Java 21、Maven、Redis、MinIO、MySQL（根据实际场景部署）。
- 启动：
  - `mvn spring-boot:run`
- 单元测试：
  - `mvn clean test`
- 生产部署建议：
  - 根据负载调整 `thread-pools.*`、`image-processing.redis-stream.batch-size`。
  - 为 MinIO 与 Redis 配置高可用；为应用增加进程与日志监控。

---

## 8. 常见问题与排查

- Redis BUSYGROUP：当 Consumer Group 已存在时，不应中断启动；本项目在消费者初始化阶段已进行容错处理并记录提示日志。
- Redis MISCONF：当 Redis RDB 持久化等配置异常时，建议先修复 Redis；应用会跳过相关初始化以保障可用性。
- 连接与权限：确认 Redis/MinIO/MySQL 的网络可达与凭证正确，优先从 `application.yml` 校验。

---

## 9. 贡献与规范

- 代码风格：保持现有包结构与命名习惯，避免不必要的大改动。
- 变更前：评估对吞吐与延迟的影响，必要时补充压测。
- 提交：为关键模块补充测试或演示样例，便于回归。

---

## 10. 许可

内部项目；如需开源或外部发布，请遵循公司政策与合规流程。