核心功能与架构
Hookaido 是一个以配置优先（config-first）的 webhook 消息队列网关，主要用于解决 webhook 接收、持久化、消费与投递的全链路管理。其核心能力包括：
1. 入站与拉取消费（Ingress + Pull）
- 支持 HTTP 入站接收 webhook，并提供 HTTP Pull API（
:9443）与可选的 gRPC Pull Worker 监听（:9943） - 消费者通过
dequeue/ack/nack/extend语义可靠消费消息 - 配置示例采用 HCL 格式，支持路由级认证（HMAC/Token）与环境变量注入
2. 推送投递（Push Delivery）
- 当目标服务可被主动连接时，支持直接推送投递
- 内置指数退避重试策略（exponential backoff），需显式配置超时与最大重试次数
- 设计为 at-least-once 语义，要求下游具备幂等处理能力
3. MCP 工作流与运行时控制
- 支持 Model Context Protocol（MCP）模式，可用于 AI 辅助诊断
- 角色分级：
read（只读诊断）、operate（允许变更）、admin（运行时控制） - 所有变更操作需提供
reason字段，满足审计要求
4. 队列运维与死信队列（DLQ）
- 提供
/healthz?details=1、/backlog/trends、/dlq等运维端点 - 支持死信消息的重新入队（requeue）与删除，要求操作者明确说明理由与回滚方案
显著优点
- 配置即代码：HCL 配置支持
fmt与validate，变更可 review、可回滚 - 多协议支持：同时支持 HTTP/gRPC 拉取，适应不同语言栈的消费者
- 安全默认：强制认证（HMAC/Token），禁止明文存储密钥，不支持 "disable auth"
- AI 原生运维：MCP 模式让 LLM 能安全地参与诊断与受限变更
潜在局限与风险
- at-least-once 语义：消息可能重复投递，下游必须实现幂等
- 依赖本地 SQLite：默认使用
./.data/hookaido.db，高可用场景需评估存储后端 - 版本锁定：当前 skill 锁定 v1.5.0，需关注上游更新与安全补丁
- gRPC 可选：gRPC pull 需显式开启，未启用时仅 HTTP 可用
适用人群
- 需要可靠接收第三方 webhook（GitHub、Stripe 等）的 SRE/DevOps 工程师
- 希望用统一网关解耦 webhook 生产与消费团队的架构师
- 需要 AI 辅助队列诊断与变更的运维团队
安全评估
| 维度 | 评级 | 说明 |
|------|------|------|
| 传输安全 | S | 支持 TLS，密钥通过 env/file 引用，无明文硬编码 |
| 认证授权 | S | 强制 HMAC/Token，不支持禁用认证 |
| 变更安全 | A | MCP 模式分级授权，要求 `reason` 审计日志 |
| 数据持久化 | B | 默认 SQLite，生产环境建议外置存储 |
常规风险：
- 配置变更未 validate 直接运行可能导致服务启动失败
- DLQ 批量 requeue 可能影响队列水位，需评估下游消费能力
- MCP
--enable-mutations若过度授权，可能扩大 AI 误操作影响面