LOCAL RUNBOOK / 15–25 MIN

亲手获得实验结果。

在自己的机器上运行两个真实会话与一个观察者。修改 SQL 与调试并发是学习流程的一部分，因此配套实验仓库公开。

01 / 准备隔离运行环境

要求 Python 3.11+、Docker Engine 与 Compose v2 或独立 docker-compose。为引擎预留 2 核、2 GiB 内存，磁盘至少空闲 2 GiB。数据库容器限制为 2 核 / 1 GiB。无需付费服务。

可使用健康的现有引擎，或在 macOS 新建专用 Colima profile。不要清理其他实验卷来腾空间。使用下方 profile 时，每条 Lab 命令都应保留 DOCKER_CONTEXT。

colima start --profile mysql-lab --cpu 2 --memory 2 --disk 12 --activate=false
export DOCKER_CONTEXT=colima-mysql-lab

02 / 启动、运行、停止

git clone https://github.com/lynnlee1229/mysql-lab.git
cd mysql-lab
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python lab.py doctor
python lab.py start --port 13316
python lab.py run
python lab.py stop

start 在忽略提交的 .local/ 中生成随机密码，限制文件权限，仅创建 lynn-mysql-lab Compose 项目，并绑定 127.0.0.1:13316。首次启动可选择其他空闲端口。不要将运行器连接到业务数据库：run 会删除并重建专用 mysql_lab 的实验表。

成功运行会在 .local/runs/ 下保存带时间戳、已筛选字段的 run.json。完整 InnoDB 死锁原文位于 raw-local-only/，不会复制到网页。失败运行返回非零状态，不会生成成功报告。

03 / 预测、检查、修改

预测哪条第二次 UPDATE 会等待。检查观察屏障、真实 data_lock_waits 边、1213 错误和最终数值，再比较同顺序对照。
预测每个隔离级别下四次读取的数值。检查 FOR UPDATE 前后的普通读取，并确认 B 的后续写入真实等待。
比较全表扫描与联合索引非覆盖查询的相同哈希；比较覆盖范围查询与 DATE_FORMAT 的相同投影及哈希。解释耗时前先阅读 EXPLAIN ANALYZE 的 actual rows。

先保留基线报告，再修改 scripts/experiments.py 的加锁顺序或查询条件，复跑并比较实际证据。固定种子保留数据，优化器与硬件行为仍可能不同。

04 / 保留数据或显式销毁

python lab.py stop       # retains the named data volume
python lab.py start      # uses the same credentials and volume
python lab.py run        # resets only the synthetic experiment tables

# Explicitly destructive: removes only this Lab project and data volume
python lab.py destroy --confirm lynn-mysql-lab

保留数据库卷时不要删除 .local/config.json 或 compose.env：密码必须与卷内保存的一致。stop 不停止 Docker 引擎。使用专用 profile 时，先停止 Lab，再按需执行 colima stop --profile mysql-lab。

05 / 构建阅读站并验证

python -m unittest discover -s tests -v
python scripts/validate.py records/run-clean.json records/run-repeat.json
python scripts/build_site.py
python scripts/check_site.py
python -m http.server 18911 --bind 127.0.0.1 --directory dist

访问 http://127.0.0.1:18911/mysql-lab/en/。导出器仅读取已提交的白名单记录与网页资源，不扫描 .local/、原始日志、环境文件或主页源码。

固定镜像与故障排查

mysql:8.4.13@sha256:a81d043930e51745522bd5c430961cf8286f0a23f0a9a2a6e0108f7ea71b0902

doctor 检查引擎、Compose、驱动与磁盘。端口占用或初始化失败会使 start 明确失败。连接拒绝时检查 context 并启动引擎。1205 请检查保存的超时案例。断言失败时保留本地证据并停止/重启后复跑，不要用预期数值替换结果。

打开公开配套实验仓库 ↗