XW-AIOT/aiot-platform-cloud
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1197363ac6ea5d7f1554360bbc89eceecb4fabbb
aiot-platform-cloud/.qoder/repowiki/zh/content/快速开始.md

11 KiB
Raw Blame History

快速开始

**本文引用的文件** - [pom.xml](file://pom.xml) - [docker-compose.core.yml](file://docker-compose.core.yml) - [script/docker/docker-compose.yml](file://script/docker/docker-compose.yml) - [docs/deployment-guide.md](file://docs/deployment-guide.md) - [docs/technical-overview/08-开发指南.md](file://docs/technical-overview/08-开发指南.md) - [.env.example](file://.env.example) - [scripts/deploy.sh](file://scripts/deploy.sh) - [docker/services-config.json](file://docker/services-config.json) - [sql/mysql/ruoyi-vue-pro.sql](file://sql/mysql/ruoyi-vue-pro.sql) - [viewsh-gateway/src/main/resources/application-local.yaml](file://viewsh-gateway/src/main/resources/application-local.yaml)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构概览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排除指南
  9. 结论
  10. 附录

简介

本指南面向新加入的开发者，帮助你在最短时间内完成 AIOT 平台云项目的本地开发与容器化部署，涵盖环境搭建、依赖安装、数据库初始化、Docker 编排、IDE 配置、调试与基本使用示例，以及常见问题排查。

项目结构

该仓库采用多模块 Maven 工程，包含网关、系统、基础设施、IoT、运维等模块，配合 Docker Compose 实现服务编排与部署。

graph TB
A["根工程<br/>pom.xml"] --> B["视图模块<br/>viewsh-gateway"]
A --> C["系统模块<br/>viewsh-module-system-server"]
A --> D["基础设施模块<br/>viewsh-module-infra-server"]
A --> E["IoT 核心服务<br/>viewsh-module-iot-server"]
A --> F["IoT 设备网关<br/>viewsh-module-iot-gateway"]
A --> G["运维服务<br/>viewsh-module-ops-server"]
A --> H["框架与依赖<br/>viewsh-framework / viewsh-dependencies"]
A --> I["服务编排<br/>docker-compose.core.yml"]
A --> J["部署脚本<br/>scripts/deploy.sh"]

图表来源

章节来源

核心组件

  • 网关服务：统一入口，负责路由与鉴权。
  • 系统服务：用户、权限、租户等基础能力。
  • 基础设施服务：文件、WebSocket、代码生成等通用能力。
  • IoT 核心服务：设备接入、规则引擎、OTA 等核心业务。
  • IoT 设备网关：MQTT/TCP/HTTP 等协议接入。
  • 运维服务：环境、设施、安全等运维能力。
  • 框架与依赖：封装通用组件与 Starter。

章节来源

架构概览

系统采用微服务 + Docker 容器化部署，服务通过 Nacos 发现与配置，数据持久化依赖 MySQL，缓存使用 Redis，消息队列使用 RocketMQ，IoT 时序数据使用 TDengine。

graph TB
subgraph "客户端"
U["浏览器/移动端/设备"]
end
subgraph "边缘与网关"
GW["API 网关<br/>viewsh-gateway"]
IOTGW["IoT 设备网关<br/>viewsh-module-iot-gateway"]
end
subgraph "业务服务"
SYS["系统服务<br/>viewsh-module-system-server"]
INF["基础设施服务<br/>viewsh-module-infra-server"]
IOT["IoT 核心服务<br/>viewsh-module-iot-server"]
OPS["运维服务<br/>viewsh-module-ops-server"]
end
subgraph "中间件"
NACOS["Nacos<br/>服务发现/配置中心"]
MYSQL["MySQL<br/>关系数据库"]
REDIS["Redis<br/>缓存/会话"]
MQ["RocketMQ<br/>消息队列"]
TD["TDengine<br/>时序数据库"]
end
U --> GW
GW --> SYS
GW --> INF
GW --> IOT
GW --> OPS
IOTGW --> IOT
IOTGW --> MQ
IOT --> MQ
IOT --> MYSQL
IOT --> REDIS
SYS --> MYSQL
SYS --> REDIS
INF --> MYSQL
INF --> REDIS
OPS --> MYSQL
OPS --> REDIS
GW --> NACOS
SYS --> NACOS
INF --> NACOS
IOT --> NACOS
OPS --> NACOS
IOTGW --> NACOS

图表来源

详细组件分析

环境与依赖准备

  • Java 17、Maven 3.8+、IntelliJ IDEA 2023.2+、Git、Docker 24.0+
  • 建议配置阿里云 Maven 镜像，提升依赖下载速度
  • IDE 需安装 Lombok、MapStruct 插件

章节来源

本地开发环境搭建

  • 使用根目录提供的 Docker Compose 快速启动依赖中间件（MySQL、Redis、Nacos、RocketMQ、TDengine）
  • 首次启动后导入 SQL 脚本初始化数据库
  • 在 Nacos 控制台导入配置（如存在导出配置）

章节来源

数据库初始化

  • 使用 MySQL 脚本初始化基础设施与业务表结构
  • 可根据需要选择不同数据库方言的脚本（MySQL/DM/Oracle 等）

章节来源

Docker 容器化部署

  • 多阶段构建：构建阶段使用 JDK，运行阶段使用 JRE，减小镜像体积
  • 通过 docker-compose.core.yml 编排服务，按依赖顺序启动
  • 支持健康检查与自动回滚
  • 提供 .env.example 作为环境变量模板，便于本地与生产环境切换

章节来源

服务配置与资源分配

  • 网关与系统/基础设施服务：内存限制约 768m，CPU 1.0
  • IoT 核心服务与设备网关：内存限制约 1024m，CPU 1.5
  • 健康检查路径统一为 /actuator/health
  • 通过环境变量覆盖默认配置（如 Nacos、数据库、Redis、RocketMQ、TDengine）

章节来源

部署脚本与流程

  • scripts/deploy.sh 支持滚动更新、健康检查与自动回滚
  • 按依赖顺序部署：gateway → system → infra → iot-server → iot-gateway
  • 支持指定服务部署，便于局部更新

章节来源

IDE 配置与调试

  • 使用 application-local.yaml 配置 Nacos 与监控端点
  • 在 IDEA 中启用 Lombok 与 MapStruct 插件，确保编译顺序正确
  • 本地启动时可通过 SPRING_PROFILES_ACTIVE 切换环境

章节来源

基本使用示例

  • 启动依赖中间件：docker-compose -f docker-compose.core.yml up -d mysql redis nacos rocketmq tdengine
  • 启动所有服务：docker compose -f docker-compose.core.yml up -d
  • 逐个启动（按依赖顺序）：先启动 gateway，再依次启动 system、infra、iot-server、iot-gateway
  • 查看日志：docker compose -f docker-compose.core.yml logs -f
  • 健康检查：curl http://:48080/actuator/health

章节来源

依赖分析

  • 服务间依赖：gateway 依赖所有后端服务；iot-server 依赖 system 与 infra；iot-gateway 依赖 iot-server
  • 中间件依赖：所有业务服务依赖 Nacos、MySQL、Redis；IoT 服务额外依赖 RocketMQ、TDengine
  • 配置来源：本地 application-local.yaml 与 Nacos 配置中心，后者可动态覆盖
graph LR
GW["gateway"] --> SYS["system-server"]
GW --> INF["infra-server"]
GW --> IOT["iot-server"]
GW --> OPS["ops-server"]
IOT --> SYS
IOT --> INF
IOTGW["iot-gateway"] --> IOT

图表来源

章节来源

性能考虑

  • 多阶段构建减少镜像体积，提升拉取与启动速度
  • 按服务维度设置内存与 CPU 限额，核心服务（IoT）分配更高资源
  • 健康检查与自动回滚保障部署稳定性
  • 建议在生产环境为中间件单独管理内存与存储

章节来源

故障排除指南

  • 启动报“Connection refused”：检查 Nacos 是否启动成功，确认端口未被防火墙拦截
  • Maven 依赖下载失败：检查 pom.xml 中的仓库配置与本地 settings.xml mirror 设置
  • MapStruct 转换对象属性为 null：确保 Lombok 在 MapStruct 之前执行（参考父工程 maven-compiler-plugin 配置）
  • 服务启动后不健康：查看容器健康检查状态与日志，确认依赖中间件可用
  • 部署失败自动回滚：脚本会记录当前镜像标签并在失败时尝试回滚

章节来源

结论

通过本指南，你可以完成从环境准备、依赖安装、数据库初始化到容器化部署与本地调试的全流程。建议优先使用 docker-compose.core.yml 一键启动核心服务，并结合 scripts/deploy.sh 实现滚动更新与回滚。遇到问题时，优先检查 Nacos、数据库、Redis、RocketMQ、TDengine 的连通性与健康状态。

附录

  • 服务端口与健康检查路径
    • 网关：48080，/actuator/health
    • 系统服务：48081，/actuator/health
    • 基础设施服务：48082，/actuator/health
    • IoT 核心服务：48091，/actuator/health
    • IoT 设备网关：1883/8091/8092（MQTT/HTTP/TCP），容器运行状态检查
    • 运维服务：48092，/actuator/health

章节来源