Excalidraw集成C#后端服务：实现企业级白板数据持久化存储

Excalidraw 与 C# 后端集成：构建企业级白板数据持久化方案

在现代软件研发和产品设计流程中，可视化协作已不再是“加分项”，而是团队高效沟通的基础设施。随着远程办公常态化，工程师、架构师和产品经理越来越依赖像 Excalidraw 这样的轻量级绘图工具来快速表达复杂逻辑——从系统架构草图到业务流程梳理，一张随手可画的白板图往往胜过千言万语。

但问题也随之而来：这些关键的设计资产常常只存在于某个浏览器标签页里，刷新即丢；或者散落在不同成员的本地设备上，无法共享、难以追溯。如何将这种“灵感瞬间”转化为可管理、可复用的企业知识资产？答案就是——为开源白板加上企业级后端支持。

本文将以 Excalidraw 前端为核心，结合 C# 与 ASP.NET Core 构建稳定可靠的后端服务，实现白板内容的持久化存储与安全访问。这不是简单的“存取 JSON”，而是一次面向生产环境的真实工程实践。

我们先来看一个典型场景：某技术团队正在评审微服务架构方案。一位架构师在 Excalidraw 中绘制了完整的服务拓扑图，并标注了关键的数据流和调用关系。会议结束时，他想把这张图保存下来供后续参考。如果仅靠前端默认的导出功能，这张图可能会被下载成.excalidraw文件，然后塞进某个网盘或邮件附件中。下次需要修改时，谁能保证还能找到它？

更糟糕的是，当另一位同事想要在此基础上补充新模块时，很可能因为版本混乱导致重复劳动。这正是许多团队面临的“协作断层”：工具很先进，管理却停留在 U 盘时代。

要打破这一困境，核心在于建立统一的数据中枢。我们需要让每一次绘图操作都能自动同步到服务器，就像代码提交到 Git 仓库一样自然。而这背后的关键，是前后端之间的无缝对接。

Excalidraw 提供了一个非常友好的切入点：它的所有图形状态都可以通过serializeAsJSON()方法序列化为标准 JSON 结构。这个 JSON 不仅包含了每个元素的位置、样式、类型等信息，还保留了文件引用、协作上下文等元数据。换句话说，只要把这个 JSON 存下来，整个画布的状态就完整定格了。

const saveDiagram = () => { if (excalidrawRef.current) { const serializedData = serializeAsJSON( excalidrawRef.current.getSceneElements(), excalidrawRef.current.getAppState(), excalidrawRef.current.getFiles() ); fetch("https://api.example.com/diagrams", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ title: "订单系统架构", content: serializedData, userId: "user-123", createdAt: new Date().toISOString(), }), }); } };

这段代码看似简单，却是整个集成链条的第一环。它把用户的创作成果打包成 HTTP 请求，送往后端 API。接下来的任务，就交给了我们的 C# 服务。

选择 C# 和 ASP.NET Core 并非偶然。在企业级系统开发中，C# 凭借其强类型、高性能和成熟的生态体系，尤其适合处理高并发、严安全要求的业务场景。配合 EF Core 的 ORM 能力，我们可以快速搭建一个既能应对流量压力又能保障数据一致性的后端服务。

来看后端模型的设计：

public class Diagram { public int Id { get; set; } public string Title { get; set; } public string Content { get; set; } // 存储原始 JSON 字符串 public string UserId { get; set; } public DateTime CreatedAt { get; set; } public DateTime UpdatedAt { get; set; } }

这里有个值得深思的设计决策：为什么不把Content拆分成多个字段映射为复杂对象，而是直接存为字符串？原因有三：

1. 灵活性优先：Excalidraw 的 JSON schema 可能随版本演进而变化，硬编码类结构容易导致兼容性问题；
2. 性能考量：反序列化大型 JSON 到对象树成本较高，尤其在频繁读取场景下；
3. 关注点分离：后端只需负责“原样存储”和“按需返回”，解析工作交给前端更合理。

当然，这也带来新的挑战——如何防止恶意用户上传超大或非法内容？这就需要我们在控制器层面做好输入验证。

[ApiController] [Route("api/[controller]")] public class DiagramsController : ControllerBase { private readonly ApplicationDbContext _context; public DiagramsController(ApplicationDbContext context) => _context = context; [HttpPost] public async Task<IActionResult> CreateDiagram([FromBody] CreateDiagramRequest request) { if (!ModelState.IsValid) return BadRequest(ModelState); // 防止内容过大（例如超过 5MB） if (request.Content?.Length > 5_000_000) return BadRequest("Diagram content too large."); var diagram = new Diagram { Title = request.Title, Content = request.Content, UserId = request.UserId, CreatedAt = DateTime.UtcNow, UpdatedAt = DateTime.UtcNow }; _context.Diagrams.Add(diagram); await _context.SaveChangesAsync(); return CreatedAtAction(nameof(GetDiagramById), new { id = diagram.Id }, diagram); } [HttpGet("{id}")] public async Task<IActionResult> GetDiagramById(int id) { var diagram = await _context.Diagrams.FindAsync(id); return diagram is null ? NotFound() : Ok(diagram); } }

在这个控制器中，我们不仅实现了基本的 CRUD 接口，还加入了实际项目中必不可少的防护机制：模型验证、大小限制、时间戳记录。特别是CreatedAt和UpdatedAt的引入，为后续实现版本对比和审计日志打下了基础。

数据库方面，使用 EF Core 配合 SQL Server 是一种稳妥选择。对于大多数企业而言，已有现成的数据库运维体系，接入成本低。

public class ApplicationDbContext : DbContext { public DbSet<Diagram> Diagrams { get; set; } protected override void OnConfiguring(DbContextOptionsBuilder options) => options.UseSqlServer("Your_Connection_String_Here"); }

但在真实部署中，连接字符串应通过IConfiguration注入，并启用连接池以提升性能。此外，考虑到某些图表访问频率极高，可以引入 Redis 缓存热点数据，减少对主库的压力。

整个系统的架构可以用一句话概括：前端专注交互体验，后端保障数据可靠。

+------------------+ +---------------------+ | Excalidraw |<----->| C# ASP.NET Core | | (React 前端) | HTTP | Web API | +------------------+ +----------+----------+ | v +----------------------+ | 数据库（SQL Server） | +----------------------+

当用户打开页面时，若携带了图表 ID，前端会立即发起 GET 请求加载历史数据，并通过loadFromBackend()将 JSON 还原为可视化的画布。编辑完成后点击保存，新一轮 POST 请求再次触发持久化流程。整个过程对用户透明，仿佛本地操作一般流畅。

但这只是起点。一旦数据进入后端系统，更多可能性便随之展开：

• 可以增加ProjectId字段，将图表归类到具体项目中；
• 添加标签系统，支持按主题检索；
• 实现权限控制，确保敏感架构图只能被授权人员查看；
• 记录每次保存的快照，形成版本历史，支持回滚与 diff 分析；
• 结合 SignalR 推送变更通知，迈向真正的实时协作。

甚至，未来还可以探索 AI 集成路径：比如用户输入“请画一个包含用户中心、订单服务和支付网关的分布式系统”，后端调用 LLM 解析意图并生成初始 JSON 结构，再由 Excalidraw 渲染呈现。这不再是幻想，而是正在发生的趋势。

值得注意的是，在设计此类系统时有几个容易忽视但至关重要的细节：

• 字符集与编码：确保数据库使用 UTF-8 支持多语言文本标注；
• CORS 策略配置：开发阶段允许http://localhost:3000，上线后锁定正式域名；
• HTTPS 强制启用：避免敏感设计图在传输过程中被窃听；
• 软删除机制：不要物理删除记录，而是标记IsDeleted字段，便于恢复误删内容；
• 定期备份策略：白板数据也是企业资产，必须纳入整体灾备计划。

最终，这套方案的价值远不止于“能保存图纸”。它真正改变的是团队的知识沉淀方式——从碎片化、易丢失的临时记录，转变为结构化、可追溯的数字资产。每一次会议的讨论成果、每一次设计迭代的过程，都被清晰地留存下来，成为组织智慧的一部分。

试想几年后，新入职的工程师想要了解系统演进历程，不再需要四处打听“谁参与过早期设计”，而是可以直接查阅最早的那张手绘风格架构图，看着它一步步演化至今。这种连续性，正是高质量工程文化的体现。

Excalidraw 本身是一款极简主义的产品，但它所承载的内容，完全可以变得极为厚重。当我们用 C# 构建起坚固的后端支撑时，实际上是在为创造力提供一座可信赖的档案馆。在这里，每一个想法都值得被记住，每一份努力都不会消失。

这条路才刚刚开始。下一个版本，也许我们就该考虑加上评论系统、变更提醒、甚至自动化合规检查。毕竟，真正的企业级工具，从来都不是一蹴而就的。