Excalidraw在CI/CD流程可视化中的落地案例

Excalidraw在CI/CD流程可视化中的落地案例

在现代软件交付节奏日益加快的背景下，一个典型的CI/CD流水线可能涵盖十几甚至几十个阶段：从代码提交、静态分析、单元测试，到镜像构建、安全扫描、多环境部署，再到自动化回归与金丝雀发布。这些环节往往横跨多个工具链和团队边界，而传统的YAML配置文件或Wiki文档却难以让人一眼看清全貌。

更常见的情况是，新入职的工程师面对.gitlab-ci.yml中密密麻麻的stages和jobs时一脸茫然；故障复盘会议上，大家各执一词，因为对“到底哪个步骤出了问题”没有统一认知。这些问题的本质，并非技术实现不足，而是信息传递方式落后于系统复杂度。

正是在这种需求驱动下，轻量级可视化工具开始进入DevOps视野。其中，Excalidraw以其极简设计、开源属性和出色的协作能力，逐渐成为许多团队绘制CI/CD流程图的新选择——它不像Visio那样笨重，也不像Draw.io那样工业化，反而用一种看似随意的手绘风格，降低了沟通的心理门槛。

为什么是Excalidraw？

很多人第一次看到Excalidraw都会问：“这不就是个画草图的工具吗？”但恰恰是这种“不够正式”的特质，让它在工程协作中展现出独特价值。

它的核心定位不是替代专业建模软件，而是作为临时但重要的沟通载体——比如一次架构评审会前快速拉出的流程草图，或是事故复盘时现场勾勒的失败路径。这类场景不需要像素级精准，反而需要足够的灵活性和低参与成本。

从技术角度看，Excalidraw基于Web Canvas实现图形渲染，所有元素以JSON结构存储，支持实时多人编辑（通过WebSocket + OT算法），并可无缝嵌入Notion、Obsidian等主流知识管理平台。更重要的是，它是完全开源的，允许企业私有化部署，满足安全合规要求。

这意味着你可以把一张流程图当作代码一样对待：放进Git仓库，做PR评审，记录变更历史。当某天有人质疑“我们以前不是这么走的”时，你完全可以翻出三个月前的版本对比一下。

如何让流程图“活”起来？

真正让Excalidraw区别于普通绘图工具的，是它与现代开发工作流的融合能力。我们曾在一次CI/CD重构项目中尝试将其深度集成，效果远超预期。

最初，团队通过会议梳理出关键阶段：代码检出 → 依赖安装 → 静态检查 → 单元测试 → 构建镜像 → 推送Registry → 部署预发 → 自动化测试 → 手动审批 → 生产发布。以往的做法是会后由一人整理成PPT发群，但很快就被遗忘。

这次我们换了个方式：主持人直接打开Excalidraw共享链接，边讨论边拖拽矩形框连线。每个人都能实时看到修改，随时暂停补充细节。不到半小时，一张清晰的端到端流程图就成型了。会后生成的链接被置顶在项目频道，后续每次变更都直接在这张图上迭代。

更有意思的是，当我们引入AI辅助后，效率进一步提升。下面这段Python脚本展示了如何通过LLM自动生成流程初稿：

import requests import json def generate_flow_description(prompt): response = requests.post( "http://localhost:11434/api/generate", json={ "model": "llama3", "prompt": f"{prompt}\n请输出JSON格式，字段：nodes（名称、类型）、edges（from, to）" } ) return eval(response.text) def create_excalidraw_element(type_name, text, x, y, width=120, height=60, id=None): base = { "type": "rectangle", "version": 1, "versionNonce": 0, "isDeleted": False, "id": id or f"{type_name}_{x}_{y}", "fillStyle": "hachure" if type_name == "stage" else "solid", "strokeWidth": 2, "roughness": 2, "opacity": 100, "angle": 0, "x": x, "y": y, "stroke": "#000", "background": "#fff", "width": width, "height": height, "seed": 123456, "shape": ["rectangle", {"width": width, "height": height}] } if text: base["text"] = text base["fontSize"] = 16 base["fontFamily"] = 1 return base def build_excalidraw_json(nodes, edges): elements = [] positions = {} start_x, start_y = 100, 100 dx, dy = 200, 100 for i, node in enumerate(nodes): x = start_x + (i % 3) * dx y = start_y + (i // 3) * dy elem = create_excalidraw_element("stage", node["name"], x, y, id=node["id"]) elements.append(elem) positions[node["id"]] = (x, y) for edge in edges: from_id = edge["from"] to_id = edge["to"] fx, fy = positions[from_id] tx, ty = positions[to_id] arrow = { "type": "arrow", "version": 1, "versionNonce": 0, "isDeleted": False, "id": f"arrow_{from_id}_{to_id}", "points": [[0, 0], [tx - fx, ty - fy]], "x": fx, "y": fy, "startBinding": {"elementId": from_id, "focus": 0.5, "gap": 10}, "endBinding": {"elementId": to_id, "focus": 0.5, "gap": 10} } elements.append(arrow) excalidraw_data = { "type": "excalidraw", "version": 2, "source": "https://excalidraw.com", "elements": elements, "appState": { "theme": "light", "viewBackgroundColor": "#ffffff" } } return excalidraw_data if __name__ == "__main__": prompt = """ 请描述一个典型的CI/CD流程，包括以下阶段： 代码提交 → 静态检查 → 单元测试 → 构建镜像 → 推送镜像 → 部署到预发 → 自动化测试 → 生产发布 """ result = generate_flow_description(prompt) nodes = [ {"id": f"node_{i}", "name": item.strip()} for i, item in enumerate(result.get("nodes", [])) ] edges = result.get("edges", []) excalidraw_json = build_excalidraw_json(nodes, edges) with open("ci_cd_pipeline.excalidraw.json", "w") as f: json.dump(excalidraw_json, f, indent=2) print("✅ Excalidraw CI/CD 流程图已生成：ci_cd_pipeline.excalidraw.json")

这个小工具的意义在于，它把原本需要30分钟手动绘制的工作压缩到了几分钟。更重要的是，生成的.excalidraw.json文件可以直接提交到Git，与实际的CI配置文件放在同一个仓库里。下次有人修改了流水线逻辑，CI系统甚至可以自动触发图表更新任务，确保文档永不脱节。

实战中的设计经验

在长期使用过程中，我们也总结出一些实用的设计原则，帮助团队更好地发挥Excalidraw的价值。

首先是控制复杂度。一张图最好不要超过10个主要节点。如果流程太长，建议按环境拆分（如“CI阶段”、“预发部署流”、“生产发布策略”），并通过颜色编码建立关联。我们曾见过有人试图在一个画布上画完整个组织的交付体系，结果变成了一团无法解读的线条迷宫。

其次是建立符号规范。虽然手绘风格追求轻松感，但在关键语义上必须保持一致。例如：
- 圆角矩形代表执行阶段；
- 菱形用于条件判断（如“测试通过？”）；
- 虚线箭头表示人工干预点；
- 红色边框标记高风险操作。

这样的约定虽简单，却能极大减少误解。尤其在故障排查时，一眼就能定位到“卡在哪一步”。

另一个容易被忽视的点是权限管理。公开链接固然方便协作，但对于涉及生产发布的审批流程图，必须部署私有实例并集成LDAP认证。我们曾发生过外部顾问误删关键节点的事件——幸好有Git版本控制兜底。

最后一点建议是：别把它当成终点，而是一个起点。流程图的价值不在于画得多精美，而在于能否引发讨论、暴露盲区。有一次我们在绘制发布流程时才发现，竟然没人清楚回滚机制的具体触发条件。这张“难看”的草图最终推动了SOP文档的补全。

从“看得见”到“可参与”

回顾整个实践过程，最深刻的体会是：Excalidraw带来的不仅是工具升级，更是一种协作文化的转变。

过去，流程设计往往是少数资深工程师闭门完成的任务，其他人只能被动接受。而现在，任何人都可以在共享画布上添加注释：“这里是不是少了权限校验？”、“上次故障就是因为这步超时”。这种低门槛的参与感，使得流程本身变得更加健壮。

特别是在Postmortem场景中，我们不再依赖文字报告去还原时间线，而是直接在Excalidraw中复现“失败路径”：用红色箭头标出异常流向，附加日志截图和责任人说明。这种视觉化的根因分析方式，让复盘会议效率提升了近一倍。

未来，随着LLM能力的增强，我们可以设想更智能的工作模式：输入一段自然语言描述，系统自动生成候选流程图；或者反向操作，将.github/workflows/deploy.yml解析为可视化拓扑，并高亮潜在瓶颈。届时，Excalidraw或将演变为一种“可执行的文档”——不仅展示流程，还能联动真实系统的状态更新。

某种意义上，这正是DevOps精神的具象化：打破隔阂，让所有人对系统拥有共同的理解。而一张随手可改的手绘图，也许比一百页PDF更能承载这份透明与协作的初心。