运行管理后台

创建第一个管理员、完成上线检查清单、熟悉侧边栏,并在 /admin 中管理插件、调整缓存和查看审计日志。

/admin 管理后台是运营人员管理产品的地方。安装完成后先按本指南操作一遍,之后调整缓存或查看审计日志时再回来查阅。

准备工作

  • 已完成迁移的数据库(pnpm db:migrate)。
  • 一台能连上该数据库的机器上的终端。
  • 第一个管理员要使用的邮箱和密码。

创建第一个管理员

在有用户具备 admin.access 权限之前,没有人能打开 /admin,而授权又必须在后台里完成。初始化脚本从命令行创建第一个管理员。

把管理员写入 .env

.env
SUPER_ADMIN_EMAIL=you@example.com
SUPER_ADMIN_PASSWORD=at-least-8-characters
SUPER_ADMIN_NAME="Super Admin"

SUPER_ADMIN_EMAIL 和 SUPER_ADMIN_PASSWORD 必填。密码至少 8 位,仅在新建账号时使用。SUPER_ADMIN_NAME 可选,默认 Super Admin。

运行初始化脚本

pnpm db:bootstrap-super-admin

脚本会新建该邮箱的账号并标记为已验证;如果账号已存在,则直接提升为管理员,不修改原密码。随后它把访问状态设为 Active,写入模板自带的全部权限,全部授予 Super Admin 角色并分配给该账号。脚本还会写入基础邮件模板、营销页面和频率限制规则。

删除密码并登录

从 .env 中删除 SUPER_ADMIN_PASSWORD,这些变量只有该脚本读取。在 /auth/sign-in 登录并打开 /admin。

升级或安装模块后如果新增了权限,再运行一次脚本,让 Super Admin 角色获得新权限。

完成上线检查清单

打开设置

在工作台侧边栏点击 设置(/setup)。该页面每次加载都读取实时配置。

处理每个未就绪的条目

每个条目都列出缺少的配置,并提供 去配置 按钮跳转到对应页面。

必需项是 会话密钥、登录方式、邮件投递 和 定时任务;支付供应商、对象存储、AI 渠道、订阅供应商(安装 Newsletter 模块时)和 分析供应商 为可选。所有必需项就绪后,徽标显示 必需项已齐备。

有两个必需项不在后台中配置。会话密钥 是环境变量 BETTER_AUTH_SECRET,因为它在读取数据库之前就要用到,见管理配置。定时任务 反映每分钟一轮的后台任务是否在运行。它没有 去配置 按钮,提示信息会指出该检查部署平台上的哪个开关。见排查项目问题。

熟悉侧边栏

侧边栏按分组组织,用户没有某个入口所需的权限时,该入口不会显示。

分组入口
概览工作台(/admin)、用户、国家统计
运营角色、权限、工单
商业化套餐(/admin/plans)、订单、订阅
平台AI Tasks、对话、API Keys、限流配置、资源
内容CMS、Waitlist 和推广合作,随各自的模块出现
安全Webhooks、审计
设置认证、支付、存储、AI、分析和邮件配置,邮件、通知、插件(/admin/plugins),以及随 agent 模块出现的沙箱配置、搜索配置和图片 Agent

套餐 用来创建 /pricing 列出、结账时实际收费的定价套餐。查看需要 plans.read,保存需要 plans.write。见定价套餐。

启用或停用插件

  1. 打开 设置 → 插件(/admin/plugins,需要 config.read)。页面列出这份构建里安装的所有插件及其贡献的内容。
  2. 使用模块所在行的开关;保存需要 config.write。内置的 foundation 插件始终启用。

停用后,插件在后台的入口消失,它的 /admin 和 /app 页面返回 not found,数据保留。这个页面不能安装插件,安装插件是把它加进 src/plugins/installed.ts。见后台插件。

调整缓存

打开缓存设置

打开 /admin/config/cache。侧边栏中没有入口,保存需要 config.write。

逐个区域设置

针对每个区域勾选 启用,设置 存活时长(秒),选择当前运行时可用的 后端,点击 保存。

需要时清空缓存

清空此域 会立即清空该区域的缓存。

查看审计日志

打开 安全 → 审计(/admin/audit,需要 audit.read)。页面列出最近 500 条事件,例如用户状态变更、认证与服务商配置保存、API Key 事件和频率限制判定,并提供 CSV 下载。

配置之前

不运行初始化脚本,就没有人能进入后台。已登录但不具备 admin.access 的用户会被跳转到 /system/permission-denied,没有会话的访问者跳转到 /system/session-expired。

验证

  • 以管理员身份登录:/admin 可以打开,侧边栏显示所有分组。
  • 必需项就绪后,/setup 显示 必需项已齐备。
  • 在仓库中运行:
pnpm validate:users
pnpm validate:auth-boundary

常见问题

出现 SUPER_ADMIN_EMAIL is required.

脚本没有读到值。把两个变量写入 .env,或者在命令前直接传入:SUPER_ADMIN_EMAIL=you@example.com SUPER_ADMIN_PASSWORD='<password>' pnpm db:bootstrap-super-admin。

页面显示 Permission denied: <权限>

用户能进入后台,但缺少该页面检查的权限。仅 /admin 仪表盘就需要 admin.dashboard.read、users.read、credits.read 和 ai.read。见管理用户、角色与权限。

新权限没有授予 Super Admin

角色权限在运行 pnpm db:bootstrap-super-admin 时写入。再运行一次即可。

侧边栏缺少某个菜单

侧边栏会隐藏用户无权访问的菜单项。给该用户分配带有该页面所需权限的角色,见角色与权限。

参考

下一步