diff --git a/docs/build-optimization-guide.md b/docs/build-optimization-guide.md deleted file mode 100644 index abc8fe1..0000000 --- a/docs/build-optimization-guide.md +++ /dev/null @@ -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 - - - nexus - http://127.0.0.1:8081/repository/maven-public/ - - -``` - -**预期效果**: -- 依赖下载速度提升 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分钟 | ⭐⭐⭐⭐ 最复杂 | - ---- - -## 下一步 - -选择您想要实施的优化方案，我会帮您修改配置文件！ diff --git a/docs/deployment-guide.md b/docs/deployment-guide.md new file mode 100644 index 0000000..6a0db61 --- /dev/null +++ b/docs/deployment-guide.md @@ -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 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= + +# 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://: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 配置 \ No newline at end of file diff --git a/docs/jenkinsfile-optimization.md b/docs/jenkinsfile-optimization.md deleted file mode 100644 index b8e6c33..0000000 --- a/docs/jenkinsfile-optimization.md +++ /dev/null @@ -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 -// 构建单个服务 -// 构���单个服务 (乱码) -``` - -#### 之后 -```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 diff --git a/docs/production-config-guide.md b/docs/production-config-guide.md deleted file mode 100644 index 7127a7b..0000000 --- a/docs/production-config-guide.md +++ /dev/null @@ -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) 进行部署。 diff --git a/docs/server-deployment-guide.md b/docs/server-deployment-guide.md deleted file mode 100644 index 07c928a..0000000 --- a/docs/server-deployment-guide.md +++ /dev/null @@ -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 中）