A. docs/ 根目录下 5 篇过期/迁移类文档归档到 docs/archive/ - LOGGING_IMPROVEMENTS.md (日志系统迭代报告,与 archive/日志系统优化说明.md 重复) - OCR性能分析报告.md (历史性能分析) - 统一截图和分数记录说明.md (重构方案,已合并到代码) - AI_PROJECT_SUMMARY.md (提到的 Underlying_Operations.py / path_config.py 路径已与 main 重构后不一致) - param_usage.md (模块使用说明,零引用,模块本身有 docstring) B. docs/optimization/ 整目录归档为 docs/archive/optimization/(7 篇) - ADB_EXECOUT_OPTIMIZATION / OCR_PERFORMANCE_OPTIMIZATION - SCREENSHOT_PERFORMANCE_DIAGNOSIS / SCREENSHOT_VERIFICATION_GUIDE - STREAMING_SCREENSHOT_DISABLED / STREAMING_SCREENSHOT_COMPLETELY_DISABLED - optimize_file_replace 全部是优化报告 / 已禁用功能记录,属于历史迭代而非活文档 C. docs/README.md 重写为按主题分组的索引,明确"活文档 vs 归档"边界 保留为活文档: - 日志系统规范文档.md(被 3 处引用) - 日志轮转功能说明.md(描述当前在用的轮转策略) - 截图服务日志说明.md(描述当前服务行为) - 完整技术文档.md / 流程图.md / 预约系统详细流程.md / 高价值房间重访功能说明.md 回归:纯文档归档不影响代码;140 .py 全量编译通过; test_filter_logging / check_web_gui_config_sync 通过。 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
6.7 KiB
6.7 KiB
截图性能诊断与优化指南
概述
本文档说明如何使用新增的截图性能诊断功能,以及如何通过配置优化截图速度。
已完成的优化
1. 细粒度计时日志
在 _get_screenshot_direct 中添加了详细的计时日志,可以精确定位每个步骤的耗时:
[截图] ADB exec-out subprocess耗时(ms)=...- ADB 子进程执行耗时[截图] flush+fsync耗时(ms)=...- 文件刷新和同步耗时[截图] 临时文件验证耗时(ms)=...- PNG 验证耗时[截图] 文件替换耗时(ms)=...- 文件替换操作耗时[截图] 镜像总耗时(ms)=...- 外部镜像复制耗时[截图] _get_screenshot_direct总耗时(ms)=...- 总耗时
使用方法: 运行程序后,查看日志输出,找出耗时最长的步骤。
2. 环境变量开关
禁用 PNG 验证 (SKIP_SCREENSHOT_VERIFY)
如果 PNG 验证是瓶颈,可以临时禁用以测试:
# Windows PowerShell
$env:SKIP_SCREENSHOT_VERIFY = "1"
python your_script.py
或在程序启动前设置环境变量。
注意: 禁用验证会跳过文件完整性检查,可能导致读取到损坏的截图。仅用于性能测试。
禁用外部镜像 (DISABLE_SCREENSHOT_MIRROR)
如果外部镜像路径是网络路径或较慢的路径,可以禁用以提升性能:
# Windows PowerShell
$env:DISABLE_SCREENSHOT_MIRROR = "1"
python your_script.py
3. 外部路径诊断
系统会自动检测外部镜像路径是否是网络路径(UNC 路径),并在日志中标记:
[截图] 检测到网络路径,镜像可能较慢: \\server\path
如果看到此警告,建议:
- 禁用镜像功能(设置
DISABLE_SCREENSHOT_MIRROR=1) - 或使用本地路径而非网络路径
4. 后台截图服务诊断
改进了 ScreenshotService 的诊断和自动启动:
- 如果服务未运行,会自动尝试启动
- 如果服务不可用,会记录详细错误信息
- 日志会显示服务是否成功返回截图
查看日志中的 [截图] 使用后台服务耗时(ms)=... 来判断服务是否正常工作。
5. ADB 基准测试脚本
创建了 test_adb_screenshot_timing.py 用于独立测试 ADB 截图性能。
使用方法:
# 测试默认设备
python test_adb_screenshot_timing.py
# 测试指定设备
python test_adb_screenshot_timing.py <device_id>
脚本会:
- 测试
exec-out screencap(主要方案)的耗时 - 测试
shell screencap + pull(回退方案)的耗时 - 提供统计信息(平均、最小、最大耗时)
预期结果:
- USB 连接:通常 < 2000ms
- Wi-Fi 连接:可能 > 3000ms
如果测试结果显示耗时过长,检查:
- USB 连接是否稳定
- 是否使用 Wi-Fi ADB(通常较慢)
- 设备性能是否正常
诊断流程
步骤 1: 运行程序并查看日志
运行程序,观察日志中的计时信息:
[截图] ADB exec-out subprocess耗时(ms)=4500.0 device=xxx
[截图] _get_screenshot_direct总耗时(ms)=5200.0 device=xxx
步骤 2: 识别瓶颈
根据日志找出耗时最长的步骤:
-
ADB exec-out subprocess 耗时 > 3000ms:
- 可能是网络/连接问题
- 运行
test_adb_screenshot_timing.py进行独立测试 - 检查是否使用 Wi-Fi ADB
-
文件验证耗时 > 500ms:
- 尝试设置
SKIP_SCREENSHOT_VERIFY=1测试 - 注意:这会跳过完整性检查
- 尝试设置
-
镜像耗时 > 500ms:
- 检查外部路径是否是网络路径
- 设置
DISABLE_SCREENSHOT_MIRROR=1测试
-
文件替换耗时 > 500ms:
- 可能是文件被占用或磁盘 I/O 慢
- 检查是否有其他进程在访问截图文件
步骤 3: 应用优化
根据诊断结果应用相应的优化:
-
如果 ADB 慢:
- 确保使用 USB 连接而非 Wi-Fi
- 检查 USB 驱动是否正确安装
- 尝试重启 ADB:
adb kill-server && adb start-server
-
如果验证慢:
- 临时禁用验证测试:
SKIP_SCREENSHOT_VERIFY=1 - 如果禁用后明显变快,考虑优化验证逻辑
- 临时禁用验证测试:
-
如果镜像慢:
- 禁用镜像:
DISABLE_SCREENSHOT_MIRROR=1 - 或使用本地路径而非网络路径
- 禁用镜像:
-
如果后台服务不可用:
- 检查
operations/screenshot_service.py是否存在 - 检查配置中是否禁用了流式截图
- 查看服务启动日志
- 检查
步骤 4: 验证改进
应用优化后,重新运行程序,对比日志中的总耗时:
优化前: [截图] _get_screenshot_direct总耗时(ms)=5200.0
优化后: [截图] _get_screenshot_direct总耗时(ms)=2100.0
常见问题
Q: 为什么截图从 2s 变慢到 5s?
可能原因:
- 连接方式变化: 从 USB 切换到 Wi-Fi ADB
- 外部镜像路径: 配置了网络路径,每次截图都要复制到网络位置
- 文件验证: PNG 验证逻辑变慢(可能是磁盘 I/O 或 PIL 版本问题)
- 后台服务不可用: 服务未启动或失败,回退到直接截图
诊断方法:
- 查看日志中的细粒度计时,找出最慢的步骤
- 运行
test_adb_screenshot_timing.py测试 ADB 本身的速度 - 检查环境变量和配置
Q: 如何确认后台截图服务是否工作?
查看日志:
- 如果看到
[截图] 使用后台服务耗时(ms)=...,说明服务正常工作 - 如果看到
[截图操作] 后台服务未提供有效截图,回退到直接截图,说明服务未返回有效截图 - 如果看到
[截图操作] 服务模式不可用,回退到直接截图,说明服务模块无法导入或启动
Q: 禁用验证是否安全?
不建议在生产环境禁用验证,因为:
- 可能读取到损坏或不完整的截图
- 可能导致后续检测逻辑出错
仅在以下情况考虑禁用:
- 性能测试和诊断
- 确认验证是瓶颈后,可以优化验证逻辑而非完全禁用
后续优化建议
短期(已完成)
- ✅ 添加细粒度计时日志
- ✅ 提供环境变量开关
- ✅ 创建 ADB 基准测试工具
- ✅ 改进后台服务诊断
中期(待实现)
- 内存解码复用:在
get_screenshot后立即解码一次,传递 Image 对象给所有检测函数,避免重复从磁盘读取 - 优化 PNG 验证:使用更快的验证方法,或只在必要时验证
- 优化文件替换:减少重试次数或使用更快的替换策略
长期(待实现)
- 实现真正的后台截图服务:持续在后台截图,主流程直接读取缓存
- 截图缓存机制:复用最近的有效截图,避免频繁截图
相关文件
Underlying_Operations.py- 截图核心逻辑operations/screenshot_service.py- 后台截图服务test_adb_screenshot_timing.py- ADB 基准测试脚本