admin/NETWORK_SCAN_TIMEOUT_FIX.md

网络扫描超时和进度条修复说明

问题描述

1. 进度条显示问题：后端是同步扫描，前端无法实时获取进度，导致进度条显示不准确
2. 前端请求超时：默认 10 秒超时，大网段扫描时后端还未完成前端就超时了

解决方案

1. 前端修改

增加请求超时时间

• 文件：src/service/api/device.ts
• 修改：将网络扫描请求的超时时间从默认 10 秒增加到 10 分钟

export function fetchScanNetwork(data: Api.Device.NetworkScanRequest) {
  return request<Api.Device.NetworkScanResult>({
    url: '/device/amt/scanNetwork',
    method: 'post',
    data,
    timeout: 10 * 60 * 1000 // 10 分钟超时
  });
}

修复进度条显示

• 文件：src/views/device/list/index.vue
• 修改：使用不确定进度条（processing 状态）替代百分比进度条
• 移除：scanProgress 计算属性和 scanProgressTimer 轮询
• 显示：简单的"正在扫描网络，请稍候..."提示

修改前：

<n-progress
  type="line"
  :percentage="scanProgress"
  :status="scanning ? 'default' : 'success'"
/>
<div class="text-sm text-gray-500 mt-2">
  已扫描: {{ scanResult?.scannedIps || 0 }} / {{ scanResult?.totalIps || 0 }}
</div>

修改后：

<n-progress
  type="line"
  :percentage="100"
  status="default"
  :show-indicator="false"
  processing
/>
<div class="text-sm text-gray-500 mt-2">
  正在扫描网络，请稍候...
</div>

2. 后端修改

增加扫描超时时间

• 文件：backend/src/main/java/com/soybean/admin/service/AmtNetworkScanService.java
• 修改：将扫描超时从 5 分钟增加到 10 分钟

// 等待所有扫描完成（最多等待 10 分钟）
boolean completed = latch.await(10, TimeUnit.MINUTES);

增加并发线程数

• 从 10 个线程增加到 20 个线程
• 提高扫描效率，减少总扫描时间

private final ExecutorService executorService = Executors.newFixedThreadPool(20);

优化进度日志

• 使用 AtomicInteger 线程安全地统计已扫描数量
• 每扫描 10 个 IP 输出一次进度日志

AtomicInteger scannedCount = new AtomicInteger(0);
// ...
int scanned = scannedCount.incrementAndGet();
result.setScannedIps(scanned);
if (scanned % 10 == 0) {
    logger.info("扫描进度: {}/{}", scanned, ipList.size());
}

添加超时警告

boolean completed = latch.await(10, TimeUnit.MINUTES);
if (!completed) {
    logger.warn("扫描超时，部分 IP 未完成扫描");
}

性能优化

扫描时间估算

假设每个 IP 扫描耗时 2 秒（包括连接超时）：

网段大小	IP 数量	10 线程耗时	20 线程耗时
/28	14	~3 秒	~2 秒
/27	30	~6 秒	~3 秒
/26	62	~13 秒	~7 秒
/25	126	~26 秒	~13 秒
/24	254	~51 秒	~26 秒

优化建议

1. 小网段扫描（/28 - /26）：

   • 推荐使用，扫描时间短
   • 适合精确定位设备

2. 中等网段（/25 - /24）：

   • 可以使用，但需要等待
   • 建议在非高峰时段扫描

3. 大网段（/23 及以上）：

   • 不推荐，扫描时间过长
   • 建议分段扫描

测试步骤

1. 重新编译后端

cd backend
mvn clean package -DskipTests

2. 重启后端服务

cd backend
java -jar target/soybean-admin-1.0.0.jar

或使用批处理文件：

start_backend.bat

3. 测试扫描功能

测试场景 1：小网段（快速测试）

• 网络地址：192.168.8.0
• 子网掩码：/28 或 255.255.255.240
• 预期时间：2-5 秒
• 预期结果：进度条显示动画，扫描完成后显示结果

测试场景 2：中等网段

• 网络地址：192.168.8.0
• 子网掩码：/24 或 255.255.255.0
• 预期时间：20-40 秒
• 预期结果：进度条持续显示动画，不会超时

测试场景 3：验证超时处理

• 网络地址：192.168.0.0
• 子网掩码：/23 或 255.255.254.0
• 预期时间：1-2 分钟
• 预期结果：能够完成扫描，不会前端超时

后端日志示例

扫描过程中，后端会输出详细日志：

2026-03-01 16:00:00.000  INFO  --- AmtNetworkScanService : 开始扫描网络: 192.168.8.0/24
2026-03-01 16:00:00.010  INFO  --- AmtNetworkScanService : 生成 IP 列表，共 254 个 IP
2026-03-01 16:00:02.000  INFO  --- AmtNetworkScanService : 扫描进度: 10/254
2026-03-01 16:00:04.000  INFO  --- AmtNetworkScanService : 扫描进度: 20/254
2026-03-01 16:00:06.000  INFO  --- AmtNetworkScanService : 扫描进度: 30/254
...
2026-03-01 16:00:10.000  INFO  --- AmtDigestService      : 发现 AMT 设备: 192.168.8.112 (DESKTOP-ABC123)
...
2026-03-01 16:00:30.000  INFO  --- AmtNetworkScanService : 扫描完成，发现 3 个设备

注意事项

1. 网络环境：

   • 扫描时间受网络延迟影响
   • 局域网环境扫描更快
   • 跨网段扫描可能较慢

2. AMT 设备响应：

   • 已启用 AMT 的设备响应快
   • 未启用 AMT 的设备会超时（增加扫描时间）

3. 防火墙设置：

   • 确保 AMT 端口（16992/16993）未被防火墙阻止
   • 某些网络可能限制端口扫描

4. 资源占用：

   • 20 个并发线程会占用一定系统资源
   • 大网段扫描时注意服务器负载

故障排查

问题 1：前端仍然超时

• 检查是否重新编译了前端代码
• 清除浏览器缓存
• 检查网络请求的实际超时时间

问题 2：后端扫描超时

• 检查网段大小，是否过大
• 查看后端日志，确认扫描进度
• 考虑增加后端超时时间或减小扫描范围

问题 3：进度条不显示

• 检查 scanning 状态是否正确
• 查看浏览器控制台是否有错误
• 确认 Naive UI 版本支持 processing 属性

问题 4：扫描速度慢

• 检查网络延迟
• 考虑增加并发线程数（需要评估服务器性能）
• 缩小扫描范围

未来优化方向

1. 实时进度推送：

   • 使用 WebSocket 或 SSE 实现实时进度推送
   • 前端可以显示准确的扫描进度

2. 分批扫描：

   • 将大网段分成多个小批次
   • 每批扫描完成后返回部分结果

3. 智能扫描：

   • 先 ping 检测主机是否在线
   • 只对在线主机进行 AMT 检测

4. 缓存机制：

   • 缓存最近扫描的结果
   • 避免重复扫描同一网段

5. 后台任务：

   • 将扫描作为后台任务执行
   • 用户可以继续其他操作
   • 扫描完成后通知用户