From ebf7e902eb6da76835fcae6463a0e81db429d100 Mon Sep 17 00:00:00 2001
From: wt <sdxt_0802@163.com>
Date: Mon, 27 Oct 2025 17:27:22 +0800
Subject: [PATCH] update README.md

---
 README.md | 230 +++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 186 insertions(+), 44 deletions(-)

diff --git a/README.md b/README.md
index ef53526..b325e0f 100644
--- a/README.md
+++ b/README.md
@@ -1,60 +1,202 @@
+# Zhitan Gateway
 
-
-# Zhitan-Gateway 项目简介
-
-Zhitan-Gateway 是一个基于 Java 的网关服务，主要功能是接收 MQTT 协议的数据，并将这些数据写入时间序列数据库 InfluxDB 或关系型数据库中。该项目适用于物联网（IoT）场景下的数据采集和处理。
+基于 Spring Boot 的物联网 MQTT 数据网关，用于接收电力监测设备数据并存储至 InfluxDB 时序数据库。
 
 ## 技术栈
-- Spring Boot
-- MQTT
-- InfluxDB
-- MyBatis Plus
+
+- **Spring Boot 2.6.15** - 应用框架
+- **Spring Integration MQTT** - MQTT 消息集成
+- **InfluxDB 6.6.0** - 时序数据库
+- **MyBatis Plus 3.5.6** - ORM 框架
+- **PostgreSQL** - 关系数据库
+- **Redis** - 缓存中间件
+- **Druid 1.2.20** - 数据库连接池
+- **Undertow** - 嵌入式服务器
+
+## 核心功能
+
+- MQTT 消息订阅与实时接收
+- 电力数据 JSON 解析与转换
+- 点位模板映射（支持 Redis 缓存）
+- InfluxDB 时序数据批量写入
+- Druid 连接池监控
+
+## 项目结构
+
+```
+src/main/java/com/zhitan/
+├── config/
+│   ├── influxdb/          # InfluxDB 配置
+│   ├── mqtt/              # MQTT 客户端配置
+│   ├── mybatis/           # MyBatis Plus 配置
+│   ├── redis/             # Redis 配置
+│   └── DruidConfig.java   # Druid 数据源配置
+├── handler/
+│   └── MqttMessageHandler.java  # MQTT 消息处理器
+├── influxdb/
+│   └── InfluxdbRepository.java  # InfluxDB 数据操作
+├── mapper/
+│   └── CommonMapper.java        # 数据访问接口
+├── model/
+│   ├── entity/ElectricPower.java  # 电力数据实体
+│   └── IndexTemplate.java         # 点位模板
+├── redis/
+│   └── RedisCache.java           # Redis 缓存工具
+├── service/
+│   └── impl/DataServiceImpl.java # 数据处理服务
+└── MQTTGatewayApplication.java   # 启动类
+```
+
+## 快速开始
+
+### 环境要求
+
+- JDK 8+
+- Maven 3.6+
+- MQTT Broker
+- InfluxDB 2.x
+- PostgreSQL
 - Redis
-- Druid 数据库连接池
 
-## 主要功能
-- 通过 MQTT 协议接收数据并进行处理。
-- 支持将数据写入 InfluxDB 或其他数据库。
-- 配置 Druid 数据库连接池以管理主从数据库连接。
-- 提供 Redis 缓存服务以提升数据处理效率。
+### 配置文件
 
-## 模块说明
-- `MQTTGatewayApplication.java`：Spring Boot 启动类。
-- `MqttConfig.java` 和 `MqttInboundConfig.java`：负责 MQTT 的连接和消息接收配置。
-- `InfluxdbConfig.java` 和 `InfluxdbRepository.java`：负责 InfluxDB 的连接和数据写入。
-- `DataServiceImpl.java`：实现数据处理逻辑，包括接收 MQTT 消息并写入数据库。
-- `DruidConfig.java` 和 `DruidProperties.java`：配置 Druid 数据库连接池。
-- `RedisConfig.java` 和 `RedisCache.java`：配置 Redis 缓存并提供缓存操作方法。
-- `MyBatisPlusConfig.java`：配置 MyBatis Plus 的拦截器。
+编辑 `application-dev.yml`：
 
-## 使用说明
-### 配置
-确保在 `application.yml` 或 `application-dev.yml` 中配置以下内容：
-- MQTT 服务器连接信息（broker-url, username, password）
-- InfluxDB 连接参数（host, org, bucket, token）
-- Redis 配置信息
-- Druid 数据源配置
+```yaml
+spring:
+  datasource:
+    druid:
+      master:
+        url: jdbc:postgresql://localhost:5432/energy
+        username: postgres
+        password: postgres
+  mqtt:
+    client-id: your-client-id
+    broker-url: tcp://broker.emqx.io
+    username: 
+    password: 
+    default-topic: zhitan
+    timeout: 30
+    keep-alive: 60
+  redis:
+    host: localhost
+    port: 6379
+    password: 
 
-### 启动
-运行 `MQTTGatewayApplication.java` 中的 `main` 方法启动服务。
+influxdb:
+  host: http://localhost:8086
+  org: your-org
+  bucket: your-bucket
+  token: your-token
+  measurement: data
+  enable: true
+```
 
-### 数据处理
-当 MQTT 消息到达时，`MqttInboundConfig` 会监听指定的 Topic，并通过 `MqttMessageHandler` 处理数据。数据将根据配置写入 InfluxDB 或其他数据库。
+### 启动应用
 
-## 依赖管理
-使用 Maven 进行依赖管理，核心依赖包括：
-- Spring Boot Starter
-- MQTT 支持库
-- InfluxDB Java 客户端
-- MyBatis Plus
-- Druid 数据库连接池
-- Redis 客户端
+```bash
+# 编译
+mvn clean compile
+
+# 运行
+mvn spring-boot:run
+
+# 打包
+mvn clean package
+java -jar target/MQTTGateway.jar
+```
+
+## 数据格式
+
+### MQTT 消息示例
+
+```json
+{
+  "SN": "device001",
+  "Pt": 2250.5,
+  "Ua": 220.1,
+  "Ub": 221.3,
+  "Uc": 219.8,
+  "Ia": 10.2,
+  "Ib": 10.5,
+  "Ic": 10.1,
+  "Pw": 2250.0,
+  "Pwa": 750.0,
+  "Pwb": 750.0,
+  "Pwc": 750.0,
+  "Time": "2024-01-01 12:00:00",
+  "Type": 1
+}
+```
+
+### 支持的电力参数
+
+- **电压**: Ua, Ub, Uc (相电压), Uab, Ubc, Uca (线电压)
+- **电流**: Ia, Ib, Ic
+- **功率**: Pt (总功率), Pw/Pwa/Pwb/Pwc (有功功率), Pq/Pqa/Pqb/Pqc (无功功率)
+- **电量**: Q, Qa, Qb, Qc
+
+## 数据流程
+
+```
+MQTT Broker → MqttInboundConfig → MqttMessageHandler 
+    → DataServiceImpl → IndexTemplate 映射 → InfluxDB
+                     ↓
+                Redis 缓存
+```
+
+1. 订阅 MQTT Topic 接收消息
+2. 解析 JSON 为 ElectricPower 对象
+3. 从数据库/缓存获取点位模板
+4. 映射字段并转换为 InfluxDB Point
+5. 批量写入时序数据库
+
+## 监控管理
+
+### Druid 监控
+
+访问: `http://localhost:8080/druid/`
+
+- 用户名: `admin`
+- 密码: `123456`
+
+### 日志配置
+
+```yaml
+logging:
+  level:
+    com.zhitan: debug
+    org.springframework: warn
+```
+
+## 部署
+
+### Docker 部署
+
+```bash
+# 构建镜像
+docker build -t zhitan-gateway .
+
+# 运行容器
+docker run -d \
+  -p 8080:8080 \
+  -e MQTT_BROKER=tcp://mqtt-broker:1883 \
+  -e INFLUXDB_HOST=http://influxdb:8086 \
+  zhitan-gateway
+```
+
+### 生产环境建议
+
+- 调整日志级别为 INFO
+- 配置 MQTT 自动重连
+- 启用 InfluxDB 批量写入
+- 设置 Redis 缓存过期时间
+- 配置 Druid 连接池参数
 
 ## 许可证
-本项目遵循 MIT 许可证，详见 [LICENSE](LICENSE) 文件。
+
+Apache-2.0 License
 
 ## 注意事项
 - 本项目需要依赖 MQTT Broker 和 InfluxDB/MySQL 等数据库，请确保相关服务已启动。
 - 配置文件中需根据实际环境修改配置，特别是数据库和 MQTT 的连接参数。
-
-如需进一步了解，请查阅源码或联系项目维护者。
\ No newline at end of file