App 管理员与 RBAC | EasyStarter Docs

EasyStarter App 与 Web 共享同一套全局 RBAC。服务端在用户记录中保存 user 或 admin 角色，App 根据会话中的角色显示管理入口。

配置 App 管理功能

开启共享功能开关

修改 packages/app-config/src/app-config.ts：

common: {
  admin: {
    // 开启付费用户管理
    paidUsers: {
      enabled: true,
    },
    // 开启用户管理和管理操作记录
    userManagement: {
      enabled: true,
    },
  },
  auth: {
    // 其他认证配置……
    rbac: {
      defaultRole: "user",
      adminRoles: ["admin"],
    },
  },
}

apps/native/configs/app-config.ts 会读取这些共享值，并暴露 adminUserManagementEnabled 和 adminPaidUsersEnabled。

请保持 defaultRole: "user"，避免所有新账户默认成为管理员。

在 Server 配置初始管理员

本地开发：

apps/server/.dev.vars

ADMIN_EMAIL=admin@yourcompany.com

生产环境：

apps/server/.env.production

ADMIN_EMAIL=admin@yourcompany.com

推送生产 Secret：

pnpm -F server secrets:bulk:production

ADMIN_EMAIL 是服务端秘密，不要把它写入 apps/native/.env* 或任何 EXPO_PUBLIC_* 变量。

它应填写已验证的真实账户邮箱，而不是发件地址或 supportEmail。当前只支持一个邮箱。

在 App 中激活管理员

配置 ADMIN_EMAIL 后，重新部署 Server 即可。

如果该用户已经在 App 中登录过，让其退出后重新登录。新会话会带上 admin 角色，个人中心随后显示管理入口。

App 中的管理入口

apps/native/app/(tabs)/(profile)/index.tsx 会同时检查登录状态、功能开关和权限：

const canManageUsers =
  isAuthenticated &&
  appConfig.adminUserManagementEnabled &&
  hasPermission(user?.role, "user", "list");

const canViewPaidUsers =
  isAuthenticated &&
  appConfig.adminPaidUsersEnabled &&
  hasPermission(user?.role, "admin", "access");

当前 App 管理区域包含：

用户管理
付费用户管理
积分调整与 Membership 试用赠送
管理操作记录

保护 App 管理页面

不要只隐藏个人中心里的菜单。管理路由布局还应检查 admin:access：

if (!isAuthenticated) {
  return <Redirect href="/(auth)/sign-in" />;
}

if (!hasPermission(user?.role, "admin", "access")) {
  return <Redirect href="/(tabs)/(profile)" />;
}

return <Slot />;

单个功能的 _layout.tsx 可以使用 AdminFeatureStack 检查功能开关：

<AdminFeatureStack enabled={appConfig.adminUserManagementEnabled}>
  <Stack.Screen name="index" />
</AdminFeatureStack>

这些 App 检查只负责导航与页面显示。所有读取用户、修改角色、封禁、积分和 Membership 操作都必须由服务端 oRPC 再次校验权限。

默认权限

权限	App 中的用途
`admin:access`	进入管理区域
`user:list`	查看用户
`user:set-role`	修改用户角色
`user:ban`	封禁和解封用户
`credits:adjust`	调整积分
`membership:grant-trial`	赠送 Membership 试用
`operation:list`	查看管理操作记录

普通 user 不拥有上述管理权限，admin 拥有全部默认管理权限。

撤销管理员

删除或更换 ADMIN_EMAIL 不会自动撤销旧管理员。请先通过用户管理把旧管理员改回 user，再更换服务端环境变量。

角色改变后，让该用户在 App 中退出并重新登录，以刷新本地会话和管理入口。