FlowSync

基于 YJS + WebSocket + React Flow 的实时协作流程图编辑器

---

⚠️ 说明: 本项目是 DocFlow 项目协同编辑功能的基础实现示例。如果你想学习更完整的协同编辑解决方案（包括富文本编辑、权限管理、AI 集成等企业级功能），请访问 DocFlow 项目。

💬 联系作者: 如有问题或想深入交流，欢迎添加作者微信 yunmz777

---

📚 项目简介

FlowSync 是一个实时协作的流程图编辑器，展示了如何使用 Yjs CRDT 算法实现多人协同编辑的核心功能。项目支持多人同时编辑、实时光标显示和节点同步。

✨ 主要特性

• 🔄 实时协作: 多用户可同时编辑同一个流程图
• 👁️ 实时光标: 查看其他用户的光标位置和操作
• 🎯 节点同步: 节点的拖动、连接等操作实时同步
• 📦 Monorepo 架构: 使用 Turbo + pnpm 管理前后端代码
• ⚡ 现代技术栈: React 19 + NestJS 11 + Yjs 13

🏗️ 技术架构

Monorepo 结构

本项目采用 Turbo + pnpm 的 Monorepo 架构：

flowsync/
├── backend/          # NestJS 后端服务
│   ├── src/
│   │   └── yjs/     # WebSocket 协同服务
│   └── package.json
├── frontend/         # React + Vite 前端应用
│   ├── src/
│   │   └── components/
│   └── package.json
├── turbo.json       # Turbo 构建配置
├── pnpm-workspace.yaml
└── package.json

技术栈

前端

• React 19.2.3
• ReactFlow 11.11.4 - 流程图编辑器
• Yjs 13.6.28 - CRDT 数据结构
• y-websocket 3.0.0 - WebSocket 客户端
• Framer Motion 12.23.26 - 动画库
• Vite 7.3.0 - 构建工具

后端

• NestJS 11.1.10 - Node.js 框架
• Yjs 13.6.28 - CRDT 协同引擎
• y-protocols 1.0.7 - Yjs 协议
• WebSocket (ws) 8.18.3 - WebSocket 服务器

🚀 快速开始

环境要求

• Node.js >= 18
• pnpm >= 8

安装依赖

# 在项目根目录安装所有依赖
pnpm install

开发模式

同时启动前后端

# 在项目根目录运行
pnpm dev

服务将运行在：

• 前端: http://localhost:5173
• 后端 WebSocket: ws://localhost:1234

单独运行服务

# 只运行后端
cd backend
pnpm dev

# 只运行前端
cd frontend
pnpm dev

构建项目

# 构建所有项目
pnpm build

# 构建指定项目
pnpm --filter backend build
pnpm --filter frontend build

📝 可用命令

# 开发
pnpm dev              # 启动所有服务

# 构建
pnpm build            # 构建所有项目

# 代码检查
pnpm lint             # 运行 ESLint

# 测试
pnpm test             # 运行测试

# 清理
pnpm clean            # 清理构建产物和依赖

🎯 核心功能

实时协作

• 使用 Yjs CRDT 实现无冲突的数据同步
• WebSocket 实时通信
• 自动处理网络断线重连

光标追踪

• 实时显示其他用户的光标位置
• 支持画布缩放和平移时的坐标转换
• 平滑的光标动画效果

节点操作

• 拖拽节点
• 连接节点
• 删除连接
• 所有操作实时同步到所有用户

📖 项目说明

WebSocket 协议

后端 WebSocket 服务器监听在 1234 端口，实现了 Yjs 的同步协议：

• 消息类型 0: 文档同步消息
• 消息类型 1: Awareness (光标/状态) 更新

数据结构

使用 Yjs 的 Y.Map 存储：

• nodes: 存储所有节点数据
• edges: 存储所有连接数据

🔧 故障排除

WebSocket 连接失败

1. 确保后端服务正在运行
2. 检查端口 1234 是否被占用
3. 检查防火墙设置

依赖安装失败

# 清理并重新安装
rm -rf node_modules **/node_modules pnpm-lock.yaml
pnpm install

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！