核心用法
Hookaido 提供完整的 webhook 生命周期管理，涵盖接收（ingress）、队列存储（SQLite/Postgres/Memory）、投递（HTTP push/exec 子进程/gRPC pull）三大环节。用户通过声明式 Hookaidofile（HCL 语法）定义路由、认证策略和投递行为，CLI 提供 config fmt/validate 用于配置检查，run 启动服务，mcp serve 启用 AI 操作接口。
典型工作流：
1. 拓扑确认：明确是 inbound+pull、push outbound 还是 exec 模式
2. 配置编辑：最小化修改 Hookaidofile，优先使用 env: 或 file: 引用密钥
3. 验证阶段：hookaido config validate [--strict-secrets] 确保配置合法
4. 运行时启动：SQLite 后端用 --db，Postgres 用 --postgres-dsn
5. 健康检查：GET /healthz?details=1 验证队列状态
6. 端到端测试：模拟 webhook 投递，验证 dequeue/ack/nack/extend 循环
显著优点
- 多协议支持：HTTP pull/gRPC pull/HTTP push/exec 子进程四模态灵活切换
- 企业级安全：内置 GitHub/Gitea/Stripe 兼容 HMAC 签名验证，支持密钥环境变量引用
- 可靠投递：指数退避重试（exponential backoff）、死信队列（DLQ）、批量 ack/nack 提升吞吐
- 模块化存储：SQLite 默认轻量，Postgres 可选用于共享队列场景
- AI 友好：MCP 模式支持只读诊断（
--role read）和受控运维操作（--role operate/admin）
潜在缺点/局限性
- 社区生态较新：相比成熟方案（如 RabbitMQ、AWS EventBridge），周边集成和可视化工具较少
- 配置复杂度：HCL 语法虽强大，但新手需理解
pull_api、ingress、deliver等概念层级 - 子进程模式限制：
sign指令与deliver exec互斥，且退出码语义（126/127=DLQ）需严格遵循 - 无内置 UI：队列监控依赖 HTTP API 或外部工具
适合人群
- 需要自托管 webhook 网关的中小型团队（尤其使用 GitHub/Gitea CI/CD 场景）
- 对投递可靠性有硬性要求（至少一次投递 + 死信队列）的事件驱动架构
- 希望通过声明式配置替代手写胶水代码的 DevOps 工程师
常规风险
- 密钥泄露：配置文件内联密钥会被
--strict-secrets拦截，但人为绕过仍可能发生 - DLQ 堆积：失败消息无自动清理策略，需运维手动 requeue/delete
- Postgres 依赖：生产使用 postgres 后端时，DSN 配置错误或网络分区会导致队列不可用
- 重试风暴：指数退退参数配置不当（如
cap过大）可能延长故障恢复时间
参考
- 上游仓库：github.com/nuetzliches/hookaido
- 版本：v2.2.4（技能锁定 v2.2.2 以保障稳定性）