postgres-howto 中文站焕新：PostgreSQL 排障专题索引与推荐路径发布

各位 PGer 大家好，今天想和大家介绍一个我最近重新整理和优化的小项目：postgres-howto in chinese，距离上一次正式发布快两年有余（参见说件正事：postgres-howto 系列）。

当你在生产环境里真的遇到 PostgreSQL 问题时，应该从哪里下手？

比如：

• 查询为什么慢？
• 索引该怎么建？
• 锁应该怎么查？
• WAL 为什么突然暴涨？
• 复制延迟怎么定位？
• work_mem 到底怎么调？
• pg_stat_statements 该怎么看？
• ...

这些问题，官方文档当然都有相关章节，但如果真在凌晨处理故障，很多时候我们需要的不是完整手册，而是一篇能快速帮你进入现场、建立判断力、找到排查方向的文章。这也是 postgres-howto 这个项目存在的意义。

项目背景

postgres-howto 原项目来自 postgres.ai 团队，原始项目地址：https://gitlab.com/postgres-ai/postgresql-consulting/postgres-howtos

原作者有一句话我很喜欢，大意是：

PostgreSQL 官方文档非常好，但有时候缺少一些面向真实场景的实践建议。

这句话其实很准确。PostgreSQL 文档质量很高，但文档更偏“解释机制”和“定义行为”；而我们日常处理问题时，往往更需要知道：

• 这个现象意味着什么？
• 我应该先查哪个视图？
• 这个指标高了是否一定有问题？
• 这个优化动作会不会带来副作用？
• 线上能不能做？
• 做到什么程度算合理？

所以我做了 postgres-howto in chinese 这个项目，希望把这些文章翻译、整理出来，同时也补充一些我自己的理解和延伸，让中文读者能够更方便地阅读和查阅。

适合谁？

这个项目主要适合几类人。

第一类是 DBA / DBRE。
如果你平时需要处理 PostgreSQL 的锁、复制、WAL、膨胀、统计信息、参数配置、备份恢复等问题，这个项目里有很多文章可以直接作为排障入口。

第二类是后端工程师。
很多后端同学并不是专职 DBA，但经常会写 SQL、建索引、做 schema 变更、分析慢查询。这个项目可以帮助你理解 SQL 背后的执行计划、索引代价、事务行为和线上变更风险。

第三类是正在学习 PostgreSQL 的同学。
我一直觉得，学习数据库不能只停留在语法层面。真正有价值的学习，往往来自真实问题。你遇到一个慢 SQL，去看执行计划；你遇到一个锁等待，去理解事务和锁；你遇到 WAL 暴涨，去理解写入路径和检查点。这就是所谓的“干中学”。

最近做了哪些更新？

借助 AI，对整个中文站做了一轮比较系统的整理和优化。

1. 首页重新设计

之前首页更像一个普通 README 页面，信息是有的，但入口不够明显。这次重新梳理后，首页更强调三个入口：

• 按专题阅读
• 推荐路径
• 从第 1 篇开始

如果你是带着具体问题来的，可以直接进入专题索引；如果你不知道从哪篇开始，可以看推荐路径；如果你想完整阅读，也可以从第 1 篇开始。

2. 增加专题索引

文章数量多了以后，最大的问题不是“有没有内容”，而是“怎么找到内容”。所以这次新增了专题索引，把文章按场景重新组织，比如：

• 查询性能与观测
• 索引治理
• 锁、事务与在线变更
• 存储、WAL 与 Vacuum
• 复制、校验与升级
• 运维排障与日常工具
• SQL、数据建模与扩展玩法

这样遇到问题时，不需要从 90 多篇文章里一篇篇翻，可以直接按场景定位。

3. 增加推荐路径

专题索引适合“查问题”，推荐路径更适合“系统读”。比如性能优化路径，会从 EXPLAIN、pg_stat_statements、慢 SQL 判断、基准测试开始，再进入索引和参数调优。DBA 排障路径，则会围绕重启、WAL 增长、复制延迟、锁等待这些生产环境常见问题展开。我希望它不只是文章列表，而是能帮助读者建立一条学习路线。

4. 侧边栏重新分层

原来的侧边栏内容比较多，阅读时容易有压迫感。这次按照专题重新分组，让分类标题更明显，文章列表也更容易扫读。对于这种技术文档站来说，侧边栏其实很关键，因为它决定了读者能不能快速建立全局地图。

5. 页面视觉做了一轮优化

这次也顺手把整体视觉重新整理了一遍。整体风格还是保持克制，不做花里胡哨的东西——毕竟这是一个技术文档站，不是营销页。PostgreSQL 的蓝色也继续保留，因为这个颜色本身就很适合技术文档，既有识别度，也不会太跳。另外，暗色模式也重新调整了一轮。之前有读者反馈，深色背景下蓝色文字对比度不够，这次也做了修复，尽量保证夜间阅读时不折磨眼睛。

为什么还要做这个项目？

其实做开源翻译和资料整理，有时候是一件挺“笨”的事情。

• 它不像写一篇爆款文章或流量水文，短期反馈很明显。
• 它也不像做一个工具，功能一上线就能立刻看到效果。
• 很多时候，它只是默默放在那里，某天某个同学搜到一篇文章，刚好解决了一个线上问题。

但我觉得这件事情仍然值得做。PostgreSQL 这些年在国内发展很快，越来越多公司开始真正把它用在核心系统里。postgres-howto 中文版就是我做的一点小沉淀。

后续计划

后面这个项目还会继续更新，主要有几个方向：

1. 继续补齐翻译内容。
2. 修正一些不符合中文阅读习惯的表达。
3. 补充我自己的实践理解。
4. 持续优化站点阅读体验。
5. 把文章之间的关联做得更清楚。

如果你在阅读过程中发现翻译错误、链接失效、内容过期，或者有更好的实践经验，也欢迎通过 GitHub 或邮件联系我。技术资料不是一次性写完的，它更像一个持续维护的知识库，需要慢慢打磨。

最后

如果你平时使用 PostgreSQL，尤其是经常处理生产问题，我建议可以把这个站点收藏一下：https://postgres-howto.cn/

它不一定能回答所有问题，但在很多具体场景下，应该能帮你更快找到方向。也欢迎给项目点个 Star：https://github.com/xiongcccc/postgres-howto

希望这个项目能成为大家日常学习 PostgreSQL、排查 PostgreSQL 问题时，一个顺手、实用、靠谱的小工具。也欢迎大家来云栈社区一起交流。

日拱一卒，功不唐捐。在这个浮躁的时代，我们继续折腾 PostgreSQL。