先说一个我印象很深的场景。去年有段时间我们组的 CI 跑得特别慢每次合并 PR 之后大家都要轮流刷新 Jenkins 页面就为了看一眼自己的分支到底过了没有。后来有个同事直接在群里问“能不能把这东西放到我们自己的页面上”——于是就有了这个 Embeddable-Build-Status-Plugin。这个插件的核心功能一句话就能说清把 CI/CD 的构建状态从 Jenkins、GitLab CI 这些平台里抽出来以徽章、卡片或者 JSON 接口的形式嵌入到任何你说了算的页面上。README、内部 Wiki、Dashboard、团队大屏、自动生成的项目周报都可以实时显示当前构建是绿是红。适合谁适合所有被“构建状态分散在各个平台”困扰的团队也适合想给自己的开源项目加一个状态展示层的开发者。下面我把这个插件从设计思路、服务端实现到接入侧的正确姿势完整拆一遍。这不是官方文档式的说明书而是我实际开发、部署、被坑之后沉淀下来的一手经验。1. 为什么要把构建状态“嵌”出去场景与痛点1.1 团队协作中构建信息的流向大多数人觉得构建状态“看一眼就行”但实际协作里构建信息是一种高频查询数据。开发者在等构建结果测试在等构建产物项目经理在看版本是否可交付开源维护者要确认每个 PR 是否健康。这些人的工作入口不在 CI 平台上而在各自熟悉的工具里。你可以批评他们“为什么不去开 Jenkins 看一眼”但现实是人的注意力在哪里信息就应该跟到哪里。强行让人切换工具结果就是大家反复刷新页面、群里不停有人问“过了吗”“红了吗”信息损耗极大。1.2 嵌入场景盘点README、Dashboard、周报、大屏我梳理过自己项目里出现的典型嵌入需求基本可以归成四类。README 徽章开源项目最常用仓库首页直接显示 build passing / build failing访客不用点进 CI 就知道项目健康状况。这也是最轻量的嵌入方式一张图片搞定。内部 Dashboard团队自己搭建的研发效能看板聚合多个仓库、多个流水线的状态按服务分组展示。这里需要的是结构化数据而不是一张图片。自动生成周报每周自动汇总哪些服务构建失败、平均恢复时间多长。这需要历史状态记录单纯当前状态不够用。团队大屏 / 走廊电视持续展示主干分支是否绿失败时高亮。这里需要的是大字版卡片和 README 徽章完全不同。这些场景有一个共同点它们都不属于 CI 平台自带的功能范畴。Jenkins 有自己的 ViewGitLab 有自己的 Pipeline 页但它们的展示逻辑绑定在平台内部做不了跨平台、跨页面的自由组合。1.3 主流 CI 平台原生方案为什么不够用先说结论GitLab 提供了现成的 pipeline badgeJenkins 也有插件可以生成 status icon但真正用起来你会发现三个硬伤。第一样式和位置不可控。原生 badge 只能放在 README 或官方页面里你想把它嵌进一张深色背景的大屏颜色、尺寸、字体全都没法调。第二数据不集中。公司里通常同时跑着 Jenkins、GitLab CI甚至还有自研的发布系统。每个平台一个 badge视觉语言不统一信息还是分散的。第三权限模型不匹配。CI 平台的接口通常需要登录凭证而 README 和 Dashboard 是半公开的你不能把 Jenkins 的 API Token 塞进前端页面里。原生方案没有提供“安全的只读代理”这一层。所以做一个独立的、可嵌入的构建状态插件本质上是加了一层“状态代理”它订阅各 CI 平台的构建事件归一化成统一的状态模型再通过多种输出方式图片、卡片、JSON提供给任意消费端。这就是 Embeddable-Build-Status-Plugin 的核心价值。2. 插件设计的分岔路徽章、Iframe 还是 API 轮询2.1 三种形态的能力边界对照动手之前我先把输出形态列了个表挨个分析优缺点。这是这个项目最关键的设计决策选错后面全是返工。形态实现成本可定制性数据实时性适合场景SVG/PNG 徽章图片低中颜色、文本可配受缓存策略限制README、外部博客、GitHub 页iframe 状态卡片中高内嵌完整页面高可轮询或 WebSocket内部 Dashboard、大屏JSON API低极高前端自由渲染高自定义系统、周报脚本、聚合平台我最终的选择是以徽章图片为核心入口同时保留 JSON API 和 iframe 卡片两种输出。理由很简单——徽章是普适性最强的形式一个img标签在任何 Markdown 或 HTML 里都能用零依赖但徽章承载的信息量太有限遇到 Dashboard 和自动化脚本时必须给出结构化数据。2.2 最终选型以徽章为核心保留 API 接口徽章怎么做两条路。一条是调用 shields.io 的动态 badge 接口把 JSON 数据源地址传给 shields.io让它生成图片。优点是省事样式也好看。缺点也明显如果你的服务在内网shields.io 访问不到内网地址这条路直接断了而且多了一层外部依赖数据链路更长。另一条是自研徽章渲染直接用 SVG 模板在服务端拼出状态图。颜色、圆角、字体、左侧标签和右侧状态值都是模板参数生成一张 SVG 只有几 KB浏览器加载极快。我选的是这条因为自研 SVG 在完全离线、内网部署的场景下最可控。2.3 状态机建模从 Pending 到 Failed 的完整流转这个部分最容易被忽略但恰恰是插件的灵魂。CI 构建状态不是简单的“成功/失败”二值而是一个有生命周期的状态机。我参考 Jenkins 和 GitLab CI 的状态定义归一化成了五个状态pending排队中等待执行器。颜色用灰色。running正在构建。颜色用蓝色表示进行中。success构建通过。绿色主色。failure构建失败。红色必须醒目。canceled/skipped手动取消或条件跳过。灰色但与 pending 的灰要做区分否则看板上一片灰分不清。这里有一个关键设计状态流转必须有方向约束。比如success之后如果来了一个pending事件这通常不是正常的“重新构建”而是某个下游平台发来的历史消息乱序到达。我在状态更新层加了一个版本号校验每个构建事件携带build_number和timestamp只有比当前记录更新的数据才允许覆盖。这个设计在后面帮我挡掉了大部分“状态回跳”的问题。3. 服务端实现的核心链路3.1 对接 CI Webhook 与主动拉取的取舍插件要拿到构建状态无非两种方式等 CI 平台推过来或者主动去拉。Webhook 是首选。Jenkins 可以在构建结束后向指定 URL 发送 JSON 负载GitLab CI 也有 Pipeline Events 钩子。我在插件里实现了一个统一的 webhook 接收端点把不同平台的负载解析成内部状态模型。但只靠 webhook 会踩坑。内网环境经常有网络策略问题CI 服务器和插件服务不在同一个网段时webhook 可能根本投递不到。所以我加了一个兜底方案定时拉取器。每个配置了数据源的平台插件会每隔 30 秒主动调用一次 CI 平台的只读 API对比本地最新状态发现有差异就更新。Webhook 负责实时性拉取器负责最终一致性两者叠加才能保证数据不丢。3.2 缓存设计与过期策略徽章图片是高频访问资源。GitHub 的 README 渲染、团队 Dashboard 的多个标签页都会反复请求同一个徽章 URL。如果每次请求都去查 Jenkins API不仅慢还会把 CI 平台的接口打爆。所以我把状态数据放在了一个带 TTL 的缓存层里。缓存键的粒度是关键不能只有项目 ID必须包含分支和流水线上下文。同一个仓库主干分支和 PR 分支的状态截然不同同一个分支release 流水线和 test 流水线的状态也完全不同。我的缓存键设计长这样{platform}:{project_id}:{branch}:{pipeline_name}:{build_number}TTL 我设置为 60 秒。Webhook 到达时会主动失效对应缓存让最新状态立即生效如果 webhook 没到靠定时拉取器 30 秒内也会刷新一遍。这个节奏在我们的使用场景里视觉上基本感觉不到延迟。3.3 徽章图片的即时生成SVG 方案自研 SVG 徽章核心就是一个模板渲染函数。我参考了 shields.io 的视觉风格左侧深色标签显示项目名右侧亮色区域显示状态文本中间用一条白色像素线分隔。下面是一个极简的生成逻辑示例用 Python 的字符串模板实现BADGE_TEMPLATE svg xmlnshttp://www.w3.org/2000/svg width{width} height20 linearGradient idsmooth x20 y2100% stop offset0 stop-color#bbb stop-opacity.1/ stop offset1 stop-opacity.1/ /linearGradient mask idroundrect width{width} height20 rx3 fill#fff//mask g maskurl(#round) rect width{label_width} height20 fill#555/ rect x{label_width} width{value_width} height20 fill{color}/ rect width{width} height20 fillurl(#smooth)/ /g g fill#fff text-anchormiddle font-familyDejaVu Sans,Verdana,Geneva,sans-serif font-size11 text x{label_center} y14{label}/text text x{value_center} y14{value}/text /g /svg里面的关键点是文字宽度要动态计算。中文标签和英文标签的宽度差很多如果固定写死要么文字溢出要么右边空出一大截。我的做法是先算出文本像素宽度再反推整个 SVG 的宽度然后重新布局。这个细节看起来小但实际观感差异极大。3.4 访问控制与内网部署细节嵌入场景里消费端可能是公开的GitHub Pages 上的项目主页也可能是内网系统。权限控制必须分两层考虑。对于公开徽章我推荐在插件前面加一层 CDN 或者直接允许匿名只读。徽章是状态展示不含敏感信息公开反而有利于缓存。比如开源项目在 README 里展示徽章就不该带任何鉴权参数否则访客看到的全是裂图。对于内网 Dashboard 和 JSON API就不能裸奔了。我实现了两种简单的鉴权方式Token 查询参数?tokenxxx适合脚本和 iframe 场景。Header 鉴权适合服务端到服务端调用。需要特别提醒的是不要在 JSON API 里返回 CI 平台的内部 URL 或构建日志路径。这些信息一旦泄露等于把内网入口暴露给了外部。我在响应结构里统一把内部地址剥离只保留状态、构建号、时间戳和提交号。4. 嵌入端接入实操README、Dashboard 与第三方页面4.1 在 README 里放徽章的几种写法接入 README 是最常见的需求但很多人忽略了一个细节Markdown 图片语法会把 URL 中的特殊字符吃掉。如果你的徽章 URL 带分支名而分支名里有/就必须做 URL 编码。推荐写法如果你用的是 GitLab 的 merge request pipeline分支名经常是feature/xxx此时要写成这里%2F是编码后的/不编码的话服务端路由解析会把feature和xxx拆成两个路径段直接 404。还有一个小经验徽章 URL 最好支持在末尾追加?logoxxx之类的参数控制左侧标签方便不同团队统一视觉。但别做得太复杂README 里的徽章核心还是“一眼看出红绿”。4.2 把状态卡嵌入内部 Dashboard内部 Dashboard 我推荐用 iframe 卡片因为可以塞进更丰富的信息项目名、分支、构建号、持续时间、最后提交人。这些都是纯图片徽章表达不了的。接入方式很简单iframe srchttps://build.example.com/card/gitlab/42/main width280 height96 frameborder0 loadinglazy /iframe这里必须确认插件响应头里带了正确的X-Frame-Options或者 CSP 的frame-ancestors。默认情况下现代浏览器会阻止跨域 iframe 嵌入你需要把 Dashboard 的域名加进白名单或者干脆放开frame-ancestors *仅限内网环境。这个坑我后面会细说。卡片内部我做了自刷新前端每 30 秒请求一次 JSON API有变化时用平滑过渡更新界面而不是整页刷新。这个体验比图片徽章好很多尤其在大屏上状态切换有动画提醒团队反应速度明显变快。4.3 通过 API 在自定义系统里消费状态数据如果你不想用我的前端想自己渲染JSON API 就是最灵活的方式。接口返回格式设计如下{ project: gitlab/42, branch: main, pipeline_name: test, status: success, build_number: 1280, commit: a1b2c3d, duration_seconds: 342, updated_at: 2024-06-20T10:30:00Z }消费端只依赖status字段其他字段都是扩展信息。我见过有人直接把duration_seconds拿来算构建耗时趋势也有人把commit和内部缺陷管理系统关联。这就体现了结构化数据的价值status只是一个布尔信号但完整数据可以做更多分析。5. 上线之后踩过的坑缓存、权限与状态时序5.1 徽章缓存导致的状态延迟第一个坑是缓存。我把徽章的Cache-Control设置成max-age300本意是想减轻服务压力结果测试的时候就发现Jenkins 那边已经显示构建失败README 上的徽章还是绿的而且一直绿了五分钟。原因很简单用户看到的不是你的插件而是中间所有缓存层叠加的结果。GitHub 和很多代码托管平台的图片代理会做额外的缓存你的max-age300会被再加一层实际生效时间远超预期。我的解决办法分两步。第一步把Cache-Control改短对徽章图片设置为max-age60, must-revalidate同时输出ETag。第二步在 Dashboard 和检测脚本里在 URL 末尾追加一个构建号参数/badge/gitlab/42/main.svg?build1280这样每次构建号变更URL 就变了所有缓存层视为新资源强制回源。副作用是访问量会增加但对内网服务完全可接受换来的是状态真实可靠。5.2 分支状态与 PR 状态的混淆第二个坑特别容易发生同一时间一个项目的不同分支可能处于完全不同的状态。我刚上线时只按项目维度存状态结果 README 上明明显示绿色点进去看 PR 分支却是红的。团队里立刻出现了“徽章不准”的声音。排查后确认不是缓存问题是建模问题。后来我把状态存储和查询都强制带上 branch 和 pipeline 维度默认查询主干分支的默认流水线。同时在卡片 UI 上明确标注分支名让用户不会误以为这是“整个项目”的状态。这是一个信息呈现层面的教训状态必须带上上下文否则绿和红都没有意义。5.3 并发触发时状态回跳问题第三个坑最隐蔽。某个分支同时触发了两个构建旧的还在跑新的已经排上队。如果 webhook 乱序到达插件可能先收到新构建的pending再收到旧构建的success导致状态从“构建中”跳回“成功”过几秒又跳回“构建中”。在 Dashboard 上看起来就是状态闪来闪去非常影响信任感。我在 2.3 节提到的版本号校验在这里真正派上用场。每个状态记录里保存build_number和started_at更新时做一次判断if incoming.build_number current.build_number: drop_event(stale build event ignored) elif incoming.build_number current.build_number and incoming.timestamp current.timestamp: drop_event(out-of-order update ignored) else: apply_update(incoming)这套逻辑很朴素但效果立竿见影。后来在 GitLab 的 merged result pipeline 场景里也验证了它的价值——那些并发触发的流水线事件数量非常可观没有版本号校验状态几乎必然回跳。5.4 跨域携带凭据的坑最后一个坑是跨域。我们的 Dashboard 放在ops.example.com插件服务在build.example.com前端用fetch请求 JSON API一开始直接失败。浏览器控制台明确提示 CORS 错误可我明明配置了Access-Control-Allow-Origin。问题出在 Token 上。我想省事把 Token 放在了AuthorizationHeader 里但 Dashboard 的前端是纯静态页面没法安全保存 Token。最终我选择对于浏览器场景不做 Header 鉴权改用内网 IP 白名单 Cookie 短会话。服务端只对公网出口 IP 做限制内网用户直接访问不需要携带任何凭据。如果你实在需要在 Header 里带 Token请记住 CORS 预检请求的规则跨域请求带自定义 Header 时浏览器会先发一个OPTIONS请求服务端必须对这个预检请求返回明确的Access-Control-Allow-Headers否则真实请求不会发出。这个细节卡了我半小时写在这里帮大家省时间。6. 进阶玩法状态历史、多项目聚合与通知联动6.1 状态历史曲线与稳定性度量当插件稳定运行一段时间后本地会积累大量的状态变更记录。这些数据的价值远超“当前红绿”可以做很多团队效能分析。我开始做的第一件事是按天统计每个项目的构建成功率和平均恢复时长。成功率好理解就是success次数除以总完成次数恢复时长是失败开始到下一次成功之间的时间差。有了这两个指标周报里的“本周构建质量”就不需要人工填了直接由插件自动生成。实现上我用了 SQLite 做本地存储每次状态变更插入一条记录CREATE TABLE build_events ( id INTEGER PRIMARY KEY AUTOINCREMENT, project_id TEXT NOT NULL, branch TEXT NOT NULL, pipeline TEXT NOT NULL, status TEXT NOT NULL, build_number INTEGER, started_at TIMESTAMP, finished_at TIMESTAMP );查询某个项目最近 7 天的成功率一条 SQL 就够SELECT date(started_at) AS day, COUNT(*) AS total, SUM(CASE WHEN status success THEN 1 ELSE 0 END) AS success_count FROM build_events WHERE project_id ? AND started_at datetime(now, -7 days) GROUP BY date(started_at);6.2 多仓库聚合视图的聚合策略单项目状态只能说明单个服务健康团队更关心的是整体。我接着做了一组聚合视图把多个项目按业务线分组计算“整体通过率”和“当前阻塞数量”。聚合策略有一点要注意不要把不同流水线的状态混在一起算。比如 A 项目的构建失败 3 次B 项目的构建成功 100 次简单算成功率会被 B 稀释。更好的方式是按项目维度先算各自状态再用“最差即整体”的逻辑——只要有一个核心项目失败聚合视图就标记为黄色多个失败则标记为红色。这种“木桶效应”式的聚合逻辑更符合管理层视角他们不关心具体哪个项目失败次数多而是想知道“现在是不是有东西是红的”。6.3 与钉钉、企微、邮件通知的联动状态插件不仅是被动展示也可以主动通知。我在插件里加了一个简单的通知器当状态发生“变化”时触发而不是每次 webhook 到达都触发。这里的“变化”指状态值本身变化比如从success变成failure或者从failure恢复为success。通知文案我做得比较克制只在失败和恢复两个时刻发消息失败时【构建失败】project (main) #1280 pipelinetest提交 a1b2c3d恢复时【构建恢复】project (main) #1281 已通过没有加一堆语气词和表情。团队里消息噪音已经够多了通知的价值是让人注意到状态变化而不是代替人去打开 CI 页面。如果能把失败消息带上失败原因摘要比如编译错误的第一行日志价值会更高。我从 Jenkins API 里取了失败日志的前 200 个字符作为扩展字段团队定位问题快了很多。最后再分享一个实际操作中的体会构建状态插件这类工具技术实现难度真的不高难的是让团队信任它。而信任来自两件事——数据准确展示克制。宁可不展示也不要展示一个经常出错的状态。所以我把缓存策略、版本号校验、聚合逻辑做到位之后整个插件在团队里才真正被当成“可信数据源”日常使用。这个项目到目前的演进方向是加构建耗时趋势图让团队不仅能看出“红没红”还能看出“是不是越来越慢”。如果你也在做类似的状态聚合建议从最简单的 README 徽章切入跑通后再慢慢加能力。