RajarsiGit/hunter-simulations

# DBA 演练模拟 — Claude-Code / Agent 版 这是一个用于练习 PostgreSQL/RDS 故障响应的独立实验室：将其指向一个 **非生产环境**实例，选择一个主题，它就会按需重现该故障模式 （连接耗尽、锁/死锁、慢查询，或 autovacuum/膨胀/复制/临时 文件），这样你就可以针对真实的实时症状，而不是 日志记录，来演练检测和恢复。专为人类（交互式演练，每次运行一个脚本）和 agent （非交互式 `--yes` 运行，通过 `run_all.sh` 实现全套自动化）构建。 这是 `gpt-docs/` 中涵盖的四种 PostgreSQL/RDS 故障 类别的模拟和重现脚本，它们根据那些 ChatGPT 对话记录生成，并且（在某个主题已有脚本集的情况下）从顶层的 `connection-exhaustion/` 和 `locks-deadlocks-blocking-queries/` 文件夹移植到了 一个共享的、对 agent 友好的规范上： - **通过 `.env` 提供凭据** — 无需记住导出的环境变量，也没有 硬编码的密钥。无论你从哪个目录运行脚本，只需将 `.env.example` 复制到该目录下的 `.env` 并填写内容即可。 - **非交互式安全** — 每个破坏性/变更性演练仍然会提示 `Type 'yes' to proceed`（输入 yes 继续），但 agent（或 CI）可以传入 `--yes` / 设置 `DRILL_YES=1` 来跳过提示，而不会冒任何 *意外* 自动运行的风险（这是可选启用的，而不是“因为 stdin 不是 TTY 就跳过”）。 - **Claude Code 技能就绪** — 每个主题文件夹都有一个包含 正确 frontmatter（`name`、`description`）的 `SKILL.md`，因此可以将其放入 技能目录中（或由 agent 通过 `Skill`/`Agent` 工具引用）， 并在相关的触发短语上被激活。 ``` simulations/ ├── .env.example Credential template — copy to .env ├── _lib/env.sh Shared: loads .env, confirm_drill(), strip_flags() ├── _lib/runner.sh Shared: step()/run_step() manifest runner for run_all.sh scripts ├── run_all.sh Runs all 4 topics' run_all.sh in sequence ├── 01-connection-exhaustion/ 11 scripts + run_all.sh + SKILL.md + README.md ├── 02-locks-deadlocks-blocking-queries/ 20 scripts + run_all.sh + SKILL.md + README.md ├── 03-slow-queries/ 9 scripts + run_all.sh + SKILL.md + README.md ├── 04-autovacuum-bloat-replication-temp-files/ 11 scripts + run_all.sh + SKILL.md + README.md └── README.md This file ``` 每个子文件夹都是独立的：它有自己的 `README.md`，记录了每个脚本 （它重现的内容、参数、关键观察点），并且它有自己的 `SKILL.md` 作为 面向 Claude-Code 的摘要 — 如果你是一个决定 运行哪个脚本的 agent，请先阅读它。 ## 快速开始 ``` cd simulations cp .env.example .env $EDITOR .env # PGHOST/PGPORT/PGUSER/PGPASSWORD/PGDATABASE (+ PGBOUNCER_*/DRILL_ROLE* as needed) # 人工、交互式： ./01-connection-exhaustion/06_simulate_idle_in_transaction.sh 5 300 my_test_table # Agent / 非交互式： DRILL_YES=1 ./02-locks-deadlocks-blocking-queries/03_simulate_deadlock.sh # 或者：./03-slow-queries/02_simulate_missing_index_scan.sh simulate --yes ``` 所有脚本都假定 `.env` 在调用时位于 **当前工作目录** 中 （根据 `_lib/env.sh`）— 从 `simulations/` 本身运行它们，或者 在你调用它们的任何位置旁边 `cp .env`。 ## 自动化运行 每个主题文件夹都有一个 `run_all.sh`，它通过一个命令按顺序排列该主题的完整 清单 — 设置 → 每个演练 → 检测 → 清理 — 并在最后给出一个通过/失败摘要。还有一个顶层的 `run_all.sh` 按顺序运行所有四个主题（绝不并行 — 它们共享 同一个实例，并且交错的演练会使产生的 `pg_stat_activity`/日志信号变得难以阅读）。 ``` cd simulations cp .env.example .env && $EDITOR .env # 预览整个测试套件，不接触 DB ./run_all.sh --list # 运行整个测试套件，快速扩展，非交互式 DRILL_YES=1 ./run_all.sh # 仅一个主题，doc-example 规模 ./03-slow-queries/run_all.sh --full --yes # 仅顶层中的两个主题 ./run_all.sh --topics 1,4 --yes ``` 每个 `run_all.sh` 都支持 `--list`（预览解析后的清单，不运行 任何内容）、`--fast`/`--full`（调整规模）、`--only`/`--skip`（缩小范围至特定 脚本 ID）、`--no-cleanup` 和 `--yes`/`DRILL_YES=1`。请参阅每个脚本的 头部注释（或其主题的 `README.md`/`SKILL.md`）以获取完整的标志 参考和特定于主题的选项。完整运行的输出会按步骤记录在 你调用它的任何层级下的 `run_all_logs//` 中。 ## 主题索引 | 文件夹 | 涵盖范围 | 源文档 | |---|---|---| | [`01-connection-exhaustion`](01-connection-exhaustion/README.md) | Idle-in-transaction 洪水，PgBouncer 连接池饱和（事务和会话模式），role/DB 连接数限制突破，普通 idle-connection 风暴/泄漏 | `ChatGPT-ChatGPT - Senthil.md` (+ (1)), `ChatGPT-PgBouncer Connection Exhaustion.md`, `ChatGPT-RDS Postgres Issue Guide.md` §8 | | [`02-locks-deadlocks-blocking-queries`](02-locks-deadlocks-blocking-queries/README.md) | 行/表锁，死锁，DDL 阻塞 DML，advisory locks，FK 争用，VACUUM FULL 阻塞，锁队列放大，卡住的 worker 工作流阻塞，自动化故障 RCA | `ChatGPT-RDS PostgreSQL Lock Investigation.md`, `ChatGPT-RDS PostgreSQL Lock Troubleshooting.md` | | [`03-slow-queries`](03-slow-queries/README.md) | 缺失索引扫描，函数包装的谓词，offset 与 keyset 分页，JSONB CPU 飙升，过时的 planner 统计信息，重试风暴 | `ChatGPT-RDS PostgreSQL Performance Optimization.md`, `ChatGPT-RDS Postgres Issue Guide.md` §7 | | [`04-autovacuum-bloat-replication-temp-files`](04-autovacuum-bloat-replication-temp-files/README.md) | 表/索引膨胀，autovacuum 滞后，过时统计信息导致的错误执行计划，temp-file 磁盘溢出，replication-slot WAL 保留，replica 延迟 | `ChatGPT-RDS PostgreSQL Investigation Guide.md`, `ChatGPT-RDS Postgres Issue Guide.md` §5–§6, `ChatGPT-RDS PostgreSQL Infra Monitoring.md` | `ChatGPT-AWS RDS Cost Anomalies.md` 已经过审查，但它是一个成本/计费主题， 而不是一种操作性故障模式 — 超出了这四个类别的范围，因此没有 为其生成脚本。 ## 与原始 `connection-exhaustion/` 和 `locks-deadlocks-blocking-queries/` 文件夹的关系 这两个文件夹未受影响且仍然有效 — 它们是最初的 映射到 runbook 的演练集（仅限环境变量，仅限交互式确认）。此 `simulations/` 树在 agent 驱动的使用场景中取代了它们：这里的主题 1 和 2 是直接的行为移植（相同的场景，相同的参数）到 `.env` + `--yes` 规范上，并且在 `gpt-docs` 对话记录中发现了 尚未编写脚本的场景时，每个主题增加了少量新脚本。 主题 3 和 4 完全是全新的。 ## 安全性 每个演练脚本都是 **仅限非生产环境**：它使用 独特的 `application_name`（`drill_*`）标记其会话，以便于识别和清理， 并将任何改变状态的操作限制在 `confirm_drill()` 之后（输入 `yes`， 或显式传入 `--yes`/`DRILL_YES=1`）。从该树运行脚本时，切勿将 `.env` 指向生产环境的 endpoint。每个主题文件夹都有自己的 清理脚本，可在你完成操作后移除演练会话/表。

标签：Cutter, PostgreSQL, 事故响应, 故障演练, 数据库运维, 测试用例