aiot-platform-cloud/docs/deployment-guide.md

AIOT Platform Cloud 部署方案说明

本文档说明 AIOT Platform Cloud 的部署架构、CI/CD 流程和关键配置。

系统架构

服务列表

服务名称	容器名称	端口	说明
viewsh-gateway	aiot-gateway	48080	API 网关（统一入口）
viewsh-module-system-server	aiot-system-server	48081	系统管理服务
viewsh-module-infra-server	aiot-infra-server	48082	基础设施服务
viewsh-module-iot-server	aiot-iot-server	48091	IoT 核心服务
viewsh-module-iot-gateway	aiot-iot-gateway	-	IoT 设备网关（内部服务）

技术栈

• Java: 17
• Spring Boot: 3.5.9
• 构建工具: Maven 3.8+
• 容器: Docker 20.10+, Docker Compose 2.20+
• CI/CD: Jenkins 2.400+

依赖服务

服务	地址	端口	用途
Nacos	172.17.16.14	8848	服务发现、配置中心
MySQL	172.17.16.14	3306	数据库
Redis	172.17.16.14	6379	缓存
RocketMQ	172.17.16.14	9876	消息队列
TDengine	172.17.16.14	6041	时序数据库
Docker Registry	localhost	5000	镜像仓库

CI/CD 方案

Jenkins Pipeline 工作流

代码提交 → 变更检测 → 构建依赖镜像 → 并行构建服务 → 推送镜像 → 按序部署 → 健康检查

配置文件: Jenkinsfile

核心特性:

1. 智能构建

   • 检测变更文件，只构建受影响的服务
   • Maven 依赖层缓存，避免重复下载
   • 动态并行构建（根据 CPU 和内存自动调整并行度）

2. 部署策略

   • 依赖顺序部署：gateway → system → infra → iot-server → iot-gateway
   • 部署前自动备份当前版本
   • 健康检查失败自动回滚

3. 性能监控

   • 阶段耗时统计
   • 自动生成性能报告
   • 系统资源检测

关键配置:

REGISTRY = 'localhost:5000'              // 镜像仓库
DEPLOY_HOST = '172.19.0.1'               // 部署目标服务器
DEPLOY_PATH = '/opt/aiot-platform-cloud' // 部署目录
CORE_SERVICES = 'gateway,system,infra,iot-server,iot-gateway'

Docker 部署方案

镜像构建

多阶段构建 (docker/Dockerfile.template):

Stage 1: 构建阶段 (eclipse-temurin:17-jdk-alpine)
  - Maven 编译打包
  - 利用 Docker 层缓存加速依赖下载

Stage 2: 运行阶段 (eclipse-temurin:17-jre-alpine)
  - 复制 JAR 文件
  - 非 root 用户运行
  - 内置健康检查

优化点:

• 依赖缓存层（pom.xml 先于源码复制）
• 最小化运行时镜像（JRE 替代 JDK）
• 安全性（非 root 用户）

容器编排

配置文件: docker-compose.core.yml

网络配置:

networks:
  default:
    name: 1panel-network
    external: true

资源限制:

服务	内存限制	CPU 限制
gateway	1536m	1.0
system	1536m	1.0
infra	1536m	1.0
iot-server	2560m	1.5
iot-gateway	2560m	1.5

健康检查:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:48080/actuator/health"]
  interval: 10s
  timeout: 5s
  retries: 12
  start_period: 120s

环境配置

通过环境变量注入配置，支持动态覆盖：

environment:
  # Spring Profile
  SPRING_PROFILES_ACTIVE: prod

  # JVM 参数
  JAVA_OPTS: "-Xms512m -Xmx1024m ..."

  # Nacos 配置
  NACOS_ADDR: 172.17.16.14:8848
  NACOS_NAMESPACE: "8efd6d96-de7f-4664-b28e-c2788ffa1395"

  # 数据库
  SPRING_DATASOURCE_DYNAMIC_DATASOURCE_MASTER_URL: jdbc:mysql://...

  # Redis
  SPRING_DATA_REDIS_HOST: 172.17.16.14

服务发现与配置

Nacos 集成

所有服务通过 Nacos 实现服务发现和配置管理：

命名空间: 8efd6d96-de7f-4664-b28e-c2788ffa1395

配置文件命名规范: {服务名}-{profile}.yaml

示例：

• gateway-server-prod.yaml
• system-server-prod.yaml
• iot-server-prod.yaml

配置加载顺序:

1. 本地配置 application-local.yaml
2. Nacos 配置（覆盖本地配置）

部署流程

自动部署（推荐）

git push origin master
# Jenkins 自动触发构建和部署

手动部署

适用于紧急部署或 Jenkins 不可用的场景。

前置准备

1. 确保依赖服务可用

# 检查 Nacos
curl http://172.17.16.14:8848/nacos/

# 检查 MySQL
mysql -h 172.17.16.14 -u root -p -e "SELECT 1"

# 检查 Redis
redis-cli -h 172.17.16.14 -a <password> PING

2. 准备部署环境

# 创建部署目录
mkdir -p /opt/aiot-platform-cloud
cd /opt/aiot-platform-cloud

# 创建 Docker 网络（如果不存在）
docker network create 1panel-network

# 创建日志卷
docker volume create app-logs

3. 上传配置文件

将 docker-compose.core.yml 上传到 /opt/aiot-platform-cloud/ 目录。

根据实际环境修改配置：

• 镜像仓库地址 REGISTRY_HOST
• Nacos 地址和命名空间
• 数据库连接信息
• Redis 连接信息

构建镜像（可选）

如果镜像仓库中已有镜像，可跳过此步骤。

# 构建依赖镜像（首次构建或 pom.xml 变更时）
docker build -f docker/Dockerfile.deps -t localhost:5000/aiot-deps:latest .

# 构建服务镜像
docker build \
  -f docker/Dockerfile.service \
  --build-arg MODULE_NAME=viewsh-gateway \
  --build-arg JAR_NAME=viewsh-gateway \
  -t localhost:5000/viewsh-gateway:latest \
  .

# 推送到镜像仓库
docker push localhost:5000/viewsh-gateway:latest

部署服务

1. 拉取镜像

docker compose -f docker-compose.core.yml pull

2. 启动服务

# 启动所有服务
docker compose -f docker-compose.core.yml up -d

# 或按依赖顺序逐个启动（推荐用于故障排查）
docker compose -f docker-compose.core.yml up -d viewsh-gateway
docker compose -f docker-compose.core.yml up -d viewsh-module-system-server
docker compose -f docker-compose.core.yml up -d viewsh-module-infra-server
docker compose -f docker-compose.core.yml up -d viewsh-module-iot-server
docker compose -f docker-compose.core.yml up -d viewsh-module-iot-gateway

3. 查看启动状态

# 查看容器状态
docker compose -f docker-compose.core.yml ps

# 查看服务日志
docker compose -f docker-compose.core.yml logs -f

# 查看特定服务日志
docker logs -f aiot-gateway

更新服务

更新已有服务：

# 拉取新镜像
docker compose -f docker-compose.core.yml pull

# 重启服务（保持配置不变）
docker compose -f docker-compose.core.yml up -d

# 或重启特定服务
docker compose -f docker-compose.core.yml up -d viewsh-module-iot-server

回滚服务

如果新版本出现问题：

# 1. 查看可用镜像版本
docker images | grep viewsh

# 2. 修改 docker-compose.core.yml 中的 IMAGE_TAG
# 或者通过环境变量指定
export IMAGE_TAG=<previous-tag>

# 3. 重新拉取并启动
docker compose -f docker-compose.core.yml pull
docker compose -f docker-compose.core.yml up -d

验证部署

# 检查容器状态
docker compose -f docker-compose.core.yml ps

# 检查健康状态
docker inspect --format='{{.State.Health.Status}}' aiot-gateway

# 访问 API
curl http://<IP>:48080/actuator/health

关键设计决策

1. 为什么要用 Docker 多阶段构建？

• 构建阶段: 需要 JDK + Maven（体积大）
• 运行阶段: 只需 JRE（体积小）
• 结果: 镜像从 500MB+ 降至 200MB 左右

2. 为什么要智能构建检测？

• 只构建变更的服务，节省时间
• Maven 依赖缓存，避免重复下载
• 并行构建，提升效率

对比:

• 全量构建：~15 分钟
• 智能构建：~5 分钟（单服务变更）

3. 为什么要按依赖顺序部署？

服务间存在依赖关系：

• gateway 需要所有后端服务先启动
• iot-server 依赖 system 和 infra
• iot-gateway 依赖 iot-server

4. 为什么要健康检查和自动回滚？

• 保证部署失败时服务可用
• 减少故障恢复时间
• 提高系统可靠性

5. IoT Gateway 为什么没有健康检查？

IoT Gateway 是轻量级设备网关，不暴露 HTTP 端点，只检查容器运行状态。

目录结构

aiot-platform-cloud/
├── Jenkinsfile                    # CI/CD 流程定义
├── docker-compose.core.yml        # 服务编排配置
├── docker/
│   ├── Dockerfile.template        # 通用镜像模板
│   ├── Dockerfile.deps           # Maven 依赖镜像
│   └── Dockerfile.service        # 服务构建镜像
├── viewsh-gateway/               # 网关服务
├── viewsh-module-system/         # 系统服务
├── viewsh-module-infra/          # 基础设施服务
└── viewsh-module-iot/            # IoT 服务
    ├── viewsh-module-iot-server/    # IoT 核心服务
    └── viewsh-module-iot-gateway/   # IoT 设备网关

相关文档

• Jenkinsfile - Jenkins Pipeline 完整定义
• docker-compose.core.yml - Docker Compose 配置