SupoClip管理后台使用指南:用户权限、数据看板与YouTube授权一站管理
SupoClip管理后台使用指南:用户权限、数据看板与YouTube授权一站管理
SupoClip 是一款开源的 AI 视频剪辑工具(OpusClip 替代品),能把长视频自动剪成带字幕的短视频。它的管理后台(/admin)支持管理员一键切换用户权限、查看平台级数据看板,并在 Runtime Settings 面板中安全管理 YouTube Data API key 等第三方授权密钥,全程无需修改 env 文件或重新部署。
SupoClip 的核心能力是把长视频一键拆分为多条带病毒度评分的短视频:
如何进入管理后台:入口与访问控制
管理后台入口是 /admin,只有 is_admin=true 的用户才能看到完整功能,未登录或无权限的账号会被拦截并给出提示。
权限校验分为前后端两层:
- 前端:页面渲染前先读取 Better Auth 会话,判断
session.user.is_admin,非管理员直接进入提示页; - 后端:所有管理 API 都会调用
require_admin_user再查一次数据库的is_admin字段,防止绕过。
相关源码:
- 管理后台页面:frontend/src/app/admin/page.tsx
- 后端权限校验:backend/src/admin_auth.py
提示:布局层还设置了 noIndex,避免 /admin 被搜索引擎收录。见 frontend/src/app/admin/layout.tsx。
用户权限管理:一键授予或移除管理员
管理后台的 Users 面板展示最近 30 个用户,每行都有 Make Admin / Remove Admin 按钮,点击即可切换该用户的 is_admin 状态,无需登录数据库手动改表。
几个值得注意的设计:
- 切换请求走前端 API 路由
PATCH /api/admin/users/[id]/admin,路由内部会二次校验当前操作者必须是管理员(401 / 403 分层返回); - 当前登录的管理员无法移除自己的权限,避免"最后一个管理员把门锁死"的经典事故;
- 用户的计划档位(plan)、注册时间、任务总数都在同一行可见,方便快速判断用户画像。
相关源码:
- 权限切换按钮组件:frontend/src/components/admin/admin-user-toggle.tsx
- 权限切换 API:frontend/src/app/api/admin/users/[id]/admin/route.ts
平台数据看板:核心指标一次看全
打开 /admin 顶部就是 5 张统计卡片,覆盖最常用的运营指标:
| 指标 | 含义 |
|---|---|
| Total users | 平台总用户数 |
| Admins | 管理员数量 |
| Total tasks | 全部生成任务数 |
| Completed tasks | 已完成任务数 |
| Currently processing | 当前正在排队/处理中的任务数(有任务时卡片带高亮动效,方便值班时一眼扫到) |
卡片下方还有三块运营视图:
- Currently Processing Tasks:全平台实时队列,显示每个进行中任务的所属用户、状态和最后更新时间,排查"某用户任务卡住"时最先看这里;
- User Task Explorer:点击任意用户的任务数,即可展开该用户最近 40 条任务,逐条查看状态与产出的 Clip 数量;
- Recent Generations:最近 40 条全平台任务流水,包含用户、状态、Clip 数量与创建时间。
YouTube授权管理:在管理面板里配置 API key
长视频剪辑工具的"重活"是下载和识别视频。SupoClip 通过 Runtime Settings 面板(位于 /admin 页面底部)统一管理所有第三方密钥,管理员可以在浏览器里直接填入、覆盖或删除,保存后立即生效,不需要动环境变量文件。
面板里与 YouTube 授权直接相关的配置项:
YOUTUBE_DATA_API_KEY:YouTube Data API 密钥,用于拉取视频元数据(标题、时长、缩略图、播放量、点赞数等);GOOGLE_API_KEY:Google API key,可作为 YouTube Data API key 的兜底——源码中resolve_youtube_data_api_key的逻辑是"优先取 YouTube 专属 key,取不到就用 Google key";- 其他同面板配置项包括
ASSEMBLY_AI_API_KEY(转录)、OPENAI_API_KEY/OPENROUTER_API_KEY/ANTHROPIC_API_KEY(LLM)、OLLAMA_BASE_URL(本地模型)、APIFY_API_TOKEN(YouTube 下载兜底通道)、PEXELS_API_KEY(B-roll 素材)。
每个配置项还会显示当前生效来源徽章(Environment / Admin setting / Unset),并支持两个精细开关:
- Prefer saved:勾选后,即使环境变量已设置,也优先使用面板保存的值;
- Clear saved:删除面板保存的加密值,回退到环境变量。
安全上,密钥以 AES-GCM 加密后写入 app_settings 表,页面永远不会回显明文。
相关源码:
- 运行时设置模块(加密与缓存):backend/src/runtime_settings.py
- 管理端读写接口:backend/src/api/routes/admin.py
- YouTube 元数据获取逻辑:backend/src/youtube_utils.py
- 密钥兜底解析:backend/src/config.py
附:公告管理与其他管理入口
/admin 页面顶部有 Manage announcements 链接,跳转到 /admin/announcements:管理员在这里创建、编辑、定时发布或隐藏公告,发布后立即出现在官网首页和应用内的 "What's new" 面板,数据存在 PostgreSQL 的 announcements 表中,发布无需改代码或重新部署。
另外,后端还提供 GET /admin/health 接口用于验证管理访问权限与后端连通性,配合 scripts/monitor-production.py 和 docs/production-monitoring.md 可以做生产环境巡检。
小结
SupoClip 的管理后台把三件事做进了同一个页面:
- 用户权限——按钮式升降管理员,带自我锁死保护;
- 平台数据看板——用户、任务、实时队列、单用户下钻一站式查看;
- YouTube 授权管理——YouTube Data API key / Google key 兜底 + 全量第三方密钥的加密运行时配置。
对自部署的运营者来说,这三个功能覆盖了日常运维的绝大部分操作,源码索引可参考 docs/api-reference.md 与 docs/architecture.md。

