XW-AIOT/aiot-platform-cloud
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add deployment guide document

Browse Source 
- 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>
This commit is contained in:
lzh
2026-01-14 22:39:53 +08:00
parent 520aa027fa
commit b4592c30ba
5 changed files with 376 additions and 1396 deletions
Download Patch File Download Diff File Expand all files Collapse all files

273
docs/build-optimization-guide.md
View File

@@ -1,273 +0,0 @@
# Jenkins 构建速度优化方案
## 当前问题
1. **Maven 依赖重复下载** - 每次构建都要下载依赖（~5-10分钟）
2. **串行构建** - 5个服务依次构建（~30-50分钟）
3. **无 Docker 缓存** - 每次都是全新构建
4. **无 Maven 缓存** - 依赖不复用
## 优化方案
### 方案 1: 启用 Docker BuildKit 缓存（推荐，最简单）
**优化效果**: 构建时间减少 60-80%
#### 实施步骤
1. **修改 Jenkinsfile，启用 BuildKit**
```groovy
environment {
// 启用 Docker BuildKit
DOCKER_BUILDKIT = '1'
BUILDKIT_PROGRESS = 'plain'
}
```
2. **使用缓存挂载优化 Dockerfile**
修改 `docker/Dockerfile.template`:
```dockerfile
# syntax=docker/dockerfile:1.4
# ============ 构建阶段 ============
FROM maven:3.9.9-eclipse-temurin-17-alpine AS builder
WORKDIR /build
# 利用 BuildKit 缓存挂载
RUN --mount=type=cache,target=/root/.m2 \
echo "Maven cache enabled"
# 复制 pom 文件
COPY pom.xml .
COPY viewsh-dependencies/pom.xml viewsh-dependencies/
# ... 其他 pom 文件
# 下载依赖（利用缓存）
RUN --mount=type=cache,target=/root/.m2 \
mvn dependency:go-offline -B
# 复制源代码
COPY . .
# 构建（利用缓存）
ARG MODULE_NAME
ARG SKIP_TESTS=true
RUN --mount=type=cache,target=/root/.m2 \
mvn clean package -pl ${MODULE_NAME} -am -DskipTests=${SKIP_TESTS} -B
# ============ 运行阶段 ============
FROM eclipse-temurin:17-jre-alpine
WORKDIR /app
ARG MODULE_NAME
ARG JAR_NAME
COPY --from=builder /build/${MODULE_NAME}/target/${JAR_NAME}.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]
```
**预期效果**:
- 首次构建: ~30分钟
- 后续构建（无代码变更）: ~2分钟
- 后续构建（有代码变更）: ~5-10分钟
---
### 方案 2: 并行构建（中等难度）
**优化效果**: 构建时间减少 50-70%
#### 修改 Jenkinsfile
```groovy
stage('Build Docker Images') {
steps {
script {
def services = env.SERVICES_TO_BUILD.split(',')
// 并行构建
def parallelBuilds = [:]
services.each { service ->
parallelBuilds[service] = {
stage("Build ${service}") {
// 构建逻辑
}
}
}
parallel parallelBuilds
}
}
}
```
**注意**: 需要确保服务器有足够内存（至少 8GB）
---
### 方案 3: 使用 Maven 本地仓库缓存（推荐）
**优化效果**: 依赖下载时间减少 90%
#### 实施步骤
1. **在宿主机创建 Maven 缓存目录**
```bash
mkdir -p /opt/jenkins-cache/maven-repo
chown -R 1000:1000 /opt/jenkins-cache/maven-repo
```
2. **修改 Jenkinsfile，挂载缓存**
```groovy
stage('Build Docker Images') {
steps {
script {
services.each { service ->
sh """
docker build \
-f docker/Dockerfile.template \
--build-arg MODULE_NAME=${modulePath} \
--build-arg JAR_NAME=${jarName} \
-v /opt/jenkins-cache/maven-repo:/root/.m2/repository \
-t ${REGISTRY}/${service}:${IMAGE_TAG} \
.
"""
}
}
}
}
```
**预期效果**:
- 首次构建: ~30分钟
- 后续构建: ~8-12分钟
---
### 方案 4: 使用 Nexus 私服（最佳，但需要额外部署）
**优化效果**: 构建时间减少 70-90%
#### 部署 Nexus
```bash
# 使用 1Panel 部署 Nexus
# 或使用 Docker Compose
docker run -d \
--name nexus \
-p 8081:8081 \
-v nexus-data:/nexus-data \
sonatype/nexus3
```
#### 配置 Maven 使用 Nexus
修改 `pom.xml`:
```xml
<repositories>
<repository>
<id>nexus</id>
<url>http://127.0.0.1:8081/repository/maven-public/</url>
</repository>
</repositories>
```
**预期效果**:
- 依赖下载速度提升 5-10 倍
- 构建时间减少 70%
---
### 方案 5: 增量构建优化（已实现）
**当前状态**: ✅ 已实现
- 只构建变更的服务
- 跳过未变更的服务
---
## 推荐组合方案
### 🚀 快速优化（5分钟实施）
**方案 1 + 方案 3**
1. 启用 Docker BuildKit
2. 挂载 Maven 缓存目录
**预期效果**: 构建时间从 30分钟 → 8-10分钟
### 🎯 最佳优化（30分钟实施）
**方案 1 + 方案 2 + 方案 3**
1. 启用 Docker BuildKit
2. 并行构建
3. Maven 缓存
**预期效果**: 构建时间从 30分钟 → 3-5分钟
### 💎 终极优化（需要额外资源）
**方案 1 + 方案 2 + 方案 4**
1. 启用 Docker BuildKit
2. 并行构建
3. Nexus 私服
**预期效果**: 构建时间从 30分钟 → 2-3分钟
---
## 立即可实施的优化
### 1. 启用 Docker BuildKit（最简单）
修改 Jenkinsfile:
```groovy
environment {
DOCKER_BUILDKIT = '1'
}
```
### 2. 创建 Maven 缓存目录
```bash
ssh root@172.19.0.1 'mkdir -p /opt/jenkins-cache/maven-repo && chown -R 1000:1000 /opt/jenkins-cache/maven-repo'
```
### 3. 修改 Dockerfile 使用缓存挂载
使用 BuildKit 的 `--mount=type=cache` 特性
---
## 性能对比
| 优化方案 | 首次构建 | 后续构建（无变更） | 后续构建（有变更） | 实施难度 |
|---------|---------|------------------|------------------|---------|
| 无优化 | 30分钟 | 30分钟 | 30分钟 | - |
| BuildKit | 30分钟 | 2分钟 | 8分钟 | ⭐ 简单 |
| BuildKit + Maven缓存 | 30分钟 | 2分钟 | 5分钟 | ⭐⭐ 中等 |
| BuildKit + 并行 | 15分钟 | 1分钟 | 4分钟 | ⭐⭐⭐ 复杂 |
| 全部优化 + Nexus | 15分钟 | 1分钟 | 2分钟 | ⭐⭐⭐⭐ 最复杂 |
---
## 下一步
选择您想要实施的优化方案，我会帮您修改配置文件！

376
docs/deployment-guide.md Normal file
View File

@@ -0,0 +1,376 @@
# 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 配置

481
docs/jenkinsfile-optimization.md
View File

@@ -1,481 +0,0 @@
# Jenkinsfile 优化说明
## 📊 优化总结
从 416 行优化到 650+ 行，增加了 **40%** 的企业级功能和错误处理逻辑。
---
## 🎯 主要优化点
### 1. **环境变量修复** (P0 - 关键)
#### 问题
```groovy
// 之前：在 environment 块中无法正确获取
IMAGE_TAG = "${env.BRANCH_NAME}-${env.BUILD_NUMBER}-${env.GIT_COMMIT?.take(8)}"
```
- `env.GIT_COMMIT` 在 environment 块执行时还未获取
- 导致 IMAGE_TAG 可能为 `master-1-null` 或 `master-1-`
#### 修复
```groovy
// 之后：在 Checkout 阶段动态设置
stage('Checkout') {
steps {
script {
def shortCommit = sh(
script: 'git rev-parse --short HEAD',
returnStdout: true
).trim()
env.IMAGE_TAG = "${env.BRANCH_NAME}-${env.BUILD_NUMBER}-${shortCommit}"
}
}
}
```
- ✅ 在 git checkout 后动态获取 commit hash
- ✅ 确保标签格式正确：`master-29-1f03c44a`
---
### 2. **消除重复的 Git 命令** (P1 - 性能)
#### 问题
```groovy
// 之前：detectChangedServices 和 checkDepsChanged 都执行相同的 git diff
def detectChangedServices() {
def changedFiles = sh(script: 'git diff ...', returnStdout: true).trim()
// ...
}
def checkDepsChanged() {
def changedFiles = sh(script: 'git diff ...', returnStdout: true).trim()
// ...
}
```
- **浪费**：同一命令执行 2 次
- **耗时**：每次 ~2-5 秒
#### 修复
```groovy
// 之后：只执行一次，共享结果
stage('Detect Changes') {
steps {
script {
def changedFiles = getChangedFiles() // 只执行一次
env.SERVICES_TO_BUILD = detectServicesToBuild(changedFiles)
env.DEPS_CHANGED = checkIfDepsChanged(changedFiles)
}
}
}
```
- ✅ 减少 50% 的 git 操作
- ✅ 节省 2-5 秒构建时间
---
### 3. **添加重试机制** (P1 - 可靠性)
#### 之前
```groovy
// 无重试，一次失败即终止
buildService(service)
```
#### 之后
```groovy
// 自动重试 2 次
def buildServiceWithRetry(String service) {
retry(2) {
timeout(time: 45, unit: 'MINUTES') {
buildService(service)
}
}
}
```
- ✅ 网络波动时自动重试
- ✅ 减少偶发性失败导致的构建中断
---
### 4. **超时保护** (P1 - 稳定性)
#### 之前
```groovy
// 无超时限制，可能永久挂起
waitForServiceHealthy(containerName, service, sshOpts)
```
#### 之后
```groovy
// 分级超时控制
timeout(time: 90, unit: 'MINUTES') { // 整个 Pipeline
timeout(time: 45, unit: 'MINUTES') { // 单个构建
timeout(time: 10, unit: 'MINUTES') { // 单次部署
// ...
}
}
}
```
- ✅ 防止构建永久挂起
- ✅ 自动释放资源
---
### 5. **预构建检查** (P2 - 质量)
#### 新增功能
```groovy
stage('Pre-build Check') {
steps {
script {
// 1. Docker 可用性检查
sh "docker version >/dev/null 2>&1"
// 2. 磁盘空间检查（> 80% 自动清理）
if (diskUsage > 80) {
sh "docker system prune -f"
}
// 3. 镜像仓库连接检查
sh "curl -f ${REGISTRY}/v2/"
}
}
}
```
- ✅ 提前发现问题
- ✅ 避免构建中途失败
---
### 6. **完善的错误处理** (P1 - 可维护性)
#### 之前
```groovy
// 简单的错误输出
catch (Exception e) {
echo "Failed: ${e.message}"
throw e
}
```
#### 之后
```groovy
// 详细的错误信息和诊断
catch (Exception e) {
echo "❌ Failed to build ${service}: ${e.message}"
// 收集诊断信息
sh """
echo "=== Docker Build Logs ==="
docker logs ${service}-builder || true
echo "=== Container Status ==="
docker ps -a | grep ${service}
echo "=== Disk Usage ==="
df -h
"""
throw e
}
```
- ✅ 快速定位问题
- ✅ 提供诊断信息
---
### 7. **增强的健康检查** (P1 - 可靠性)
#### 之前
```groovy
// 简单的状态检查
if [ "$STATUS" = "healthy" ]; then
exit 0
else
exit 1
fi
```
#### 之后
```groovy
// 详细的状态判断和日志输出
case "$STATUS" in
healthy)
echo "✅ Service is healthy"
;;
unhealthy)
echo "❌ Service is unhealthy"
docker logs --tail 100 ${containerName}
exit 1
;;
starting)
echo "⏳ Service is starting... (${elapsed}s)"
;;
*)
echo "⚠️ Unknown status: $STATUS"
;;
esac
```
- ✅ 区分不同状态
- ✅ 提供进度反馈
- ✅ 失败时输出日志
---
### 8. **资源清理优化** (P2 - 效率)
#### 之前
```groovy
// 只清理镜像
sh "docker image prune -f"
```
#### 之后
```groovy
always {
script {
// 1. 清理悬空镜像
sh "docker image prune -f"
// 2. 清理旧日志（> 30 天）
sh "find ${WORKSPACE} -name '*.log' -mtime +30 -delete"
// 3. 显示最终状态
sh 'docker system df'
}
}
```
- ✅ 定期清理，节省磁盘
- ✅ 防止日志堆积
---
### 9. **新增初始化阶段** (P2 - 可读性)
#### 新增
```groovy
stage('Initialize') {
steps {
script {
echo "=========================================="
echo " AIOT Platform - CI/CD Pipeline"
echo "=========================================="
echo "Branch: ${BRANCH_NAME}"
echo "Build: #${BUILD_NUMBER}"
echo "Workspace: ${WORKSPACE}"
echo "=========================================="
}
}
}
```
- ✅ 快速了解构建上下文
- ✅ 便于日志搜索
---
### 10. **构建统计信息** (P2 - 监控)
#### 新增
```groovy
// 构建后显示镜像大小
def imageSize = sh(
script: "docker images ${REGISTRY}/${service}:latest --format '{{.Size}}'",
returnStdout: true
).trim()
echo "📊 Image size: ${imageSize}"
// 显示所有构建的镜像
sh """
echo "📊 Built images:"
docker images ${REGISTRY}/*:${IMAGE_TAG} --format ' {{.Repository}} - {{.Size}}'
"""
```
- ✅ 了解镜像大小变化
- ✅ 检测异常增长
---
### 11. **优化的并行策略** (P1 - 性能)
#### 之前
```groovy
// 所有服务并行构建
parallel buildTasks
```
#### 之后
```groovy
// 可配置的并发数
MAX_PARALLEL_BUILDS = 2
// 分批执行，避免资源耗尽
servicesToBuild.collate(batchSize).each { batch ->
parallel buildTasks
}
```
- ✅ 避免过多并发导致资源耗尽
- ✅ 可根据服务器配置调整
---
### 12. **代码质量改进** (P2 - 可读性)
#### 修复
- ✅ 修复所有中文注释乱码
- ✅ 统一代码格式
- ✅ 添加详细的分隔线
- ✅ 改进变量命名
#### 之前
```groovy
// 构建单个服务
// 构<><E69E84><EFBFBD>单个服务 (乱码)
```
#### 之后
```groovy
// ============================================
// Build Services
// ============================================
```
---
## 📈 性能对比
| 指标 | 之前 | 之后 | 改进 |
|------|------|------|------|
| **Git 操作次数** | 3-4 次 | 1-2 次 | ⬇️ 50% |
| **失败重试** | 无 | 2 次 | ⬆️ 可靠性 |
| **超时保护** | 部分 | 完整 | ⬆️ 稳定性 |
| **错误日志** | 简单 | 详细 | ⬆️ 可调试性 |
| **磁盘清理** | 手动 | 自动 | ⬆️ 自动化 |
| **健康检查** | 基础 | 增强 | ⬆️ 准确性 |
| **代码行数** | 416 行 | 650+ 行 | ⬆️ 56% |
---
## 🚀 使用方法
### 方法 1：替换现有文件
```bash
cp Jenkinsfile Jenkinsfile.backup
cp Jenkinsfile.optimized Jenkinsfile
git add Jenkinsfile
git commit -m "feat: 优化 Jenkinsfile，添加企业级功能"
```
### 方法 2：对比查看
```bash
diff -u Jenkinsfile Jenkinsfile.optimized
```
---
## ✅ 新增功能清单
### 构建阶段
- [x] Initialize 阶段（构建前信息展示）
- [x] Pre-build Check（预构建检查）
- [x] 重试机制（retry）
- [x] 超时保护（timeout）
- [x] 镜像大小统计
### 部署阶段
- [x] 部署超时控制
- [x] 详细的状态检查
- [x] 失败诊断信息收集
### 健康检查
- [x] 多状态判断（healthy/unhealthy/starting）
- [x] 进度反馈（已等待时间）
- [x] 自动重试
### 错误处理
- [x] 统一的 try-catch
- [x] 详细的错误日志
- [x] 诊断信息收集
### 资源管理
- [x] 自动清理悬空镜像
- [x] 自动清理旧日志
- [x] 磁盘空间检查
---
## 🎯 配置建议
### 环境变量调整
```groovy
// 根据服务器性能调整
MAX_PARALLEL_BUILDS = 2 // 构建并发数（建议：CPU 核心数 / 2）
BUILD_TIMEOUT = 45 // 单服务构建超时（分钟）
DEPLOY_TIMEOUT = 10 // 单服务部署超时（分钟）
HEALTH_CHECK_TIMEOUT = 180 // 健康检查总超时（秒）
HEALTH_CHECK_INTERVAL = 10 // 健康检查间隔（秒）
```
### 高性能服务器（16 核 + 32GB RAM）
```groovy
MAX_PARALLEL_BUILDS = 4
BUILD_TIMEOUT = 30
```
### 低性能服务器（4 核 + 8GB RAM）
```groovy
MAX_PARALLEL_BUILDS = 1 // 串行构建
BUILD_TIMEOUT = 60
```
---
## 🔧 故障排查
### 问题 1：构建超时
```
Timeout: 45 minutes exceeded
```
**解决**：
- 增加 `BUILD_TIMEOUT`
- 检查 Maven 构建是否卡住
- 优化 Dockerfile 层缓存
### 问题 2：健康检查失败
```
Service health check timeout
```
**解决**：
- 增加 `HEALTH_CHECK_TIMEOUT`
- 检查应用日志（是否启动失败）
- 检查 Nacos 连接
### 问题 3：磁盘空间不足
```
No space left on device
```
**解决**：
- 自动清理会触发（> 80%）
- 手动执行：`docker system prune -af --volumes`
---
## 📝 总结
### 优化效果
1. ✅ **更可靠**：重试机制 + 超时保护
2. ✅ **更快速**：减少重复操作
3. ✅ **更安全**：预检查 + 资源管理
4. ✅ **更清晰**：详细日志 + 错误诊断
5. ✅ **更专业**：企业级代码质量
### 适用场景
- ✅ 生产环境部署
- ✅ 大型团队协作
- ✅ 频繁迭代项目
- ✅ 多服务微服务架构
---
**优化完成时间**: 2026-01-13
**优化版本**: v2.0.0-enterprise

180
docs/production-config-guide.md
View File

@@ -1,180 +0,0 @@
# 生产环境配置说明
本文档说明如何使用 `application-prod.yaml` 配置文件。
## 配置架构
### 三层配置体系
```
1. application.yaml (基础配置)
↓
2. application-prod.yaml (生产环境配置 + 环境变量占位符)
↓
3. Nacos 配置中心 (动态配置，优先级最高)
```
### 配置优先级
```
Nacos 配置 > 环境变量 > application-prod.yaml 默认值 > application.yaml
```
## 环境变量命名规范
### 通用环境变量
| 环境变量 | 说明 | 默认值 | 示例 |
|---------|------|--------|------|
| `NACOS_SERVER_ADDR` | Nacos 服务器地址 | 127.0.0.1:8848 | 127.0.0.1:8848 |
| `NACOS_USERNAME` | Nacos 用户名 | 空 | nacos |
| `NACOS_PASSWORD` | Nacos 密码 | 空 | nacos123 |
| `NACOS_NAMESPACE` | Nacos 命名空间 | 空 | prod |
| `NACOS_GROUP` | Nacos 分组 | DEFAULT_GROUP | DEFAULT_GROUP |
### 数据库环境变量
| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `MYSQL_HOST` | MySQL 主机地址 | 127.0.0.1 |
| `MYSQL_PORT` | MySQL 端口 | 3306 |
| `MYSQL_DATABASE` | 数据库名 | aiot_platform |
| `MYSQL_USER` | 数据库用户名 | root |
| `MYSQL_PASSWORD` | 数据库密码 | 空 |
### Redis 环境变量
| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `REDIS_HOST` | Redis 主机地址 | 127.0.0.1 |
| `REDIS_PORT` | Redis 端口 | 6379 |
| `REDIS_DATABASE` | Redis 数据库索引 | 0 |
| `REDIS_PASSWORD` | Redis 密码 | 空 |
### 消息队列环境变量
| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `ROCKETMQ_NAMESRV_ADDR` | RocketMQ NameServer 地址 | 127.0.0.1:9876 |
## 使用方式
### 方式 1: Docker Compose 环境变量注入（推荐）
在 `docker-compose.core.yml` 中已配置：
```yaml
viewsh-module-system-server:
environment:
SPRING_PROFILES_ACTIVE: prod # ← 激活 prod 配置
NACOS_SERVER_ADDR: ${NACOS_HOST}:${NACOS_PORT}
MYSQL_HOST: ${MYSQL_HOST}
MYSQL_PASSWORD: ${MYSQL_PASSWORD}
# ... 其他环境变量
```
### 方式 2: Nacos 配置中心覆盖
在 Nacos 控制台创建配置文件，会覆盖环境变量和本地配置：
**Data ID**: `system-server-prod.yaml`
**Group**: `DEFAULT_GROUP`
```yaml
spring:
datasource:
dynamic:
datasource:
master:
password: 从Nacos管理的密码 # ← 覆盖环境变量
```
### 方式 3: 混合使用（最佳实践）
- **环境变量**：配置基础设施连接信息（MySQL、Redis、Nacos）
- **Nacos**：配置业务参数、功能开关、动态配置
## 各服务配置差异
### 需要 MySQL 的服务
- `viewsh-module-system-server`
- `viewsh-module-infra-server`
- `viewsh-module-iot-server`
### 需要 RocketMQ 的服务
- `viewsh-module-iot-server`
- `viewsh-module-iot-gateway`
### 仅需要 Redis 的服务
- `viewsh-gateway`
- `viewsh-module-iot-gateway`
## 激活生产环境配置
### 在 Docker Compose 中
已在 `docker-compose.core.yml` 中配置：
```yaml
environment:
SPRING_PROFILES_ACTIVE: prod
```
### 手动启动
```bash
java -jar app.jar --spring.profiles.active=prod
```
## 配置验证
### 查看生效的配置
```bash
# 进入容器
docker exec -it aiot-system-server sh
# 查看环境变量
env | grep MYSQL
env | grep REDIS
# 查看 Spring Boot 配置
curl http://localhost:48081/actuator/env
```
## 常见问题
### Q: 如何确认使用了 prod 配置？
A: 查看日志，应该看到：
```
The following 1 profile is active: "prod"
```
### Q: 环境变量和 Nacos 哪个优先级高？
A: Nacos 配置优先级最高，会覆盖环境变量。
### Q: 如何临时修改配置？
A:
1. **临时修改**：在 Nacos 中修改（无需重启）
2. **永久修改**：修改 `.env` 文件并重启容器
## 配置文件位置
```
viewsh-gateway/src/main/resources/application-prod.yaml
viewsh-module-system/viewsh-module-system-server/src/main/resources/application-prod.yaml
viewsh-module-infra/viewsh-module-infra-server/src/main/resources/application-prod.yaml
viewsh-module-iot/viewsh-module-iot-server/src/main/resources/application-prod.yaml
viewsh-module-iot/viewsh-module-iot-gateway/src/main/resources/application-prod.yaml
```
## 下一步
配置完成后，参考 [部署操作指南](deployment-guide.md) 进行部署。

462
docs/server-deployment-guide.md
View File

@@ -1,462 +0,0 @@
# 服务器部署操作指南
本文档提供服务器环境配置和 Nacos 配置的详细步骤。
## 第一步：服务器环境配置
### 1. SSH 登录服务器
```bash
ssh root@124.221.55.225
```
### 2. 创建项目目录
```bash
# 创建项目目录
mkdir -p /opt/aiot-platform-cloud
cd /opt/aiot-platform-cloud
```
### 3. 下载配置文件
```bash
# 下载 docker-compose 配置
wget http://172.17.16.14:3000/XW-AIOT/aiot-platform-cloud/raw/branch/master/docker-compose.core.yml
# 下载环境变量模板
wget http://172.17.16.14:3000/XW-AIOT/aiot-platform-cloud/raw/branch/master/.env.example
# 或者使用 git clone（推荐）
git clone http://172.17.16.14:3000/XW-AIOT/aiot-platform-cloud.git .
```
### 4. 创建并编辑 .env 文件
```bash
# 复制模板
cp .env.example .env
# 编辑配置
vi .env
```
### 5. 必须修改的配置项
在 `.env` 文件中，按 `i` 进入编辑模式，修改以下内容：
```bash
# ============ 数据库配置 ============
# 从 1Panel 获取 MySQL 密码
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_ROOT_PASSWORD=你的1Panel_MySQL_root密码 # ← 修改这里
MYSQL_DATABASE=aiot_platform
MYSQL_USER=aiot
MYSQL_PASSWORD=你的aiot用户密码 # ← 修改这里
# ============ Redis 配置 ============
# 从 1Panel 获取 Redis 密码
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=你的1Panel_Redis密码 # ← 修改这里
REDIS_DATABASE=0
# ============ Nacos 配置 ============
# 从 1Panel 获取 Nacos 配置
NACOS_HOST=127.0.0.1
NACOS_PORT=8848
NACOS_NAMESPACE= # 留空使用 public 命名空间，或填写 aiot-platform
NACOS_USERNAME=nacos
NACOS_PASSWORD=你的1Panel_Nacos密码 # ← 修改这里
# ============ RocketMQ 配置 ============
ROCKETMQ_NAMESRV_HOST=127.0.0.1
ROCKETMQ_NAMESRV_PORT=9876
# ============ IoT Gateway 特有配置 ============
# 生产环境必须修改为强密钥（至少32位）
IOT_TOKEN_SECRET=你的强密钥_至少32位字符 # ← 修改这里
```
**保存并退出**：
- 按 `Esc` 退出编辑模式
- 输入 `:wq` 保存并退出
### 6. 验证配置
```bash
# 查看配置（隐藏密码）
cat .env | grep -v PASSWORD | grep -v SECRET
# 测试 MySQL 连接
mysql -h 127.0.0.1 -P 3306 -u aiot -p
# 输入密码后，如果能连接成功，说明配置正确
# 测试 Redis 连接
redis-cli -h 127.0.0.1 -p 6379 -a 你的Redis密码 PING
# 应该返回 PONG
# 测试 Nacos 连接
curl http://127.0.0.1:8848/nacos/v1/console/health/readiness
# 应该返回 UP
```
### 7. 如何获取 1Panel 中间件密码
#### 获取 MySQL 密码
```bash
# 在 1Panel 面板中
1. 进入"数据库" → "MySQL"
2. 找到 root 用户，点击"查看密码"
3. 复制密码到 .env 文件
```
#### 获取 Redis 密码
```bash
# 在 1Panel 面板中
1. 进入"应用商店" → "已安装"
2. 找到 Redis，点击"设置"
3. 查看"requirepass"配置
4. 复制密码到 .env 文件
```
#### 获取 Nacos 密码
```bash
# 在 1Panel 面板中
1. 进入"应用商店" → "已安装"
2. 找到 Nacos，点击"设置"
3. 查看环境变量中的密码
4. 复制密码到 .env 文件
```
---
## 第二步：Nacos 配置管理
### 1. 访问 Nacos 控制台
```
URL: http://124.221.55.225:8848/nacos
用户名: nacos
密码: 你的Nacos密码
```
### 2. 创建命名空间（可选）
**推荐创建独立的命名空间用于生产环境**
1. 点击左侧菜单"命名空间"
2. 点击右上角"新建命名空间"
3. 填写信息：
- **命名空间名**: `aiot-platform`
- **命名空间ID**: `aiot-platform`（自动生成）
- **描述**: `AIOT 平台生产环境`
4. 点击"确定"
### 3. 为每个服务创建配置
#### 配置 1: system-server
**Data ID**: `system-server-prod.yaml`
**Group**: `DEFAULT_GROUP`
**配置格式**: `YAML`
**配置内容**:
```yaml
# 系统服务配置
spring:
datasource:
dynamic:
datasource:
master:
url: jdbc:mysql://127.0.0.1:3306/aiot_platform?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true&nullCatalogMeansCurrent=true&rewriteBatchedStatements=true
username: aiot
password: 你的MySQL密码 # ← 在这里填写实际密码
data:
redis:
host: 127.0.0.1
port: 6379
password: 你的Redis密码 # ← 在这里填写实际密码
database: 0
# 日志级别（可动态调整）
logging:
level:
com.viewsh.module.system: INFO
```
#### 配置 2: infra-server
**Data ID**: `infra-server-prod.yaml`
**Group**: `DEFAULT_GROUP`
**配置格式**: `YAML`
**配置内容**:
```yaml
# 基础设施服务配置
spring:
datasource:
dynamic:
datasource:
master:
url: jdbc:mysql://127.0.0.1:3306/aiot_platform?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true&nullCatalogMeansCurrent=true&rewriteBatchedStatements=true
username: aiot
password: 你的MySQL密码
data:
redis:
host: 127.0.0.1
port: 6379
password: 你的Redis密码
database: 0
logging:
level:
com.viewsh.module.infra: INFO
```
#### 配置 3: iot-server
**Data ID**: `iot-server-prod.yaml`
**Group**: `DEFAULT_GROUP`
**配置格式**: `YAML`
**配置内容**:
```yaml
# IoT 业务服务配置
spring:
datasource:
dynamic:
datasource:
master:
url: jdbc:mysql://127.0.0.1:3306/aiot_platform?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true&nullCatalogMeansCurrent=true&rewriteBatchedStatements=true
username: aiot
password: 你的MySQL密码
data:
redis:
host: 127.0.0.1
port: 6379
password: 你的Redis密码
database: 0
rocketmq:
name-server: 127.0.0.1:9876
viewsh:
iot:
message-bus:
type: redis
logging:
level:
com.viewsh.module.iot: INFO
```
#### 配置 4: iot-gateway-server
**Data ID**: `iot-gateway-server-prod.yaml`
**Group**: `DEFAULT_GROUP`
**配置格式**: `YAML`
**配置内容**:
```yaml
# IoT 设备网关配置
spring:
data:
redis:
host: 127.0.0.1
port: 6379
password: 你的Redis密码
database: 0
rocketmq:
name-server: 127.0.0.1:9876
viewsh:
iot:
message-bus:
type: redis
gateway:
# 设备 RPC 配置
rpc:
url: http://127.0.0.1:48091
connect-timeout: 30s
read-timeout: 30s
# 设备 Token 配置
token:
secret: 你的强密钥_至少32位字符 # ← 生产环境必须修改
expiration: 7d
# 协议配置（可动态调整）
protocol:
http:
enabled: true
server-port: 8092
mqtt:
enabled: true
port: 1883
max-message-size: 8192
connect-timeout-seconds: 60
ssl-enabled: false
tcp:
enabled: false
port: 8091
emqx:
enabled: false
logging:
level:
com.viewsh.module.iot.gateway: INFO
com.viewsh.module.iot.gateway.protocol.mqtt: INFO
```
#### 配置 5: gateway-server
**Data ID**: `gateway-server-prod.yaml`
**Group**: `DEFAULT_GROUP`
**配置格式**: `YAML`
**配置内容**:
```yaml
# API 网关配置
spring:
data:
redis:
host: 127.0.0.1
port: 6379
password: 你的Redis密码
database: 0
logging:
level:
com.viewsh.gateway: INFO
```
### 4. 发布配置
每个配置创建完成后：
1. 点击"发布"按钮
2. 确认配置内容
3. 点击"确定"
### 5. 验证配置
在"配置列表"中可以看到所有已发布的配置：
- `system-server-prod.yaml`
- `infra-server-prod.yaml`
- `iot-server-prod.yaml`
- `iot-gateway-server-prod.yaml`
- `gateway-server-prod.yaml`
---
## 第三步：部署服务
### 1. 确认配置完成
```bash
# 检查 .env 文件
cat .env | grep -E "MYSQL_PASSWORD|REDIS_PASSWORD|NACOS_PASSWORD|IOT_TOKEN_SECRET"
# 确保所有密码都已填写，不是默认值
```
### 2. 在 Jenkins 中触发构建
1. 访问 Jenkins: `http://124.221.55.225:5050/`
2. 进入项目: `aiot-platform-cloud` → `master`
3. 点击"立即构建"（Build Now）
### 3. 监控部署进度
在 Jenkins 中查看构建日志：
- ✅ Checkout 代码
- ✅ 检测变更
- ✅ 构建 Docker 镜像
- ✅ 推送到 Registry
- ✅ 部署服务
### 4. 验证服务状态
```bash
# 查看运行中的容器
docker ps
# 查看服务日志
docker logs -f aiot-system-server
docker logs -f aiot-iot-gateway
# 检查健康状态
curl http://127.0.0.1:48081/actuator/health # system-server
curl http://127.0.0.1:48091/actuator/health # iot-server
curl http://127.0.0.1:48084/actuator/health # iot-gateway
```
---
## 常见问题
### Q1: 如何修改 Nacos 中的配置？
1. 登录 Nacos 控制台
2. 找到对应的配置文件
3. 点击"编辑"
4. 修改配置
5. 点击"发布"
6. **配置立即生效，无需重启服务！**
### Q2: 如何查看服务是否连接到 Nacos？
```bash
# 查看服务日志
docker logs aiot-system-server | grep nacos
# 应该看到类似输出：
# Nacos config center started successfully
```
### Q3: 如果 Nacos 配置错误怎么办？
1. 在 Nacos 控制台点击"历史版本"
2. 选择之前的版本
3. 点击"回滚"
4. 配置立即恢复
### Q4: 如何生成强密钥？
```bash
# 生成 32 位随机密钥
openssl rand -base64 32
# 或者使用在线工具
# https://www.random.org/strings/
```
---
## 配置优先级说明
```
Nacos 配置 > .env 环境变量 > application-prod.yaml 默认值
```
**推荐做法**：
- **基础设施配置**（MySQL、Redis 地址）→ `.env` 文件
- **业务配置**（功能开关、日志级别）→ Nacos 配置中心
- **默认值** → `application-prod.yaml`
这样可以：
- ✅ 基础配置稳定（在 .env 中）
- ✅ 业务配置灵活（在 Nacos 中动态调整）
- ✅ 有默认值兜底（在 application-prod.yaml 中）