用途:在项目中集成 Better Auth 的组织(organizations)能力,覆盖成员、邀请、团队与基于角色的访问控制(RBAC)。核心原则是以项目已安装的 Better Auth 版本和当前官方组织文档为契约;若安装版本与文档不一致,应检查本地类型定义。
主要能力:通过 organization 插件启用组织功能,可配置 allowUserToCreateOrganization、organizationLimit 与 membershipLimit。organizationLimit 既可是数值,也可是函数;函数返回用户是否已达到上限,而非返回数值上限。可在服务端调用 auth.api.createOrganization 为其他用户创建组织(需不带 session 头并传 userId;若带 session 头,文档称 userId 被忽略)。成员可直接由服务端添加(auth.api.addMember)。邀请流程需配置 sendInvitationEmail 并调用 inviteMember,可在邮件回调中根据邀请 ID 生成接受 URL,由 acceptInvitation 完成接受。权限检查使用资源到动作对象,如 hasPermission,可支持动态角色;checkRolePermission 仅适用于已配置的静态角色,是同步的客户端便捷方法,不能单独用于服务端数据保护。自定义资源需用 createAccessControl 定义 statement 与角色,并在服务端与客户端插件中传入同一控制器与静态角色。
使用方式:设置激活组织用 setActive,查询成员用 listMembers。数据库迁移方面,新库或为已迁移的 1.7 库添加插件时,使用 CLI 的 auth generate 查看 SQL,内置 Kysely 适配器用 auth migrate;Prisma 和 Drizzle 在 auth generate 后使用各自的迁移工具。CLI 需固定为项目的 Better Auth 版本。注意已发布的 1.7.2 CLI 并未实现官网所述 migrate plan / migrate apply 命令。
限制与安全不变量:不要信任客户端提供的 organizationId,所有服务端操作都必须认证会话并校验该组织的成员与权限。即使 UI 隐藏操作,也必须在服务端强制权限。至少保留一名 owner,转移所有权需显式操作。邀请应视为会过期、绑定被邀地址的一次性凭证。删除组织需确认并考虑依赖数据。应测试跨租户访问、角色变更、过期邀请与最后一名 owner 的行为。高级静态角色、动态组织角色、团队、生命周期钩子与删除控制参见 references/advanced.md;填充过的 1.6 数据迁移细节见 references/better-auth-1-7-migration.md。