MySQLTuner-perl 实验产物目录清理机制详解：`examples/` 保留最近 10 次测试结果的完整实现

• 数据库
• 运维

导读

MySQLTuner-perl 的实验室测试套件（build/test_envs.sh）会在每次运行时向examples/目录写入海量的报告产物，若不加以控制，磁盘占用与检索成本会持续膨胀。本文以仓库内.agent/workflows/examples-cleanup.md工作流文档为主线，逐层拆解该清理机制的完整闭环：从触发入口、底层清理函数、独立清理脚本到 Makefile 集成与验证方法。读完本文，你将掌握如何按需保留最近 N 次测试结果、清理逻辑的实现原理，以及该机制在 CI 与手动维护中的正确用法。

一、工作流文档与清理机制的定位

仓库.agent/workflows/目录存放面向 Agent 与自动化流程的显式调用型工具说明。examples-cleanup.md 是其中的一份精简工作流定义，其全文骨架如下：

--- trigger: explicit_call description: Maintain only the 10 most recent results in the examples directory category: tool --- 1. Execute the cleanup logic from the build script: bash build/test_envs.sh --cleanup 2. Verify that the `examples/` directory count is reduced to 10.

从 YAML frontmatter 可以读出该工作流的三个关键属性：

也就是说，这是一个"两步入仓"式的维护流程：先执行清理命令，再校验结果数量，防止误删或清理失效。该工作流在 releases/v2.8.30.md 中有明确出处：ci: automate cleanup of examples/ directory to keep only the 10 most recent results与ci: add /examples-cleanup workflow for manual laboratory maintenance，说明其既是 CI 自动化的一部分，也为手动实验室维护提供了入口。

二、examples/目录里到底装了什么：产物的来源与结构

要理解清理逻辑，必须先清楚examples/的产物从何而来。实验室编排脚本 build/test_envs.sh 是所有产物的生产者：

1. 脚本启动时执行mkdir -p "$EXAMPLES_DIR"（EXAMPLES_DIR="$PROJECT_ROOT/examples"）；
2. 每次针对一个数据库配置跑实验室测试时，创建以时间戳命名的结果目录：

local current_date=$(date +%Y%m%d_%H%M%S) local root_target_dir="$EXAMPLES_DIR/${current_date}_${config}" mkdir -p "$root_target_dir"

因此examples/下的每个一级子目录都遵循YYYYMMDD_HHMMSS_config命名规范（例如20260925_003000_mysql84），这一规范是后续按"新旧"排序清理的前提。

3. 在每个结果目录内部，脚本依次执行四种审计场景（for scenario in Standard Container Dumpdir Schemadir），每个场景生成独立子目录并产出：

• report.html：汇总仪表盘（由generate_report()生成，含执行时间轴、运行时审计、产物文件清单）；
• mysqltuner_report.html：MySQLTuner 独立 HTML 报告；
• mysqltuner_output.txt：MySQLTuner 原始文本输出；
• execution.log：完整执行轨迹（stdout/stderr）；
• docker_start.log、db_injection.log、container_logs.log、container_inspect.json：基础设施与容器相关日志；
• dumps/与schemas/：Dumpdir/Schemadir 场景下的数据与结构快照（ps_*.csv、ifs_*.csv、sys_*.csv等）。

可见一个单次实验室运行即可产生数十个文件，若不清理，长期累积会显著膨胀仓库体积，这正是清理机制存在的直接动因。

三、核心入口：build/test_envs.sh --cleanup的实现

3.1 参数解析

在 build/test_envs.sh 的参数解析循环中，--cleanup被单独识别并切换运行模式：

--cleanup) MODE="cleanup" shift ;;

帮助信息中同样声明了该选项：--cleanup Maintain only 10 latest results in examples/。

3.2 清理函数cleanup_examples()

脚本在run_cmd、check_exit_code等辅助函数之后定义了清理函数（约第 176～181 行）：

# Maintain only 10 latest results in examples/ cleanup_examples() { log_step "Cleaning up old examples (keeping 10 latest)..." # List directories in EXAMPLES_DIR, sort by modification time descending, skip first 10, then remove the rest. ls -dt "$EXAMPLES_DIR"/*/ 2>/dev/null | tail -n +11 | xargs -r rm -rf }

逐段拆解这条"一行清理"的核心逻辑：

值得注意：ls -t依赖文件系统记录的目录修改时间（mtime）。由于每次测试都会在新目录内写入文件，新目录的 mtime 自然大于旧目录；同时cleanup_examples在每次完整实验室运行结束（主流程case "$MODE"之后）都会被调用一次，形成"边跑边清"的自维护闭环：

# Always cleanup at the end of a successful run cleanup_examples

而在cleanup模式下（--cleanup），主流程直接调用该函数后即退出：

cleanup) cleanup_examples exit 0 ;;

3.3 两种调用路径的对比

两者复用同一个cleanup_examples()函数，行为完全一致，这也是.agent/workflows/examples-cleanup.md可以放心把--cleanup作为唯一命令的原因。

四、独立清理脚本：build/clean_examples.sh与 KEEP 参数

除了集成在test_envs.sh中的清理逻辑，仓库还提供了一个更通用、参数化的独立版本 build/clean_examples.sh。它同样以examples/为清理对象，但把保留数量抽象为命令行参数：

set -euo pipefail EXAMPLES_DIR="examples" KEEP=${1:-5}

核心差异在于排序与筛选方式：

DIRS_TO_DELETE=$(ls -1d "$EXAMPLES_DIR"/*/ 2>/dev/null | sort -r | tail -n +$((KEEP + 1)))

这里不再依赖 mtime，而是按目录名的字典序逆序（sort -r）筛选——因为目录名自带YYYYMMDD_HHMMSS_config时间前缀，字典序与时间序完全一致，sort -r等价于"最新在前"。随后逐目录打印并删除：

for dir in $DIRS_TO_DELETE; do echo "Deleting $dir" rm -rf "$dir" done

两种实现各有侧重：

• test_envs.sh --cleanup：保留数量固定为 10，贴合实验室"最近 10 次"的既定策略；
• clean_examples.sh：KEEP可调，默认保留 5 个，灵活应对不同维护需求，且set -euo pipefail使脚本在异常时立即失败，更适合作独立工具使用。

从 documentation/QUALITY_AND_TESTING.md 的脚本清单也可以印证其定位：Cleanup Utility，用途为"Keeps theexamples/directory lean by pruning oldest test run folders"，参数[KEEP]默认 5。

五、Makefile 集成：把清理变成一等公民

清理逻辑被完整接入了项目构建体系，见 Makefile：

clean_examples: @echo "Cleaning up examples..." bash build/clean_examples.sh $(KEEP)

• 默认执行：make clean_examples，等效于bash build/clean_examples.sh（KEEP 默认 5）；
• 指定保留数量：make clean_examples KEEP=10，即保留最近 10 个结果目录，与工作流文档的策略一致；
• 帮助文本中亦有声明：clean_examples: Cleanup examples directory (KEEP=n, default 5)。

更重要的是，test-parallel目标把并行测试与清理串联成一个完整流程：

test-parallel: vendor_setup @echo "Running MySQLTuner Parallel Lab Tests..." bash build/parallel_test.sh && $(MAKE) clean_examples KEEP=10

这表示：并行实验室测试全部成功后，自动执行清理并固定保留 10 份结果——正是.agent/workflows/examples-cleanup.md中"10"这个数字在 CI 侧的对应实现。清理由此不再依赖人工，而是内建于质量流水线。

六、验证步骤：如何确认清理成功

工作流文档的第二步是"Verify that theexamples/directory count is reduced to 10"。仓库中虽然没有专门的自动化断言脚本，但该验证可以完全借助标准的 Shell 命令完成：

# 统计 examples/ 下的一级目录数量（清理后应为 10） ls -1d examples/*/ | wc -l # 或使用 find 的 maxdepth 计数 find examples -maxdepth 1 -type d ! -name examples | wc -l # 查看保留的是否为最新 10 个（按时间从新到旧） ls -dt examples/*/

验证要点：

1. 数量：一级子目录数必须等于 10（或等于KEEP指定值），多则清理未生效，少则可能存在误删；
2. 时效性：保留的必须是"最近"的结果——由于目录名带时间戳前缀，ls -1d examples/*/ | sort -r | head -n 10输出的目录应与实际保留目录完全一致；
3. 完整性：抽查保留目录内仍包含report.html、execution.log等关键产物，确认清理只删旧不伤新。

若清理后发现数量不符，可从以下角度排查：确认目录确实遵循YYYYMMDD_HHMMSS_config命名规范（clean_examples.sh的sort -r依赖此规范）；确认examples/下没有混入非结果目录（如 README 等文件不会被*/通配命中，但若存在其他无时间戳前缀的目录，排序可能失真）。

七、机制要点与使用建议

综合.agent/workflows/examples-cleanup.md与仓库实现，可以总结出该清理机制的几条工程要点：

1. 双入口单逻辑：test_envs.sh --cleanup与clean_examples.sh KEEP=n分别面向"固定 10 份"和"可调数量"两种场景，选择时按需使用；
2. 命名规范即排序依据：YYYYMMDD_HHMMSS_config的目录命名让 mtime 排序（ls -t）与字典序排序（sort -r）等价，这是清理正确性的根基；
3. 自动化与手动并存：test-parallel在 CI 侧自动清理，--cleanup工作流在手动维护侧按需清理，二者共用同一保留策略，避免仓库因测试产物膨胀；
4. 验证闭环：清理动作本身不可信，必须通过目录计数与时效性校验确认结果，这正是工作流文档把"Verify"列为第二步的原因。

对于使用该仓库测试基础设施的开发者，建议将make clean_examples KEEP=10纳入常规实验室维护流程；若只想临时瘦身，直接执行bash build/test_envs.sh --cleanup即可，两者都能让examples/保持"最近 10 次结果"的整洁状态，为后续审计（如make audit-logs对examples/的日志扫描）提供稳定的输入集合。

参考路径速查

• 工作流定义：.agent/workflows/examples-cleanup.md
• 实验室编排与清理主入口：build/test_envs.sh
• 独立清理脚本（KEEP 可调）：build/clean_examples.sh
• Makefile 集成：Makefile
• 测试基础设施文档：documentation/QUALITY_AND_TESTING.md
• 功能引入记录：releases/v2.8.30.md

• 数据库
• 运维