Methexx/Oncallr

# OnCallr — 实时事件与值班管理平台 ## 1. 项目简介 OnCallr 是一个面向工程团队的单团队事件响应与值班管理平台。它可以检测或接收事件，实时立即通知当前值班的工程师，在无人响应时自动升级，跟踪完整的事件时间线，并在事件解决后生成 AI 起草的复盘报告。 它是 PagerDuty 或 Opsgenie 等工具的精简版、作品集级版本——旨在展示实时系统、基于时间的调度逻辑和应用 AI，而不是为了在商业上与这些产品竞争。 ## 2. 问题描述 工程团队需要在生产环境出现故障（例如服务中断、错误率激增、延迟增加）时立即知晓。如果没有结构化的流程： - 告警可能会在 Slack 等聊天工具中被遗漏或淹没 - 不清楚在任何特定时间由谁负责响应 - 如果责任人无法处理，没有任何机制会自动升级 - 险情排除后，没人记录发生过什么，导致相同的事件反复发生 OnCallr 通过清晰的自动化升级 pipeline 以及在每个事件结束时的强制文档记录步骤（复盘报告）解决了这些问题。 ## 3. 目标 ### 主要目标 为单个工程团队提供实时的事件检测、通知和升级，并包含完整的事件历史记录和 AI 辅助复盘报告。 ### 次要目标 - 可视化的值班调度（谁在什么时间值班） - 基于 Webhook 的事件接入（以便外部工具可以触发事件） - 带有评论和审计追踪的事件时间线 - 分析功能：MTTA（平均确认时间）和 MTTR（平均解决时间） - 简洁、快速、可演示的 dashboard UX ### 非目标（在 v1 版本中明确不包含的内容） - 多租户支持（一个平台上存在多个组织） - 真实的外部监控集成（Datadog、Sentry 等）—— 改为通过 webhook endpoint 进行通用模拟 - 短信/电话告警（仅限推送/应用内通知 + 电子邮件） - 移动应用 ## 4. 目标用户 ### 工程师 需求： - 在需要值班时能立即知晓 - 在分配给他们事件时获得即时通知 - 一种简单的方式来确认、调查和解决事件 - 在接手他人的事件时获取上下文（时间线、评论） ### 团队负责人 / Admin 需求： - 能够查看所有服务中所有事件的全貌 - 能够配置值班轮换和升级策略 - 团队响应速度的分析数据（MTTA/MTTR） - 可审查、可编辑的 AI 生成的复盘报告，用于记录归档 ## 5. 核心功能（摘要 —— 详情请参阅 features.md） 1. **服务** —— 被监控的逻辑单元（例如“支付 API”、“认证服务”） 2. **值班调度** —— 将工程师分配到基于时间的轮班中的轮换机制 3. **Webhook 接入** —— 外部系统向每个服务的唯一 URL 发送 POST 请求以创建事件 4. **实时通知** —— Socket.io 将事件告警即时推送到值班工程师的 dashboard 5. **升级引擎** —— 如果在配置的超时时间内未确认，将自动升级给链条中的下一个人 6. **事件时间线** —— 记录每次状态变更、升级和评论的完整审计追踪 7. **AI 复盘报告** —— 事件解决后，根据事件时间线起草结构化的复盘报告；由人工进行编辑和最终确认 8. **分析 Dashboard** —— MTTA、MTTR、按服务统计的事件量、最繁忙的值班时段 ## 6. 角色 | 角色 | 权限 | |---|---| | **工程师** | 查看分配给自己的事件，确认/评论/解决事件，查看自己的轮班，查看自己的复盘报告 | | **Admin** | 包含工程师的所有权限，另外：创建/编辑服务，配置升级策略，创建/编辑调度，查看所有事件，查看分析数据 | 这是一个单团队系统 —— 没有组织/租户边界。所有用户都属于同一个团队。 ## 7. 技术架构 ### 技术栈 | 层级 | 技术 | 原因 | |---|---|---| | 前端 | Next.js 14 + Tailwind + shadcn/ui | 构建快，dashboard UI 整洁，熟悉的技术栈 | | 实时通信 | Socket.io | 成熟，文档齐全，与 Fastify 配合良好 | | 后端 | Fastify (TypeScript) | 轻量级、速度快，在其他项目中已使用过 | | 数据库 | PostgreSQL | 为事件/调度/用户提供关系完整性 | | 任务队列 / 定时器 | Redis + BullMQ | 用于升级定时器的持久化延迟任务 —— 与 `setTimeout` 不同，它能在服务器重启后依然生效 | | AI | OpenAI `gpt-4o-mini` | 根据结构化的事件数据起草复盘报告 | | 认证 | JWT (HTTP-only cookie, web) | 与之前的项目采用相同的模式 | | 邮件（可选后备方案） | Resend | 如果用户没有在查看 dashboard，则提供电子邮件通知 | | 托管 | Vercel (前端) + Railway (后端, Postgres, Redis) | 低成本，简单的部署 pipeline | ### 高层架构 ``` ┌─────────────┐ webhook POST ┌──────────────────┐ │ External │ ─────────────────────────▶ │ Fastify API │ │ Monitor / │ │ (webhook intake) │ │ curl demo │ └─────────┬─────────┘ └─────────────┘ │ ▼ ┌──────────────────┐ │ PostgreSQL │ │ (incidents, etc.) │ └─────────┬─────────┘ │ ┌───────────────────────┼───────────────────────┐ ▼ ▼ ┌──────────────────┐ ┌──────────────────┐ │ Socket.io │ ───── live push ───────▶│ Next.js client │ │ (real-time layer) │ │ (dashboard) │ └──────────────────┘ └──────────────────┘ ▲ │ schedule / cancel ▼ ┌──────────────────┐ │ Redis + BullMQ │ │ (escalation jobs) │ └──────────────────┘ ``` ### 文件夹结构（建议） ``` oncallr/ ├── apps/ │ ├── web/ # Next.js frontend │ │ ├── app/ │ │ ├── components/ │ │ └── lib/ │ └── api/ # Fastify backend │ ├── src/ │ │ ├── routes/ │ │ ├── services/ # business logic (escalation, ai, etc.) │ │ ├── jobs/ # BullMQ job definitions │ │ ├── sockets/ # Socket.io event handlers │ │ ├── db/ # migrations, schema, queries │ │ └── plugins/ ├── packages/ │ └── shared-types/ # shared TS types between web and api └── docs/ ├── 00-master-overview.md └── features.md ``` ## 8. 开发阶段 | 阶段 | 持续时间 | 交付物 | |---|---|---| | 1. 基础建设 | 1 周 | 认证、服务 CRUD、基础 dashboard 布局 | | 2. 调度 | 1.5 周 | 值班轮换、日历视图、“当前谁在值班” | | 3. Webhook + 实时核心 | 1.5 周 | Webhook endpoint、Socket.io 实时通知 | | 4. 升级引擎 | 1.5 周 | BullMQ 延迟任务、升级链条逻辑 | | 5. 事件时间线与评论 | 1 周 | 事件日志、评论、状态转换 | | 6. AI 复盘报告 | 1 周 | 生成、编辑、保存 | | 7. 分析与完善 | 1 周 | MTTA/MTTR 图表、部署、演示完善 | **总计：约 9 周** ## 9. MVP 定义 OnCallr 的 MVP 完成标准如下： - Admin 可以创建服务和值班调度 - 向服务的唯一 URL 发送 Webhook POST 请求可以创建事件 - 当前值班的工程师会收到即时的实时通知 - 如果在配置的超时时间内未确认，事件将自动升级给下一个人 - 工程师可以确认、评论并解决事件 - 已解决的事件可以生成 AI 起草的复盘报告，该报告可以编辑和保存 - Admin 可以查看基础分析数据（MTTA、MTTR、事件量） ## 10. 作品集价值 本项目展示了： - 实时系统设计（Socket.io，实时状态同步） - 持久化的、基于时间的任务调度（Redis/BullMQ —— 而不是原生的 `setTimeout`） - 状态机设计（事件生命周期：触发 → 已确认 → 已解决） - 将 AI 应用于结构化文档生成（而不仅仅是 chatbot 包装器） - 安全防范意识（webhook token 验证、速率限制） - 针对调度和审计追踪数据的关系型数据库设计 - 包含真实工程领域指标（MTTA/MTTR）的 dashboard/分析 UX 本项目的初衷是让它看起来像是一个令人信服的“我了解生产环境事件响应工具是如何运作的”项目，而不仅仅是一个 CRUD 演示。

标签：AI复盘, 值班管理, 告警系统, 搜索引擎查询, 测试用例, 自动化升级, 自动化攻击, 运维