lzh
b4592c30ba
- Add deployment-guide.md for CI/CD and Docker deployment - Consolidate deployment architecture and workflow documentation - Add detailed manual deployment steps - Remove old scattered documents for unified maintenance Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
376 lines
9.0 KiB
Markdown
376 lines
9.0 KiB
Markdown
# 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 配置 |