Pipelines 常见陷阱

# Pipelines 常见问题与注意事项 ## 关键问题 ### 事件被静默丢弃 **最常见的问题。** 事件被接受（HTTP 200）但从未出现在接收器中。 **原因：** 1. Schema 验证失败 - 结构化流会静默丢弃无效事件 2. 等待滚动间隔（10-300秒） - 预期行为 **解决方案：** 使用 Zod 在客户端进行验证： typescript const EventSchema = z.object({ user_id: z.string(), amount: z.number() }); try { const validated = EventSchema.parse(rawEvent); await env.STREAM.send([validated]); } catch (e) { /* 获取即时反馈 */ } ### 管道是不可变的 创建后无法修改 SQL。必须删除并重新创建。 bash npx wrangler pipelines delete old-pipeline npx wrangler pipelines create new-pipeline --sql "..." **提示：** 使用版本命名（`events-pipeline-v1`）并将 SQL 保存在版本控制中。 ### 找不到 Worker 绑定 **`env.STREAM is undefined`** 1. 在 `wrangler.jsonc` 中使用 **流 ID**（而非管道 ID） 2. 添加绑定后重新部署 bash npx wrangler pipelines streams list # 获取流 ID npx wrangler deploy ## 常见错误 | 错误 | 原因 | 修复 | |-------|-------|-----| | R2 中无事件 | 未达到滚动间隔 | 等待 10-300秒，检查 `roll_interval` | | Schema 验证失败 | 类型不匹配，缺少字段 | 在客户端进行验证 | | 速率限制 (429) | 每个流 >5 MB/s | 批量发送事件，请求增加配额 | | 有效载荷过大 (413) | 请求 >1 MB | 拆分为更小的批次 | | 无法删除流 | 管道引用了它 | 先删除管道 | | 接收器凭据错误 | 令牌过期 | 使用新凭据重新创建接收器 | ## 限制（公开测试版） | 资源 | 限制 | |----------|-------| | 每个账户的流/接收器/管道数 | 各 20 个 | | 有效载荷大小 | 1 MB | | 每个流的摄取速率 | 5 MB/s | | 事件保留期 | 24 小时 | | 建议批处理大小 | 100 个事件 | ## SQL 限制 - **无 JOIN** - 每个管道仅支持单个流 - **无窗口函数** - 仅支持基础 SQL - **无子查询** - 必须使用 `INSERT INTO ... SELECT ... FROM` - **无模式演进** - 创建后无法修改 ## 调试清单 - [ ] 流已存在: `npx wrangler pipelines streams list` - [ ] 管道状态健康: `npx wrangler pipelines get ` - [ ] SQL 语法符合 Schema - [ ] 添加绑定后已重新部署 Worker - [ ] 已等待滚动间隔 - [ ] 已接受与已处理计数匹配（无验证丢弃）