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. **性能监控**
   - 阶段耗时统计
   - 自动生成性能报告
   - 系统资源检测

**关键配置**:

```groovy
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`):

```dockerfile
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`

**网络配置**:
```yaml
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 |

**健康检查**:
```yaml
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:48080/actuator/health"]
  interval: 10s
  timeout: 5s
  retries: 12
  start_period: 120s
```

### 环境配置

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

```yaml
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 配置（覆盖本地配置）

## 部署流程

### 自动部署（推荐）

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

### 手动部署

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

#### 前置准备

**1. 确保依赖服务可用**

```bash
# 检查 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. 准备部署环境**

```bash
# 创建部署目录
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 连接信息

#### 构建镜像（可选）

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

```bash
# 构建依赖镜像（首次构建或 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. 拉取镜像**

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

**2. 启动服务**

```bash
# 启动所有服务
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. 查看启动状态**

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

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

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

#### 更新服务

更新已有服务：

```bash
# 拉取新镜像
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
```

#### 回滚服务

如果新版本出现问题：

```bash
# 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
```

### 验证部署

```bash
# 检查容器状态
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](../Jenkinsfile) - Jenkins Pipeline 完整定义
- [docker-compose.core.yml](../docker-compose.core.yml) - Docker Compose 配置