SafeW如何为Serverless函数开启按请求限频的API密钥？
功能定位：为什么要在 SafeW 里做“按请求限频”
Serverless 的“弹性”常被误用成“无上限”。当函数被前端、小程序或第三方同时调用，瞬时并发可能把月度免费额度秒光，甚至触发链上防火墙的异常告警。SafeW 在 2026-02 版推出的“API 密钥级限频”把频率控制下放到单密钥维度，让同一条函数可以面向不同调用方提供差异化配额，既防滥用也避免“一刀切”误伤正常用户。
与云厂商的“函数级限流”相比，SafeW 方案把密钥、链上身份、税率模块一并绑定，适合需要同时解决“谁在用、用多少、要不要扣税”的 Web3 场景；代价是多了一步密钥签发，且限频窗口固定 1 秒粒度，无法像 AWS API Gateway 那样自定义毫秒精度。
前置条件与角色清单
1. 钱包所有者：需持有 SafeWallet v6.4.2 及以上版本，已开启“链上防火墙”开关（设置→安全→链上防火墙→启用）。
2. 函数部署者：已在 SafeW 控制台创建 Serverless 函数，且函数运行时选择“Node.js 20.x”或“Python 3.11”，旧运行时暂不支持密钥注入。
3. 调用方：至少一个外部系统，能携带 HTTP Header x-api-key 访问函数 URL。
决策树：先选“函数级”还是“密钥级”限频
提示：若你的函数只服务单一前端，且域名固定，直接用云厂商的函数级限流即可；当同一条函数需要给“白名单 DApp”“社区机器人”“空投脚本”三组不同配额时，再走 SafeW 密钥级方案。
控制台操作路径（桌面端最短）
- 登录 console.safew.com → 左上角网络切换至所需 EVM 链（如 Arbitrum）。
- 侧边栏选择 Serverless→函数管理，点击目标函数名称进入详情页。
- 顶部标签切换到 API 密钥 → 右侧蓝色按钮 新建密钥。
- 在弹窗里填写“调用方名称”“QPS 上限”（整数，≤100）、“日累计上限”（0=不限制）、“是否计入空投税”（默认关）。
- 点击 生成并签名，此时桌面端会唤起 SafeWallet 插件，要求确认一笔“添加访问凭证”链上交易；确认后约 10 秒，页面自动刷新，即可看到密钥明文（仅展示一次）。
移动端路径差异：App 暂不支持直接签发密钥，需用“扫码→插件签名→返回 App”完成接力；iOS 19.4 以下若遇 NFC 签名失败，可临时关闭 NFC 改用 USB-C 有线连接。
把密钥注入函数运行时
SafeW 会在每次冷启动时把密钥白名单注入环境变量 SAFEW_API_KEYS，格式为 JSON 数组。示例代码（Node.js）：
const allowList = JSON.parse(process.env.SAFEW_API_KEYS || '[]');
const clientKey = req.headers['x-api-key'];
if (!allowList.includes(clientKey)) {
return res.status(401).json({error: 'Invalid key'});
}
限频逻辑由 SafeW 边缘网关统一处理，函数内只需做密钥存在性校验即可，无需再写计数器，减少冷启动耗时。
验证限频是否生效
1. 用 curl 连续发送 120 次请求，QPS 设为 100，期望最后 20 次返回 429。
2. 观察响应头 x-safew-rate-limit：剩余配额、重置倒计时均在此返回。
3. 若日累计上限非 0，可在次日凌晨 00:00 UTC 后看到计数器归零（经验性观察：实际重置时间可能前后漂移 30 秒）。
常见失败分支与回退
- 链上交易卡 pending：Arbitrum 网络拥堵时，建议把 gas 价提高 10% 再签名；若 5 分钟未上链，控制台会提示“创建失败”，此时可废弃该密钥 ID 重新走流程，不会产生费用。
- 误把测试密钥发到生产：立即在控制台“停用”密钥，停用动作 0 手续费且实时生效；已泄露的字符串无法再次启用，只能新建。
- 空投税模块误扣：若密钥勾选了“计入空投税”，但调用方只是内部机器人，可在“设置→空投税→白名单地址”把机器人地址加入，系统会在次日 03:00 UTC 自动回退税额。
与第三方机器人协同的最小权限原则
经验性观察：社区最常见的是把“第三方归档机器人”加入通知频道，同时让它调用函数写库。此时应单独给机器人签发“QPS=1、日累计=1000”的只读密钥，并在函数内把机器人地址写死在 req.headers['x-forwarded-for'] 校验层，防止密钥被转卖后滥用。
不适用场景清单
| 场景特征 | 原因 |
|---|---|
| 需要毫秒级突发精控 | SafeW 窗口固定 1 秒，无法细化到 10ms |
| 函数运行时 < v6.4 | 旧运行时无环境变量注入，需整体迁移 |
| 完全匿名开放 API | 密钥级限频必须携带 x-api-key，与匿名矛盾 |
最佳实践 5 条速查表
- 同一业务线用同一密钥，方便日累计统一扣税。
- QPS 先给 20% 冗余，上线 24h 后看
x-safew-rate-limit峰值再收紧。 - 密钥名称加上“日期+业务”后缀，方便 30 天后滚动回收。
- 不要把密钥写进前端常量，统一走后端转发，避免 CORS 暴露。
- 每次重大促销前 24h 新建临时密钥，促销结束立即停用，防止遗忘。
FAQ（结构化数据）
密钥丢失还能找回吗？
不能。SafeW 只在创建时展示一次明文，丢失后只能停用旧密钥并新建。
日累计上限统计的是请求数还是调用费用？
统计的是 HTTP 请求次数，与链上 gas 费用无关。
可以动态修改 QPS 吗？
目前必须停用旧密钥、新建密钥，暂不支持热更。
收尾：下一步行动建议
如果你已经走到这里，建议立刻在测试函数上新建一条“QPS=5、日累计=100”的密钥，用 curl 跑一轮 200 次请求，亲眼看一次 429 响应——这比任何文档都直观。验证通过后，再把生产密钥换上，并给团队共享一份“密钥滚动日历”，30 天回收一次，既安全也不给未来自己埋坑。