chore: stop tracking docs directory and update gitignore
This commit is contained in:
@@ -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 <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 配置
|
||||
@@ -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 的集成测试基类。
|
||||
Reference in New Issue
Block a user