多功能架构设计系统

一个面向架构梳理、方案设计、知识拆解和多人协作的在线思维导图系统。项目基于 Node.js 自托管服务，提供账号登录、云端文档、分享链接、实时协同编辑、本地文件持久化和数据备份能力，适合用于产品规划、技术架构设计、项目复盘、学习笔记和团队方案共创。

项目定位

多功能架构设计系统不是单纯的静态思维导图页面，而是一套可本地部署、可持续保存、可多人协作的架构设计工作台。它把 Markdown 式结构化编辑、可视化脑图、云文档管理和实时协作整合在同一个轻量服务里。

主要功能

• 在线思维导图编辑：支持节点编辑、层级组织、样式调整和可视化排版。
• 多人实时协作：基于 WebSocket、Yjs 和 Hocuspocus 实现同一文档内的协同编辑。
• 账号与会话：支持用户注册、登录和基于 Cookie 的会话管理。
• 云端文档：文档状态保存到本地 data/ 目录，服务重启后仍可恢复。
• 分享协作：支持通过分享链接邀请其他用户进入指定文档。
• 贡献记录：记录文档协作过程中的贡献信息，便于回溯。
• 数据备份：提供备份与数据压缩脚本，降低自托管维护成本。
• 前后端拆分：前端静态资源由 Node 服务托管，后端负责登录、文档、分享和协作接口。

技术架构

• 运行环境：Node.js 20+
• Web 服务：Express
• 实时协作：Yjs、Hocuspocus、WebSocket
• 数据存储：本地文件系统
• 安全基础：Helmet、HttpOnly Cookie、会话密钥
• 前端形态：原生 HTML、CSS、JavaScript
• 构建工具：esbuild

目录结构

server/                 服务端入口、路由、中间件、存储和协作模块
server/frontend/        页面入口
server/public/          前端脚本、样式和协作客户端构建产物
scripts/                构建、备份和数据整理脚本
项目资料/               项目规划、背景资料和历史单文件版本
data/                   运行期数据目录，不提交到 Git
.env                    本地环境变量，不提交到 Git

快速开始

npm install
Copy-Item .env.example .env
npm run build:collab-client
npm start

默认访问地址：

http://localhost:3000

健康检查地址：

http://localhost:3000/healthz

环境变量

复制 .env.example 为 .env 后按需修改：

PORT=3000
PUBLIC_BASE_URL=http://localhost:3000
DATA_DIR=data
SESSION_SECRET=replace-with-a-long-random-secret
SESSION_COOKIE_SECURE=auto

说明：

• PORT：服务监听端口。
• PUBLIC_BASE_URL：生成分享链接时使用的公开访问地址。
• DATA_DIR：账号、文档、协作状态和备份数据的保存目录。
• SESSION_SECRET：会话签名密钥，正式部署前必须换成高强度随机字符串。
• SESSION_COOKIE_SECURE：Cookie 安全策略，生产环境 HTTPS 可设为 true，本地调试可保持 auto。

常用命令

npm start

启动服务。

npm run dev

以监听模式启动开发服务。

npm run build:collab-client

构建实时协作客户端资源。

npm run backup

备份本地运行数据。

npm run compact:data

整理和压缩本地数据。

部署建议

本项目需要长期运行 Node.js 服务，并依赖 data/ 目录保存账号、文档和协作状态。不建议部署到纯静态网站托管平台，也不建议使用会在重启或重新部署后清空本地文件的免费 Web 服务。

更适合的部署方式：

• 一台可长期运行的云服务器或 VPS。
• 持久化磁盘保存 data/。
• 使用域名和 HTTPS 对外提供访问。
• 使用 systemd、PM2 或类似工具守护 Node 服务。
• 定期执行 npm run backup 并异地保存备份。

更详细的免费部署建议见 DEPLOY_FREE.md。

GitHub About 建议

仓库简介：

面向架构梳理、方案设计和团队协作的自托管在线思维导图系统，支持账号、云文档、分享链接、实时协同编辑和本地数据备份。

推荐 Topics：

mindmap, architecture-design, collaboration, yjs, hocuspocus, nodejs, express, websocket, self-hosted, knowledge-management

数据与安全

• .env、data/ 和 node_modules/ 已加入 .gitignore，不会提交到公开仓库。
• 正式部署前请替换 SESSION_SECRET。
• 对外开放前请确认 PUBLIC_BASE_URL 与实际域名一致。
• 生产环境建议启用 HTTPS，并定期备份 data/。

适用场景

• 技术架构设计和方案推演
• 产品功能拆解和路线规划
• 团队会议共创和复盘
• 课程、知识库和学习笔记整理
• 多人维护的结构化项目资料