前言
各位 PGer 大家好，今天想和大家介绍一个我最近重新整理和优化的小项目：postgres-howto in chinese 🔗 https://postgres-howto.cn，距离上一次正式发布快两年有余 说件正事：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 中文版就是我做的一点小沉淀。
后续计划
后面这个项目还会继续更新，主要有几个方向。
第一，继续补齐翻译内容。 第二，修正一些不符合中文阅读习惯的表达。 第三，补充我自己的实践理解。 第四，持续优化站点阅读体验。 第五，把文章之间的关联做得更清楚。
如果你在阅读过程中发现翻译错误、链接失效、内容过期，或者有更好的实践经验，也欢迎通过 GitHub、邮件或公众号联系我。
技术资料不是一次性写完的，它更像一个持续维护的知识库，需要慢慢打磨。
最后
如果你平时使用 PostgreSQL，尤其是经常处理生产问题，我建议可以把这个站点收藏一下：
https://postgres-howto.cn/
它不一定能回答所有问题，但在很多具体场景下，应该能帮你更快找到方向。
也欢迎给项目点个 Star：
https://github.com/xiongcccc/postgres-howto
希望这个项目能成为大家日常学习 PostgreSQL、排查 PostgreSQL 问题时，一个顺手、实用、靠谱的小工具。
日拱一卒，功不唐捐。在这个浮躁的时代，我们继续折腾 PostgreSQL
