CellSpec Inbox 容量配置
wesgine 的 CellSpec.InboxCap 控制 Cell 内部消息收件箱的容量上限。
设计目的
Cell 的 Inbox 是接收外部事件的入口：
- IM 渠道消息到达
- Email 接收
- Webhook 回调
- Cron 触发
- API 请求
当 Inbox 满时，新消息被拒绝（背压），防止 Cell 被消息洪流压垮。
配置方式
CellSpec{
InboxCap: 100, // 最大容纳 100 条待处理消息
}
- 默认值由引擎决定
- 0 或未设置使用默认值
- 可通过
SpecPatch运行时修改
Inbox 工作机制
外部事件 → Inbox（有界队列）→ Supervisor 分发 → 处理器
消息入队
- 外部事件到达（IM / Email / Webhook / Cron / API）
- 检查 Inbox 容量
- 未满 → 入队
- 已满 → 拒绝（返回 429 或丢弃，取决于来源）
消息出队
Supervisor goroutine 从 Inbox 取出消息并分发：
- Chat 消息 → Runtime.Run()
- 渠道事件 → Channel adapter
- 定时任务 → Cron executor
- 管理命令 → 对应 Handle
背压行为
| 来源 | Inbox 满时行为 |
|---|---|
| HTTP API 请求 | 429 Too Many Requests |
| IM 渠道消息 | 消息丢弃 + 日志警告 |
| Webhook 回调 | 502 + 期望调用方重试 |
| Cron 触发 | 跳过本次执行 + 记录 |
容量选择建议
| 场景 | 推荐 InboxCap |
|---|---|
| 个人桌面（单用户） | 50-100 |
| 团队部署（多用户） | 200-500 |
| 高流量 IM 渠道 | 500-1000 |
与其他配额的关系
| 配额 | 控制目标 |
|---|---|
InboxCap | 待处理消息队列深度 |
MaxConcurrentRuns | 同时执行的 Run 数量 |
TokensPerMinute | LLM token 消耗速率 |
三者正交，各自独立限制。
监控
Inbox 当前深度可通过 Cell 状态观测：
GET /cells/{id}/state
响应中包含 Inbox 当前使用量和容量。
运行时修改
PATCH /admin/cells/{id}
{
"inbox_cap": 200
}
修改后立即生效，无需重启 Cell。
相关文档
- Inbox 与 EventBus →
inbox-eventbus.md - Cell Supervisor →
cell-supervisor.md - Cell 配额 →
cell-quotas.md