运行管理后台
创建第一个管理员、完成上线检查清单、熟悉侧边栏,并在 /admin 中管理插件、调整缓存和查看审计日志。
/admin 管理后台是运营人员管理产品的地方。安装完成后先按本指南操作一遍,之后调整缓存或查看审计日志时再回来查阅。
准备工作
- 已完成迁移的数据库(
pnpm db:migrate)。 - 一台能连上该数据库的机器上的终端。
- 第一个管理员要使用的邮箱和密码。
创建第一个管理员
在有用户具备 admin.access 权限之前,没有人能打开 /admin,而授权又必须在后台里完成。初始化脚本从命令行创建第一个管理员。
把管理员写入 .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。见定价套餐。
启用或停用插件
- 打开 设置 → 插件(
/admin/plugins,需要config.read)。页面列出这份构建里安装的所有插件及其贡献的内容。 - 使用模块所在行的开关;保存需要
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 时写入。再运行一次即可。
侧边栏缺少某个菜单
侧边栏会隐藏用户无权访问的菜单项。给该用户分配带有该页面所需权限的角色,见角色与权限。