PGSimCity：把 PostgreSQL 集群变成一座能走进去的 3D 城市
该项目围绕「An explorable 3D city that shows how Postgres actually works. PGSimCity An explorable 3D city that shows how PostgreSQL actually works.** PGSimCity turns a PostgreSQL cluster into a city you can inspect, walk through, and break.」构建，适用于实际场景的开源实践，提供可复用的工具链与集成方式。
秒懂
- 它是什么？
- PGSimCity 是一个开源的教学可视化项目，把 PostgreSQL 集群的内部机制映射成一座可探索的 3D 城市。它面向没有运维经验的工程师，用直观的动画解释 checkpoint、WAL、vacuum 等概念，但项目仍处于 0.x 阶段，模型简化之处需要留意。
- 适合谁用？
- PGSimCity 适合那些已经会用 PostgreSQL 但从未真正操作过数据库的工程师，比如后端开发、数据分析师或刚接触数据库管理的运维新人。它不适合用来学习 PostgreSQL 的精确数值行为，因为动画中的比例是经过缩放的，而且部分模型（如 buffer ring）仍是历史简化版本。
- 能商用吗？
- 可以。Apache-2.0 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 3 天前。
- 用什么语言写的？
- 主要是 TypeScript（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月14日）和我们的分析，不构成法律意见。
开源项目深度解析
一座为不懂运维的工程师建的城市
PGSimCity 解决的问题很具体：很多工程师每天都在写 SQL，却从未真正理解数据库在底层做了什么。为什么一次 checkpoint 会让延迟突然飙升？为什么一个忘记提交的事务会让表无限膨胀？synchronous_commit 到底在收取什么代价？这些问题在文档里是一堆术语，在 PGSimCity 里变成了一座可以走进去的城市。项目面向的是「擅长本职工作但从未操作过数据库的工程师」，它用 3D 场景把 PostgreSQL 集群的各个组件映射成不同的街区，让用户像逛城市一样观察数据流。这个定位很聪明，因为数据库内部机制往往抽象且难以观察，而可视化能降低理解门槛。不过要注意，这座城是模型，不是模拟器，它不运行 PostgreSQL 源码，数字也是经过缩放以便人眼观察。
从客户端到磁盘：城市布局就是架构图
PGSimCity 的城市布局直接对应 PostgreSQL 的架构。北边是客户端天空，代表来自应用层的连接；Postmaster 是监督者，它只负责派生后端进程，从不触碰数据。后端行有 16 个进程，它们的灯光颜色就是状态，包括 idle in transaction 这种容易被忽略的状态。buffer pool 区域展示 shared_buffers 的代表帧，旁边是 wal_buffers、ProcArray、锁表和 CLOG。往下的挖掘坑是数据目录，标记了内存和存储的分界。存储区把堆文件画成 8 KiB 页面的田地，B-tree 画成真正的树，还有 TOAST、FSM 和可见性映射。东边是 WAL 区，西边是维护场，南边是备库。颜色语义全局统一：WAL 是琥珀色，脏页是红色，干净页是蓝色，vacuum 是紫色，checkpoint 是粉色。这种布局让用户一眼就能看出数据从客户端到磁盘的完整路径，比阅读架构图直观得多。
交互式教学：按 T 键开始 14 章导览，按 Enter 追踪一条语句
项目内置了多种交互方式。按 T 键启动 14 章导览，它会跟随一个连接从客户端开始，经过规划、缓存、WAL、checkpoint、vacuum 和复制。按 Enter 键可以追踪一条语句，比如选择 Non-HOT UPDATE，慢速播放会展示它如何进入 buffer pool、产生 WAL 并等待提交。场景菜单里还有几个精心设计的实验：Cache thrash 把 shared_buffers 设为 16 MiB，低于手动控制的最小值 128 MiB，让时钟扫描竞争加剧，后端进程在读取新页面前不得不先写自己的脏页。The work_mem cliff 场景固定 Sort 和 HashAggregate 节点，在 2 MiB 时溢出，4 MiB 时刚好放下，展示私有内存池和临时文件的影响。Long-running transaction 场景让 xmin 地平线下降并变红，autovacuum 仍然出发，但报告零可删除行，表持续膨胀。这些场景把抽象的参数变化变成可观察的因果链，比单纯读文档更有说服力。
运行方式：无需安装，浏览器即开即用
PGSimCity 的主页提供 live city，无需安装，直接打开浏览器就能探索。如果你想在本地跑，仓库是 TypeScript 项目，采用 Apache-2.0 许可证，默认分支是 main。要构建和运行，你需要克隆仓库，安装依赖（比如 npm install），然后启动开发服务器。具体命令在 README 中没有详细列出，但作为标准 TypeScript 项目，通常会有 npm run dev 或类似脚本。项目还包含一个可选的 Query flow 和 Machine 组件，它们可以运行 PGlite，这是一个编译为 WebAssembly 的真实内存版 PostgreSQL。这意味着虽然城市本身是模型，但你可以选择接入真实的 PostgreSQL 执行引擎来验证某些行为。对于只想快速体验的用户，直接访问 live city 是最快路径。
信任边界：模型不是模拟器，数字不能当版本证据
README 明确警告：PGSimCity 是 PostgreSQL 的模型，不是模拟器，城市里没有运行任何 PostgreSQL 源码，数字经过缩放以便人眼观察。项目针对 PostgreSQL 18 主线，18.4 是审查参考版本，机制声明遵循 REL_18_STABLE 源码。但存在已知的简化：比如 TypeScript buffer 采样仍使用固定的 32 帧环形缓冲区，这不是 PostgreSQL 18 的环形大小规则。README 明确说，动画不能用作数值版本证据，直到模型对齐。还有一个已知的失败模式：确定性测试套件在 CI 上有一个红测试，因为它固定了缩放的 WAL 触发器近似值，而 PostgreSQL 18 实际使用整段取整。cache hit ratio 的计算和 clock-sweep 的 usage_count 上限也有类似问题。这说明项目作者对准确性很认真，但你也应该清楚，任何动画展示的数值都可能与真实数据库有偏差。
替代方案：从文档到真实集群的连续谱
如果你不需要 3D 可视化，官方 PostgreSQL 文档始终是最权威的参考。项目本身也承认这一点，它引用了 postgresql.org/docs 和源码来验证机制。另一个替代方案是使用真实的 PostgreSQL 实例配合 pg_stat_statements、pg_stat_bgwriter 等视图观察实时指标，但这需要你具备一定的操作能力，而这正是 PGSimCity 想帮你建立的。还有像 pganalyze 或 pgHero 这样的监控工具，它们提供图表而不是 3D 城市，但数据来自真实集群，没有缩放。PGSimCity 的独特之处在于它把机制变成可探索的空间，而不是图表。对于理解概念，它比文档生动；对于验证精确行为，它不如真实集群。选择哪个取决于你的目标是「理解」还是「测量」。
维护与升级成本：0.x 阶段，变化快，需要关注
项目目前是 0.x 版本，最近发布频繁，比如 v0.40.0 到 v0.39.5 间隔不到一天。这反映了项目仍处于快速迭代期，新功能不断加入，比如 v0.40.0 的标题是「十九个缺陷，和一个月球」，说明连月球都画出来了。维护成本主要在两方面：一是你需要跟上版本更新，因为模型可能随着 PostgreSQL 新版本而变化；二是如果你依赖它做教学材料，需要定期检查 README 中的已知偏差列表。许可证是 Apache-2.0，这意味着你可以自由使用、修改和分发，但要注意项目与 SimCity 的商标无关，它明确声明不包含任何 SimCity 代码或资产，以免引起法律纠纷。对于个人学习或内部培训，Apache-2.0 没有额外限制。
编辑结论
PGSimCity 适合那些已经会用 PostgreSQL 但从未真正操作过数据库的工程师，比如后端开发、数据分析师或刚接触数据库管理的运维新人。它不适合用来学习 PostgreSQL 的精确数值行为，因为动画中的比例是经过缩放的，而且部分模型（如 buffer ring）仍是历史简化版本。如果你打算用它做教学或演示，先确认你讲解的版本对应的 PostgreSQL 版本（当前针对 18 主线），并查阅 README 中披露的已知偏差，比如 WAL 触发器的取整问题和 cache hit ratio 的计算方式。如果你是资深 DBA，想用它来验证某个具体参数的影响，建议直接阅读 PostgreSQL 官方文档或源码，而不是依赖动画。在采用之前，先打开 live city 试玩一下，确认 3D 交互在你的设备上流畅，尤其是触控操作目前只在 Chrome 的移动模拟中验证过。
社区笔记