262 lines
11 KiB
Markdown
262 lines
11 KiB
Markdown
# 快速开始
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [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)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构概览](#架构概览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖分析](#依赖分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排除指南](#故障排除指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本指南面向新加入的开发者，帮助你在最短时间内完成 AIOT 平台云项目的本地开发与容器化部署，涵盖环境搭建、依赖安装、数据库初始化、Docker 编排、IDE 配置、调试与基本使用示例，以及常见问题排查。
|
||
|
||
## 项目结构
|
||
该仓库采用多模块 Maven 工程，包含网关、系统、基础设施、IoT、运维等模块，配合 Docker Compose 实现服务编排与部署。
|
||
|
||
```mermaid
|
||
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"]
|
||
```
|
||
|
||
图表来源
|
||
- [pom.xml](file://pom.xml#L10-L30)
|
||
- [docker-compose.core.yml](file://docker-compose.core.yml#L11-L266)
|
||
|
||
章节来源
|
||
- [pom.xml](file://pom.xml#L10-L30)
|
||
- [docs/deployment-guide.md](file://docs/deployment-guide.md#L355-L376)
|
||
|
||
## 核心组件
|
||
- 网关服务：统一入口，负责路由与鉴权。
|
||
- 系统服务：用户、权限、租户等基础能力。
|
||
- 基础设施服务：文件、WebSocket、代码生成等通用能力。
|
||
- IoT 核心服务：设备接入、规则引擎、OTA 等核心业务。
|
||
- IoT 设备网关：MQTT/TCP/HTTP 等协议接入。
|
||
- 运维服务：环境、设施、安全等运维能力。
|
||
- 框架与依赖：封装通用组件与 Starter。
|
||
|
||
章节来源
|
||
- [docs/deployment-guide.md](file://docs/deployment-guide.md#L7-L16)
|
||
- [docker/services-config.json](file://docker/services-config.json#L1-L166)
|
||
|
||
## 架构概览
|
||
系统采用微服务 + Docker 容器化部署，服务通过 Nacos 发现与配置，数据持久化依赖 MySQL，缓存使用 Redis，消息队列使用 RocketMQ，IoT 时序数据使用 TDengine。
|
||
|
||
```mermaid
|
||
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
|
||
```
|
||
|
||
图表来源
|
||
- [docs/deployment-guide.md](file://docs/deployment-guide.md#L5-L35)
|
||
- [docker-compose.core.yml](file://docker-compose.core.yml#L11-L266)
|
||
|
||
## 详细组件分析
|
||
|
||
### 环境与依赖准备
|
||
- Java 17、Maven 3.8+、IntelliJ IDEA 2023.2+、Git、Docker 24.0+
|
||
- 建议配置阿里云 Maven 镜像，提升依赖下载速度
|
||
- IDE 需安装 Lombok、MapStruct 插件
|
||
|
||
章节来源
|
||
- [docs/technical-overview/08-开发指南.md](file://docs/technical-overview/08-开发指南.md#L7-L15)
|
||
|
||
### 本地开发环境搭建
|
||
- 使用根目录提供的 Docker Compose 快速启动依赖中间件（MySQL、Redis、Nacos、RocketMQ、TDengine）
|
||
- 首次启动后导入 SQL 脚本初始化数据库
|
||
- 在 Nacos 控制台导入配置（如存在导出配置）
|
||
|
||
章节来源
|
||
- [docs/technical-overview/08-开发指南.md](file://docs/technical-overview/08-开发指南.md#L16-L24)
|
||
|
||
### 数据库初始化
|
||
- 使用 MySQL 脚本初始化基础设施与业务表结构
|
||
- 可根据需要选择不同数据库方言的脚本（MySQL/DM/Oracle 等）
|
||
|
||
章节来源
|
||
- [sql/mysql/ruoyi-vue-pro.sql](file://sql/mysql/ruoyi-vue-pro.sql#L1-L200)
|
||
|
||
### Docker 容器化部署
|
||
- 多阶段构建：构建阶段使用 JDK，运行阶段使用 JRE，减小镜像体积
|
||
- 通过 docker-compose.core.yml 编排服务，按依赖顺序启动
|
||
- 支持健康检查与自动回滚
|
||
- 提供 .env.example 作为环境变量模板，便于本地与生产环境切换
|
||
|
||
章节来源
|
||
- [docs/deployment-guide.md](file://docs/deployment-guide.md#L72-L148)
|
||
- [docker-compose.core.yml](file://docker-compose.core.yml#L11-L266)
|
||
- [.env.example](file://.env.example#L1-L191)
|
||
|
||
### 服务配置与资源分配
|
||
- 网关与系统/基础设施服务：内存限制约 768m，CPU 1.0
|
||
- IoT 核心服务与设备网关：内存限制约 1024m，CPU 1.5
|
||
- 健康检查路径统一为 /actuator/health
|
||
- 通过环境变量覆盖默认配置（如 Nacos、数据库、Redis、RocketMQ、TDengine）
|
||
|
||
章节来源
|
||
- [docker/services-config.json](file://docker/services-config.json#L6-L106)
|
||
- [docker-compose.core.yml](file://docker-compose.core.yml#L106-L114)
|
||
|
||
### 部署脚本与流程
|
||
- scripts/deploy.sh 支持滚动更新、健康检查与自动回滚
|
||
- 按依赖顺序部署：gateway → system → infra → iot-server → iot-gateway
|
||
- 支持指定服务部署，便于局部更新
|
||
|
||
章节来源
|
||
- [scripts/deploy.sh](file://scripts/deploy.sh#L134-L194)
|
||
- [docs/deployment-guide.md](file://docs/deployment-guide.md#L168-L260)
|
||
|
||
### IDE 配置与调试
|
||
- 使用 application-local.yaml 配置 Nacos 与监控端点
|
||
- 在 IDEA 中启用 Lombok 与 MapStruct 插件，确保编译顺序正确
|
||
- 本地启动时可通过 SPRING_PROFILES_ACTIVE 切换环境
|
||
|
||
章节来源
|
||
- [viewsh-gateway/src/main/resources/application-local.yaml](file://viewsh-gateway/src/main/resources/application-local.yaml#L1-L47)
|
||
- [docs/technical-overview/08-开发指南.md](file://docs/technical-overview/08-开发指南.md#L16-L24)
|
||
|
||
### 基本使用示例
|
||
- 启动依赖中间件：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://<IP>:48080/actuator/health
|
||
|
||
章节来源
|
||
- [docs/technical-overview/08-开发指南.md](file://docs/technical-overview/08-开发指南.md#L16-L24)
|
||
- [docs/deployment-guide.md](file://docs/deployment-guide.md#L240-L318)
|
||
|
||
## 依赖分析
|
||
- 服务间依赖：gateway 依赖所有后端服务；iot-server 依赖 system 与 infra；iot-gateway 依赖 iot-server
|
||
- 中间件依赖：所有业务服务依赖 Nacos、MySQL、Redis；IoT 服务额外依赖 RocketMQ、TDengine
|
||
- 配置来源：本地 application-local.yaml 与 Nacos 配置中心，后者可动态覆盖
|
||
|
||
```mermaid
|
||
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
|
||
```
|
||
|
||
图表来源
|
||
- [docker-compose.core.yml](file://docker-compose.core.yml#L101-L103)
|
||
- [docker-compose.core.yml](file://docker-compose.core.yml#L140-L142)
|
||
- [docker-compose.core.yml](file://docker-compose.core.yml#L223-L224)
|
||
|
||
章节来源
|
||
- [docker-compose.core.yml](file://docker-compose.core.yml#L101-L103)
|
||
- [docker-compose.core.yml](file://docker-compose.core.yml#L140-L142)
|
||
- [docker-compose.core.yml](file://docker-compose.core.yml#L223-L224)
|
||
|
||
## 性能考虑
|
||
- 多阶段构建减少镜像体积，提升拉取与启动速度
|
||
- 按服务维度设置内存与 CPU 限额，核心服务（IoT）分配更高资源
|
||
- 健康检查与自动回滚保障部署稳定性
|
||
- 建议在生产环境为中间件单独管理内存与存储
|
||
|
||
章节来源
|
||
- [docs/deployment-guide.md](file://docs/deployment-guide.md#L74-L93)
|
||
- [docker/services-config.json](file://docker/services-config.json#L54-L71)
|
||
|
||
## 故障排除指南
|
||
- 启动报“Connection refused”：检查 Nacos 是否启动成功，确认端口未被防火墙拦截
|
||
- Maven 依赖下载失败：检查 pom.xml 中的仓库配置与本地 settings.xml mirror 设置
|
||
- MapStruct 转换对象属性为 null：确保 Lombok 在 MapStruct 之前执行（参考父工程 maven-compiler-plugin 配置）
|
||
- 服务启动后不健康：查看容器健康检查状态与日志，确认依赖中间件可用
|
||
- 部署失败自动回滚：脚本会记录当前镜像标签并在失败时尝试回滚
|
||
|
||
章节来源
|
||
- [docs/technical-overview/08-开发指南.md](file://docs/technical-overview/08-开发指南.md#L71-L81)
|
||
- [scripts/deploy.sh](file://scripts/deploy.sh#L35-L57)
|
||
|
||
## 结论
|
||
通过本指南，你可以完成从环境准备、依赖安装、数据库初始化到容器化部署与本地调试的全流程。建议优先使用 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
|
||
|
||
章节来源
|
||
- [docker-compose.core.yml](file://docker-compose.core.yml#L16-L18)
|
||
- [docker-compose.core.yml](file://docker-compose.core.yml#L56-L58)
|
||
- [docker-compose.core.yml](file://docker-compose.core.yml#L109-L111)
|
||
- [docker-compose.core.yml](file://docker-compose.core.yml#L148-L150)
|
||
- [docker-compose.core.yml](file://docker-compose.core.yml#L200-L203)
|
||
- [docker-compose.core.yml](file://docker-compose.core.yml#L230-L232) |