搭建过 PostgreSQL 流复制或做过时间点恢复（PITR）的运维人员，几乎都遇到过归档目录越来越大、磁盘被 WAL 文件塞满的情况。PostgreSQL 提供了一个专门的参数 archive_cleanup_command，可以在恢复过程中自动清理已经不再需要的归档日志。这个参数用好了能省不少运维精力，用错了却可能把主库的归档直接删光。下面从工作原理、配置方法、常见坑和最佳实践几个方面详细聊一聊。
archive_cleanup_command 的工作原理
archive_cleanup_command 是 PostgreSQL 恢复相关的一个参数，与 restore_command 相对应。它的定位很明确：在归档恢复（standby 模式或 PITR 恢复）过程中，每当数据库成功回放了一个 WAL 归档文件，PostgreSQL 就会执行一次这个参数指定的 shell 命令，让你有机会删除那些已经回放完毕、不再需要的归档文件。
注意几个关键细节。第一，这个命令只在恢复模式下生效，也就是数据库处于 standby 或者正在进行恢复时，正常运行的主库上配置它是没有意义的，甚至可能带来风险。第二，PostgreSQL 会把最近一个被成功回放的归档文件名作为参数追加到命令后面，比如你配置了 archive_cleanup_command = '/usr/local/bin/pg_archivecleanup %r'，实际执行时命令会变成 pg_archivecleanup 000000010000000000000042 这样的形式，工具拿到这个文件名后，删除所有比它更旧的归档。第三，命令的退出状态很重要，返回非零值时 PostgreSQL 会在日志中记录一条 WARNING，但不会中断恢复进程。
还有一点容易被忽略：%r 是唯一被替换的占位符，它代表最近可用的重启点对应的 WAL 文件名。使用这个占位符是安全清理的前提，因为重启点之前的归档即使被删除，恢复依然可以继续。
如何配置 pg_archivecleanup 工具
pg_archivecleanup 是 PostgreSQL 自带的清理工具，专门配合 archive_cleanup_command 使用。它的基本语法是 pg_archivecleanup [选项] 归档目录 最近需要的文件名。典型配置写在 postgresql.conf 或 recovery 配置中：
# postgresql.conf 中的配置 archive_cleanup_command = 'pg_archivecleanup /data/pg_archive %r' # 假设归档文件带 .arch 后缀，需要额外指定扩展名 archive_cleanup_command = 'pg_archivecleanup /data/pg_archive %.arch %r'
上面的例子中，/data/pg_archive 是归档文件所在目录，%r 会被替换成最近回放完成的 WAL 文件名（不带后缀）。pg_archivecleanup 会扫描目录，删除所有序号小于该文件名的归档文件，这一规则基于 WAL 文件名的字典序比较，因此文件命名不规范时工具可能无法正确工作。
这个工具还提供了一个 -d 参数用于输出调试信息，排查清理问题时非常有用。可以手动执行一次观察输出：
# 手动测试清理逻辑，-d 打印详细信息，实际不删除文件时先观察输出 pg_archivecleanup -d /data/pg_archive 000000010000000000000042 # 确认无误后去掉 -d 正式执行（会真实删除文件） pg_archivecleanup /data/pg_archive 000000010000000000000042
需要提醒的是，手动测试时一定要确认目标文件名的正确性，否则直接删掉了主库恢复还需要的归档，后果可能需要重新做基础备份。建议先在测试环境完整演练一遍。
生产环境中的常见坑与最佳实践
第一个大坑是在主库上配置了这个参数。有些同学为了省事，把同一份配置文件分发到主库和备库，结果主库某天重启进入恢复模式（比如从备份恢复），archive_cleanup_command 被触发，把生产归档删掉一大片。如果主库后面还挂着多个备库，其他备库可能因此无法追上进度。正确做法是使用 ALTER SYSTEM 在备库上单独设置，或者通过配置文件的管理工具区分主备角色的参数。
第二个坑是清理延迟导致归档目录仍然堆积。archive_cleanup_command 的触发依赖备库的回放进度，如果备库负载高、回放滞后严重，主库归档目录可能依然被快速填满。这种情况下更稳妥的方案是在归档命令中维护一个保留窗口，例如配合 archive_command 中的脚本，保留最近 N 小时的归档，或者使用独立的定时任务定期清理，但定时任务必须知道备库的最小回放位置，否则同样有误删风险。
# 备库查询当前回放位置，可作为外部清理脚本的依据 psql -c "SELECT pg_last_wal_replay_lsn();" # 结合 pg_controdata 查看最近检查点对应的 WAL 文件 pg_controdata /var/lib/postgresql/16/main | grep -i checkpoint
第三个坑是级联复制场景。如果备库下面还挂着级联备库，父备库上无脑清理归档会导致下游备库无法获取历史 WAL。此时应改用 replication slot 机制来管理 WAL 保留，或者在清理脚本中检查下游备库的进度。总的来说，如果只是单一备库加 PITR 需求，archive_cleanup_command 配合 pg_archivecleanup 是最简单可靠的方案；架构一旦复杂，就要慎重考虑保留策略，宁可多留几个小时的归档，也不要因为省那点磁盘把恢复链路删断。
最后总结一下使用要点：只在备库或恢复实例上启用；务必使用 %r 占位符而不是写死文件名；配置前手动测试 pg_archivecleanup 的行为；监控归档目录大小和备库回放延迟，把清理参数纳入日常巡检。做到这几点，归档空间管理基本就不会出问题。
PostgreSQLarchive_cleanup_command归档日志清理修改时间：2026-09-13 12:56:39