核心用法
Hookaido 是一个专注于可靠 Webhook 交付的基础设施组件，采用配置优先（config-first）的工作流。核心操作围绕 Hookaidofile 展开：编辑配置 → 格式化验证 → 启动运行时 → 验证端到端行为。
主要能力模块：
1. Webhook 接收（Ingress）：HTTP 端点接收推送，支持 HMAC 签名验证（GitHub/Gitea/Stripe 等 Provider 兼容模式）
2. 队列后端：SQLite（默认）、内存（开发测试）、Postgres（生产共享存储）
3. 消费模式：
4. Admin API：健康检查、队列积压趋势、死信队列（DLQ）查看与重入/删除操作
5. MCP 模式：AI 操作接口，支持只读诊断（--role read）和受限变更（--role operate/admin）
- Pull API：HTTP 拉取 + 可选 gRPC 工作流监听，支持
dequeue/ack/nack/extend语义及批量确认 - Push 交付：直接 HTTP POST 到下游，需配置指数退避重试策略
- Exec 交付：子进程模式，payload 通过 stdin 传递，退出码控制重试（0=成功，1-125=重试，126/127=死信）
配置验证链：
hookaido config fmt → hookaido config validate [--strict-secrets] → hookaido run
显著优点
- 多后端弹性：SQLite 单节点零依赖，Postgres 支持多实例共享队列，内存模式快速迭代
- Provider 原生兼容：内置 GitHub/Gitea HMAC 签名格式，无需手动解析 header
- 灵活的交付语义：Pull/Push/Exec 三种模式覆盖从微服务到 Serverless 的架构需求
- 可观测性：健康端点带 details、积压趋势、DLQ 管理，支持生产排障
- 供应安全：官方 release 支持 checksum 与 provenance 验证，多平台二进制分发
潜在局限
- Exec 模式限制：不支持
sign指令，需自行处理下游认证；脚本需严格遵守退出码约定 - Provider 模式牺牲安全：启用
provider github/gitea后禁用重放保护（无 timestamp/nonce 校验） - Postgres 运维复杂度：相比 SQLite 需额外管理 DSN、连接池、备份策略
- MCP 权限边界：AI 操作需显式声明角色和变更理由，人机协作流程较重
适合人群
- 需要自建 Webhook 网关的 SRE/DevOps 团队
- 使用 GitHub/Gitea CI 事件驱动内部平台的开发者
- 对交付可靠性有要求（至少一次语义+死信队列）的异步任务系统架构师
常规风险
| 风险点 | 说明 |
|--------|------|
| 密钥泄露 | 强制使用 `env:` 或 `file:` 引用，禁止内联明文；`--strict-secrets` 验证 |
| 无限重试风暴 | Push 模式需显式配置 `retry exponential max` 和 `cap` |
| DLQ 堆积未处理 | 生产环境需配置 DLQ 监控告警和人工/自动重入策略 |
| Exec 模式权限过大 | 子进程继承运行环境，需限制 `deliver exec` 目标路径权限 |
| 队列后端迁移 | SQLite → Postgres 非自动迁移，需规划停机或双写切换 |