冰山图宇宙项目指南

这是什么

冰山图（Iceberg Chart）这种形式你可能在 Reddit 或 B 站见过 —— 一个话题从水面之上的「大众常识」一层层往下挖，越深越冷门、越深越离谱。「冰山图宇宙」是把这种形式做成一个开放协作的知识平台，而不只是某个人画的一张图。

目前站内有三座冰山图：

• 🕳️ 中文兔子洞冰山图【重制版】 — 点进去就再也出不来的互联网深坑
• 🤪 奇异搞笑互联网冰山图（持续更新） — 早期论坛神帖、抽象文化名场面
• 📼 中文失传媒体冰山图（提案征集中） — 曾经存在但今天难以寻觅的中文内容

和 Reddit 帖子或零散博客不同 —— 这里的信息被组织成结构化、可协作、可沉淀的知识地图。每层条目有详细描述（支持 Markdown + KaTeX），可以投票、评论、协作编辑，积累品质分还能解锁 151 种成就徽章。

技术栈

一条 docker compose up -d 就起来了。

核心功能

冰山图编辑器

可视化拖拽编辑，支持 Markdown + KaTeX 公式，Ctrl+Z/Y 撤销重做，自动保存草稿，多人可同时协作编辑。这是整个平台最核心的组件，基本是从零手搓的。

社区机制

进阶功能

本地开发

环境要求

• Node.js 18+
• PostgreSQL 16+
• Docker（可选，推荐）

Docker 一键部署（推荐）

git clone https://github.com/Gnix807/icebergs-1.0.git
cd icebergs-1.0/frontend
cp .env.docker .env   # 编辑 .env 填必要配置
docker compose up -d

访问 http://localhost:4321。

手动开发

cd frontend
cp .env.example .env  # 填你的数据库连接等配置
npm install
npx prisma generate
npx prisma db push
npm run dev

数据库迁移和种子数据按 Prisma 文档 标准流程操作。

设计理念

这个项目从一开始就没打算做成「又一个笔记工具」或者「又一个 Wiki」。有几个核心设计决策贯穿始终：

为什么要用冰山图

冰山图天然适合呈现认知梯度。一篇长文可以讲一个话题，但读者很难直观感受到「我知道的只是皮毛」。冰山图把信息按层级排列 —— 水面之上是常识，往下每一层都在挑战读者的既有认知。这种形式本身就是一种叙事。

更重要的是，冰山图鼓励探索而非灌输。读者可以只看表层就走，也可以一路挖到底 —— 没有人强迫你读完。这种「按需深入」的节奏感，是传统文章做不到的。

为什么是社区驱动而不是单人创作

一个人的知识面再广也有限。Reddit 上那些经典冰山图之所以精彩，恰恰因为它们是多人贡献的 —— 论坛里你一句我一句，冰山就越堆越厚。把这种协作模式做成一个专门平台，让贡献变得结构化（而不是散在评论区里），是这个项目最核心的价值。

为什么选 Astro 而不是纯 React / Next.js

这个选择可能让一些前端朋友感到意外。说实话，一开始确实是用纯 React 写的原型，但很快发现两个问题：

1. 首屏加载：冰山图页面有大量内容（层级 + 条目 + 描述），纯 CSR 下首屏白屏时间太长。Astro 默认 SSR，首屏直出 HTML，体验好很多。
2. 内容为主：冰山图本质上是一个「内容网站」，不是「应用」。Astro 的「岛屿架构」很适合这种场景 —— 大部分页面是静态内容，只有在需要交互的地方（编辑器、搜索、投票）才激活 React。

冰山编辑器是怎么做的

编辑器是整个项目最难的部分，也是我花时间最多的组件。说几个关键设计：

数据模型

每条冰山条目本质上是一棵树 —— 每层（Level）下面有多个条目（Entry），每个条目有标题、描述、图片、来源链接。存储时用 Prisma 的关系映射，一层层往下查就行。

拖拽交互

用的是原生 HTML5 Drag & Drop API，没有额外依赖。层级和条目都可以拖拽排序、拖拽移动位置。拖拽过程中维护一个乐观更新的状态，松手后才发请求持久化 —— 这样拖起来丝滑，不会一卡一卡的。

撤销 / 重做

实现了简单的 Command 模式。每次操作（新增、删除、移动、编辑）都会往一个操作栈里 push 一个可逆的命令对象。Ctrl+Z 就从栈里 pop 并执行 undo。这个功能看着简单，实测对编辑体验提升非常大 —— 敢随便拖、随便改，错了就后悔。

Markdown + KaTeX 渲染

条目描述支持 Markdown（用 react-markdown），公式用 KaTeX 渲染。做这个主要是为了让技术类冰山图能写得好看 —— 比如数学、物理、计算机相关的条目经常需要公式。

自动保存

编辑器每次变更后会设一个防抖定时器（2 秒），定时器触发时自动保存到后端。如果用户在保存前关闭页面，下次打开会提示「恢复未保存的草稿」。这个细节说实话花了不少心思，但能防止意外丢内容。

成就系统设计

成就系统最开始只是「加个好玩的东西」，后来发现它意外地有效 —— 很多用户为了解锁某个徽章会主动探索平台功能。目前有 151 种徽章，分四个稀有度：

技术实现上，成就检查是事件驱动的 —— 当用户完成某个操作（创建、投票、评论等），后端会检查所有未解锁成就的条件是否满足。徽章的图标和描述在管理面板可配，不硬编码。

社区治理：从 RBAC 到 RfA

权限体系分了六层（USER → CONTRIBUTOR → EDITOR → MODERATOR → ADMIN → FOUNDER），但最核心的设计其实是 RfA（Request for Access，借鉴了维基百科的 RfA 流程）。

普通用户想成为 EDITOR（可以审核和编辑他人提交），不是管理员手动给 —— 而是需要发起一个 RfA 申请，由社区投票表决。赞成票超过阈值且满足最低参与人数，自动晋升。

同理，如果 EDITOR 严重失职，任何 USER 可以发起弹劾。弹劾流程和 RfA 类似，只是反过来 —— 票数够了就降级。

和同类项目的区别

简单说 ——Reddit 上做冰山图是「用工具凑合」，冰山图宇宙是「为这件事专门造了工具」。

未来计划

以下在 roadmap 里，但还没排具体时间：

• 多语言支持：目前只有中文，计划加 i18n
• API 开放：提供 REST API，让第三方可以嵌入冰山图
• 联邦制：支持自建实例之间互链（类似 Mastodon 的 ActivityPub）
• AI 辅助整理：让 LLM 帮你从长文中提取关键信息、自动建议冰山层级 —— 这个是想想有意思的方向，但还没想清楚怎么做比较合理

项目结构

frontend/
├── src/
│   ├── components/   # React 组件（冰山编辑器、词条弹窗等）
│   ├── pages/        # Astro 页面路由
│   ├── layouts/      # 页面布局
│   ├── lib/          # 工具库、认证、API 封装
│   └── styles/       # 全局样式
├── prisma/           # 数据库 Schema + 迁移
├── public/           # 静态资源
│   ├── screenshots/  # 项目截图
│   └── readme-banner.svg
├── docker-compose.yml
├── Dockerfile
└── astro.config.mjs

贡献方式

项目完全开源（MIT 协议），欢迎参与：

• 创建冰山图：直接在网站上用编辑器创建新主题
• 编辑现有条目：完善、修正或翻译已有内容
• 提交代码：Fork 仓库 → 创建分支 → 提交 PR
• 报告问题：在 GitHub Issues 提 bug 或功能建议
• 创意提交：在站内「创意池」提交想法，有感兴趣的人会认领实现

架构简图

用户浏览器 ──→ Astro SSR ──→ React 组件（冰山编辑器/词条弹窗/搜索）
                              │
                              ├── Prisma ORM ──→ PostgreSQL
                              ├── Better Auth ──→ 用户认证
                              └── Orama ──→ 全文搜索索引

写在后面

冰山图宇宙可以说是我写的第一个像样的全栈项目，从最开始的 idea → 原型 → 反复重写 → 到现在的版本，中间踩了不少坑也学了不少东西。它不只是一个「看冰山图」的网站 —— 我更希望它变成一个由社区共同维护的知识仓库。冷门话题、互联网史记、小众爱好、失传媒体…… 这些散落的信息如果能被系统地整理成冰山图，比零散的帖子有用太多。

有什么想法或想参与，直接来仓库找我或者站内留言。