// src/include/access/xlogrecord.h
typedef struct XLogRecord {
    uint32      xl_tot_len;     // 整个 record 的总长度（包括 header）
    TransactionId xl_xid;       // 产生此 record 的事务 ID
    XLogRecPtr  xl_prev;        // 上一个 record 的起始 LSN（形成链）
    uint8       xl_info;        // flag bits（XLR_SPECIAL_REL_UPDATE 等）
    RmgrId      xl_rmid;        // 资源管理器 ID（RM_HEAP, RM_BTREE, RM_XLOG 等）
    pg_crc32c   xl_crc;         // CRC-32C 校验和（覆盖整个 record）
    // 后面紧跟着：
    //   XLogRecordBlockHeader（可能有多个，每个 block 一个）
    //   XLogRecordDataHeader[Short|Long]（main data）
} XLogRecord;
```text

`xl_rmid` 是 RMGR ID，决定恢复时由哪个资源管理器处理这个 record：

```c
// src/include/access/xlog_internal.h
#define RM_XLOG_ID          0
#define RM_XACT_ID          1
#define RM_SMGR_ID          2
#define RM_CLOG_ID          3
#define RM_DBASE_ID         4
// ...
#define RM_HEAP_ID          10
#define RM_BTREE_ID         12
#define RM_GIN_ID           15

// src/include/access/xlogrecord.h
typedef struct XLogRecordBlockHeader {
    uint8       block_id;       // 此 block 在 record 中的编号（0-31）
    uint8       fork_flags;     // fork 类型（MAIN_FORKNUM 等）+ flags
    uint16      data_length;    // 紧跟在后面的 block data 的长度
    // 接着是：
    //   BlockIdData  (RelFileNode + BlockNumber) 或 XLogRecordBlockCompressHeader
    //   block data（整页镜像或 diff 数据）
} XLogRecordBlockHeader;
```text

Block 的映像有三种注册方式（通过 `fork_flags` 的高位 bit 区分）：

| 注册方式 | fork_flags 标志 | 含义 | 恢复时如何使用 |
|---------|----------------|------|--------------|
| `REG_BUF_STANDARD` | `BKPBLOCK_HAS_IMAGE` | 记录整页镜像（FPW, Full Page Write） | 直接覆盖目标页 |
| `REG_BUF_STANDARD` | 无 image flag | 只记录操作描述（如"在 offset 插入这个 tuple"） | 在目标页上重放操作 |
| `REG_BUF_STANDARD` | `BKPBLOCK_HAS_IMAGE \| BKPBLOCK_COMPRESSED` | 整页压缩镜像 | 解压后覆盖目标页 |

**FPW（Full Page Write）的意义**：checkpoint 之后每个页面第一次被修改时，PG 把整页镜像写入 WAL。这听起来浪费，但它是防止页面撕裂的关键。如果不用 FPW，恢复时 REDO 操作必须假设目标页是 checkpoint 时的旧版本——但一次中途崩溃可能让页面处于"旧 header + 新数据"的撕裂状态。FPW 绕过了这个问题：直接用整页镜像覆盖，确保页面的完整性和自一致性。

FPW 的数据量是 WAL 写入量的主要来源。一个 UPDATE 只改了几十个字节，但如果涉及的页面是 checkpoint 后的首次修改，FPW 会把整个 8KB 页面写进 WAL。这也解释了为什么 checkpoint 之后 WAL 写入会出现一个高峰。

### 一个 INSERT 的 WAL Record 示例

执行 `INSERT INTO t VALUES (1, 'hello')` 并提交，产生的 WAL record 链：

### 3.1 WALInsertLock：分段锁的并发设计

多个 Backend 同时产生 WAL record 时，如果用一个全局锁保护 WAL Buffer 的写入位置，锁竞争会成为瓶颈。PG 的策略是把 WAL 插入位置分成多个 **WALInsertLock** 插槽：

```c
// src/backend/access/transam/xloginsert.c
// PG 17 默认 WALInsertLock 数量 (xlog.h)
#define NUM_XLOGINSERT_LOCKS  8

// 每个 Backend 在插入 WAL 时：
// 1. 持有一个 WALInsertLock（通过 MyProc->lockGroupLeader 或 hash(ProcNumber) 选择）
// 2. 在自己的 slot 中预留空间
// 3. 复制数据到 WAL Buffer

// src/backend/access/transam/xloginsert.c
// ReserveXLogInsertLocation() 的核心逻辑（简化）
static XLogRecPtr
ReserveXLogInsertLocation(int size)
{
    // 1. 检查 WAL Writer 是否已刷到安全位置，如果 WAL Buffer 满了则自旋等待
    do {
        if (WAL buffer 空间不足) {
            WALInsertLockRelease();
            WaitXLogInsertionsToFinish(RequiredFree);
            WALInsertLockAcquire();
        }

        // 2. 为当前 record 预留空间
        StartPos = XLogBytePosToRecPtr(CurrPos);
        CurrPos += size;

        // 3. 如果跨越 WAL segment 边界
        if (CurrPos / XLOG_SEG_SIZE != PrePos / XLOG_SEG_SIZE) {
            AdvanceXLInsertBuffer(CurrPos);  // 分配新 WAL buffer
        }
    } while (false);

    return StartPos;
}
```text

预留在 WAL Buffer 中的空间是 **Lock 区域的私人空间**，其他 Backend 不能碰，但 WAL Writer 可以安全刷盘——因为它只刷"所有 Lock 都已完成的连续字节"。

### 3.3 CopyXLogRecordToWAL：组装并拷贝

```c
// src/backend/access/transam/xloginsert.c
// 拷贝过程（简化）
static void
CopyXLogRecordToWAL(int write_len, XLogRecPtr StartPos)
{
    // 1. 组装 XLogRecord header（填充 xl_prev, xl_rmid, xl_xid 等）
    XLogRecord *rechdr = &hdr_rdt;
    rechdr->xl_tot_len = write_len;
    rechdr->xl_prev = ProcLastRecPtr;
    // ...

    // 2. 计算 CRC（覆盖除 xl_crc 字段外的整个 record）
    INIT_CRC32C(rechdr->xl_crc);
    COMP_CRC32C(rechdr->xl_crc, ...);

    // 3. 按字节拷贝到 WAL Buffer
    memcpy(wal_buffer + offset, rec_data, rec_len);

    // 4. 更新 WAL 插入位置（原子写）
    pg_atomic_write_u64(&WALInsertLocks[l].insertingAt, CurrPos);
}

// src/backend/postmaster/walwriter.c, WalWriterMain() 核心逻辑（简化）
for (;;) {
    // 1. 等待 WAL flush position 落后于 insert position（有数据需要刷）
    WaitXLogActivity(WAL_WRITER_FLUSH_AFTER, ...);

    // 2. 把 WAL Buffer 中已完成的 WAL record 写入 OS page cache
    XLogBackgroundFlush();

    // 3. 如果累积了足够的数据或时间，调用 issue_xlog_fsync()
    if (足够条件) {
        issue_xlog_fsync(openLogFile, openLogSegNo);
    }
}
```text

注意 WAL Writer 做的是**异步刷盘**。它把 WAL 数据从 WAL Buffer 写到 OS page cache，然后定期 fsync。对于普通事务，`COMMIT` 后的数据不保证立即落盘——这取决于 `synchronous_commit` 和 `wal_sync_method` 的设置。

### 4.2 同步提交时 Backend 直接 fsync

当 `synchronous_commit = on`（默认）时，`COMMIT` 的调用路径是：

// src/backend/access/transam/xlog.c, CreateCheckPoint() Phase 1（简化）
// 1. 获取当前 WAL 插入位置作为 checkpoint 结束 LSN
checkPoint.redo = GetRedoRecPtr();  // 获取最老的脏页 LSN
                                    // 即 REDO 必须从这个 LSN 开始

// 2. 让共享内存中的 checkpoint 信息对所有进程可见
SpinLockAcquire(&XLogCtl->info_lck);
XLogCtl->RedoRecPtr = checkPoint.redo;
SpinLockRelease(&XLogCtl->info_lck);
```text

`GetRedoRecPtr()` 的内部逻辑是扫描所有 buffer，找到最老的脏页 LSN。因为脏页在系统崩溃时会丢失，而 WAL 从该 LSN 开始需要重放才能恢复所有已暂存（committed 但未刷盘）的数据。REDO point 越老，下次崩溃恢复需要重放的 WAL 越少——因为更多的脏页已被刷盘，对应的 WAL 段可以被回收。

**Phase 2：刷脏页并写 checkpoint record**

```c
// src/backend/access/transam/xlog.c, CreateCheckPoint() Phase 2（简化）
// 1. 刷所有脏页到磁盘
CheckPointGuts(checkPoint.redo, flags);
//   → CheckPointBuffers()         // 刷 shared_buffers 脏页
//   → CheckPointSnapBuilding()    // 刷 snap 构建相关的状态
//   → CheckPointReplicationSlots()// 刷 replication slot 状态
//   → CheckPointSnapBuild()       // 刷逻辑解码 snapshot builder 状态
//   → CheckPointTwoPhase()        // 刷 2PC 状态文件

// 2. 写 checkpoint WAL record
XLogBeginInsert();
XLogRegisterData(&checkPoint, sizeof(checkPoint));
recptr = XLogInsert(RM_XLOG_ID, XLOG_CHECKPOINT_SHUTDOWN);

// 3. 更新 pg_control 文件
UpdateControlFile();

// 每刷一定数量的 buffer 后调用 CheckpointWriteDelay()
// 计算目标进度：
progress = (当前已刷脏页数) / (预期总脏页数);
elapsed = (当前时间 - checkpoint 开始时间);
target_elapsed = checkpoint_timeout * checkpoint_completion_target * progress;

// 如果刷得太快（progress 超前于 elapsed），sleep
if (elapsed < target_elapsed) {
    sleep_time = target_elapsed - elapsed;
    pg_usleep(sleep_time * 1000000L);
}
```text

核心陷阱：如果 `checkpoint_completion_target = 0.9` 看起来"接近 1，已经够激进了"，但实际效果取决于 `checkpoint_timeout` 和 `max_wal_size` 谁先触发 checkpoint：

- 如果 checkpoint 由 `max_wal_size` 触发（WAL 写入速度很高），而 `checkpoint_timeout` 是 5 分钟、`completion_target` 是 0.9，那么 Checkpointer 的任务窗口是 **4.5 分钟**。如果实际脏页量需要 10 分钟才能在不打满 IO 的情况下刷完，那么 4.5 分钟窗口根本不够——Checkpointer 会卡在 sleep 和 write 之间，最终在 checkpoint 结束时仍然全力冲刺刷脏页。
- 实际情况中，如果 WAL 写入速率很高（例如 100MB/s），`max_wal_size = 1GB` 的默认值意味着约 10 秒就触发一次 checkpoint。此时 `completion_target` 根本不起作用——总时间窗口太短，无法摊平。

---

## 六、REDO 恢复：StartupXLOG

当 PG crash 后重启时，`PostmasterMain()` 调用 `StartupXLOG()` 执行 REDO 恢复。`StartupXLOG()` 是 `src/backend/access/transam/xlog.c` 中最长也最复杂的函数（PG 17 中约 2000 行）。

### 6.1 恢复流程

### 6.2 RMGR 分发

每个 RMGR（Resource Manager）是一个静态结构，在 `src/include/access/rmgr.h` 中注册：

```c
// 例：Heap RMGR 的 redo 入口
// src/backend/access/heap/heapam.c
const RmgrData RmgrTable[] = {
    // ...
    [RM_HEAP_ID] = {
        .rm_name    = "Heap",
        .rm_redo    = heap_redo,
        .rm_desc    = heap_desc,
        .rm_identify = heap_identify,
    },
};

// src/backend/access/heap/heapam.c
void heap_redo(XLogReaderState *record) {
    uint8   info = XLogRecGetInfo(record) & ~XLR_INFO_MASK;
    switch (info & XLOG_HEAP_OPMASK) {
        case XLOG_HEAP_INSERT:
            heap_xlog_insert(record);  // 重放 INSERT
            break;
        case XLOG_HEAP_DELETE:
            heap_xlog_delete(record);  // 重放 DELETE
            break;
        case XLOG_HEAP_UPDATE:
            heap_xlog_update(record);  // 重放 UPDATE
            break;
        // ...
    }
}
```bash

### 6.3 REDO 的幂等性

恢复过程中 PG 如何保证不会重复 REDO 一个页面？每个页面上的 `pd_lsn` 字段（`PageHeaderData.pd_lsn`，8 bytes）是关键。REDO 函数在重放每个 record 之前检查：

```c
// REDO 函数中的典型逻辑
if (record_LSN <= page->pd_lsn)
    return;  // 此页面已经 REDO 过了，跳过
// ... 执行 REDO 操作 ...
page->pd_lsn = record_LSN;

-- 1. 观察 checkpoint 触发频率
SELECT * FROM pg_stat_bgwriter;
-- 关注 checkpoints_timed（时间触发）和 checkpoints_req（WAL 触发）的比值
-- 如果 checkpoints_req >> checkpoints_timed，说明 max_wal_size 太容易触发

-- 2. 观察 checkpoint 写入量
-- buffers_checkpoint：checkpoint 刷了多少 buffer
-- buffers_clean：bgwriter 刷了多少 buffer
-- 如果 buffers_checkpoint >> buffers_clean，说明 bgwriter 没分担足够的脏页刷盘

-- 3. 看实际的 WAL 写入速率
SELECT pg_wal_lsn_diff(pg_current_wal_lsn(), '0/0') / 1024 / 1024 AS wal_mb;
-- 连续两次执行，除以时间差，得到 WAL 写入速率（MB/s）

-- 4. 确认 checkpoint 间隔
SELECT * FROM pg_control_checkpoint();
-- 对比两次查询的 checkpoint_time 字段的间隔
```text

**调优策略**：

1. **增大 `max_wal_size`**：如果 `checkpoints_req`（WAL 触发）过多，说明 WAL 段积累太快。把 `max_wal_size` 从 1GB 调到 8-16GB 能显著降低 checkpoint 频率。但代价是：崩溃恢复时需要重放更多的 WAL，恢复时间变长。恢复时间 ≈ WAL 量 / 恢复吞吐（SSD 上约 200-500MB/s）。16GB WAL 在 SSD 上恢复约 30-80 秒。

2. **增加 `checkpoint_timeout`**：如果脏页总量不大但 `checkpoint_timeout` 触发太快（默认 5 分钟），可以调大（如 15-30 分钟）。代价同样是更长的恢复时间。

3. **调整 `checkpoint_completion_target`**：如果 checkpoint 由 `max_wal_size` 触发，并且 WAL 写入速率接近或超过磁盘带宽的一半，`completion_target` 设为 0.9 可能根本不够。此时该调到 0.5-0.7 吗？不是——Cheap 的"摊平窗口" = `min(checkpoint_timeout, max_wal_size / WAL 写入速率) * completion_target`。如果这个窗口太小，该调的其实是 `max_wal_size`。

4. **启用 `wal_compression = zstd`**（PG 15+）：压缩 FPW 镜像，减少 WAL 写入量。CPU 开销可控（zstd 压缩比和速度的平衡很好），能显著降低 checkpoint 期间的 WAL 写入压力。

5. **提高 `bgwriter` 的积极性**：bgwriter 能在 checkpoint 之前刷掉一部分脏页，减少 checkpoint 的压力。相关参数：`bgwriter_lru_maxpages`（每次最多刷多少页）、`bgwriter_delay`（多久醒来一次）。bgwriter 按 `bgwriter_lru_multiplier` 计算每次应刷的页数，公式基于最近的平均 buffer 替换需求。

### 8.2 max_wal_size 设小导致 WAL 段疯狂切换

**症状**：`pg_stat_bgwriter` 中 `checkpoints_req` 非常高（每秒多次），`pg_ls_waldir()` 显示 WAL 文件不断创建和删除，但每个文件都很小。系统 CPU sys 高（大量 `walwriter` 的 `open()`/`unlink()` 系统调用）。

**根因**：`max_wal_size` 设得过小，WAL 段积累速度远超设定值。每次 WAL 超过 `max_wal_size`，PG 触发一次 checkpoint，刷脏页后回收 WAL 段。如果 WAL 写入速率很高，这个循环在几秒内完成，然后又触发下一次 checkpoint。每次 checkpoint 带来的 FPW 写入进一步增加了 WAL 量，形成恶性循环。

```bash
# 观察 WAL 段文件大小和创建速率
ls -lh $PGDATA/pg_wal/ | head -20

# 观察 WAL segment 切换频率（PG 日志或 pg_stat_wal）
SELECT * FROM pg_stat_wal;
-- wal_segment_size 默认 16MB，所以：
-- wal_bytes / 16MB = segment 切换次数
-- 如果 wal_bytes 增长 1GB 而 max_wal_size=1GB，每 1GB 触发一次 checkpoint

# 查看当前 WAL 段中最新 10 条 record
pg_waldump -p $PGDATA/pg_wal -n 10

# 从指定 LSN 开始查看
pg_waldump -p $PGDATA/pg_wal -s 0/01000028 -n 20

# 只看特定 RMGR（如 Heap）的 record
pg_waldump -p $PGDATA/pg_wal -r Heap -n 20

# 只看特定事务 ID
pg_waldump -p $PGDATA/pg_wal -x 12345

# 查看 record 的统计信息（按 RMGR 和 record 类型统计数量和大小）
pg_waldump -p $PGDATA/pg_wal --stats

# 输出格式：
# rmgr: Heap        len (rec/tot):     54/    54, tx:        585,
#     lsn: 0/01000028, prev 0/01000000, desc: INSERT off 2, blkref #0: ...
# rmgr 表示资源管理器，desc 是对操作的描述
```text

**排查场景 1：WAL 写入量异常大**

```bash
# 统计各 RMGR 的 WAL 输出量
pg_waldump -p $PGDATA/pg_wal -z 0/01000000 --stats=record 2>&1 | head -30

# 查找事务 12345 的开始和结束
pg_waldump -p $PGDATA/pg_wal -x 12345

# 统计此事务的 WAL 量
pg_waldump -p $PGDATA/pg_wal -x 12345 | awk 'BEGIN{sum=0} /len.*tot:/{match($0, /[0-9]+\/[0-9]+/); print $0; sum+=gensub(/.*\/([0-9]+),.*/, "\\1", "g", $0)} END{print "Total bytes:", sum}'
```text

**排查场景 3：确认 WAL 段是否可安全回收**

```bash
# 查看 replication slot 的 restart_lsn
SELECT slot_name, restart_lsn,
       pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn) / 1024 / 1024 AS lag_mb
FROM pg_replication_slots;

# restart_lsn 之前的 WAL 段不能回收。
# 如果某个 slot 的 lag_mb 很大且 active=false，说明 standby 已经离线
# WAL 一直攒着不被回收——最终可能导致 pg_wal 占满磁盘

-- 准备测试表
CREATE TABLE wal_test (id SERIAL PRIMARY KEY, data TEXT);
-- 先跑 4 轮预热
INSERT INTO wal_test (data) SELECT md5(random()::text) FROM generate_series(1, 100000);

-- 在每次测试前重启 PG 并切换 wal_level
-- 然后执行相同负载：
INSERT INTO wal_test (data) SELECT md5(random()::text) FROM generate_series(1, 100000);
DELETE FROM wal_test WHERE id % 10 = 0;
UPDATE wal_test SET data = md5(random()::text) WHERE id % 5 = 0;

-- 测量 WAL 写入量
SELECT pg_current_wal_lsn() AS end_lsn;
-- 实验前后 LSN 差值即 WAL 写入量
```text

对比 `minimal`、`replica`、`logical` 三种 wal_level 下的 WAL 写入量，观察 `logical` 级别下 UPDATE/DELETE 带来的额外 WAL。

### 9.2 观察 checkpoint 对 WAL 写入的影响

```sql
-- 观察 FPW 行为：checkpoint 后第一次 UPDATE 产生 FPW
CHECKPOINT;  -- 强制一次 checkpoint

-- 记录当前 WAL LSN
SELECT pg_current_wal_lsn();

-- 执行一次 UPDATE
UPDATE wal_test SET data = 'x' WHERE id = 1;

-- 记录 WAL LSN 差异
SELECT pg_current_wal_lsn();
-- 这个 UPDATE 对应的 WAL record 包含整页镜像（FPW），WAL 量应该约 8KB

-- 再次 UPDATE 同一行（同一页面）
UPDATE wal_test SET data = 'y' WHERE id = 1;

-- 这次不需要 FPW，WAL 量只有几十字节

-- 把 max_wal_size 设得极小（需要重启）
ALTER SYSTEM SET max_wal_size = '64MB';
SELECT pg_reload_conf();

-- 疯狂写入
INSERT INTO wal_test (data) SELECT md5(random()::text) FROM generate_series(1, 500000);

-- 观察 checkpoint 频率
SELECT checkpoints_timed, checkpoints_req FROM pg_stat_bgwriter;
-- checkpoints_req 应该涨了好几倍
```text

完成后记得恢复 `max_wal_size`。

### 9.4 用 pg_waldump 解读 WAL

```bash
# 找到当前使用的 WAL segment
SELECT pg_walfile_name(pg_current_wal_lsn());

# 解码此 WAL segment 中的 record
pg_waldump -p $PGDATA/pg_wal -s 0/01000000 -n 30

# 观察输出中的 rmgr 字段：
# rmgr: Heap        — heap 表的操作
# rmgr: Btree       — B-Tree 索引的操作
# rmgr: Transaction — 事务提交/回滚
# rmgr: XLOG        — checkpoint、WAL 切换等
# rmgr: Storage     — 文件创建/截断