管理员与 RBAC | EasyStarter Docs

EasyStarter 已经集成全局 RBAC，默认包含 user 和 admin 两种角色。每个账户只保存一个角色。

配置 RBAC

开启管理功能

修改 packages/app-config/src/app-config.ts 中的 appConfig.common：

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

userManagement.enabled 控制用户管理和管理操作记录。paidUsers.enabled 控制付费用户管理。关闭后，对应页面和 API 会同时停用。

请保持 defaultRole: "user"。如果改成 "admin"，每个新账户都会获得管理权限。

配置初始管理员邮箱

ADMIN_EMAIL 应填写将要登录管理后台的真实账户邮箱：

apps/server/.dev.vars

ADMIN_EMAIL=admin@yourcompany.com

生产环境填写到：

apps/server/.env.production

ADMIN_EMAIL=admin@yourcompany.com

然后上传 Cloudflare Secret：

pnpm -F server secrets:bulk:production

ADMIN_EMAIL 不是发件地址，也不是 supportEmail。它必须与登录账户的已验证邮箱一致。

当前只支持填写一个邮箱，不要使用逗号分隔多个地址。第一个管理员登录后，可以在用户管理页为其他账户分配 admin 角色。

让管理员角色生效

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

如果该用户已经登录过，让其退出后重新登录。Server 会在创建新会话时把该账户的 role 更新为 admin。

默认权限

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

权限字典和角色矩阵位于 packages/app-config/src/rbac/index.ts。

Web 端如何使用 RBAC

Web 侧边栏会同时检查功能开关和当前用户权限。路由也会在 beforeLoad 内再次校验：

beforeLoad: ({ context }) => {
  if (!webConfig.adminUserManagementEnabled) {
    throw notFound();
  }

  if (!hasPermission(context.user.role, "user", "list")) {
    throw redirect({ to: "/forbidden" });
  }
},

前端检查只用于导航和用户体验。服务端仍必须独立检查权限。

import { assertPermission, protectedProcedure } from "@/lib/orpc";

export const adjustCredits = protectedProcedure.handler(async ({ context }) => {
  assertPermission(context, "credits", "adjust");

  // 业务逻辑
});

只需要通用管理权限时，可以直接使用 adminProcedure。它要求当前账户具备 admin:access。

撤销管理员

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