Clerk 认证集成

通过 Next.js Edge Middleware 保护 Clerk 身份认证路由，彻底阻断 VPN、代理与 Tor 流量。

企业级、零依赖的 Next.js 中间件包装器，原生集成 ProxyTracer 与 Clerk。通过阻断 VPN、代理与 Tor 节点，保护您的身份认证路由免受恶意流量、凭据撞库与未授权访问的侵害，且绝不牺牲边缘网络性能。

功能特性

亚 10 毫秒确定性代理、VPN 和 Tor 节点检测，由 ProxyTracer 提供支持。
与 Clerk 的 clerkMiddleware() 实现无缝零依赖集成。
细粒度路由策略：按路由配置不同的安全防护规则（如针对 /sign-up 严格拦截，针对 /api/* 仅打标记）。
原生 Cloudflare CIDR 校验，有效防御 IP 请求头伪造与绕过行为。
双层缓存系统：内置内存缓存可平抑突发流量，并原生支持全局 Redis 扩展集成。
可配置的容灾降级：在 API 发生超时或网络异常时，灵活切换故障开放（Fail-Open，保障可用性）或故障关闭（Fail-Closed，严格安全）模式。

安装指南


npm install proxytracer-clerk-middleware
# or
yarn add proxytracer-clerk-middleware
pnpm add proxytracer-clerk-middleware

集成实施指南

前置要求

此扩展包依赖 Next.js Edge Middleware。请确保在项目根目录或 src/ 目录下已包含 middleware.ts（或 .js）文件。

基础使用

通过包装 clerkMiddleware() 即可轻松集成 ProxyTracer。默认情况下，这将在 Next.js 中间件配置匹配的所有路由上执行安全检查。


import { clerkMiddleware } from "@clerk/nextjs/server";
import { withProxyTracer } from "proxytracer-clerk-middleware";
 
export default withProxyTracer(clerkMiddleware(), {
  apiKey: process.env.PROXYTRACER_API_KEY || "", // 请勿使用 NEXT_PUBLIC_ 前缀
});
 
export const config = {
  matcher: [
    // 排除 Next.js 内部文件及所有静态资源
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // 始终对 API 和 tRPC 路由执行
    '/(api|trpc)(.*)',
  ],
};

高级配置

对于生产环境，建议针对受保护路由配置精细化防护策略，并显式指定基础设施的反向代理类型。

1. 细粒度路由策略

根据不同路由灵活指定处置动作，兼顾安全防御与用户访问体验。


export default withProxyTracer(clerkMiddleware(), {
  apiKey: process.env.PROXYTRACER_API_KEY || "",
  
  // 定义特定路由的访问策略
  routeRules: [
    { path: "/sign-up", action: "block", fallbackUrl: "/vpn-warning" },
    { path: "/sign-in", action: "allow" }, // 显式允许该路由放行代理访问
  ],
  
  // 未单独匹配的被拦截路由的全局重定向 URL
  fallbackUrl: "/access-denied" 
});

2. 原生基础设施支持

根据基础设施提供商配置 IP 提取规则，安全校验 CIDR 网段，防止请求头被恶意伪造。


export default withProxyTracer(clerkMiddleware(), {
  apiKey: process.env.PROXYTRACER_API_KEY || "",
  trustedProxy: "vercel", // Cloudflare 环境使用 'cloudflare'，Vercel/Nginx 环境使用 'vercel'
});

3. 全局 Redis 缓存（可选）

ProxyTracer 内置针对 Edge 隔离实例的 5 分钟本地内存缓存。如需在全球分布式架构中进一步优化 API 调用频次，可传入自定义 Redis 适配器。


import { Redis } from '@upstash/redis';
 
const redis = Redis.fromEnv();
 
export default withProxyTracer(clerkMiddleware(), {
  apiKey: process.env.PROXYTRACER_API_KEY || "",
  cache: {
    get: async (key) => await redis.get(key),
    set: async (key, isProxy) => await redis.set(key, isProxy, { ex: 86400 }) // 全局缓存 24 小时
  }
});

API 参考

配置项	类型	默认值	说明
`apiKey`	`string`	必填	您的 ProxyTracer API 密钥。
`trustedProxy`	`string`	`'none'`	设置为 'vercel' 或 'cloudflare' 以安全解析 IP 请求头。
`routeRules`	`array`	`undefined`	用于定义细粒度路由策略的对象数组，结构为 { path, action, fallbackUrl }。
`routesToProtect`	`string[]`	`undefined`	已弃用的拦截路径数组（例如：['/sign-up']）。
`fallbackUrl`	`string`	`undefined`	被拦截用户重定向的目标 URL。若缺省，则默认返回 403 文本响应。
`failOpen`	`boolean`	`true`	决定在 API 发生错误或超时时是否放行请求。
`timeoutMs`	`number`	`1000`	等待 API 响应的最长超时时间（毫秒）。
`extractIp`	`function`	`undefined`	用于执行自定义 IP 解析逻辑的回调函数。

架构与安全考量

为在使用 Next.js Edge Middleware 时兼顾极致性能与成本效益，请遵循以下架构准则：

1. Next.js 路由匹配器（关键）

默认情况下，Next.js 会对每个 HTTP 请求执行中间件。若未正确配置匹配器（matcher），将导致对静态资源（如 .png、.css、_next/static）产生不必要的 API 调用。您必须在 middleware.ts 文件底部配置标准的 Next.js 排除规则以跳过静态文件，如基础使用示例所示。

2. Fail-Open 与 Fail-Closed 策略配置

默认情况下，该扩展包启用了 failOpen: true。若 ProxyTracer API 发生超时或网络异常，请求将被允许继续访问。该策略优先保障高可用性与用户体验。对于金融交易、实名认证等极高敏感度端点，强烈建议显式设置 failOpen: false，确保系统在异常时进入严格安全封锁状态。

3. 边缘节点本地缓存特性

内置内存缓存在每个 Edge 隔离实例中保留 IP 分类结果 5 分钟。由于 Vercel、Cloudflare 等平台将请求分发至全球数百个独立边缘节点，该缓存仅在各节点本地生效。它能有效抵御瞬时流量洪峰，但无法实现跨节点全局同步。若需进一步节省 API 额度并实现真正的 24 小时全局缓存，建议接入 Redis 数据库。

安全准则

请务必确保您的 ProxyTracer API 密钥不带有 NEXT_PUBLIC_ 前缀。若包含该前缀，中间件将在启动阶段抛出异常并阻止运行，以防止密钥意外泄露至前端浏览器。
如果您使用 Nginx 反向代理进行部署，必须配置 Nginx 透传 X-Real-IP 或 X-Forwarded-For 请求头。配置完成后，只需在中间件选项中指定 trustedProxy: "vercel"，中间件即可安全合规地解析真实 IP。

开源协议

本项目基于 GNU Affero General Public License v3.0 (AGPLv3) 开源协议发布。详情请参阅 LICENSE 文件。