暂无图片
暂无图片
4
暂无图片
暂无图片
暂无图片

PostgreSQL 三类存储完整性故障:TOAST 缺块、B-tree 零页与业务字段恢复

原创 瓶盖吃芥末 2026-11-08
190

PostgreSQL 三类存储完整性故障:TOAST 缺块、B-tree 零页与业务字段恢复

文中的主机、库名、Schema、表名、索引名、OID、主键、时间、数据量、连接参数和文件路径均已泛化。
SQL 中的示例对象必须替换成实际对象;
不能直接在生产库执行。

最近遇到的三次 PostgreSQL 存储完整性故障的处理记录:

  1. pg_statistic 的 TOAST 值缺块,业务 SQL 在规划阶段失败;
  2. 分区叶子表的唯一 B-tree 索引出现零页,新增数据失败;
  3. 业务表大字段的 TOAST chunk 丢失,查询和 pg_dump 都无法完整读取。

处理这类问题时,最重要的不是马上跑 REINDEX 或 VACUUM FULL,而是先回答两个问题:

  • 损坏的到底是统计信息、索引,还是业务数据?
  • 损坏内容能否从其他数据重建?
    这两个答案决定了后面的修复方式。

案例一:pg_statistic TOAST 缺块

故障现象

某条业务 UPDATE 还没进入正常执行,就在规划/绑定阶段报错:

ERROR: missing chunk number 0 for toast value ... in pg_toast_<oid>

第一反应往往是“业务表里某个大字段坏了”。但把报错中的 TOAST 表映射回 owner 后,发现它属于 pg_catalog.pg_statistic。

SELECT c.oid, c.oid::regclass AS owner_relation, c.reltoastrelid::regclass AS toast_relation FROM pg_catalog.pg_class AS c WHERE c.reltoastrelid = 'pg_toast.pg_toast_<oid>'::regclass;

这一步很关键。pg_statistic 保存优化器使用的列统计信息,其中的 MCV、直方图边界等数组也可能进入 TOAST。业务 SQL 在生成计划时要读这些统计值,所以即使 SQL 没有选取任何大字段,也会被损坏的统计信息拦住。

怎样缩小范围

分区表的统计信息通常分布在父表和多个叶子分区上。直接对整张表做大范围维护,既扩大锁和 I/O,也会破坏现场。

排查时先确定哪个叶子分区拥有统计记录,再对 staattnum 做范围切分。因为一条 SELECT 遇到第一个坏值就会中止,可以通过二分法把坏统计列缩小到很小的范围。

测试时要显式解码统计槽,只查目录行数不够:

SELECT staattnum, stakind1, stakind2, stavalues1::text, stavalues2::text, stanumbers1::text, stanumbers2::text FROM pg_catalog.pg_statistic WHERE starelid = 'schema_name.partition_name'::regclass AND staattnum BETWEEN 1 AND 16;

如果该范围报 missing chunk,就继续缩小;正常返回则检查另一半。

为什么普通 ANALYZE 没有直接修好

对准确的叶子分区执行 ANALYZE,采样阶段完成了,但替换旧统计记录时又读到了损坏的 TOAST 值,命令整体回滚。

所以不能只看 ANALYZE VERBOSE 前面的采样输出。必须确认命令最终成功,并检查 pg_stat_all_tables.last_analyze 和损坏统计槽的解码结果。

最终修复

pg_statistic 是可再生数据。精确定位目标叶子分区后,可在受控事务内删除该对象的旧统计记录,紧接着重新 ANALYZE:

BEGIN; DELETE FROM pg_catalog.pg_statistic WHERE starelid = 'schema_name.partition_name'::regclass; ANALYZE VERBOSE schema_name.partition_name; COMMIT;

这是针对“已精确定位的 pg_statistic 损坏”的例外处置,需要超级用户权限和完整审批。它不是 missing chunk 的通用修复模板,更不能照搬到业务表上。

修复后至少要检查:

  • ANALYZE 最终成功;
  • last_analyze 更新;
  • 所有 stavaluesN/stanumbersN 都能转成文本;
  • 原业务 SQL 能正常生成计划;
  • 日志不再出现同类 value ID。

案例二:B-tree 索引出现零页

故障现象

一条 INSERT 在维护分区叶子表的唯一索引时失败:

ERROR: index "..." contains unexpected zero page at block ... HINT: Please REINDEX it.

B-tree 页应该有合法页头和索引内容。“unexpected zero page”表示访问到的块呈现为未初始化或异常全零状态,它不再符合 B-tree 结构要求。

pg_index.indisvalid=true 和 indisready=true 并不能反证物理页正常。这两个标志是目录状态,PostgreSQL 不会因为某个索引块损坏就自动把索引标记为 invalid。

先确认损坏范围

处理前要保存以下信息:

SELECT i.indexrelid::regclass AS index_name, i.indrelid::regclass AS table_name, i.indisunique, i.indisprimary, i.indisvalid, i.indisready, pg_get_indexdef(i.indexrelid) AS index_definition FROM pg_catalog.pg_index AS i WHERE i.indexrelid = 'schema_name.index_name'::regclass;

还要核对:

  • 该索引是普通索引、主键还是唯一约束的依托索引;
  • 是分区父索引还是真正存储数据的叶子索引;
  • 同表其他索引和同父索引下其他叶子是否报错;
  • 源堆表能否完整读取;
  • 唯一键是否存在重复值;
  • 当前锁等待、磁盘剩余空间和 I/O 能否支撑重建。

如果堆表本身也出现 invalid page、checksum failure 或读取错误,就不能把问题当成单纯索引损坏。

为什么 REINDEX 有效

索引是堆表的派生结构。REINDEX INDEX 不需要从旧的损坏索引中读键值,而是扫描堆表,重新生成一套 B-tree,再替换旧索引。

在确认源堆表可读、唯一键无重复、空间足够后,只重建报错的叶子索引:

REINDEX INDEX schema_name.leaf_index_name;

普通 REINDEX 锁影响明确,但路径简单,在已经损坏的索引上通常比盲目追求并发重建更稳妥。是否能使用 REINDEX CONCURRENTLY 还取决于 PostgreSQL 版本、索引状态和兼容内核的实现,不应在故障现场临时试验。

重建后检查:

  • 索引的 relfilenode 已变化;
  • 索引仍挂接在正确的分区父索引下;
  • 唯一/主键约束仍有效;
  • 原 INSERT 路径恢复;
  • 安装了 amcheck 时,对新索引执行 bt_index_check;
  • 日志中没有在其他索引上出现新的零页。
SELECT bt_index_check( 'schema_name.leaf_index_name'::regclass, true );

单个索引重建成功,只代表这个派生对象恢复了。如果同一实例在很短时间内又出现 TOAST 缺块或另一个索引零页,应该立即上升为实例级完整性事件,继续查存储、文件系统、宿主机、异常重启、HA 切换和内核缺陷。


案例三:业务表 TOAST chunk 丢失

从 pg_dump 报错开始

一次逻辑备份在 COPY 业务日志表时失败:

pg_dump: error: Dumping the contents of table "..." failed ERROR: missing chunk number 0 for toast value ... in pg_toast_<oid>

该表规模较大,包含请求参数、响应内容和错误信息等多个大字段。处理目标不是跳过整张表,而是找到引用缺失 TOAST value 的准确字段和业务行。

先判断是索引问题还是真缺块

每个外置 TOAST 值都会被拆成多个 chunk,TOAST 表上的唯一索引键为 (chunk_id, chunk_seq)。

如果只通过索引查不到 chunk_id,还不能说明数据真的没了,因为也可能是 TOAST 索引漏项。必须分别走索引和强制顺序扫描。

索引路径:

BEGIN READ ONLY; SET LOCAL enable_seqscan = off; SELECT ctid, chunk_id, chunk_seq FROM pg_toast.pg_toast_<oid> WHERE chunk_id = '<value_id>'::oid ORDER BY chunk_seq; ROLLBACK;

堆表路径:

BEGIN READ ONLY; SET LOCAL enable_indexscan = off; SET LOCAL enable_bitmapscan = off; EXPLAIN (COSTS OFF) SELECT ctid, chunk_id, chunk_seq FROM pg_toast.pg_toast_<oid> WHERE chunk_id = '<value_id>'::oid; SELECT ctid, chunk_id, chunk_seq FROM pg_toast.pg_toast_<oid> WHERE chunk_id = '<value_id>'::oid ORDER BY chunk_seq; ROLLBACK;

判断标准很直接:

索引扫描 顺序扫描 结论
0 行 有 chunk TOAST 索引可能漏项,评估 REINDEX
0 行 0 行 chunk 实际缺失,REINDEX 不能恢复数据
都有记录但序号不连续 都有记录但序号不连续 部分 chunk 丢失

本案两种扫描均为 0 行,因此没有对 TOAST 索引做无效的 REINDEX。

不读坏字段,如何找到坏行

大表上直接 SELECT * 既会很快命中坏值,也难以知道是哪一行。有效做法是把“定位”和“完整读取”分开。

先查结构,确定:

  • 哪些列可能进入 TOAST;
  • 主键是什么;
  • 有没有可用于切片的时间索引;
  • 坏列是否参与索引、触发器、检查约束和逻辑复制行标识。
SELECT a.attnum, a.attname, format_type(a.atttypid, a.atttypmod) AS data_type, a.attnotnull, a.attstorage FROM pg_catalog.pg_attribute AS a WHERE a.attrelid = 'schema_name.audit_log'::regclass AND a.attnum > 0 AND NOT a.attisdropped ORDER BY a.attnum;

再按候选大字段分开检查。大范围排查可以用首字符触发首块读取,不返回业务正文:

SELECT count(substring(request_payload::text FROM 1 FOR 1)) FROM schema_name.audit_log WHERE event_time >= timestamp 'YYYY-MM-DD 00:00:00' AND event_time < timestamp 'YYYY-MM-DD 00:00:00' AND request_payload IS NOT NULL;

时间范围按“月 → 周 → 日 → 小时 → 10 分钟”缩小。某个范围正常后就不再重复扫描,只继续细分报错范围。

到少量候选行后,每个主键用独立 SQL 完整读取字段:

SELECT record_id, md5(request_payload::text) AS payload_md5 FROM schema_name.audit_log WHERE record_id = '<candidate_id>';

substring(... FROM 1 FOR 1) 适合缩小范围,但只能保证读到所需的部分,不能代替完整值验证。最终要用 md5(column::text) 或同等方式强制读完整个值。

一个容易被忽略的陷阱:定位索引也可能不完整

本案在定位目标行时遇到过一个反常现象:

  • 主键查询能找到记录;
  • 主键加精确时间条件时,规划器选择时间索引,结果反而是 0 行。

这说明时间索引至少存在漏项迹象。如果继续把它当成“全量完整性扫描”的路径,坏行会被跳过,得到假阴性结果。

所以,修复事务最终只用主键锁定行,修复后的全表检查则显式禁用普通和位图索引扫描。出现过漏项迹象的索引还需要单独用 amcheck 或重建评估闭环。

修复前先保全其余字段

如果可靠备库、历史备份或 PITR 环境能够完整读取原值,应该优先恢复原值。只有确实没有可靠来源,而业务又接受字段丢失时,才考虑置空。

置空前把除坏字段以外的列导出到受控目录,设置严格文件权限并记录哈希:

\copy ( SELECT record_id, event_time, title, response_body, status, error_message FROM schema_name.audit_log WHERE record_id = '<bad_row_id>' ) TO '/secure/path/bad_row_without_payload.csv' WITH (FORMAT csv, HEADER true)

导出结果必须是 COPY 1。不要为了“多保一列”又把坏字段放回投影列表,否则导出本身也会失败。

为什么把坏字段设为 NULL 仍会报错

第一次修复很直接:

UPDATE schema_name.audit_log SET request_payload = NULL WHERE record_id = '<bad_row_id>';

结果仍然是同一个 missing chunk。

表上没有读取旧字段的业务触发器,坏字段也不在索引和检查约束中。继续排查发现,该表使用了:

REPLICA IDENTITY FULL

并且已经加入逻辑发布。

REPLICA IDENTITY FULL 使更新和删除需要记录旧行的全部列。即使新值是 NULL,PostgreSQL 为逻辑变更准备旧行信息时,仍会尝试解 TOAST 旧的 request_payload,因此在写入新值前就失败。

表上存在有效主键。临时切换到 REPLICA IDENTITY DEFAULT 后,变更只需要使用旧主键标识行,不再需要读取坏字段的完整旧值。

最小损失置空流程

这是生产 DDL/DML,需要业务确认字段原值无法恢复、可以丢失,并在维护窗口执行。ALTER TABLE ... REPLICA IDENTITY 需要强锁,不能在忙时不加评估地直接运行。

先切换行标识,再用主键锁定目标行。不使用已经出现漏项迹象的时间索引作为必须谓词:

\set ON_ERROR_STOP on BEGIN; SET LOCAL lock_timeout = '3s'; SET LOCAL statement_timeout = '30s'; SET LOCAL idle_in_transaction_session_timeout = '5min'; SET LOCAL synchronous_commit = on; ALTER TABLE schema_name.audit_log REPLICA IDENTITY DEFAULT; SELECT ctid, xmin::text AS xmin_before, record_id, event_time, request_payload IS NULL AS already_null FROM schema_name.audit_log WHERE record_id = '<bad_row_id>' FOR UPDATE; UPDATE schema_name.audit_log SET request_payload = NULL WHERE record_id = '<bad_row_id>' AND request_payload IS NOT NULL RETURNING ctid, xmin::text AS xmin_after, record_id, event_time, request_payload IS NULL AS payload_is_null; SELECT record_id, request_payload IS NULL AS payload_is_null, md5(request_payload::text) AS payload_md5, md5(response_body::text) AS response_md5 FROM schema_name.audit_log WHERE record_id = '<bad_row_id>';

只有以下条件同时满足才提交:

FOR UPDATE 只返回一行 record_id 和 event_time 符合预期 UPDATE 1 payload_is_null = true payload_md5 = NULL 其他大字段能正常读取
COMMIT;

任意一项不符就执行 ROLLBACK。ALTER TABLE 是事务性变更,回滚会同时撤销该事务中的 REPLICA IDENTITY DEFAULT。

修复提交后记录 WAL LSN,检查逻辑复制消费进度和订阅端结构。确认变更已正常消费后,恢复原配置:

BEGIN; SET LOCAL lock_timeout = '3s'; SET LOCAL statement_timeout = '30s'; ALTER TABLE schema_name.audit_log REPLICA IDENTITY FULL; COMMIT;

如果订阅端没有与发布端一致的主键,临时切换 DEFAULT 可能使逻辑应用失败。这个检查不能省略。

这种修复到底做了什么

置空操作不会找回原文。它只是创建了一个新的 MVCC 行版本:

  • 主键和其他业务列保留;
  • 坏字段变为 SQL NULL;
  • 新行不再保存指向缺失 TOAST value 的外置指针;
  • 新快照读取新行,不再访问丢失的 chunk;
  • 旧行版本等到不再被任何快照需要后,由常规 autovacuum 回收。

所以这是“最小数据损失隔离”,不是“原值恢复”。

修复后怎样确认没有其他坏行

精确行验证通过后,再强制扫描全表当前可见行。为了避免可疑索引跳过数据,显式关闭普通和位图索引扫描;用 MD5 强制读完整个大字段,但不把业务正文返回到客户端。

BEGIN READ ONLY; SET LOCAL enable_indexscan = off; SET LOCAL enable_bitmapscan = off; SET LOCAL enable_seqscan = on; SET LOCAL max_parallel_workers_per_gather = 0; SET LOCAL statement_timeout = '60min'; SET LOCAL lock_timeout = '2s'; EXPLAIN (COSTS OFF) SELECT count(md5(request_payload::text)) AS payload_count, count(md5(response_body::text)) AS response_count, count(md5(error_message::text)) AS error_count FROM schema_name.audit_log; SELECT count(md5(request_payload::text)) AS payload_count, count(md5(response_body::text)) AS response_count, count(md5(error_message::text)) AS error_count FROM schema_name.audit_log; ROLLBACK;

执行计划必须显示 Seq Scan。查询完成且没有新的 missing chunk,能说明该快照中当前可见行的这些字段都能完整读取。
它不能证明数据文件的每个物理字节都完好,也不会读不可见的死元组。最终还要重新执行单表 pg_dump,并在空的隔离环境中做恢复演练。


三个案例放在一起看

最容易犯的错误,是看到数据库完整性报错就套用同一个命令:

  • 用 REINDEX 修复真实丢失的 TOAST chunk,什么也找不回;
  • 把删除 pg_statistic 的方法用到业务表,会变成真正的业务数据丢失;
  • 对可从堆表重建的索引做字段置空,完全是不必要的损失。

修复手段必须由对象的可再生性决定。
前两起故障发生在同一实例的相近时间窗口,因此具有共同底层诱因的可能,应合并排查存储、文件系统、异常恢复、HA 操作和内核缺陷。
第三起发生在独立环境,虽然共享 TOAST 悬空引用这一表层机制,但没有证据支持它与前两起具有同一根因。

data_checksums=off 是不是根因

数据页校验和会在页读取时检查页内容是否与写入时的校验值一致。关闭它不会主动删除 TOAST chunk,也不会主动生成 B-tree 零页。
但它会影响发现和取证:

  • 底层静默改写可能无法在第一次读页时被明确标记为 checksum failure;
  • 日志中少了一类重要证据;
  • 事后更难区分逻辑不一致、介质错误和其他写入问题。

另一方面,即使开启 checksums,也不会检出所有逻辑损坏。一个校验正确的页仍可能包含错误的引用关系;B-tree 顺序、堆表与索引映射也需要 amcheck 等逻辑工具另行检查。
准确的结论是:


一套可复用的处理顺序

1. 先固定现场

修复前不要先跑 VACUUM FULL、CLUSTER、全库 REINDEX或者人工 DML TOAST 表。
保存:

  • 完整错误、SQLSTATE、发生时间和触发 SQL 结构;
  • 数据库和节点角色;
  • relation OID、TOAST value ID、block number;
  • PostgreSQL 启动时间;
  • 备库回放位点和延迟;
  • 故障前后的 PostgreSQL、内核、文件系统、存储和 HA 日志。

2. 把物理对象映射回逻辑 owner

目录映射做错,后面的修复命令就会整体走错方向。
先确认错误属于:

  • 系统目录;
  • 堆表;
  • TOAST 表;
  • 普通索引;
  • 分区父索引或叶子索引。

3. 判断是否可再生

先查物理备库、逻辑副本、历史备份和 PITR。副本上“其他查询正常”没有意义,必须精确读取同一对象、同一行、同一字段。

统计信息 -> 可从业务表重新采样 索引 -> 可从堆表重建 业务字段 -> 只能从副本/备份恢复,或接受损失

4. 对象恢复后继续查底层原因

建议继续核对:

  • 故障窗口是否有异常停机、崩溃恢复、主备切换或强制重启;
  • 内核日志是否有 I/O error、reset、timeout、文件系统转只读;
  • 云盘、SAN、RAID 或虚拟化层是否有介质告警;
  • PostgreSQL 或兼容内核是否有已知缺陷和补丁;
  • 基础备份、WAL 归档和 PITR 是否真正可用;
  • 重要索引能否在低峰用 amcheck 分批检查;
  • 大表的 TOAST 字段能否按时间或主键分段做逻辑读取校验。

对象修好了,只代表业务症状得到隔离,不代表介质、文件系统和整个实例已经证明安全。


参考资料

「喜欢这篇文章,您的关注和赞赏是给作者最好的鼓励」
关注作者
【版权声明】本文为墨天轮用户原创内容,转载时必须标注文章的来源(墨天轮),文章链接,文章作者等基本信息,否则作者和墨天轮有权追究责任。如果您发现墨天轮中有涉嫌抄袭或者侵权的内容,欢迎发送邮件至:contact@modb.pro进行举报,并提供相关证据,一经查实,墨天轮将立刻删除相关内容。

评论