cnb.cool 云原生构建状态蜂巢监控面板

实时监控 cnb.cool 平台上多个仓库的 CI/CD 构建状态，以蜂巢（Honeycomb）网格形式直观呈现每个仓库最新一次构建的结果。

---

本项目是一个轻量级的构建状态监控面板，面向使用 cnb.cool 云原生构建服务的团队。它通过蜂巢状六边形网格展示所有仓库的最新构建状态，让开发者一眼就能掌握哪些仓库构建成功、哪些正在运行、哪些已经失败。

前端基于 React 18 + Vite 7 构建，使用 @antv/g6 图可视化引擎渲染蜂巢布局；后端使用纯 Node.js 原生 HTTP 服务器（无框架依赖），负责代理 CNB API 请求并提供服务端缓存与限流。

• 每个仓库以一个六边形单元格展示，颜色直观标识构建状态：
  • 🟢 绿色 — 构建成功
  • 🔴 红色 — 构建失败
  • 🟠 橙色 — 运行中 / 排队中
  • ⚪ 灰色 — 状态未知
• 六边形支持 悬停查看 和 点击固定 Tooltip，展示详细信息：任务名称、分支、提交 SHA、触发人、开始时间、耗时等
• 蜂巢网格支持 拖拽 和 缩放 交互

页面顶部四张指标卡片实时汇总：

卡片	说明
仓库数	监控的仓库总数
运行中任务	当前处于 running/queued 状态的构建数
已成功的任务	最新一次构建状态为 success 的仓库数
已失败的任务	最新一次构建状态为 failed 的仓库数

• 每 30 秒 自动从服务端拉取最新构建数据
• 支持 立即刷新 按钮手动触发
• 声音提醒：开启后，检测到新失败构建播放低频提示音，新成功构建播放高频提示音
• 声音开关状态持久化到 localStorage

首次启动时若缺少 CNB_TOKEN 配置，页面会弹出配置引导遮罩层，提示用户在 .env 文件中填入必要的参数。

• API 代理：前端通过 /api/builds 获取数据，服务端代理请求 CNB API，避免跨域和 Token 暴露
• 内存缓存：10 秒 TTL 缓存，防止高频请求打满上游 API
• 并发控制：最多 5 个并发请求拉取不同仓库的构建日志
• 速率限制：每个 IP 在 10 秒内最多 30 次 API 请求
• 安全头：CSP、HSTS、X-Frame-Options 等安全响应头
• 路径穿越防护：静态文件服务阻止 ../ 等路径穿越攻击
• 优雅关停：监听 SIGTERM/SIGINT，5 秒超时强制退出

• Node.js >= 18
• yarn（或 npm）

git clone <your-repo-url>
cd cnb-ci-cellular-map

yarn install

在项目根目录创建 .env 文件：

# 必填：CNB 访问令牌（需要 account-engage:r 和 repo-cnb-trigger:r 权限）
CNB_TOKEN=<YOUR_CNB_TOKEN>

# 可选：CNB API 地址，默认 https://api.cnb.cool
CNB_API_URL=https://api.cnb.cool

# 可选：手动指定监控的仓库列表（逗号分隔），不配置则自动发现
CNB_REPOS=owner/repo-a,owner/repo-b

# 可选：自动发现仓库时的最大数量，默认 20
CNB_REPO_LIMIT=20

# 可选：API 请求超时（毫秒），默认 8000
CNB_TIMEOUT_MS=8000

权限说明：调用 /user/repos 接口需要令牌包含 account-engage:r 权限；调用构建日志接口需要 repo-cnb-trigger:r 权限。若令牌权限不足，可在 CNB_REPOS 中手动指定仓库列表以跳过自动发现。

# 构建前端资源
yarn build

# 启动生产服务（默认端口 3000）
yarn start

# 或指定端口
PORT=8080 yarn start

yarn dev

开发模式会同时启动：

• Vite 开发服务器（端口 3000）：负责前端 HMR 热更新
• Node API 服务（端口 3001）：负责代理 CNB API 请求

前端请求 /api/* 和 /healthz 会自动代理到 3001 端口。

1. 访问面板：启动服务后，浏览器打开 http://localhost:3000
2. 查看构建状态：蜂巢网格中每个六边形代表一个仓库，颜色表示最新构建状态
3. 查看详情：
   • 悬停 六边形可临时查看构建详情 Tooltip
   • 点击 六边形可固定 Tooltip（点击页面空白处取消固定）
   • Tooltip 中点击「打开构建日志」可跳转到 CNB 平台查看完整日志
4. 刷新数据：点击「立即刷新」按钮或等待 30 秒自动刷新
5. 声音提醒：点击「开启声音」/「关闭声音」按钮切换声音通知

接口	方法	说明
/api/builds	GET	获取所有仓库最新构建数据
/healthz	GET	健康检查，返回 { ok: true }

HTTP 状态码	error 字段	说明
428	cnb_config_required	缺少 CNB_TOKEN 配置，响应体包含 missingKeys
429	too_many_requests	请求过于频繁，触发速率限制
502	cnb_api_forbidden	CNB API 鉴权失败
502	cnb_api_error	CNB API 请求失败

类别	技术
前端框架	React 18
构建工具	Vite 7
图可视化	@antv/g6 v5 + @antv/g6-extension-react
后端	Node.js 原生 HTTP 服务器
语言	JavaScript (ESM)

├── server.js                  # 生产服务器（静态文件 + API 代理）
├── scripts/
│   └── dev.js                 # 开发模式启动脚本
├── src/
│   ├── main.jsx               # 应用入口
│   ├── App.jsx                # 主应用组件
│   ├── cnbClient.js           # CNB API 客户端（仓库发现、构建数据拉取、缓存）
│   ├── loadEnv.js             # .env 文件加载器
│   ├── constants.js           # 常量定义（刷新间隔、蜂巢尺寸等）
│   ├── styles.css             # 全局样式
│   ├── components/
│   │   ├── HoneycombGraph.jsx # 蜂巢图组件（G6 图实例管理）
│   │   ├── HoneycombNode.jsx  # 蜂巢六边形单元格组件
│   │   ├── BuildTooltip.jsx   # 构建详情浮动提示
│   │   ├── ConfigOverlay.jsx  # 配置引导遮罩层
│   │   └── ErrorBoundary.jsx  # React 错误边界
│   └── utils/
│       ├── audio.js           # Web Audio 声音提醒
│       ├── buildUtils.js      # 构建数据汇总与去重
│       ├── format.js          # 时间/状态/仓库名格式化
│       └── honeycomb.js       # 蜂巢网格布局计算
├── public/
│   └── cnb-logo.svg           # CNB 品牌 Logo
├── index.html                 # HTML 入口
└── vite.config.js             # Vite 配置（含开发代理）

MIT License