基于 Cloudflare Agents 构建 GitHub Webhook 实时监控面板（examples/github-webhook 全解析）

基于 Cloudflare Agents 构建 GitHub Webhook 实时监控面板（examples/github-webhook 全解析）

【免费下载链接】agentsBuild and deploy AI Agents on Cloudflare项目地址: https://gitcode.com/GitHub_Trending/agents1/agents

本指南以仓库中 examples/github-webhook/README.md 为骨架，完整拆解这个基于 Cloudflare Agents 构建的 GitHub 仓库实时活动监控示例。你将掌握如何接收并校验 GitHub Webhook、按仓库隔离 Agent 实例、用 SQLite 持久化事件，并通过 WebSocket 把更新实时推送到浏览器端——最终落地一个可直接运行的暗色主题实时监控面板。

项目定位与核心特性

examples/github-webhook是一个真实可运行的前后端一体化示例：GitHub 每次仓库活动（push、PR、issue、star、fork、release 等）都会以 Webhook POST 的形式送达 Worker，Worker 将事件路由给对应仓库专属的RepoAgent（Durable Object），Agent 完成签名校验、事件落库、状态更新与广播，浏览器端通过 WebSocket 订阅并渲染实时事件流。README 中明确列出的核心特性如下：

• Webhook Handling——接收并处理 GitHub Webhook；
• Signature Verification——对 Webhook 载荷做 HMAC-SHA256 签名校验，防止伪造请求；
• Agent-per-Repository——每个仓库拥有独立的、相互隔离的 Agent 实例；
• Real-time Updates——通过 WebSocket 连接将事件到达实时推送给浏览器；
• Event History——事件持久化到 SQLite，支持历史回溯；
• Beautiful Dashboard——暗色主题 + 实时事件流的 React 仪表盘。

快速启动：本地跑通整个监控链路

1. 安装依赖

npm install

2. 配置 Webhook 密钥

仓库提供了 .env.example 模板，复制并编辑：

cp .env.example .env

编辑.env：

GITHUB_WEBHOOK_SECRET=your-secret-here

该密钥是签名校验的基石：GitHub 用它计算X-Hub-Signature-256头，Worker 侧用同一个值重算比对。需要注意的是，密钥只会在未配置时跳过校验（见下文源码解析），生产环境务必通过wrangler secret put设置。

3. 启动开发服务器

npm start

脚本在 package.json 中定义为vite dev，由 vite.config.ts 同时加载agents/vite与@cloudflare/vite-plugin两个插件，实现本地 Worker 运行时与前端 HMR 一体化。

4. 暴露本地服务（用于联调）

GitHub 需要能访问到你的 Webhook 端点，使用 ngrok 之类工具将本地 5173 端口暴露到公网：

ngrok http 5173

复制 ngrok 分配的公网地址（例如https://abc123.ngrok.io）。

5. 在 GitHub 上配置 Webhook

1. 进入目标仓库 →Settings→Webhooks；
2. 点击Add webhook；
3. 按下表配置：

4. 点击Add webhook完成创建。

6. 连接仓库并查看事件

浏览器打开http://localhost:5173，输入仓库名（如cloudflare/agents），点击 Connect。前端会先通过GET /api/agent-name?repo=...拿到规范化后的 Agent 名，再以该名字建立 WebSocket 连接（对应 client.tsx 中handleConnect的逻辑），随后即可看到实时事件流与 Stars / Forks / Open Issues 统计条。

工作原理：从 GitHub 到浏览器的事件全链路

架构图

GitHub → POST /webhooks/github/owner/repo → Worker → RepoAgent (Durable Object) ↓ Browser ← WebSocket ← Agent broadcasts state updates ←─────┘

数据流分三段：GitHub 将事件 POST 到 Worker；Worker 按仓库路由到对应RepoAgent；Agent 更新状态后，经由 WebSocket 把状态与事件广播给所有已连接的浏览器客户端。

1. Webhook 路由：按仓库定位 Agent 实例

server.ts 中 Worker 的fetch入口首先识别/webhooks/github/:owner/:repo路径，然后从载荷中取出repository.full_name，将其规范化为 Agent 名并通过getAgentByName拿到对应 Durable Object stub，最后把原始请求转发过去：

const agentName = sanitizeRepoName(payload.repository.full_name); const agent = await getAgentByName(env.RepoAgent, agentName); return agent.fetch(request);

其中sanitizeRepoName将形如Cloudflare/Agents的完整仓库名统一小写、把/替换为-并剔除非法字符，从而映射为合法且确定的 Agent 实例名：

function sanitizeRepoName(fullName: string): string { return fullName .toLowerCase() .replace(/\//g, "-") .replace(/[^a-z0-9-]/g, ""); }

补充实现细节：getAgentByName定义于 packages/agents/src/agent-routing.ts，其核心是通过namespace.idFromName(name)基于名称生成稳定 ID，get得到 stub 后调用__unsafe_ensureInitialized确保 Agent 完成生命周期启动，再返回可供 RPC/fetch 的 stub——这就是"每个仓库一个持久 Agent 实例"的底层保障。

除 Webhook 端点外，fetch还暴露GET /api/agent-name?repo=owner/repo供前端查询规范化后的 Agent 名；其余请求（如 WebSocket 升级）则交给routeAgentRequest（见 packages/agents/src/agent-routing.ts）做默认的 Agent 路由，未命中返回 404。

2. 签名校验：用 HMAC-SHA256 甄别真实请求

RepoAgent.onRequest中，若配置了GITHUB_WEBHOOK_SECRET，则对原始请求体（注意是request.text()原文，而非解析后的 JSON）计算 HMAC-SHA256 并与X-Hub-Signature-256头做常数时间语义比较：

const key = await crypto.subtle.importKey( "raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"] ); const signatureBytes = await crypto.subtle.sign( "HMAC", key, encoder.encode(payload) ); const expectedSignature = `sha256=${Array.from(new Uint8Array(signatureBytes)) .map((b) => b.toString(16).padStart(2, "0")) .join("")}`; return signature === expectedSignature;

校验失败返回401 Invalid signature；同时端点只接受 POST（否则 405），缺少X-GitHub-Event头返回 400。这构成了完整的 Webhook 入口防护。

3. SQLite 持久化：事件表结构与索引

RepoAgent.onStart中初始化事件表与时间索引：

this.sql` CREATE TABLE IF NOT EXISTS events ( id TEXT PRIMARY KEY, type TEXT NOT NULL, action TEXT, title TEXT NOT NULL, description TEXT, url TEXT, actor_login TEXT, actor_avatar TEXT, timestamp TEXT NOT NULL ) `; this.sql` CREATE INDEX IF NOT EXISTS idx_events_timestamp ON events(timestamp DESC) `;

每次事件到达时以INSERT OR REPLACE写入，并顺手清理旧数据只保留最近 100 条：

this.sql` INSERT OR REPLACE INTO events (id, type, action, title, description, url, actor_login, actor_avatar, timestamp) VALUES (...) `; this.sql` DELETE FROM events WHERE id NOT IN ( SELECT id FROM events ORDER BY timestamp DESC LIMIT 100 ) `;

说明：示例默认只保留最近 100 条事件，避免 SQLite 无限膨胀；如需更长留存，可调整该LIMIT。

4. 实时广播：Agent 状态 + 可调用方法

Agent 维护RepoState（仓库全名、stars/forks/openIssues 统计、lastUpdated、webhookConfigured）。Webhook 到达时通过setState更新内存状态，浏览器端通过 WebSocket 收到状态更新；同时 Agent 通过@callable()装饰器暴露三个 RPC 方法供客户端调用：

• getEvents(limit = 20)——按时间倒序查询最近 N 条事件；
• getStats()——返回当前统计；
• clearEvents()——清空事件表。

前端在onOpen与每 10 秒的轮询中调用agent.call("getEvents", [50])刷新列表（见 client.tsx），实现"推送 + 兜底轮询"的双保险。

支持的事件类型

Agent 的createEvent按X-GitHub-Event头分发解析，README 整理的事件类型及语义如下：

除上述外，github-types.ts 的GitHubEventType还声明了watch、create、delete三种事件类型，但createEvent目前未为其生成展示条目，属于类型先行、行为留白的扩展点。各类型在存储时会生成统一的StoredEvent结构（type、action、title、description、url、actor、timestamp），前端据此渲染统一的 EventCard 样式与配色。

生产部署

pnpm run deploy

对应脚本为pnpm run build && wrangler deploy。部署完成后还需两步：

1. 在 Cloudflare 侧设置密钥（通过命令行交互式输入）：

   wrangler secret put GITHUB_WEBHOOK_SECRET

2. 将 GitHub Webhook 的Payload URL更新为已部署 Worker 的地址：https://your-worker.example.workers.dev/webhooks/github/owner/repo。

部署相关的 Durable Object 绑定与 SQLite 迁移都定义在 wrangler.jsonc 中：

{ "durable_objects": { "bindings": [{ "class_name": "RepoAgent", "name": "RepoAgent" }] }, "migrations": [{ "new_sqlite_classes": ["RepoAgent"], "tag": "v1" }], "compatibility_flags": ["nodejs_compat"] }

其中new_sqlite_classes迁移声明了RepoAgent使用 Durable Object 内置 SQLite 存储，nodejs_compat兼容标志则为crypto.subtle等 Web Crypto 能力提供运行时支持。环境类型声明在 env.d.ts，包含GITHUB_WEBHOOK_SECRET与RepoAgent两个绑定。

扩展方向

README 给出了基于本示例的增强思路：

• AI PR Summaries——接入 OpenAI 等模型自动总结 PR diff；
• Slack Notifications——把关键事件转发到 Slack 频道；
• Multi-Repo Dashboard——在一个面板中聚合监控所有仓库；
• Custom Alerts——为长期未合并的 PR 定时提醒；
• Webhook Replay——重放历史事件以便回归测试。

结合本仓库的 Agent 能力（@callable()RPC、SQLite 持久化、WebSocket 广播），这些扩展大多只需在processWebhook的switch分支或createEvent返回后追加业务逻辑即可落地。

项目结构

examples/github-webhook/ ├── src/ │ ├── server.ts # RepoAgent + webhook routing │ ├── client.tsx # React dashboard │ ├── github-types.ts # TypeScript types for GitHub payloads │ └── styles.css # Dashboard styles ├── public/ │ └── normalize.css ├── index.html ├── wrangler.jsonc └── package.json

关键文件与仓库根路径对应关系：

• Agent 实现与路由入口：examples/github-webhook/src/server.ts
• React 实时仪表盘：examples/github-webhook/src/client.tsx
• GitHub 载荷类型定义：examples/github-webhook/src/github-types.ts
• Worker 配置与迁移：examples/github-webhook/wrangler.jsonc
• 依赖与脚本：examples/github-webhook/package.json
• 密钥模板：examples/github-webhook/.env.example

小结

examples/github-webhook完整演示了 Cloudflare Agents 的四个关键模式：按业务实体命名并隔离 Agent 实例、在 Agent 内校验外部 Webhook 签名、用 Durable Object 内置 SQLite 持久化事件、通过 WebSocket 广播 Agent 状态实现实时推送。从本地 ngrok 联调到wrangler deploy上云，一条命令与一个密钥即可把真实仓库的每一次活动实时投递到浏览器，是理解 Agent 路由、@callable()RPC 与 SQLite 持久化的极佳入门样板。

【免费下载链接】agentsBuild and deploy AI Agents on Cloudflare项目地址: https://gitcode.com/GitHub_Trending/agents1/agents