附录 E：实验拓扑、风险与复位手册

本附录定义实验“在哪里运行、能改变什么、怎样回到可信状态”。它不是生产授权书；每个章节的 lab contract 与当前环境 authority 优先。

E.1 L1/L2/L3 资源规格、网络和成本说明

L1：单节点学习环境

项	安装下限	本书最低	推荐
node	1	1	1
vCPU	1	2	4
RAM	2 GiB	4 GiB	8 GiB
可用磁盘	20 GiB	40 GiB	80 GiB

用途：ch01～ch18 的对象、SQL、应用与 extension PoC。默认单节点 meta 模板包含 PostgreSQL 与可观测组件，但不提供独立故障域或生产 HA。见第 0 章。

L2：四 VM 生产仿真

正式拓扑 pg36-l2-vagrant：

pg-meta-1  10.10.10.10  control + single PostgreSQL service
pg-test-1  10.10.10.11  pg-test primary at baseline
pg-test-2  10.10.10.12  pg-test replica
pg-test-3  10.10.10.13  pg-test replica/offline + disposable drill host

合同：

Pigsty v4.5.0 / PostgreSQL 18
Ubuntu 24.04 / aarch64 in formal run
UTC + synchronized clocks
data_checksums=on / UTF8 / C.UTF-8 / scram-sha-256 / SSL
distinct machine identities
minimum root free 8 GiB at acceptance

三台 pg-test VM 的正式教学运行只有 1 vCPU、约 1.9 GiB RAM；这被记录为 accepted sandbox exception。推荐至少给每个 PostgreSQL VM 2 vCPU / 2 GiB，控制/压测 client 使用 2 vCPU / 4 GiB 以上，并为 WAL、backup、clone 和 fixture 预留更多磁盘。

所有 VM 共享一台 laptop/hypervisor/power/storage，因此：

3 PostgreSQL members != 3 production failure domains
1 etcd member          != production DCS quorum
local MinIO/repository != offsite disaster recovery
virtual disk result    != production IOPS/durability

见 ch19 正式合同。

L3：从可信点分叉的事故现场

L3 不是“把 L2 破坏得更严重”，而是：

managed L2 read-only/controlled boundary
  +
stopped snapshot or deterministic source
  ->
private disposable case/working/recovery copies

第 32～35 章在 L2 host 上使用 exact UUID temporary root、private Unix socket、非业务端口/无 TCP listener，并与 Patroni、DCS、HAProxy、PgBouncer、backup repository 和业务 route 隔离。L3 需要额外磁盘至少容纳 source + cases + working/recovery + evidence；运行前按 fixture 实测，而不是假定固定 8 GiB 足够。

网络

operator -> SSH to exact lab aliases
L2 internal 10.10.10.0/24 teaching network
service path and direct instance path both identifiable
disposable cluster listen_addresses='' where contract requires
no production route or public exposure

成本

本地成本来自 host RAM/CPU、磁盘、耗电与时间；云端另有 compute、volume/snapshot、 public IP、egress、object storage/API。价格随 region/日期变化，本书不冻结金额。每个环境设置 owner、expiration 与 budget alert，并把保留 evidence 的费用计入。

E.2 R0–R3 风险标记

L1/L2/L3 描述实验环境；R0–R3 描述动作风险。两者不能互推：L3 中仍有 R0 查询，L1 上误删唯一数据仍是破坏性动作。

风险	定义	例子	必备
R0 观察	不改变目标状态	identity/catalog/stats、plain `EXPLAIN`、capture	exact context、query cost、隐私
R1 可逆变更	改状态但有已验证回退	fixture DDL、bounded config、canary、精确 cancel	owner、before/after、stop、rollback
R2 受控状态变更/演练	有非平凡状态影响，但范围隔离且恢复路径已验证	一次性对象删除、隔离 PITR/failover、fault injection	guard、批准、恢复源、停止线、证据
R3 生产敏感/潜在不可逆	触及真实数据/流量、authority/lineage，或恢复昂贵	生产 failover/cutover、rewind/reinit、host rebuild、`pg_resetwal`	原件保留、明确授权、独立复核、业务验收

同一命令没有固定风险等级：在 disposable clone 上恢复一份 candidate 可以是 R2；让它接管生产流量、覆盖真实目标或改变唯一权威时就是 R3。

风险升级因素

production data or traffic
target identity ambiguity
large or unknown scope
irreversible external effect
unique copy
weak/untested rollback
authority/lineage change
service restart or route change
long lock / resource saturation
secret or personal data exposure

任一因素都可能把看似普通命令升级。风险低不代表无成本：复杂 catalog query、 EXPLAIN ANALYZE、日志导出也可能造成负载或泄露。

guard 不是免责声明

target:
environment:
production_data:
production_traffic:
scope:
confirmation:
authority:
rollback_source:

guard 必须在 mutation 前解析并 fail closed。设置 I_KNOW_WHAT_I_AM_DOING=true 这种通用 token 不证明 target 或 authority。

各章脚本还可能使用 L0/L1/L2/L3 表示其内部 mutation level；以对应 lab-contract.md 定义为准，不与拓扑层级混用。

E.3 `reset:sql`、`reset:cluster`、`reset:host`

三种复位不是强度旋钮

复位	目标	不应做
`reset:sql`	删除/重建本章 owned fixture，恢复数据库对象起点	drop 未解析 schema/database
`reset:cluster`	恢复服务、角色、配置、路由与本章 fixture baseline	删除 managed PGDATA 猜测重建
`reset:host`	从 clean OS/storage + pinned inventory 重建不可信宿主机	当作一条普通可复制命令

名称是全书实验合同类别，不保证每章存在同名脚本。

`reset:sql`

前置：

current database/role/system identity match
owned object manifest complete
no production data/traffic
dependent session/job stopped
only pg36 chapter namespace/object selected

执行后验证 object absent/recreated、其他 schema digest 不变、connection context 仍正确。用明确对象列表，不使用模糊 wildcard/cascade。

`reset:cluster`

可能包含：

remove exact fixture sessions/roles/schema
restore parameter and pending_restart state
restore Patroni role/topology baseline
restore HAProxy/PgBouncer route
re-enable archive/backup/monitoring/automation
reconcile temporary privilege and secret

先生成 plan，逐项 before/after。计划切换后的 baseline restore 仍是 HA 变更，需要 authority 和 client validation；不是测试清理的附带步骤。

`reset:host`

只有当 OS、storage、package 或 PostgreSQL 基线不再可信才进入：

preserve/hash evidence outside target
fence host from writer authority and routes
prove trusted backup or healthy source
pin inventory/release/packages/secrets
obtain destructive production approval
provision clean host/storage
restore or join as fresh replica
validate lineage, backup, monitoring, business
observe before traffic

不要复用 suspect PGDATA，不删除唯一 evidence。第 35 章只生成 l3-rebuild-plan.json，没有执行 managed reset:host。

reset 也需要验证器

exact target resolved
owned fixture removed
unrelated object/topology unchanged
temporary process stopped
route/automation restored
retained evidence still present
cleanup path exact

“脚本执行完”不等于 baseline 已恢复。

E.4 随机种子、快照、校验和与故障场景清单

可复现 fixture

generator_revision:
seed:
row_count:
distribution:
time_anchor:
locale_timezone:
scale:
expected:
  counts:
  sums:
  ordered_digest:

固定 seed 不足以保证相同结果；generator、PRNG、locale、timezone、dependency 与输入排序都要固定。摘要至少组合 row count、关键 sum/range 与确定顺序 digest。

snapshot 树

known-good immutable source
  -> case-A original
     -> working-A1
     -> working-A2
  -> case-B original
     -> recovery-B

记录 snapshot ID、parent、created_at、filesystem/database consistency、system identifier/timeline projection 和 hash。实验只改 case/working，known-good 与 original 在结论完成前保持不变。

checksum 的四种含义

checksum/hash	证明
PostgreSQL data checksum	data page 写入/读取校验范围内的物理一致性
file SHA-256	同一 byte stream 未变
canonical JSON/source hash	合同/证据 source 未漂移
business digest	所选字段/顺序在定义范围内一致

它们不能互换。hash 匹配不证明来源可信，business digest 不证明每个 page 可读。

场景清单

scenario_id:
hidden_truth:
public_packet:
allowed_mutations:
forbidden_targets:
required_evidence:
classifier_predicates:
unknown_route:
safe_actions:
dangerous_actions:
cleanup:
claims_not_made:

blind exercise 把 hidden truth 与 participant/classifier input 分离；场景 source 在公开教材中不是密码学秘密，正式考核由主持人控制访问或生成私有 seed。

evidence bundle

contract + source manifest
environment identity
before / during / after
blind packet + hidden answer
decision/classification
business manifest
negative cases
cleanup
redacted public summary

raw logs、PGDATA、query payload、credentials 和个人数据留在受控 evidence store，仓库只发布去敏 projection。

返回附录目录 · 症状索引 · 术语边界 · 查看全书目录