# @better-auth/infra 中文文档

规范地址：https://npmcn.com/package/%40better-auth/infra/

版本：0\.4\.27
npm 元数据更新时间：2026-11-04T19:05:12.820Z
中文译文更新时间：2026-11-07T23:56:56.532Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40better-auth/infra
原文对照：https://npmcn.com/package/%40better-auth/infra/?lang=original
项目主页：https://better-auth.com/
源码仓库：https://github.com/better-auth/infrastructure

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：776 kB，16 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：7 个
- peer 依赖：zod \>=4\.1\.12，better-auth \>=1\.4\.0，expo-crypto \>=13\.0\.0，expo-device \>=6\.0\.0，react-native \>=0\.74\.0，expo-constants \>=16\.0\.0，@better-auth/core \>=1\.4\.0，@react-native-async-storage/async-storage \>=1\.21\.0
- 首次发布：2026-02-18T20:15:08.062Z
- 最新版本发布：2026-11-04T19:05:12.615Z
- 近 30 天下载量：1152266（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：61（近 12 个月 61 个）

## 中文简介

更好的 Auth 的 Dashboard 和分析插件

## 安装

```sh
npm install @better-auth/infra
```

也可以使用：`pnpm add @better-auth/infra`、`yarn add @better-auth/infra`、`bun add @better-auth/infra`

## README

# 更好的 Auth 基础设施

Better Auth 的以下插件 :

-   `dash()` 用于仪表板/admin API,分析跟踪以及后端点.
-   `dashClient()` 用于仪表板客户动作(包括审计日志查询).
-   `sentinel()` 安全检查和虐待保护.
-   `sentinelClient()` 用于浏览器指纹头+可选 PoW 自动解析.
-   `sentinelNativeClient()` (从) `@better-auth/infra/native`)用于回放原生/博览会.

## 安装

```bash
npm install @better-auth/infra
# or
pnpm add @better-auth/infra
# or
bun add @better-auth/infra
```

## 服务器使用

```ts
import { betterAuth } from "better-auth";
import { dash, sentinel } from "@better-auth/infra";

export const auth = betterAuth({
  // ...your Better Auth config
  plugins: [
    dash({
      apiUrl: process.env.BETTER_AUTH_API_URL,
      kvUrl: process.env.BETTER_AUTH_KV_URL,
      apiKey: process.env.BETTER_AUTH_API_KEY,
    }),
    sentinel({
      apiUrl: process.env.BETTER_AUTH_API_URL,
      kvUrl: process.env.BETTER_AUTH_KV_URL,
      apiKey: process.env.BETTER_AUTH_API_KEY,
      security: {
        credentialStuffing: {
          enabled: true,
          thresholds: { challenge: 3, block: 5 },
        },
      },
    }),
  ],
});
```

## 客户端使用

```ts
import { createAuthClient } from "better-auth/client";
import { dashClient, sentinelClient } from "@better-auth/infra/client";

export const authClient = createAuthClient({
  plugins: [
    dashClient(),
    sentinelClient({
      autoSolveChallenge: true,
    }),
  ],
});

// Resolve user from session or pass explicit user/org context
const auditLogs = await authClient.dash.getAuditLogs({
  session: await authClient.getSession().then((r) => r.data),
  organizationId: "org_123",
  limit: 20,
});
```

## 本地客户端

将此插件用于您的 React Introduct / Expo app 。 这个插件设计与服务器侧哨和破折号插件一起工作,并将确保您的应用免受滥用和机器人攻击.

### 安装对等器

```bash
pnpm add react-native @react-native-async-storage/async-storage
# Optional, for richer device metadata in the identify payload:
pnpm add expo-constants expo-device
# Optional, secure visitor-id RNG (Expo):
pnpm add expo-crypto
# Or plain React Native — first import in the app entry:
# import "react-native-get-random-values";
```

`@react-native-async-storage/async-storage` 是可选的;如果未安装,则使用仅会话内访问者编号。 生产,安装或通过 `storage` (例如安全存储).

### 示例

```ts
import { createAuthClient } from "better-auth/client";
import { dashClient, sentinelNativeClient } from "@better-auth/infra/native";

export const authClient = createAuthClient({
  baseURL: "https://your-api.example.com",
  plugins: [
    dashClient(),
    sentinelNativeClient({
      identifyUrl: process.env.EXPO_PUBLIC_BETTER_AUTH_KV_URL,
      autoSolveChallenge: true,
    }),
  ],
});
```

### 选项( E)`sentinelNativeClient`(中文(简体) )

-   `identifyUrl?: string` - 确定终点基准(默认为: `BETTER_AUTH_KV_URL` 那么从洞里 `https://kv.better-auth.com/api/v1`) (中文(简体) ).
-   `identifyOptions?: { timeout?: number; retry?: { attempts?: number; baseDelay?: number; maxDelay?: number } }` — 识别 HTTP 超时( ms, 默认) `1000`)和 POST 重试(默认) `2` 编号 : `400` 编号 : `600`) (中文(简体) ).
-   `kvTimeout?: number` —— 说 **已贬值**,使用时 `identifyOptions.timeout`。 。 。 .
-   `autoSolveChallenge?: boolean` 何时 `true` (违约), `423` 包含有 PoW 挑战头的响应被解决,并用解决方案头重试一次.
-   `sentinelHeaders?: "legacy" | "modern"` —— 说 `"modern"` 用途 `X-Sentinel-*` 协议头而不是遗留名称。 在服务器上匹配 `sentinel()`默认 `"legacy"`。 。 。 .
-   `onChallengeReceived?` 编号 : `onChallengeSolved?` 编号 : `onChallengeFailed?` —— PoW生命周期钩(正因字符串,解出时间以ms为单位,或出错).
-   `storage?: { getItem, setItem }` ——稳定入驻访问者身份标识的Async密钥/值存储(推荐生产).

## 审计日志 APIs

### `dashClient()` API 密码

`dashClient()` 添加:

-   `authClient.dash.getAuditLogs(input)`

`getAuditLogs(input)` 接受:

-   `limit?: number` (默认) `50`最大点 `100`(中文(简体) )
-   `offset?: number` (默认) `0`(中文(简体) )
-   `organizationId?: string`
-   `identifier?: string`
-   `eventType?: string`
-   `userId?: string`
-   `user?: { id?: string | null }`
-   `session?: { user?: { id?: string | null } }`

解析的用户ID按此顺序确定:

-   `input.userId`
-   `dashClient({ resolveUserId })`
-   `input.user?.id`
-   `input.session?.user?.id`

响应形状 :

-   `events: DashAuditLog[]`
-   `total: number`
-   `limit: number`
-   `offset: number`

示例

```ts
const session = await authClient.getSession().then((r) => r.data);

const logs = await authClient.dash.getAuditLogs({
  session,
  organizationId: "org_123",
  limit: 50,
  offset: 0,
});
```

要获取所有事件, 请继续使用 `offset` 直至 `events.length < limit`。 。 。 .

### 过滤

使用 `getAuditLogs` 直接在查询中过滤 :

-   `eventType`: 只返回特定事件类型(例如) `user_signed_in`(中文(简体) )
-   `organizationId`:一个组织的范围记录
-   `identifier`: 组织日志为特定标识符
-   `userId` 编号 : `user` 编号 : `session`: 确定哪些用户的日志应被限定范围

实例:

```ts
// 1) Filter by event type
const signIns = await authClient.dash.getAuditLogs({
  session,
  eventType: "user_signed_in",
  limit: 20,
});

// 2) Filter by org + identifier
const orgMemberEvents = await authClient.dash.getAuditLogs({
  session,
  organizationId: "org_123",
  identifier: "user@example.com",
  limit: 50,
});

// 3) Combine filters
const orgSignIns = await authClient.dash.getAuditLogs({
  session,
  organizationId: "org_123",
  eventType: "user_signed_in",
  limit: 50,
});
```

### 搜索模式

`getAuditLogs` 目前不显示专用全文 `search` 查询参数. 用于文本搜索、获取页面和过滤客户端.

```ts
const matchesText = (event: { eventType: string; eventKey: string; eventData: Record<string, unknown> }, query: string) => {
  const q = query.toLowerCase().trim();
  if (!q) return true;

  const haystack = [
    event.eventType,
    event.eventKey,
    JSON.stringify(event.eventData ?? {}),
  ]
    .join(" ")
    .toLowerCase();

  return haystack.includes(q);
};

const page = await authClient.dash.getAuditLogs({ session, limit: 100, offset: 0 });
const filtered = page.data?.events.filter((event) => matchesText(event, "password")) ?? [];
```

您可以对以下对象应用相同的模式:

-   日期范围过滤( 按 `createdAt`(中文(简体) )
-   位置过滤( 按 `location.country`, (中文(简体) ), `location.city`页:1
-   多场大院过滤器

### 植入辅助器

```ts
async function getAllAuditLogs(session: unknown) {
  const limit = 100;
  let offset = 0;
  const all: Array<{
    eventType: string;
    createdAt: string;
    eventData: Record<string, unknown>;
  }> = [];

  while (true) {
    const result = await authClient.dash.getAuditLogs({ session, limit, offset });
    const events = result.data?.events ?? [];
    all.push(...events);

    if (events.length < limit) break;
    offset += limit;
  }

  return all;
}
```

### `dash()` 事件终点

这个 `dash()` 插件注册这些事件终点 :

-   `getUserEvents` 打开 `GET /events/list`
-   `getAuditLogs` 打开 `GET /events/audit-logs`
-   `getEventTypes` 打开 `GET /events/types`

`getAuditLogs` 支持查询参数 :

-   `limit`, (中文(简体) ), `offset`, (中文(简体) ), `eventType`
-   `organizationId`, (中文(简体) ), `identifier`
-   `userId` (必须匹配经认证的会话用户)

## 选项类型

### `DashOptions`

-   `apiUrl?: string`
-   `kvUrl?: string`
-   `apiKey?: string`
-   `apiOptions?: { timeout?: number }` (毫秒,默认值) `3000`(中文(简体) )
-   `kvOptions?: { timeout?: number; retry?: { attempts?: number; baseDelay?: number; maxDelay?: number } }` —— KV 超时默认 `1000`; 重试默认值 `2` 编号 : `400` 编号 : `600`
-   `apiTimeout?: number` —— 说 **已贬值**,使用时 `apiOptions.timeout`
-   `kvTimeout?: number` —— 说 **已贬值**,使用时 `kvOptions.timeout`
-   `activityTracking?: { enabled?: boolean; updateInterval?: number }`
-   `managedDirectorySync?: { enabled?: boolean; ssoPairing?: boolean; membershipProjection?: { enabled?: boolean; role?: string }; fieldProjection?: { enabled?: boolean } }` ——选择1.7+所管理的目录-同步控制平面(schema + 保留 API). `enabled` 单靠保留表/API。 启用时, 破折号 `init` 也可以用线接接接接接接接接接接接接接接接接接接 `ssoPairing` 安装 SSO `resolveUser` 编号 : `guardProviderMutation` (仅需要配对目录;需要) `sso({})` 或更丰富的选择——裸露 `sso()` 叶子 `options` 未定义),以及 `membershipProjection` 安装 SCIM `projection.reconcileUser` 为org会员同步. `fieldProjection` (默认) `false`)是一个单独的选入:当启用时,每个连接仪表板映射项目会管理SCIM用户属性(和可选默认)到更好的Auth用户/成员附加字段——启用后迁移. 默认 : `enabled: false`, (中文(简体) ), `ssoPairing: true`, (中文(简体) ), `membershipProjection.enabled: true`, (中文(简体) ), `membershipProjection.role: "member"`, (中文(简体) ), `fieldProjection.enabled: false`。必须使用 `scim({ managedConnections })` 对管理模式; 不影响或替换遗留的 SCIM 目录预-1.7 同步.

`dash()` 不再接受监控安全配置.

### `SentinelOptions`

-   `apiUrl?: string`
-   `kvUrl?: string`
-   `apiKey?: string`
-   `apiOptions?: { timeout?: number }` - 与 `DashOptions`
-   `kvOptions?: { timeout?: number; retry?: { attempts?: number; baseDelay?: number; maxDelay?: number } }` - 与 `DashOptions`
-   `apiTimeout?: number` —— 说 **已贬值**,使用时 `apiOptions.timeout`
-   `kvTimeout?: number` —— 说 **已贬值**,使用时 `kvOptions.timeout`
-   `sentinelHeaders?: "legacy" | "modern"` —— 说 `"modern"` 用途 `X-Sentinel-*` 协议头而不是遗留名称。 匹配客户端。 默认 `"legacy"`。服务器前的客户端升级.
-   `security?: SecurityOptions`

现在所有安全配置都属于 `sentinel()`。 。 。 .

### `DashClientOptions`

-   `resolveUserId?: ({ userId, user, session }) => string | undefined`

见 `Audit Log APIs` 详细方法.

### `SentinelNativeClientOptions`

从 `@better-auth/infra/native`。见 [反应本地客户端](https://npmcn.com/package/%40better-auth/infra/#readme-native-client) 用于完整选项列表和使用.

## 移徙

如果您先前通过安全配置到 `dash()`移动到 `sentinel()`数字 :

```ts
// before
dash({
  apiKey: process.env.BETTER_AUTH_API_KEY,
  // no longer supported in dash
  security: {
    credentialStuffing: { enabled: true },
  },
});

// after
dash({ apiKey: process.env.BETTER_AUTH_API_KEY });
sentinel({
  apiKey: process.env.BETTER_AUTH_API_KEY,
  security: {
    credentialStuffing: { enabled: true },
  },
});
```

## 安全说明

-   使用 `sentinel()` 执行安全检查. `dash()` 重点是遥测/admin行为.
-   提供 `BETTER_AUTH_API_KEY`;没有它,哨兵就不能安全地呼叫后方API,并在启动时警告.
-   如果您在代理/CDN之后运行, 请验证您的上游头信任模式( C) :`x-forwarded-for`等)来避免被spoofed客户端IP归属.
-   可选 `sentinelHeaders: "modern"` (服务器+客户端) `X-Sentinel-*` 协议信头如此的代理重写 `X-Request-Id` 不打破识别。 先升级客户端. 启用时, 允许/ 暴露精确的 `X-Sentinel-*` cORS 中的页眉名称( 不是通配符) .

## 常见问题

### @better-auth/infra 是什么？

更好的 Auth 的 Dashboard 和分析插件

### 如何安装 @better-auth/infra？

在项目目录运行 npm install @better-auth/infra，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（\>=4\.1\.12）、better-auth（\>=1\.4\.0）、@better-auth/core（\>=1\.4\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @better-auth/infra 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @better-auth/infra 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @better-auth/infra 可以商用吗？

@better-auth/infra 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @better-auth/infra 的下载量有多少？

根据 npm 官方下载统计，@better-auth/infra 在 2026/10/08 – 2026/11/06 这 30 天内被下载 1,152,266 次，日均约 38,409 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @better-auth/infra 还在维护吗？

最新版本 0\.4\.27 发布于 2026/11/05（3 天前）；至今共发布 61 个版本，其中过去 12 个月发布了 61 个；首次发布于 2026/02/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。