可观测性后端前端运维【免费下载链接】kenerStunning status pages, batteries included!项目地址https://gitcode.com/gh_mirrors/ke/kener点击查看免费下载Kener 内置了三种可直接以img引入的状态徽章Badgestatus实时状态徽章、dot圆点指示徽章与uptime可用率徽章。本文围绕 Kener 官方文档中的徽章语法逐一讲解每类徽章的 URL 结构、全部查询参数label、sinceLast、color、style等的取值与默认值并结合 GetBadge 控制器实现 与 各徽章路由/badge/[tag]/status/server.ts) 的源码说明徽章颜色如何跟随站点主题、时间窗口如何解析、以及找不到 monitor 时的兜底行为帮助你把这些徽章嵌进 README、文档站或监控面板中。徽章总览与 URL 语法Kener 的徽章统一挂载在/badge/[tag]/type路径下[tag]为 monitor 的唯一标识。文档中定义了三类徽章http://[hostname]/badge/[tag]/status http://[hostname]/badge/[tag]/dot http://[hostname]/badge/[tag]/uptime从源码结构看这三类路径分别对应三个 SvelteKit 路由status 路由/badge/[tag]/status/server.ts)读取label、labelColor、color、style、locale五个查询参数后调用统一的GetBadge(status, …)uptime 路由/badge/[tag]/uptime/server.ts)额外接收sinceLast与hideDuration参数dot 路由/badge/[tag]/dot/server.ts)不走GetBadge而是直接返回一段内联生成的 SVG 圆点支持animate与fillColor参数。三类徽章最终都以Content-Type: image/svgxml响应status/uptime由 badge-maker 库的makeBadge(format)渲染成 SVG。当[tag]对应的 monitor 不存在、或不是 ACTIVE 且未被隐藏状态时GetBadge会直接返回一张内置的错误 SVGErrorSvg而不是 404因此在 README 中引用徽章不会因为 monitor 被删除而“裂图”只会显示一张错误占位图。补充仓库中还额外实现了 latency 徽章路由/badge/[tag]/latency/server.ts)/badge/[tag]/latency支持metricaverage|maximum|minimum参数展示延迟指标参数体系与 uptime 徽章一致可作为 uptime 徽章的延伸阅读。Status 徽章展示最近一次健康检查结果status徽章显示 monitor 最近一次健康检查的结果取值来自UP/DOWN/DEGRADED等状态。在 HTML 与 Markdown 中的用法img srchttps://kener.ing/badge/earth/status /自定义标签label不设置label时徽章左侧标签默认取monitor 名称源码中name m.name见 GetBadge 单 monitor 分支。可以通过label查询参数覆盖label参数在 GetBadge 末尾统一处理let label: string params.label || name;即用户显式传入的标签优先级最高。状态值的国际化locale 参数status徽章支持locale查询参数status 路由/badge/[tag]/status/server.ts) 会把query.get(locale)透传给GetBadge。在 控制器中状态文案Operational / Degraded / Down / Under Maintenance / No Status Available会按指定语言翻译后再渲染进徽章该语言代码必须命中站点已启用的 i18n 语言列表否则回退到站点默认语言。也就是说中文站点的徽章可以原生显示本地化状态文字。状态色如何确定若未显式传入colorstatus徽章的色值来自站点级颜色配置site data 中的colors键内置默认值为见 状态色映射状态默认颜色UP#00dfa2DEGRADED#e6ca61DOWN#ca3038MAINTENANCE#6679ccNO_DATA#9ca3af这意味着徽章颜色会自动跟随你在 Kener 管理后台配置的主题色无需在徽章 URL 里硬编码。Dot 徽章SVG 圆点指示器dot徽章把最近一次健康检查结果显示为一个纯色圆点适合嵌入表格、日志行等只需要“一颗状态灯”的场景http://[hostname]/badge/[tag]/dot #or http://[hostname]/badge/[tag]/dot?animatepingStandard 静态圆点img srchttps://kener.ing/badge/earth/dot /dot 路由的源码/badge/[tag]/dot/server.ts#L31-L36) 会先通过GetLastMonitoringValue(tag, () GetLatestMonitoringData(tag))取最近一次监控记录带缓存再用 StatusColor 拿到站点状态色映射生成一个 32×32 的 SVGsvg width32 height32 xmlnshttp://www.w3.org/2000/svg circle cx16 cy16 r8 fill${fillColor} / /svg圆点颜色默认跟随状态UP/DEGRADED/DOWN 等默认值与 status 徽章一致也可以通过fillColor查询参数强制指定任意颜色。Animated 呼吸动效加上animateping参数后SVG 中会多出一个从半径 8 扩散到 16、透明度从 0.5 渐隐到 0 的animate动画层每秒循环一次形成类似“心跳/声呐”的脉冲效果见 动画 SVG 模板/badge/[tag]/dot/server.ts#L37-L57)img srchttps://kener.ing/badge/earth/dot?animateping /全站聚合状态tag 为_的特例从 dot 路由源码/badge/[tag]/dot/server.ts#L12-L14) 可以看到一个未写入文档的实现细节当[tag]为_时不走单个 monitor 查询而是调用GetLatestStatusActiveAll()取所有 ACTIVE monitor 的综合状态。GetBadge内部对tag _有同样的处理标签取站点名siteName兜底文案为 “All Monitors”见 聚合分支 与 uptime/latency 聚合分支。也就是说http://[hostname]/badge/_/status这类 URL 可以把“整站当前状态”做成一个徽章。Uptime 徽章按时间窗口计算可用率uptime徽章默认展示90 天可用率。可以通过sinceLast查询参数单位秒改为“最近 x 秒”的可用率。90 天可用率img srchttps://kener.ing/badge/earth/uptime /自定义时间窗口sinceLastimg srchttps://kener.ing/badge/earth/uptime?sinceLast900 /sinceLast的解析规则在 uptime/latency 分支中当参数缺失、非数字、或小于 60 秒时一律回退到默认的 90 天90 * 24 * 60 * 60秒。因此该参数存在一个 60 秒的下限sinceLast30与不传参数等效。计算过程为以当前分钟整点GetMinuteStartNowTimestampUTC()为基准向前推sinceLast秒调用db.getStatusCountsByInterval(tag, since, now, 1)按分钟聚合状态计数再交给UptimeCalculator计算百分比单个 monitor 还支持通过monitor_settings_json中的uptime_formula_numerator/uptime_formula_denominator自定义分子分母例如排除 MAINTENANCE 不计入分母默认公式为up maintenance degraded/up down degraded maintenance见 GC 默认公式。自定义标签label与 status 徽章相同不传label时默认显示monitor 名称。隐藏时间窗口后缀hideDuration徽章标签默认会在 monitor 名称后追加一个时间窗口后缀如90d、15m该后缀由 formatDuration 生成优先按天/小时/分钟取最粗粒度。设置hideDurationtrue即可隐藏它对应源码见 标签拼接处name name (hideDuration ? :${formatted});。自定义徽章外观颜色与风格labelColor、color、style三组外观参数只对status和uptime徽章生效dot 徽章有自己的fillColor/animate参数latency 徽章与 uptime 相同。它们最终汇入 badge-maker 的format对象const format { label, message, color: badgeColor, // 值区背景色默认 #0079FFstatus 徽章默认取状态色 labelColor: params.labelColor || #333, // 标签文字色默认 #333 style: getBadgeStyle(params.style ?? null), }; const svg makeBadge(format);见 徽章渲染收尾自定义标签颜色labelColor自定义值区颜色color注意color优先级高于状态色一旦传入UP/DOWN 等语义颜色将被覆盖源码中if (!params.color)才应用状态色映射。同时设置两种颜色徽章风格style通过style参数切换徽章视觉风格默认是flat。支持的风格在 BADGE_STYLES 常量 中定义为五种非法取值会被 getBadgeStyle 静默回退为flatstyle 取值说明示例flat默认带圆角的扁平风格?styleflatplastic带渐变光影的立体风格?styleplasticflat-square无圆角扁平风格?styleflat-squarefor-the-badge整体加宽加大的风格?stylefor-the-badgesocial适合社交头像区的风格?stylesocial参数速查表综合文档与源码三类徽章支持的查询参数如下参数statusdotuptime默认值 / 说明label✅—✅monitor 名称tag_时为站点名labelColor✅—✅#333color✅—✅状态色如#00dfa2/#0079FFstyle✅—✅flat仅接受五种预设值locale✅——站点默认语言须为已启用语言animate—✅—传ping启用呼吸动效fillColor—✅—状态色sinceLast——✅秒下限 60默认 90 天hideDuration——✅传true隐藏时长后缀小结把徽章用到 README 里的注意事项徽章是纯 SVG 图片端点任何支持img的地方GitHub/Gitee README、Notion、文档站均可直接嵌入无需 API Keystatus徽章展示的是最近一次检查结果uptime徽章才是时间窗口统计两者不要混用monitor 不存在时徽章会渲染成错误占位图而非报错可用于“灰度”地引用尚未创建的 monitor若希望徽章颜色与站点主题保持一致不要传color让它走站点颜色配置sinceLast最小生效值为 60 秒想展示“最近 15 分钟可用率”应写sinceLast900。核心实现集中在 GetBadge风格与状态常量见 global-constants.ts状态色映射见 color.ts三个端点路由分别位于src/routes/(kener)/badge/[tag]/下的status、dot、uptime及未写入文档的latency目录便于进一步深入。赞分享可观测性后端前端运维【免费下载链接】kenerStunning status pages, batteries included!项目地址https://gitcode.com/gh_mirrors/ke/kener点击查看免费下载相关推荐Read the Docs 文档状态徽章Status Badges完整指南URL 语法、样式与源码实现Read the Docs 文档状态徽章Status Badges完整指南URL 语法、样式与源码实现 本文以 readthedocs.org 开源项目官后端文档Woodpecker 状态徽章Status Badges使用指南端点、查询参数与源码级原理Woodpecker 状态徽章Status Badges使用指南端点、查询参数与源码级原理 Woodpecker CI/CD 引擎内置了对仓库状态徽章SCI/CDDevOpsWoodpecker 仓库状态徽章Status Badges完全指南端点、参数与 SVG 渲染原理Woodpecker 仓库状态徽章Status Badges完全指南端点、参数与 SVG 渲染原理 Woodpecker 内置了仓库状态徽章StatusCI/CDDevOps上一篇NW.js常见问题解答10个开发中典型问题和解决方案全解析下一篇【限时专享】装备库升级让Stable-Fast-3D如虎添翼的五大生态工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考