From 3d9079cbafb20ee839d2c0a0ab2078ad4d371314 Mon Sep 17 00:00:00 2001 From: lzh Date: Wed, 21 Jan 2026 09:37:29 +0800 Subject: [PATCH] chore: stop tracking docs directory and update gitignore --- docs/deployment-guide.md | 376 ------------------------ docs/ops-architecture/part8-测试指南.md | 92 ------ 2 files changed, 468 deletions(-) delete mode 100644 docs/deployment-guide.md delete mode 100644 docs/ops-architecture/part8-测试指南.md diff --git a/docs/deployment-guide.md b/docs/deployment-guide.md deleted file mode 100644 index 6a0db61..0000000 --- a/docs/deployment-guide.md +++ /dev/null @@ -1,376 +0,0 @@ -# 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/ops-architecture/part8-测试指南.md b/docs/ops-architecture/part8-测试指南.md deleted file mode 100644 index 7a5e6cd..0000000 --- a/docs/ops-architecture/part8-测试指南.md +++ /dev/null @@ -1,92 +0,0 @@ -# Ops 模块测试指南 - -本文档介绍了 Ops 模块（运维工单系统）的测试策略、核心测试类及执行方法。我们的测试重点在于验证业务逻辑的正确性和状态机转换的安全性。 - -## 1. 测试策略概述 - -Ops 模块的测试策略遵循 "金字塔模型"，侧重于 Service 层逻辑和状态机（FSM）的单元测试。 - -* **核心关注点**： - * **状态机逻辑**：验证工单状态转换的合法性、非法转换拦截及幂等性。 - * **业务流程**：验证工单从创建、分配、接单到完成的标准流转（Happy Path）。 - * **边界情况**：验证特殊流程（如从排队中分配）及异常处理。 -* **Mock 策略**：使用 Mockito 模拟数据库操作（Mapper）和外部依赖（如 Environment 模块、消息队列），确保测试聚焦于 Ops 模块自身的业务逻辑。 - -## 2. 核心测试类 - -我们主要通过以下两个测试类来保障核心功能的稳定性。 - -### 2.1 OrderStateMachineTest -位于：`viewsh-module-ops-biz/src/test/java/com/viewsh/module/ops/service/fsm/OrderStateMachineTest.java` - -* **职责**：专门测试状态机 `OrderStateMachine` 的行为。 -* **覆盖场景**： - * **合法转换**：如 `PENDING` -> `DISPATCHED`，验证状态更新事件是否正确发布。 - * **非法转换**：如 `PENDING` -> `COMPLETED`，验证是否抛出 `IllegalStateException`。 - * **幂等性**：验证状态不变时（如 `PENDING` -> `PENDING`）是否跳过无用操作。 - * **状态查询**：验证 `getAllowedTransitions` 返回正确的允许目标状态列表。 - -### 2.2 OpsOrderServiceTest -位于：`viewsh-module-ops-biz/src/test/java/com/viewsh/module/ops/service/order/OpsOrderServiceTest.java` - -* **职责**：测试工单服务 `OpsOrderService` 的业务方法。 -* **覆盖场景**： - * **CRUD**：验证 `createOrder`（含默认值填充）、`updateOrder`、`deleteOrder` 等基础操作。 - * **Happy Path**：模拟标准业务流：`assignOrder` (分配) -> `acceptOrder` (接单) -> `completeOrder` (完成)。 - * **Cleaning Flow**：验证保洁业务特有的流程，例如从 `QUEUED`（排队中）状态进行分配。 - * **生命周期委托**：验证 `pause`、`resume`、`cancel` 操作是否正确委托给 `OrderLifecycleManager`，确保与队列状态同步。 - -## 3. 如何执行测试 - -我们使用 Maven 来运行测试。 - -### 运行所有 Ops 模块测试 - -在项目根目录下执行： - -```bash -mvn test -pl viewsh-module-ops/viewsh-module-ops-biz -``` - -### 运行特定测试类 - -如果只想运行状态机的测试： - -```bash -mvn test -Dtest=OrderStateMachineTest -pl viewsh-module-ops/viewsh-module-ops-biz -``` - -如果只想运行工单服务的测试： - -```bash -mvn test -Dtest=OpsOrderServiceTest -pl viewsh-module-ops/viewsh-module-ops-biz -``` - -## 4. 测试覆盖范围说明 - -* **已覆盖**： - * `OrderStateMachine` 的所有核心转换规则。 - * `OpsOrderServiceImpl` 的主要业务方法。 - * 工单创建时的默认参数逻辑。 - * 权限校验逻辑（如非执行人操作拦截）。 -* **Mock / 未覆盖**： - * **数据库交互**：Mapper 层被 Mock，不连接真实数据库。 - * **外部集成**：Environment 模块的交互、IoT 设备消息、Redis 队列操作均通过 Mock 处理。 - * **Controller 层**：目前仅测试 Service 层，API 接口测试不在本指南范围内。 - -## 5. 既有规范回顾 - -以下内容继承自原[Part 8: 测试指南]： - -### 5.1 依赖模拟 (Mocking) -使用 `JUnit 5` 和 `Mockito`。 -- **核心原则**：Mock 掉 Mapper 层和外部 RPC 调用，专注验证 Service 层的状态转换逻辑。 - -### 5.2 集成测试规范（未来计划） -由于采用 Redis + MySQL 双写架构，未来的集成测试需重点验证： -- 事务提交后，Redis 队列中的分数（Score）与优先级（Priority）是否匹配。 -- `QueueSyncHandler` 是否正确处理了缓存失效后的补偿逻辑。 - -### 5.3 常用测试工具 -- **Podam**：用于快速生成填充了随机数据的 DO/DTO 对象。 -- **BaseDbAndRedisUnitTest**：支持 H2 内存数据库和内置 Redis 的集成测试基类。