仪表盘

仪表盘插件是您的 Better Auth 实例和 Better Auth 基础设施之间的核心连接。它为网页仪表盘提供实时数据，跟踪用户活动，并启用管理员 API。

仪表盘插件的功能

启用 dash() 后，Better Auth Infrastructure 仪表盘将为您提供：

• 用户管理 — 查看、搜索、封禁和删除用户
• 会话监控 — 查看活跃会话并撤销会话
• 组织概览 — 管理组织和成员
• 分析 — 跟踪注册、登录和活跃用户随时间的变化
• 审计日志 — 查询事件历史记录（了解更多）

安装

import { betterAuth } from "better-auth";
import { dash } from "@better-auth/infra";

export const auth = betterAuth({
  plugins: [
    dash(),
  ],
});

配置选项

DashOptions

活动跟踪

跟踪用户在您的应用中的最后活跃时间。启用后，用户活动时会自动更新 lastActiveAt 字段。

dash({
  apiKey: process.env.BETTER_AUTH_API_KEY,
  activityTracking: {
    enabled: true,
    updateInterval: 300000,  // 更新间隔，单位毫秒（默认：5 分钟）
  },
}),

模式变更

启用活动跟踪时，插件会在您的用户模式中添加一个字段：

user: {
  fields: {
    lastActiveAt: {
      type: "date",
    },
  },
}

npx auth migrate

如果您的应用单独管理模式生成，请运行 npx auth generate，然后使用您首选的工具应用生成的迁移。

托管目录同步

managedDirectorySync 选项是 SCIM 1.7 插件托管运行时流程在仪表盘侧的配套功能。当 enabled 为 true 时，仪表盘会安装托管目录同步状态所需的预留表和 API。ssoPairing 会启用目录关联用户身份与 SSO 提供商配对时所需的 SSO 钩子，而 membershipProjection 则允许系统将 SCIM 成员变更投影到组织成员记录中。

dash({
  apiKey: process.env.BETTER_AUTH_API_KEY,
  managedDirectorySync: {
    enabled: true,
    ssoPairing: true,
    membershipProjection: {
      enabled: true,
      role: "member",
    },
  },
})

此可选控制平面适用于 SCIM 1.7 插件托管运行时流程。在 Better Auth 1.7 中，SCIM 支持三种连接模式：

• 静态代码定义的连接
• 应用自行管理的运行时验证
• 通过 managedConnections 管理的插件运行时连接

managedDirectorySync 选项可在 dash 中启用用于目录同步预配的插件托管模式。它会创建管理目录连接和配对 SSO 状态所需的预留模式和 API。

托管目录同步选项

当应用希望 Better Auth 管理 SCIM 的运行时租户连接生命周期，并将其与基于 SSO 的身份解析配对时，可使用此选项。此选项适用于新的 1.7 流程，并与 scim({ managedConnections }) 配合使用。

npx auth migrate

如果您的应用单独管理模式生成，请运行 npx auth generate，然后使用您首选的工具应用生成的迁移。

数据库模式

当 managedDirectorySync.enabled 为 true 时，dash 插件会添加以下模型。Better Auth 会为每个模型提供主 id 字段。

directorySyncConnection

存储托管目录的组织、SCIM 连接、SSO 配对、生命周期和停用状态。

directorySyncMembershipProvenance

跟踪通过目录同步投影创建或管理的组织成员关系，使插件只能协调其拥有的成员关系。

完整的 SCIM 模型和迁移指南，请参阅 SCIM 插件参考和 1.7 升级指南。

事件跟踪

dash 插件会自动跟踪以下事件：

用户事件

会话事件

账户事件

验证事件

组织事件

如果您使用组织插件，也会跟踪以下事件：

仪表盘端点

dash 插件会为仪表盘注册大量管理端点：

用户管理

会话管理

组织管理

团队管理

邀请管理

SSO 管理

目录同步

日志转发

事件与审计日志

分析

双重验证管理

客户端集成

dashClient()

客户端插件提供访问审计日志查询的功能：

import { createAuthClient } from "better-auth/client";
import { dashClient } from "@better-auth/infra/client";

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

注意：对于 Expo 或 React Native，请从 @better-auth/infra/native 导入 dashClient（API 相同），并将其与 sentinelNativeClient 配合使用，具体请参阅 Sentinel — Expo 和 React Native。

配置

dashClient({
  resolveUserId: ({ userId, user, session }) => {
    return userId || user?.id || session?.user?.id;
  },
}),

获取当前用户的审计日志

返回当前用户的审计事件；如果您以成员身份传入 organizationId，则返回组织范围内的事件。

基本查询

const session = await authClient.getSession();

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

// Access the data
console.log(logs.data?.events);  // Array of audit log events
console.log(logs.data?.total);   // Total count
console.log(logs.data?.limit);   // Page size
console.log(logs.data?.offset);  // Current offset

更多信息请参阅获取当前用户的审计日志。

获取所有审计日志

返回当前用户拥有管理员或所有者访问权限的组织中的所有审计事件。角色检查需要组织插件。

基本查询

const session = await authClient.getSession();

const activity = await authClient.dash.getAllAuditLogs({
  session: session.data,
  limit: 50,
  offset: 0,
});

console.log(activity.data?.events);
console.log(activity.data?.total);

更多信息请参阅获取所有审计日志。

最佳实践

1. 始终设置 API 密钥 — 没有它，插件无法与基础设施 API 通信。

2. 合理使用活动跟踪 — 更新间隔会影响数据库写入频率。对于高流量应用，考虑使用更长的间隔。

3. 监控审计日志保留期限 — 不同套餐的保留周期不同，请检查您的套餐限制。

4. 保护您的端点 — 仪表盘端点需要认证。确保您的仪表盘用户拥有适当权限。