架构图别靠截图反复改：Mermaid 本地生成交互预览，用 cpolar 给同事短时走查-尧图网络科技

架构图别靠截图反复改：Mermaid 本地生成交互预览，用 cpolar 给同事短时走查

一张架构图发到群里，最常见的反馈往往是“这个分支连到哪里”“失败后谁来重试”“手机上看不清节点说明”。截图一旦更新，旧图仍在聊天记录里流转；流程改动几个节点，又要重新导出、重新标注、重新解释。

更适合走查的做法，是把图写成一个浏览器端可渲染的 Mermaid 单页。研发改动文本定义，产品、测试或客户打开同一个只读页面，就能放大、拖动并点击节点查看说明链接。页面先只在本机127.0.0.1提供服务，逐项确认主题、文字、连线与手机显示，再用 cpolar 暂时生成 HTTPS 地址完成远程走查。

本文全部使用虚构的“北辰订单中台”、脱敏接口名和https://docs.example.com示例域名。页面不连接数据库、不接后台接口，也不包含真实业务拓扑、内网地址、客户系统、Token 或私有链接。

先明确这次预览页的边界

这个页面的目标是让人看图和核对流程，不是搭建文档平台，更不是开放管理入口。图中只保留评审所需的抽象节点，例如“订单接入”“规则编排”“通知服务”；接口名使用/api/demo/orders这类脱敏示例；节点链接只指向公开示例说明页。

以下内容不要写入 HTML、图定义、浏览器地址栏或 cpolar 分享文本：

真实业务系统名、生产或内网 IP、真实域名、客户名称与真实调用链。
数据库连接串、消息队列地址、Access Key、Cookie、Token、账号口令和私有文档链接。
管理页、admin 凭据、Docker 控制接口、宿主机目录和文件列表。
可写表单、上传入口、登录入口、后端代理与本机文件访问能力。

cpolar 在这里仅开放一个只读静态页面，并且只在走查窗口内启用。它不用于映射数据库端口或容器控制端口。

准备目录和本地依赖

新建一个独立测试目录，避免把临时页面混进正式项目。下面使用 Mermaid 的 ESM CDN 地址，浏览器直接渲染，不需要 Node 构建链路：

mkdir -p ~/mermaid-review-demo cd ~/mermaid-review-demo

目录里只需要一个index.html。若团队网络要求将依赖离线保存，可以把审核过的 Mermaid 文件放在项目内并改为相对路径；本文为了突出最小可运行示例，使用公开 CDN。无论采用哪一种方式，都不要把本机目录通过页面、脚本或链接暴露出去。

接下来创建页面。panzoom用于在桌面端拖动和缩放 SVG，也为窄屏查看保留了可用的缩放入口。两个图分别采用flowchart和sequenceDiagram，方便把“系统关系”和“一次请求如何流转”放在同一页中核对。

写一个只读 Mermaid 单页

将下面内容保存为index.html：

<!doctype html> <html lang="zh-CN"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>北辰订单中台 - 架构与流程走查</title> <style> :root { color-scheme: light; } * { box-sizing: border-box; } body { margin: 0; color: #172033; background: #f5f7fb; font: 16px/1.6 system-ui, -apple-system, "Microsoft YaHei", sans-serif; } main { width: min(1120px, calc(100% - 32px)); margin: 32px auto 64px; } h1 { margin: 0 0 8px; font-size: 28px; } .lead { margin: 0 0 24px; color: #526075; } section { margin: 20px 0; padding: 20px; background: #fff; border: 1px solid #dbe2ef; } h2 { margin: 0 0 12px; font-size: 20px; } .diagram-shell { overflow: hidden; min-height: 260px; border: 1px solid #e3e8f2; } .mermaid { min-width: 720px; padding: 20px; } .toolbar { display: flex; gap: 8px; margin: 12px 0 0; } button { padding: 7px 12px; border: 1px solid #9aa9c1; background: #fff; color: #172033; cursor: pointer; } .note { font-size: 14px; color: #526075; } @media (max-width: 640px) { main { width: min(100% - 20px, 1120px); margin-top: 16px; } h1 { font-size: 23px; } section { padding: 14px; } .diagram-shell { overflow: auto; } .mermaid { min-width: 640px; } } </style> </head> <body> <main> <h1>北辰订单中台：架构与流程走查</h1> <p class="lead">演示数据与接口均为脱敏示例，仅供只读走查。</p> <section> <h2>系统上下文</h2> <div class="diagram-shell" id="architecture-wrap"> <pre class="mermaid" id="architecture"> flowchart LR U[业务工作台] --> G[订单接入\n/api/demo/orders] G --> R{规则编排} R -->|通过| O[订单服务] R -->|拒绝| N[通知服务] O --> E[事件总线] E --> F[履约适配器] click G "https://docs.example.com/api-demo" "查看脱敏接口说明" click R "https://docs.example.com/rules-demo" "查看规则说明" classDef entry fill:#D8F3DC,stroke:#2D6A4F,color:#123; classDef core fill:#DCEBFF,stroke:#3867A8,color:#123; class G entry; class R,O,E,F,N core; </pre> </div> <div class="toolbar"> <button type="button" />
让静态服务只监听本机
在页面目录中启动 Python 自带的静态服务器。务必显式绑定127.0.0.1，不要监听所有网卡：
cd ~/mermaid-review-demo python3 -m http.server 8080 --bind 127.0.0.1
浏览器打开http://127.0.0.1:8080后，按这个顺序完成本机走查：
检查两个图是否完整渲染，中文是否清楚，连线箭头和alt/else分支是否正确。
点击“订单接入”和“规则编排”节点，确认只跳转到docs.example.com示例链接。
用放大、缩小、复位按钮检查 SVG 操作，鼠标拖动图面检查桌面端阅读体验。
将浏览器宽度缩到 390px 左右，确认标题不遮挡、工具按钮可点、图面能横向查看；再用真机访问本机页面做一次缩放检查。
查看开发者工具的网络面板，确认页面没有请求真实 API、后台服务或本机文件。
127.0.0.1意味着服务仅接受本机连接。局域网设备无法直接打开这个地址，正好避免在本地验收阶段把页面误暴露给同网段设备。
用 cpolar 做一次短时远程走查
本机核对完毕后，另开一个终端，为这个本地 HTTP 端口创建临时 HTTPS 隧道：
cpolar http 8080
cpolar 输出中会给出 HTTPS 公网地址。把这个临时地址单独发送给需要走查的人，并同时写明有效窗口和只读用途。例如：
架构与流程走查（只读演示页） 地址：https://example-tunnel.cpolar.cn 开放时间：本次评审结束前 范围：虚构系统与脱敏接口示例，不含真实业务信息
远程参与者用电脑或手机打开地址后，依次确认架构图中“规则编排”的通过与拒绝分支、流程图中alt分支的文案、节点链接指向以及窄屏可读性。评审意见直接记录到需求或任务系统中，图定义更新后刷新页面即可复查，避免继续堆叠带版本歧义的截图。
分享前再核对一次 cpolar 的目标端口就是本地8080静态服务端口。不要建立数据库、缓存、SSH、Docker Socket、管理后台或其他端口的隧道；也不要在该静态目录中放置配置文件、导出数据、日志或任何凭据。若使用容器承载静态服务，端口发布形式应限定为127.0.0.1:8080:80，同样只让 cpolar 连接本机入口。
临时开放后的收尾清单
走查结束后立刻完成以下收尾，避免临时预览长期留在公网：
在运行cpolar http 8080的终端按Ctrl+C，关闭 cpolar 隧道。
在 Python 静态服务终端按Ctrl+C，停止127.0.0.1:8080服务。
从群聊、邮件或任务评论中撤回临时链接；无法撤回时补充“已关闭”的说明，不再转发。
删除~/mermaid-review-demo临时图表页面和测试目录，或将其保留在仅限本机使用的位置，并继续保持无敏感数据、无后台能力的边界。
复查浏览器历史、共享文档和评审记录，确认没有复制真实拓扑、内网地址、客户系统信息、Token 或私有链接。
用 Mermaid 保留可维护的图定义，用一个只读静态页验证真实的浏览体验，再用 cpolar 完成短时远程走查，能把架构讨论从反复传截图变成对节点、分支和说明的直接确认。关键并不在于把本机服务长期公开，而在于每次开放前后都严格控制内容、端口、时长和收尾动作。