Excalidraw日志收集方案：ELK栈整合实例

Excalidraw日志收集方案：ELK栈整合实例

在现代远程协作日益深入的今天，可视化工具早已不再是简单的“画图软件”，而是团队沟通、产品设计和系统架构讨论的核心载体。Excalidraw 作为一款开源的手绘风格白板应用，凭借其轻量、直观且支持实时协作的特性，正被越来越多的技术团队用于头脑风暴、原型设计乃至 AI 辅助绘图场景。

但随着使用频率上升和部署规模扩大——尤其是在企业级私有化环境中——一个问题逐渐浮现：我们如何知道用户在用哪些功能？哪些操作频繁出错？AI 生成的真实采纳率是多少？当某个用户反馈“保存失败”时，运维人员能否快速定位是网络问题、权限异常还是后端服务崩溃？

传统的日志查看方式（比如tail -f）显然无法应对这种多节点、高并发、跨前后端的复杂环境。我们需要的不再是一堆分散的日志文件，而是一个集中化、结构化、可查询、能告警的可观测性体系。

这正是 ELK 技术栈的用武之地。

ELK（Elasticsearch + Logstash + Kibana）虽然已有多年历史，但在日志聚合与分析领域依然表现出色。结合 Filebeat 等轻量采集器，它能够以极低的侵入性实现从浏览器到存储再到可视化的全链路追踪。我们将这套体系引入 Excalidraw 的监控中，并非为了炫技，而是为了解决几个实实在在的问题：

• 日志散落在各处：前端行为、后端请求、WebSocket 连接状态分别记录在不同位置，排查问题需要“拼图”；
• 格式混乱难以检索：默认的日志输出是非结构化的文本，想统计“过去24小时有多少人调用了 AI 生成功能”几乎不可能；
• 缺乏趋势洞察：没有图表展示错误率变化或用户活跃趋势，只能被动响应故障；
• 审计能力缺失：对于金融、医疗等对合规要求高的行业，缺少完整的行为审计日志。

我们的目标很明确：让每一次绘图、每一次保存、每一次 AI 调用都留下可追溯的痕迹，并通过可视化手段将其转化为有价值的运营与运维洞察。

要实现这一点，首先要做的不是部署 Elasticsearch，而是重新思考日志的源头。

Excalidraw 本身不内置复杂的日志上报机制，它的核心职责是渲染和同步图形。因此，我们必须在前端主动埋点，捕获关键用户行为事件。幸运的是，Excalidraw 提供了良好的 API 支持，我们可以轻松监听画布变更、元素增删、导出动作等。

以下是一个典型的 React 组件封装示例：

import { useEffect, useRef } from "react"; import Excalidraw from "@excalidraw/excalidraw"; function ExcalidrawWithLogging() { const excalidrawRef = useRef(); useEffect(() => { const handleCanvasChange = (elements) => { const logEntry = { eventType: "canvas-update", timestamp: new Date().toISOString(), elementCount: elements.length, userId: localStorage.getItem("userId") || "anonymous", sessionId: getSessionId(), }; // 使用 sendBeacon 确保页面关闭前也能发送 if (navigator.sendBeacon) { navigator.sendBeacon("/api/log", JSON.stringify(logEntry)); } }; const api = excalidrawRef.current?.getExcalidrawApi(); if (api) { const cleanup = api.on("change", handleCanvasChange); return () => cleanup(); } }, []); return <Excalidraw ref={excalidrawRef} />; }

这段代码的关键在于使用了navigator.sendBeacon。相比普通的fetch或XMLHttpRequest，sendBeacon是专为日志上报设计的 API——它能在页面即将卸载（如刷新、关闭）时异步发送数据，且不会阻塞主线程，极大降低了对用户体验的影响。

当然，也有一些细节需要注意：
- 如果系统未启用身份认证，建议对userId做匿名化处理，避免隐私泄露；
- 高频操作（如连续拖拽）可能导致日志暴增，可考虑节流或合并小批量变更；
-sendBeacon不支持自定义头部，因此不适合携带敏感 token，应依赖 IP + Session ID 做基础关联。

一旦日志从前端发出，接下来就是服务端的接收与处理流程。

我们采用如下架构进行日志汇聚：

+------------------+ +--------------------+ | | | | | Excalidraw |------>| Nginx / API | | Frontend | HTTP | Gateway | | (Browser) | | | | | +----------+---------+ +------------------+ | ↓ +--------+--------+ | | | Filebeat | | (or HTTP Input) | +--------+--------+ ↓ +--------+--------+ | | | Logstash | | (Filter & Route)| +--------+--------+ ↓ +--------+--------+ | | | Elasticsearch | | (Storage & Index)| +--------+--------+ ↓ +--------+--------+ | | | Kibana | | (Visualization) | +-----------------+

这个架构看似标准，但每个环节都有其设计考量。

首先是Filebeat的角色选择。传统做法是让应用将日志写入本地文件，再由 Filebeat 监控读取。但在容器化或无服务器部署中，前端根本无法写磁盘。为此，我们启用了 Filebeat 的http_endpoint功能，让它直接作为一个微型 HTTP 服务运行，接收来自浏览器的 POST 请求。

对应的配置如下：

filebeat.inputs: - type: http_endpoint host: "0.0.0.0:8080" path: "/api/log" method: "post" json.keys_under_root: true json.add_error_key: true output.logstash: hosts: ["logstash-server:5044"]

这样一来，前端只需 POST 到/api/log，Filebeat 就会自动解析 JSON 并转发给 Logstash。整个过程无需额外搭建 API 服务，简化了架构。

进入Logstash后，真正的“清洗与增强”才开始。原始日志可能只包含基本字段，但我们希望从中提取更多信息。例如：

• 将字符串时间戳转换为标准@timestamp；
• 根据事件类型动态路由到不同的索引（如excalidraw-events-*按天分片）；
• 添加客户端 IP 的地理位置信息，便于分析用户分布；
• 对敏感字段（如userId）进行脱敏处理。

以下是关键的 Logstash 配置片段：

input { beats { port => 5044 } } filter { json { source => "message" skip_on_invalid_json => true } if [eventType] == "canvas-update" { mutate { add_field => { "[@metadata][index]" => "excalidraw-events-%{+YYYY.MM.dd}" } } } date { match => [ "timestamp", "ISO8601" ] target => "@timestamp" } geoip { source => "client_ip" target => "geo_info" } } output { elasticsearch { hosts => ["http://elasticsearch:9200"] index => "%{[@metadata][index]}" user => "elastic" password => "your_secure_password" } }

这里有个实用技巧：利用[@metadata][index]字段控制输出索引名，可以实现按事件类型或日期自动分片，既方便管理，也利于后续的生命周期策略（ILM）自动归档旧数据。

最终，所有日志进入Elasticsearch，建立倒排索引，支持毫秒级全文检索与聚合分析。而真正的价值释放，则发生在Kibana中。

通过 Kibana，我们可以构建一系列仪表盘，将原始日志转化为直观的业务洞察：

• 每日活跃用户数（DAU）：基于userId和sessionId统计活跃度趋势；
• 功能使用热力图：对比eventType: "ai-generation-request"与"manual-draw"的比例，评估 AI 功能的实际接受度；
• 错误监控面板：过滤eventType: "save-failure"并按 IP、时间、浏览器类型分组，快速识别共性问题；
• 地理分布图：利用 GeoIP 数据，在地图上展示用户主要来源区域。

这些视图不只是“好看”，它们直接影响决策。比如某团队发现 AI 生成功能在亚洲地区的成功率明显低于欧美，进一步排查发现是提示词模板未适配中文语境，随后优化 prompt 工程，转化率提升了 40%。

又比如，当用户报告“偶尔无法加载画布”时，运维人员可在 Kibana 中搜索相关错误码，结合时间线发现该问题仅出现在特定时间段，最终定位为 CDN 缓存策略导致的资源加载延迟——这一切在几分钟内完成，而非过去的数小时“猜谜式”排查。

在整个方案落地过程中，我们也总结了一些工程实践中的关键考量点：

• 性能影响最小化：前端使用sendBeacon上报，完全异步，不影响主渲染线程；生产环境仅上报关键事件，避免日志爆炸。
• 安全性保障：传输全程启用 HTTPS；Elasticsearch 启用 RBAC 权限控制，限制敏感字段访问；必要时对userId等做哈希处理。
• 成本控制：采用冷热架构，热节点处理最近7天数据，冷节点存储历史日志并压缩；超过30天的数据可自动归档至 S3 或使用 OpenSearch ISM 策略降级。
• 容错与可靠性：Filebeat 支持磁盘缓冲，即使网络中断也能暂存日志；Logstash 设置批处理与重试机制，防止数据丢失。
• 扩展性预留：当前聚焦于前端操作日志，未来可接入后端服务日志、WebSocket 状态、数据库慢查询等，逐步构建全链路 APM 体系。

这套基于 ELK 的日志方案，本质上是在为 Excalidraw “赋予记忆”。它不再只是一个静态的绘图工具，而成为一个能自我观察、持续进化的协作平台。

更重要的是，这种可观测性建设并不依赖于昂贵的商业工具。Elastic Stack 开源版本已足够满足大多数中小团队的需求，配合合理的架构设计，可以在极低成本下实现专业级的监控能力。

目前，该方案已在多个技术团队的私有部署环境中稳定运行。无论是用于内部知识沉淀，还是作为客户交付项目的一部分，它都显著提升了问题响应速度和服务质量。

展望未来，我们计划进一步融合 APM（如 Elastic APM 或 OpenTelemetry），实现从一次点击 AI 按钮，到后端调用 LLM 接口，再到结果返回的全链路追踪。届时，我们将不仅能知道“谁在什么时候画了什么”，还能清楚地看到“这个请求花了多久、经过了哪些服务、瓶颈在哪里”。

这才是真正意义上的智能协作平台观测体系。