Files
douyin_guaji-main/docs/archive/optimization/SCREENSHOT_PERFORMANCE_DIAGNOSIS.md
T
CodexandClaude Opus 4.7 9a51b41c3d docs: 归档过期报告 + 整体迁移 docs/optimization → docs/archive/optimization
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>
2026-05-21 11:19:28 +08:00

6.7 KiB
Raw Blame History

截图性能诊断与优化指南

概述

本文档说明如何使用新增的截图性能诊断功能,以及如何通过配置优化截图速度。

已完成的优化

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

如果看到此警告,建议:

  1. 禁用镜像功能(设置 DISABLE_SCREENSHOT_MIRROR=1)
  2. 或使用本地路径而非网络路径

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

如果测试结果显示耗时过长,检查:

  1. USB 连接是否稳定
  2. 是否使用 Wi-Fi ADB(通常较慢)
  3. 设备性能是否正常

诊断流程

步骤 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: 应用优化

根据诊断结果应用相应的优化:

  1. 如果 ADB 慢:

    • 确保使用 USB 连接而非 Wi-Fi
    • 检查 USB 驱动是否正确安装
    • 尝试重启 ADB: adb kill-server && adb start-server
  2. 如果验证慢:

    • 临时禁用验证测试: SKIP_SCREENSHOT_VERIFY=1
    • 如果禁用后明显变快,考虑优化验证逻辑
  3. 如果镜像慢:

    • 禁用镜像: DISABLE_SCREENSHOT_MIRROR=1
    • 或使用本地路径而非网络路径
  4. 如果后台服务不可用:

    • 检查 operations/screenshot_service.py 是否存在
    • 检查配置中是否禁用了流式截图
    • 查看服务启动日志

步骤 4: 验证改进

应用优化后,重新运行程序,对比日志中的总耗时:

优化前: [截图] _get_screenshot_direct总耗时(ms)=5200.0
优化后: [截图] _get_screenshot_direct总耗时(ms)=2100.0

常见问题

Q: 为什么截图从 2s 变慢到 5s?

可能原因:

  1. 连接方式变化: 从 USB 切换到 Wi-Fi ADB
  2. 外部镜像路径: 配置了网络路径,每次截图都要复制到网络位置
  3. 文件验证: PNG 验证逻辑变慢(可能是磁盘 I/O 或 PIL 版本问题)
  4. 后台服务不可用: 服务未启动或失败,回退到直接截图

诊断方法:

  1. 查看日志中的细粒度计时,找出最慢的步骤
  2. 运行 test_adb_screenshot_timing.py 测试 ADB 本身的速度
  3. 检查环境变量和配置

Q: 如何确认后台截图服务是否工作?

查看日志:

  • 如果看到 [截图] 使用后台服务耗时(ms)=...,说明服务正常工作
  • 如果看到 [截图操作] 后台服务未提供有效截图,回退到直接截图,说明服务未返回有效截图
  • 如果看到 [截图操作] 服务模式不可用,回退到直接截图,说明服务模块无法导入或启动

Q: 禁用验证是否安全?

不建议在生产环境禁用验证,因为:

  • 可能读取到损坏或不完整的截图
  • 可能导致后续检测逻辑出错

仅在以下情况考虑禁用:

  • 性能测试和诊断
  • 确认验证是瓶颈后,可以优化验证逻辑而非完全禁用

后续优化建议

短期(已完成)

  • ✅ 添加细粒度计时日志
  • ✅ 提供环境变量开关
  • ✅ 创建 ADB 基准测试工具
  • ✅ 改进后台服务诊断

中期(待实现)

  • 内存解码复用:在 get_screenshot 后立即解码一次,传递 Image 对象给所有检测函数,避免重复从磁盘读取
  • 优化 PNG 验证:使用更快的验证方法,或只在必要时验证
  • 优化文件替换:减少重试次数或使用更快的替换策略

长期(待实现)

  • 实现真正的后台截图服务:持续在后台截图,主流程直接读取缓存
  • 截图缓存机制:复用最近的有效截图,避免频繁截图

相关文件

  • Underlying_Operations.py - 截图核心逻辑
  • operations/screenshot_service.py - 后台截图服务
  • test_adb_screenshot_timing.py - ADB 基准测试脚本