Marico's space

为何我为多租户 Apify Actor 选择纯 refresh-token OAuth

编程技术 2026-05-16 18:05:40 13

最近在搞一个 Gmail 邮件分析 Actor，第一个真正需要做的决策不是报告格式，而是授权模型。在多租户场景下，OAuth 不再只是一个安全问题，它直接决定了产品的使用门槛。

最终我选了纯 refresh-token（刷新令牌）模式，而不是每次调用都跑完整的 3-legged flow（三-legged OAuth 授权码模式）。这里面的 reasoning（考量）挺实际，没什么花哨的。

Actor 大多通过定时任务或非交互式 pipeline（管道）运行。如果每次执行都需要人工重新授权，那自动化就退化成了纯手工操作。这个决策看似小，但会悄悄吃掉整个工具的价值。

可以把这个模型看作单位经济问题：每个额外的交互式授权步骤，都是对未来每次运行的税。采用 refresh-token 模式，用户只需授权一次，之后工作流就能自由运行。

一个自然的捷径是"让平台来管理"——把用户凭证集中在服务端，用户再也不需要操心。我故意没有选这条路。

这里处理的数据类别（邮件内容）天生敏感。我不希望产品设计上要求用户"先信任我再说"。我倾向于一个可验证的模型：显式用户授权、可控权限范围、可撤销令牌、可恢复的错误处理。任何需要用户超出可审计范围去扩展信任的设计，都是埋在未来的雷。

还有一个不那么 obvious（显而易见）的原因：refresh-token-only 在多租户场景下运行良好，因为故障模式会收敛。

常见错误会归结为少量、明确的类型：

而不是一堆 callback/session/浏览器状态相关的混乱问题。作为 maintainer（维护者），这种可观测性对我来说比一个"看起来更标准"的流程重要得多。生产环境 debugging（调试）基本上由最差的几个故障场景主导，把这些场景弄得清晰可见，值回很多代价。

取最小可用数据，而不是最大可用数据。功能可以慢慢加。授权边界第一天就应该清晰。一旦拿了太多数据，再往回收几乎总是痛苦的——而且用户感知到的会是"降级"而不是"修复"。

这是一个小的思维模式差异，但会复合放大。每个新功能决策都应该从"最小可用权限范围是多少？"出发，而不是"什么权限范围能解锁最多选项？"出发。

如果你在做多租户自动化，这三个问题值得先想清楚：

答案不同，很多设计选择都会重新排序。对于我的 Actor——定时任务、多租户、敏感权限范围——refresh-token-only 不是最花哨的选择。但它匹配 Actor 实际运行的方式：可定时、可维护、可解释。

纯 refresh-token 不是什么巧妙的模式，是很无聊的模式。但授权代码就应该无聊，因为有意思的代码应该活在认证边界下游，而不是边界内部。