PGSimCity 是一个基于 TypeScript、three.js 和 Vite 构建的 PostgreSQL 内部机制 3D 可视化教育项目。它把 PostgreSQL 集群抽象成一座可探索的城市，用建筑、颜色、动画和交互场景展示连接、backend、shared_buffers、WAL、checkpoint、autovacuum、存储、复制、PITR 等核心机制。项目不是 PostgreSQL 模拟器或数据库内核实现，而是一个经过测试和审阅的教学模型，适合用于理解 PostgreSQL 运行原理、性能现象和运维风险。
适用领域
PostgreSQL / 数据库内核原理 / 数据库运维教育 / 3D 可视化 / WebGL / three.js / TypeScript / 前端工程 / 交互式教学 / 数据库性能调优
配置难度
中等。普通用户可直接访问在线版本学习；本地运行只需要 Node.js 20、npm 和支持 WebGL2 的浏览器。若要深入理解或二次开发，需要同时具备 PostgreSQL 内部机制、TypeScript、three.js、WebGL 交互和前端工程经验。
商业价值
该项目的商业价值主要体现在技术培训、开发者教育和数据库运维能力建设上。对于使用 PostgreSQL 的团队，它可以帮助后端工程师更直观地理解 checkpoint、WAL、vacuum、缓存命中率、复制延迟等问题，从而提升故障排查和性能优化效率。对于培训机构、咨询团队或数据库厂商，它可作为演示 PostgreSQL 原理的高质量互动素材。项目本身声明为非商业教育可视化，但 Apache-2.0 许可证使其具备较好的内部改造和集成潜力。
01
技术亮点
- 用城市隐喻把 PostgreSQL 内部机制可视化，学习门槛比纯文档或源码阅读低
- 覆盖 shared_buffers、WAL、checkpoint、background writer、autovacuum、replication、standby、PITR、query planning 等多个关键主题
- 提供 14 章 guided tour，适合系统化学习
- 支持交互式场景，例如 Cache thrash、Long-running transaction、Checkpoint storm、Slow replay 等
- 颜色语义明确：WAL、dirty pages、clean pages、vacuum、checkpoint、replication 等都有固定视觉编码
- 架构分层清晰：core、sim、world、engine、ui、observability 分离
- 仿真层不依赖 three.js，渲染层不直接修改仿真状态，通过 SimState 解耦
- README 明确说明准确性边界：它是教学模型，不是 PostgreSQL 仿真器或真实数据库
- 项目有 234 个测试，并在 CI 中保障关键行为不被破坏
- Apache-2.0 许可证，对学习、二次开发和企业内部使用较友好
- 已有在线演示地址，可无需安装直接体验
02
目标用户
- 想理解 PostgreSQL 内部机制的后端工程师
- 缺少数据库运维经验但需要排查数据库问题的开发者
- PostgreSQL DBA 和数据库内核学习者
- 技术培训讲师和课程设计者
- 希望通过可视化方式学习 checkpoint、WAL、vacuum、buffer cache、replication 的工程团队
- 对 three.js/WebGL 复杂可视化项目感兴趣的前端开发者
03
配置要求
- Node.js >= 20
- 支持 WebGL2 的现代浏览器，推荐 Chrome、Edge 或 Firefox
- 项目没有应用服务器依赖，构建结果是静态 bundle
- 主要运行时依赖是 three.js，构建工具为 Vite
- 可选功能 Query flow 可能在用户显式点击后加载同源的 PGlite JavaScript、数据和 WebAssembly 资源
- 默认会向 Plausible 发送匿名、无 Cookie 的聚合分析数据；阻止 plausible.io 不影响核心应用运行
- 移动端触控支持仍有限，README 中说明主要只在 Chrome 移动模拟器中验证过
04
适用场景
- 通过 3D 城市模型学习 PostgreSQL 的整体架构和数据流
- 演示一次 SQL 查询从连接、解析、计划、执行到 WAL、buffer、commit 的路径
- 解释 checkpoint storm、cache thrash、long-running transaction、autovacuum 无法清理等典型生产问题
- 用于团队内部 PostgreSQL 培训、数据库性能问题复盘和技术分享
- 作为 three.js + TypeScript 构建大型交互式可视化应用的参考项目
- 在浏览器中无需后端服务运行静态教育应用
- 通过 guided tour 快速浏览 PostgreSQL 的 14 个核心概念章节
05
部署与配置
- 安装 Node.js 20 或更新版本
- 确认浏览器支持 WebGL2
- 克隆仓库：git clone https://github.com/NikolayS/PGSimCity.git
- 进入项目目录：cd PGSimCity
- 安装依赖：npm install
- 启动开发服务器：npm run dev
- 在浏览器访问：http://localhost:5173
- 运行测试：npm test
- 执行类型检查：npm run typecheck
- 构建静态产物：npm run build
- 本地预览构建结果：npm run preview，然后访问 http://localhost:4173
06
风险与注意事项
- 项目仍处于 0.x 阶段，模型和实现可能变化较快
- 它不是 PostgreSQL 源码级模拟器，数值经过缩放，不能用于精确性能预测或生产容量评估
- 部分 PostgreSQL 内部细节做了教学简化，使用时需要结合官方文档和真实监控数据
- 移动端触控验证不充分，移动设备体验可能不稳定
- 依赖 WebGL2，老旧浏览器、低性能显卡或受限企业环境可能无法流畅运行
- 如果用于中文教学，需要自行补充中文讲义或翻译界面说明
- PGlite 相关功能为可选加载，受浏览器、WASM、资源策略影响
- Plausible 分析虽然无 Cookie，但在隐私敏感或内网环境中仍可能需要关闭或屏蔽
2026-08-01
第15名
新收录 · github_search
2026-07-31
第13名
新收录 · github_search
2026-07-30
第18名
新收录 · github_search
2026-07-29
第24名
新收录 · github_search
