TeamMapper 介绍与选型指南

目标：回答「TeamMapper 是什么、由哪些部件构成、能做什么、适合什么场景、与同类产品如何取舍」，为是否采用 TeamMapper 自建协作思维导图服务提供选型依据。本文内容基于官方仓库与官网联网溯源，查询日期 2026-11-02；配套部署与接口实测见本专栏其余各篇。

一、环境信息

• 溯源对象：TeamMapper 开源项目（GitHub 仓库 b310-digital/teammapper，官网 teammapper.org）
• 溯源渠道：GitHub 仓库页与 README、Releases 订阅源（releases.atom）、shields.io 星数徽章、Docker 镜像仓库（ghcr.io）
• 查询日期：2026-11-02
• 溯源时最新版本：v0.4.0-1（发布于 2026-10-28）
• 许可证：MIT

二、软件概述

TeamMapper 是一款可自托管的**协作思维导图（mindmap）**Web 应用，官方定位一句话：「Mindmapping made simple: Host and create your own mindmaps. Share your mindmap sessions with your team and collaborate on mindmaps.」——自己在服务器上建图、存图，把会话分享给团队并实时协作编辑。

项目沿革（来源：官方 README，查询日期 2026-11-02）：

• TeamMapper 基于早期开源项目 mindmapp（cedoor/mindmapp，已停止维护）发展而来；与 mindmapp 的关键区别是 TeamMapper 提供了基于 WebSockets 的团队共享导图会话。
• 当前维护方为企业 b310 digital（仓库归属 b310-digital 组织），持续高频发版。
• 官方提供公共演示实例 https://teammapper.org，可先试用再决定是否自建。
• 项目被德国下萨克森州教育机构平台 kits（kits.blog/tools）采用并免费面向学校提供，README 中列有 nibis、kits 等机构背书。

社区活跃度实测数据（shields.io 徽章，查询日期 2026-11-02）：

💡 说明：星数绝对值不大（516），但发版节奏是「一周多版」级别的活跃维护状态；选型时活跃度应看「最近是否有提交/发版」而非仅看星数。

三、核心架构

TeamMapper 是 monorepo（pnpm workspace）结构，按官方 README 与仓库目录归纳为「前端 + 后端 + 数据库」三件套：

teammapper/
├── teammapper-frontend/   # Angular 前端（严格模式编译，strictTemplates）
├── teammapper-backend/    # NestJS 后端（REST API + Yjs WebSocket 网关）
├── packages/
│   ├── mmp/               # @teammapper/mmp：基于 d3 的思维导图渲染库
│   ├── shared/            # @teammapper/shared：前后端共用的线协议类型与校验 schema
│   └── mermaid-mindmap-parser/  # 从 mermaid 项目 vendored 的 mindmap 解析器
├── docker-compose.yml     # 开发编排
├── docker-compose-prod.yml# 生产编排（源码构建）
└── Dockerfile             # 官方镜像构建（ghcr.io/b310-digital/teammapper）

关键机制：

• 实时协作基于 Yjs（CRDT 协同框架）：后端在 /yjs 路径挂载 Yjs WebSocket 网关，每个导图是一个 Y.Doc，节点数据存于 nodes/arrows 两个 Y.Map 共享结构；客户端断线重连、并发编辑的合并交给 CRDT 算法，服务端不仲裁顺序。
• 持久化：内存中的 Y.Doc 经防抖（debounce）写回 PostgreSQL（TypeORM），服务重启不丢数据。
• 协作权限模型：无账号体系。每张图创建时生成 adminId（管理凭据，删除用）与 modificationSecret（修改凭据，编辑用）；分享链接分「可编辑」与「只读」两种，只读连接发的写消息会被服务端丢弃。
• 前端渲染：@teammapper/mmp 用 d3 把节点画成 SVG，导出 PNG/SVG/PDF 等图像类格式在浏览器端完成。

💡 技术拓展：实时协同编辑的冲突合并机制不止 CRDT 一种。常见方案对比——

机制	原理	代表/取舍
OT（操作变换）	服务端对并发操作做变换后再应用，需中心服务器仲裁	Google Docs 经典方案；实现复杂、离线合并弱
CRDT（无冲突复制数据类型）	数据结构本身保证任意顺序合并结果一致，无需中心仲裁	Yjs、Automerge；带宽与元数据开销略高
锁/最后写入胜	粗粒度互斥或时间戳覆盖	简单文档同步工具；并发体验差

TeamMapper 采用 Yjs（CRDT 家族），适合「多人同时改一张导图」且不想自建仲裁服务的自托管场景。

四、功能特性

官方 README「Features」清单（查询日期 2026-11-02）逐条归纳：

五、快速开始

官方 README「Quick Start」给出的最小部署形态（转述官方事实，本专栏《TeamMapper 0.4.0 Docker Compose 部署指南》有完整实测）：一个预构建镜像 + 一个 PostgreSQL 即可起服务。

services:
  app_prod:
    image: ghcr.io/b310-digital/teammapper:latest
    environment:
      MODE: PROD
      BINDING: "0.0.0.0"
      POSTGRES_DATABASE: teammapper-db
      POSTGRES_HOST: postgres_prod
      POSTGRES_PASSWORD: q1w2e3r4
      POSTGRES_PORT: 5432
      POSTGRES_SSL: false
      POSTGRES_USER: teammapper-user
      DELETE_AFTER_DAYS: 30
      AI_ENABLED: false
    ports:
      - 80:3000
    depends_on:
      - postgres_prod
  postgres_prod:
    image: postgres:12-alpine
    environment:
      POSTGRES_DB: teammapper-db
      POSTGRES_PASSWORD: q1w2e3r4
      POSTGRES_USER: teammapper-user

docker compose up -d 后访问 http://localhost/ 即可建图。官方镜像发布在 GitHub Container Registry（ghcr.io/b310-digital/teammapper），Docker Hub 无官方镜像。

六、适用场景与限制

适用场景：

• 团队头脑风暴、会议共创：多人同时编辑一张导图，浏览器打开链接即可，无需注册。
• 教学/工作坊：官方演示站与 kits 平台面向学校场景，GDPR 默认 30 天自动清理正好匹配「课后不留痕」。
• 内网知识梳理：完全自托管，数据不出域。
• 轻量文档协作补充：与 DMS/笔记系统搭配，导图作为会议记录的结构化载体（文档管理侧选型见 《SeedDMS 6.0.42 介绍与选型指南》、《Papermerge 介绍与选型指南》）。

限制与不适用：

• 无账号体系：没有用户/组织/权限管理，也没有管理后台；「管理」只有每张图的 adminId（删除凭据）。需要企业级成员/空间权限的场合不适用。
• 默认保留期 30 天：长期归档的图需自行调大 DELETE_AFTER_DAYS 或定期导出 JSON 备份。
• 单实例服务：官方部署形态为单 app + 单 PostgreSQL，无集群/水平扩展方案。
• 导图单一画布模型：专注 mindmap，不是无限白板（白板需求看 4ga Boards/Miro 类），也不是流程图工具（那是 drawio 的地盘）。
• 无移动端原生应用：仅响应式 Web。

七、同类选型对比

选型建议：

• 需求是「多人同时在线画一张思维导图、数据必须在自己服务器上」→ TeamMapper 是开源里最对口的选择，几乎无同类竞品（drawio 协作弱、Freeplane 无协作）。
• 需求是「通用画图（架构图/流程图）」→ 选 drawio，协作思维导图不是它的强项。
• 需求是「个人深度笔记式 mindmap」→ Freeplane 功能更全（脚本、过滤、LaTeX）。
• 组织已有 Miro/XMind 付费且无数据主权诉求 → 不必自建。

八、参考链接

• 官方仓库：https://github.com/b310-digital/teammapper （README/releases.atom 查询日期 2026-11-02）
• 官方演示站：https://teammapper.org
• 官方镜像：https://ghcr.io/b310-digital/teammapper
• Yjs 协同框架：https://yjs.dev
• 前身项目 mindmapp：https://github.com/cedoor/mindmapp （已停止维护）