企业官网建设流程全解析

Better Auth Sentinel 插件怎么开启凭据填充、异常位置登录与速率监控防护

【免费下载链接】better-authThe most comprehensive authentication framework项目地址: https://gitcode.com/GitHub_Trending/be/better-auth

当你的登录接口被批量撞库、被异地盗号试探、或被脚本高频刷接口时，Better Auth 的 Infrastructure 服务提供了sentinel()插件来处理这三类攻击。本文的任务很具体：在一个已跑通的 Better Auth 项目中，通过sentinel()插件同时开启三项防护——凭据填充检测（credential stuffing）、异常位置登录检测（impossible travel）、速率限制监控（velocity / rate limiting），并在客户端正确接入 PoW 挑战自动求解，让防护真正生效。

文档中明确的适用前提：

• 已有一个可用的 Better Auth 安装；
• 在 Better Auth Infrastructure 仪表盘注册了账号并创建了项目，拿到了 API Key；
• 当前套餐为pro 或更高，文档明确写着sentinel()插件是 “If you're onproplan or above” 才可用（见 Getting Started）。

准备：安装包并配置 API Key

在项目中安装@better-auth/infra包：

npm install @better-auth/infra

从 Infrastructure 仪表盘拿到 API Key 后，在运行环境中配置BETTER_AUTH_API_KEY环境变量（your_api_key_here替换为你自己的 Key）：

# Required: Your Better Auth Infrastructure API key BETTER_AUTH_API_KEY=your_api_key_here

这个 Key 是服务端插件鉴权的必需项。文档同时说明，sentinel()还支持apiUrl（默认https://dash.better-auth.com）和kvUrl（默认https://kv.better-auth.com）两个地址类选项，仅在需要自定义基础设施地址时才需要传。

服务端：在 betterAuth 配置中开启三项防护

sentinel()的各项安全能力通过security选项开启。对应本文标题的三个防护，分别是credentialStuffing、impossibleTravel和velocity三个配置项，组合成一个完整的服务端配置如下：

import { betterAuth } from "better-auth"; import { sentinel } from "@better-auth/infra"; export const auth = betterAuth({ plugins: [ sentinel({ apiKey: process.env.BETTER_AUTH_API_KEY, security: { // 1. 凭据填充防护：按 visitor 跟踪失败登录 credentialStuffing: { enabled: true, thresholds: { challenge: 3, // 失败 3 次后下发 PoW 挑战 block: 5, // 失败 5 次后直接封禁该 visitor }, windowSeconds: 3600, // 1 小时统计窗口 cooldownSeconds: 900, // 封禁后 15 分钟冷却 }, // 2. 异常位置登录检测：短时间内出现地理上不可能完成的位置跳转 impossibleTravel: { enabled: true, maxSpeedKmh: 1000, // 最大“合理”移动速度 action: "challenge", // "log" | "challenge" | "block" }, // 3. 速率监控：限制各类操作频率 velocity: { enabled: true, thresholds: { challenge: 10, block: 20, }, maxSignupsPerVisitor: 5, maxPasswordResetsPerIp: 10, maxSignInsPerIp: 50, windowSeconds: 3600, action: "challenge", }, }, }), ], });

各配置项的行为依据文档说明：

• 凭据填充（credential stuffing）：按 visitor ID 跟踪失败登录次数；达到challenge阈值后下发 Proof-of-Work 挑战，达到block阈值后完全封禁该 visitor；登录成功时自动清除该 visitor 的失败计数。
• 异常位置登录（impossible travel）：检测极短时间内的远距离登录。文档给出的示例是“先在纽约登录、30 分钟后从东京登录”这类会被标记为 impossible travel 的情况（按配置要求移动速度超过maxSpeedKmh）。
• 速率（velocity）：对注册、密码重置、登录等操作分别设置每 visitor / 每 IP 的上限，超过阈值后执行action指定的动作。action的取值统一为"log"、"challenge"、"block"三种：记录、下发挑战或直接拦截。

如果你只关心其中某一项，删掉另外两个配置块即可，三项之间没有相互依赖。

客户端：接入挑战自动求解

当某项检查的动作是"challenge"时，服务端会下发一个 PoW 挑战，必须由客户端求解后重试请求。这一步不接好，challenge动作对真实用户也会表现为登录失败，所以它是防护生效的必要环节。

Web 客户端使用sentinelClient()：

import { createAuthClient } from "better-auth/client"; import { sentinelClient } from "@better-auth/infra/client"; export const authClient = createAuthClient({ plugins: [ sentinelClient({ autoSolveChallenge: true, }), ], });

autoSolveChallenge默认为true。启用后，客户端会在请求收到带X-PoW-Challenge的挑战时自动求解，并通过X-PoW-Solution头把解发回服务端。同时该客户端插件会自动为请求附加X-Visitor-Id头（浏览器指纹），凭据填充检测的按 visitor 计数依赖这个指纹。

Expo / React Native 客户端是可选分支：改用@better-auth/infra/native的sentinelNativeClient()，并对autoSolveChallenge的行为是——请求返回423且带X-PoW-Challenge时，求解后仅带X-PoW-Solution重试一次。

验证防护是否生效

文档给出两类可核对的验证方式：

1. 检查安全事件。sentinel()会记录以下与本文三个防护直接对应的事件类型：

这些事件显示在 Security dashboard 中，并会进入审计日志。你可以用这些事件类型确认对应的防护项确实被触发过。

2. 按文档的排障清单核对常见故障：

• 如果启动时看到[Sentinel] Missing BETTER_AUTH_API_KEY. Security checks may fall back to allow mode.警告，说明 API Key 环境变量没配好，此时安全检查会退化为放行模式，需要先修环境变量。
• 如果 PoW 挑战不被客户端求解（表现为challenge一直卡住），文档给出的检查顺序是：确认用对了客户端插件（Web 用sentinelClient()，Expo / React Native 用sentinelNativeClient()）→ 确认autoSolveChallenge为true→ 确认客户端能访问到服务端。
• 如果正常用户也被误拦，文档建议：调高 thresholds、把action从"block"改为"challenge"、并回看安全事件找出被误判的模式。

上线建议与限制

文档的 Best Practices 给出了明确的上线节奏，值得直接照做：

1. 先以 log 模式起步——把所有action先设为"log"，观察一段时间的真实流量模式，再切换为拦截；
2. 先挑战、后封禁——"challenge"能让正常用户通过、拦住自动化攻击，比直接"block"更安全；
3. 持续调阈值——文档明确说 “Every application is different”，需要监控误报并相应调整；
4. 客户端始终开启自动求解——Web 端sentinelClient({ autoSolveChallenge: true })，Expo / React Native 端sentinelNativeClient({ autoSolveChallenge: true })。

需要注意的边界：impossibleTravel与velocity的判定基于地理位置、IP 与 visitor 指纹，因此客户端必须正确接入（Web 用sentinelClient、原生端用sentinelNativeClient），否则计数与判定所依赖的标识不完整；sentinel()依赖 Better Auth Infrastructure 的托管服务，且要求 pro 及以上套餐。完整的配置参考与更多安全项（geo-blocking、bot 拦截、泄露密码检测等）见 sentinel 插件文档。

【免费下载链接】better-authThe most comprehensive authentication framework项目地址: https://gitcode.com/GitHub_Trending/be/better-auth