核心用法
gws-gmail-watch 是 gws 工具集的一部分，用于实时监控 Gmail 收件箱变化并通过 Google Cloud Pub/Sub 将新邮件以 NDJSON 格式流式输出。相比轮询 Gmail API，该工具利用 Google 的推送通知机制实现更低延迟、更高效率的邮件同步。
基础启动流程：
1. 确保已通过 gws-shared 完成 OAuth2 认证
2. 指定 GCP 项目 ID（--project）自动创建 Pub/Sub Topic 和 Subscription
3. 或使用现有资源（--topic/--subscription）跳过初始化
4. 可选指定标签过滤（--label-ids INBOX,UNREAD）
5. 流式输出或按文件分批保存（--output-dir）
关键参数组合：
- 一次性同步：
--once配合--max-messages - 生产常驻：
--poll-interval调整拉取频率，注意 7 天过期需重启 - 测试环境：
--cleanup自动清理云资源避免费用残留
显著优点
1. 推送优于拉取：基于 Gmail watch API + Pub/Sub，秒级延迟，远胜传统轮询
2. 云原生架构：天然支持水平扩展，多个 consumer 可共享同一 subscription
3. 灵活输出：支持流式 NDJSON、单文件 JSON 或目录分文件存储，便于下游管道处理
4. 成本可控：--cleanup 一键销毁临时资源，避免 Pub/Sub 持续计费
5. 与 gws 生态集成：复用统一认证体系，无需重复配置 service account
潜在局限与风险
| 问题 | 说明 |
|------|------|
| **7天过期机制** | Gmail watch 授权自动失效，必须设计守护进程或 cron 定期重连 |
| **GCP 依赖** | 必须拥有启用了 Pub/Sub 的 GCP 项目，个人用户门槛较高 |
| **权限复杂度** | 需同时满足 Gmail API + Pub/Sub IAM + 域名验证（部分场景），排错困难 |
| **消息去重** | Pub/Sub 可能投递重复消息，下游需实现幂等处理 |
| **无内置过滤** | 仅支持 Gmail 标签级过滤，无法按发件人/主题细粒度筛选 |
适合人群
- SaaS 集成开发者：构建邮件驱动的自动化工作流（CRM 同步、工单系统）
- 数据工程团队：将邮件流接入 Kafka/Dataflow 等实时管道
- 安全运维人员：监控特定标签的敏感邮件到达事件
- 已有 GCP 基础设施的企业：降低多云复杂度，复用现有 IAM
常规风险提示
- 计费盲区：忘记
--cleanup会导致 Topic/Subscription 持续产生月度费用 - 认证泄露：
gws的 OAuth token 存储在本地，共享环境需加密 - 数据驻留：邮件内容流经 GCP Pub/Sub，需确认合规性（GDPR/等保）
- 流控冲击：默认
--max-messages=10在 burst 场景可能丢消息，需压力测试调整