企业官网建设流程全解析

• 数据库
• 运维

导读

MySQLTuner-perl 作为一款基于 Perl 的 MySQL 配置诊断与性能调优脚本，其正确性高度依赖一套可重复、可审计的测试体系。本文围绕仓库中.agent/skills/testing-orchestration/SKILL.md这份测试编排技能文档展开，系统讲解该项目的测试发现与执行方式、三方测试标准（Standard / Container / Dumpdir）、验证硬性要求与可复现性保证。读完本文，你将掌握如何用prove与 Makefile 入口运行单元测试、如何在多数据库 Docker 实验室中执行场景化测试、如何借助build/audit_tests.pl对测试输出做二次审计，以及如何在本地复现 CI 中的全部验证动作。

一、测试编排技能的定位与设计动机

MySQLTuner-perl 仓库在.agent/目录下维护了一套面向 AI Agent 的治理体系（见 .agent/README.md），其中skills/testing-orchestration/专门沉淀"如何运行、编排与验证 MySQLTuner 测试"的知识。该技能文档的Rationale明确指出：

Centralizing test execution knowledge ensures consistency across different workflows (CI, manual testing, git-flow) and provides a single source of truth for test patterns and mandates.

也就是说，集中化测试执行知识的目的是：让 CI、手工测试、git-flow 发布流程等不同工作流使用同一套测试模式和强制要求，避免各流程各自为政、标准漂移。从仓库结构看，这一设计落地为两层：

• 技能层（Skill）：testing-orchestration/SKILL.md 定义"做什么、按什么标准做"；
• 工作流层（Workflow）：run-tests.md 定义"具体怎么执行"，是技能模式的落地工具，覆盖本地单元测试、多数据库 Docker 集成测试、现有容器诊断与远程审计四个场景。

这种"技能规定标准 + 工作流固化命令"的分层方式，保证了无论测试由人类还是 Agent 触发，最终都收敛到同一批命令与同一组判定规则上。

二、测试发现与执行：从 prove 到 Makefile 的四个入口

MySQLTuner-perl 使用 Perl 标准的Test::More测试框架，测试文件统一位于tests/目录，并以.t扩展名命名（仓库当前已积累test_issue_*.t、unit_*.t、repro_*.t、cli_*.t等上百个测试文件，如 tests/test_issue_932.t、tests/verbose_timing.t）。测试辅助代码集中在 tests/MySQLTuner/TestHelper.pm。

技能文档给出的执行矩阵如下：

2.1 prove：最直接的测试驱动器

prove -r tests/是 Perl 生态的标准测试驱动工具，-r表示递归扫描tests/下的所有.t文件。当某个用例失败时，切换到prove -v -r tests/可看到每个断言（ok/not ok）的完整细节。

2.2 make unit-tests：带审计门禁的 CI 标准入口

make unit-tests在 Makefile 中定义为：

unit-tests: @echo "Running unit and regression tests..." perl ./build/audit_tests.pl

与直接跑prove不同，这个入口绕过了裸 prove，改由 build/audit_tests.pl 执行四阶段流水线：

1. 编译期语法检查（Phase 1）：对mysqltuner.pl、tests/MySQLTuner/TestHelper.pm及所有tests/*.t逐个执行perl -I. -Itests -wc，捕获syntax error、Compilation failed、Can't locate、Undefined subroutine等编译错误；
2. SQL 静态 Lint（Phase 1.5）：调用 build/check_sql_linter.pl，校验脚本内嵌 SQL 查询是否符合项目约定；
3. 测试执行（Phase 2）：默认运行prove -j4 -r tests/（4 进程并行），并把输出实时透传；
4. 输出审计门禁（Audit Gate）：逐行扫描测试输出，命中Use of uninitialized value、possible typo、syntax error、Bail out!、died at、Modification of a read-only value、Out of memory、Dubious, test returned、Failed test等模式时，分类记为 warning 或 anomaly，并最终以非零退出码阻断失败构建。

调试时可用make unit-tests-debug（对应perl ./build/audit_tests.pl --debug），它会切换为prove -j4 -rv tests/并关闭 quiet 过滤，输出所有细节。

2.3 make test / make test-it：Docker 多数据库实验室

技能文档提到的make test-it对应 Docker 化测试套件。在 README.md 中项目明确说明：Vagrant 测试环境已被视为 legacy，现代测试应使用基于 Docker 的套件，通过make test-it或build/test_envs.sh驱动。在当前 Makefile 中，等价入口为：

test: vendor_setup @echo "Running MySQLTuner Lab Tests..." bash build/test_envs.sh $(CONFIGS) test-all: vendor_setup bash build/test_envs.sh `perl build/get_supported_envs.pl` test-container: bash build/test_envs.sh -e "$(CONTAINER)"

其中vendor_setup会克隆外部实验室仓库（multi-db-docker-env与test_db到vendor/），test_envs.sh才是真正驱动多数据库场景的核心脚本。

三、三方测试标准：任何逻辑变更都必须覆盖的三个场景

技能文档规定：任何逻辑变更，测试必须覆盖以下三态：

1. Standard：--verbose
2. Container：--container
3. Dumpdir：--dumpdir=dumps

这并非随意组合，而是对应 MySQLTuner 的三种典型运行形态，分别验证不同的代码路径。

3.1 Standard 模式：完整诊断输出

--verbose是 MySQLTuner 的输出增强开关。在 mysqltuner.pl 中其定义为布尔开关（'verbose|v'，type => '!'），且带有一组隐含依赖——开启 verbose 会自动连带启用dbstat、tbstat、idxstat、sysstat、buffers、pfstat、structstat、myisamstat、plugininfo等统计项，即"打印所有选项"。测试用 tests/verbose_timing.t 专门验证：verbose 开启时各阶段执行时间与起止时间戳被输出，关闭 verbose 后这些信息消失，而--stage-timings可在不开启完整 verbose 的情况下单独输出阶段计时与汇总。

3.2 Container 模式：容器内诊断

--container在 mysqltuner.pl 中定义为接受参数值（type => '=s'）："Enable container mode with ID or name (requires docker, podman, or kubectl client)"。从源码看，该选项支持docker:、podman:、kubectl:前缀（见 get_container_prefix 子程序），用于把主机命令通过容器前缀包装后执行（mysqltuner.pl）。错误日志的获取同样支持显式指定容器（mysqltuner.pl）。机器类型检测逻辑（tests/machine_type.t）还验证了--container存在时，无论底层是 VM 还是物理机，系统类型都应被判定为 Container。

3.3 Dumpdir 模式：离线数据转储与分析

--dumpdir在 mysqltuner.pl 中定义为type => '=s'，接受一个目录路径，用于"dump information files"（数据信息文件转储）。其核心实现在dump_csv_files子程序（mysqltuner.pl）：目录不存在则自动创建；无论是否设置--outputfile，都会在 dumpdir 中生成raw_mysqltuner.txt完整原始输出；随后把各类诊断数据导出为 CSV 文件（例如user_with_general_wildcard.csv、fragmented_tables.csv、table_indexes_potential_issues.csv等，见 mysqltuner.pl 与 mysqltuner.pl）。配套的--dump-limit（默认 50000 行，mysqltuner.pl）与--compress-dump用于控制 CSV 导出的规模与压缩。这也是"离线分析"模式的基石——先 dump 数据，再脱离实时数据库做分析。

3.4 实验室脚本如何落地三态验证

build/test_envs.sh 中为每个数据库环境依次生成三个场景（build/test_envs.sh）：

# Scenario 1 - Standard：直接连库 + verbose perl mysqltuner.pl --host 127.0.0.1 --user root --pass mysqltuner_test $db_param --verbose \ --cvefile "$CVE_FILE" --outputfile "$target_dir/mysqltuner_output.txt" \ --reportfile="$target_dir/mysqltuner_report.html" # Scenario 2 - Container：经由 docker 容器前缀执行 perl mysqltuner.pl --container docker:"$container_name" --user root --pass mysqltuner_test $db_param --verbose ... # Scenario 3 - Dumpdir：生成离线数据转储 perl mysqltuner.pl --host 127.0.0.1 --user root --pass mysqltuner_test $db_param --verbose \ --dumpdir="$target_dir/dumps" ...

每次运行产物统一落入examples/目录（脚本顶部EXAMPLES_DIR="$PROJECT_ROOT/examples"，build/test_envs.sh），形成"结果快照"，便于后续审计与回归比对。make clean_examples KEEP=10用于只保留最近 10 份结果，控制磁盘占用（Makefile）。

四、验证硬性要求：三项 Mandate 必须全部满足

技能文档对每次测试运行提出三条强制验证要求：

1. 零回归（Zero Regression）：通过率必须 100%；
2. 干净报告（Clean Reports）：输出文件（HTML/日志）中不得出现error、warning、fatal、failed等关键字；
3. 基础设施日志（Infrastructure Logs）：必须采集 Docker 日志、数据库注入脚本输出等运行痕迹。

4.1 零回归如何被机器化执行

build/audit_tests.pl的 Audit Gate 就是零回归的机器化实现：任何Failed test、Dubious, test returned、Bail out!都会累积为 anomaly，最终exit 1阻断（build/audit_tests.pl）。即便 prove 的退出码为 0，只要输出中出现未初始化的值警告或拼写可疑项，也会被记入 warnings 清单——这正是"不止看退出码，还看输出质量"的设计。

4.2 干净报告的语义与实现

"输出文件不得包含 error/warning 等关键字"是一个相当严格的约定，它与项目的文档治理一脉相承（参见 documentation/specifications/test_log_auditing.md：实验室运行产生的日志中，Perl warnings、SQL errors、shell 脚本崩溃可能不触发退出码失败，但意味着质量下降或潜在缺陷）。因此 MySQLTuner 还有专门的日志审计器perl build/audit_logs.pl --dir=examples --verbose（对应make audit-logs，Makefile），用于对examples/下的历史运行产物做二次扫描。这正是"干净报告"要求的配套工具。

4.3 基础设施日志采集

在build/test_envs.sh中，每次场景运行的标准输出与错误被重定向到execution.log（> "$target_dir/execution.log" 2>&1），同时生成 HTML 报告mysqltuner_report.html与文本输出mysqltuner_output.txt。Docker 容器的启停、数据库注入脚本的执行均围绕这些日志形成完整轨迹，便于事后追溯"这次运行到底发生了什么"。

五、可复现性：每条命令都可原样重放

技能文档强调："Every test run MUST be reproducible via provided commands or scripts." 这在test_envs.sh中有直接落地——每个场景生成后，脚本会把可重放命令写入repro_cmds变量并输出，例如：

# Standard 场景的可复现命令 perl mysqltuner.pl --host 127.0.0.1 --user root --pass mysqltuner_test $db_param --verbose \ --cvefile vulnerabilities.csv --reportfile=mysqltuner_report.html # Container 场景的可复现命令 perl mysqltuner.pl --container docker:"$container_name" --verbose \ --cvefile vulnerabilities.csv --reportfile=mysqltuner_report.html # Dumpdir 场景的可复现命令 perl mysqltuner.pl --host 127.0.0.1 --user root --pass mysqltuner_test $db_param --verbose \ --dumpdir=dumps --cvefile vulnerabilities.csv --reportfile=mysqltuner_report.html

（见 build/test_envs.sh）这些命令即仓库内"怎么测的"的最精确记录，任何人拿到都能原样重放同一场景。配合vendor_setup固定的数据库镜像与test_db样本数据，多数据库实验的输入侧也保持确定性。此外，.agent/workflows/run-tests.md 还提供了远程审计的可复现形态：bash build/test_envs.sh --remote <host> --audit（等价于make audit HOST=<host>），以及针对现有容器的--existing-container <container_id>。

六、验证技能本身：如何确认测试环境就绪

技能文档给出了两个自检动作：

1. 运行prove -r tests/验证测试环境可用；
2. 验证make unit-tests能正确执行预期测试套件。

更完整的验收标准在 .agent/workflows/run-tests.md 中：所有命令退出码必须为 0，并在examples/中复查三类关键产物：

• report.html：多数据库分析结果汇总仪表盘；
• raw_mysqltuner.txt：完整分析输出（dumpdir 模式下由 dump_csv_files 无条件生成）；
• execution.log：全系统执行轨迹。

需要注意的是，examples/的自动化生成仅针对"受支持（Supported）"的 MySQL 与 MariaDB 版本，以确保样例与项目当前支持矩阵一致，避免对 EOL 版本产出误导性样本（参见 run-tests.md 中的说明）。完整的测试分类与运行说明还可参考 TESTS.md。

七、与相邻技能的协同

测试编排不是孤立的。在.agent/skills/体系中，它与另外三项技能配合构成完整的开发闭环：

• cli-execution-mastery/SKILL.md：掌握 MySQLTuner CLI 的连接与认证选项，是构造可复现测试命令的前提；
• db-version-rift/SKILL.md：映射 MySQL 与 MariaDB 各版本间的关键差异，支撑多数据库实验室的场景设计与版本矩阵选择；
• legacy-perl-patterns/SKILL.md：维护对老版本 Perl（5.8+）的向后兼容，约束测试代码本身的写法。

当三者与本文的测试编排技能共同启用时，Agent 才能既"测得全"（覆盖版本矩阵与三态场景）、又"测得对"（CLI 参数正确）、还"测得稳"（兼容性不回归）。

八、实践建议：给贡献者的最小工作流

综合技能文档与仓库实现，一个合格的"逻辑变更 + 测试"提交流程可归纳为四步：

1. 本地快速验证：prove -r tests/或prove -v -r tests/调试新用例；
2. 完整单元回归：make unit-tests，让audit_tests.pl完成语法检查、SQL lint、并行执行与输出审计四道门禁；
3. 多数据库场景验证：make test（按CONFIGS指定的版本）或make test-all（全部受支持版本），确认 Standard / Container / Dumpdir 三态全部通过、产物落在examples/；
4. 产物复核：检查examples/中最近一次运行的report.html与execution.log，确认无error、warning、fatal、failed关键字后，再进入 git-flow 提交流程。

这套流程正是 testing-orchestration/SKILL.md 所定义的"单一事实来源"——无论 CI、手工测试还是 Agent 触发，验证标准始终一致，从而保证 MySQLTuner-perl 在持续演进中保持可预期的质量基线。

• 数据库
• 运维