13 KiB
13 KiB
阿里云 VOD 媒体资源管理器 - 产品需求文档 (PRD)
版本：v1.0
状态：草稿 / 待评审
目标：构建一个轻量、开源、可自托管的阿里云视频点播（VOD）媒体资源管理后台，解决官方控制台操作繁琐、批量处理能力弱的问题。
1. 项目概述
1.1 背景
阿里云视频点播（VOD）官方管理控制台功能全面，但在以下场景中存在明显痛点：
- 查看视频麻烦：控制台层级深、加载慢、筛选和搜索体验一般。
- 批量下载困难：无法一次性选中多个视频并批量获取下载地址。
- 删除操作繁琐：批量删除步骤多，确认链路过长。
- 权限过重：需要将阿里云账号或复杂 RAM 权限交给所有操作人员。
- 成本不透明：难以快速统计某个分类/标签下的视频数量、存储时长、转码状态等。
1.2 产品定位
一个面向开发者和内容运营人员的轻量 VOD 管理后台，支持：
- 快速查看、搜索、筛选媒体库。
- 批量获取播放/下载地址。
- 批量删除、批量修改分类/标签/标题。
- 多账号配置切换（支持多个阿里云 VOD 账号/Region）。
- 简单自托管部署（Docker / 二进制 / 源码）。
1.3 目标用户
- 使用阿里云 VOD 存储大量视频的内容团队。
- 需要将 VOD 管理能力集成到内部工作流的开发者。
- 希望拥有可定制、可私有部署的媒体管理工具的开源社区用户。
1.4 开源声明
本项目以 MIT License 开源，代码托管于 GitHub，欢迎 Issue / PR / Fork。设计上避免引入商业依赖，保证社区可长期免费使用与二次开发。
2. 功能需求
2.1 核心功能
| 功能模块 | 功能说明 | 优先级 |
|---|---|---|
| 视频列表 | 分页展示 VOD 媒体库，支持按标题、ID、分类、标签、状态、时间筛选 | P0 |
| 视频详情 | 查看单个视频的元信息（ID、标题、描述、时长、大小、创建时间、转码状态、封面、播放 URL 等） | P0 |
| 批量下载 | 勾选多个视频，批量获取原片或指定清晰度播放地址，导出为 CSV / 直接触发浏览器下载 | P0 |
| 批量删除 | 勾选多个视频，二次确认后批量删除（支持逻辑删除/物理删除配置） | P0 |
| 批量编辑 | 批量修改标题前缀、分类、标签 | P1 |
| 账号管理 | 配置多个阿里云 AccessKey / Region / 存储区域，支持切换 | P0 |
| 权限控制 | 内置简单登录与只读/读写角色（可选） | P1 |
| 操作日志 | 记录谁在什么时间做了下载/删除/编辑操作 | P1 |
2.2 视频列表字段
默认展示字段：
- 视频 ID（VideoId）
- 标题（Title）
- 分类（CateId / CateName）
- 标签（Tags）
- 时长（Duration）
- 文件大小（Size）
- 创建时间（CreationTime）
- 状态（Status：上传中 / 转码中 / 正常 / 审核中 / 屏蔽）
- 转码状态（TranscodeStatus）
- 缩略图（CoverURL）
2.3 筛选与搜索
- 关键词搜索：标题、VideoId。
- 分类筛选：下拉选择 VOD 分类树。
- 标签筛选：输入标签，支持多选。
- 时间范围：创建时间、更新时间。
- 状态筛选：上传状态、转码状态。
- 文件大小、时长范围筛选（P2）。
2.4 批量下载
- 支持选择：原片 / 指定清晰度（如 LD/SD/HD/FHD/4K）。
- 输出方式：
- 生成临时下载地址列表，导出 CSV（含 VideoId、标题、URL、过期时间）。
- 对浏览器可直接访问的资源，触发浏览器多文件下载（受浏览器策略限制）。
- 支持设置 URL 过期时间（默认 2 小时，最大 24 小时）。
- 下载任务队列，避免一次性请求过多导致限流。
2.5 批量删除
- 选中视频后弹出确认框，列出待删除的视频标题与 ID。
- 支持“仅删除媒资信息（逻辑删除）”或“彻底删除（包括存储文件）”。
- 删除前二次确认，防止误操作。
2.6 账号与 Region 管理
- 添加账号：AccessKey ID、AccessKey Secret、Region（如 cn-shanghai）、存储区域。
- 支持同时保存多个账号，通过下拉切换。
- 敏感信息（AccessKey Secret）在本地配置中加密存储或仅保留在服务端环境变量中。
3. 非功能需求
3.1 性能
- 视频列表首屏加载 < 2s（1000 条以内）。
- 批量操作（下载/删除/编辑）单次最多支持 100 条，超过时分批处理并展示进度。
- 支持阿里云 VOD API 分页与限流自动重试。
3.2 安全
- AccessKey 不暴露给前端，所有阿里云 API 调用由后端代理完成。
- 支持通过环境变量注入 AccessKey，避免写入代码或前端配置。
- 内置登录态（JWT），可配置只读账号与管理员账号。
- 支持 HTTPS 部署（通过反向代理）。
3.3 易用性
- 单 Docker 镜像即可运行，5 分钟内完成部署。
- 提供开箱即用的 Docker Compose 配置。
- 前端响应式，支持桌面端与平板。
- 中文/英文界面（i18n，P1）。
3.4 可维护性
- 前后端分离，代码结构清晰。
- 统一 REST API 规范。
- 完善的类型定义（TypeScript）。
- 单元测试覆盖核心 API 调用与工具函数。
4. 技术栈
采用前后端分离架构，整体追求轻量、现代、易部署。
4.1 前端
| 技术 | 版本/选型 | 说明 |
|---|---|---|
| 框架 | React 18 | 组件化、生态成熟、社区广泛 |
| 语言 | TypeScript 5 | 类型安全，降低维护成本 |
| 构建工具 | Vite 5 | 极速冷启动与 HMR |
| UI 组件库 | Ant Design 5 | 完善的中后台组件，支持国际化 |
| 状态管理 | Zustand | 轻量，适合中小型应用 |
| 路由 | React Router v6 | 声明式路由 |
| HTTP 客户端 | Axios | 统一拦截、错误处理 |
| 表格/虚拟滚动 | Ant Design Table + 按需分页 | 处理大量视频列表 |
| 代码规范 | ESLint + Prettier | 统一代码风格 |
4.2 后端
| 技术 | 版本/选型 | 说明 |
|---|---|---|
| 运行时 | Node.js 20 LTS | 长期支持，性能稳定 |
| 框架 | Express 4 | 轻量、成熟、文档丰富 |
| 语言 | TypeScript 5 | 类型安全 |
| 阿里云 SDK | @alicloud/pop-core 或官方 @alicloud/vod-sdk | 调用 VOD OpenAPI |
| 配置管理 | cosmiconfig / dotenv | 支持环境变量与配置文件 |
| 身份认证 | jsonwebtoken + bcryptjs | JWT + 密码哈希 |
| 持久化 | SQLite（可选） | 存储账号配置、操作日志，零部署成本 |
| 日志 | pino | 高性能结构化日志 |
| 任务队列 | bullmq 或内存队列 | 批量任务异步处理 |
| 代码规范 | ESLint + Prettier | 统一代码风格 |
4.3 部署与运维
| 技术 | 说明 |
|---|---|
| Docker | 前后端统一镜像或多镜像编排 |
| Docker Compose | 一键启动完整服务 |
| Nginx / Caddy | 反向代理、SSL 终止（可选，由用户自行配置） |
| GitHub Actions | CI： lint / test / build / Docker 镜像发布 |
4.4 整体架构
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Web Browser │──────▶ React Frontend │──────▶ Node.js Backend │
│ (Ant Design) │ │ (Vite + TS) │ │ (Express + TS) │
└─────────────────┘ └──────────────────┘ └────────┬────────┘
│
▼
┌─────────────────┐
│ 阿里云 VOD API │
│ (pop-core SDK) │
└─────────────────┘
│
▼
┌─────────────────┐
│ SQLite (可选) │
│ 配置 / 操作日志 │
└─────────────────┘
4.5 目录结构（建议）
Aliyun-VOD-Media-Library-Manager/
├── apps/
│ ├── web/ # 前端 (React + Vite)
│ │ ├── src/
│ │ ├── package.json
│ │ └── vite.config.ts
│ └── server/ # 后端 (Node.js + Express)
│ ├── src/
│ ├── package.json
│ └── tsconfig.json
├── docker/
│ ├── Dockerfile.web
│ ├── Dockerfile.server
│ └── docker-compose.yml
├── docs/ # 使用文档、部署文档
├── .github/
│ └── workflows/ci.yml
├── LICENSE (MIT)
├── README.md
└── PRD.md
5. API 设计（核心）
5.1 账号配置
GET /api/config- 获取当前账号配置（脱敏）POST /api/config- 新增/更新账号配置DELETE /api/config/:id- 删除账号配置POST /api/config/:id/switch- 切换当前使用账号
5.2 媒体库
GET /api/videos- 视频列表（分页、筛选）GET /api/videos/:id- 视频详情POST /api/videos/:id/play-info- 获取播放信息POST /api/videos/batch-delete- 批量删除POST /api/videos/batch-download- 批量获取下载地址POST /api/videos/batch-update- 批量更新元信息（P1）
5.3 分类
GET /api/categories- 获取 VOD 分类树
5.4 系统
POST /api/auth/login- 登录GET /api/auth/me- 当前用户GET /api/logs- 操作日志（P1）
6. 界面原型要点
6.1 布局
- 左侧导航：视频库、批量任务、账号配置、系统设置、操作日志。
- 顶部：当前账号/Region 切换、用户头像/退出。
- 主内容区：面包屑 + 筛选栏 + 数据表格。
6.2 视频库页面
- 筛选栏：关键词输入、分类下拉、标签输入、时间选择、状态选择、刷新按钮。
- 操作栏：批量下载、批量删除、批量编辑。
- 表格：支持多选、排序、列自定义。
- 点击行展开/抽屉查看详情与预览。
6.3 批量任务页面
- 展示当前批量下载/删除任务进度。
- 完成后可导出结果 CSV。
7. 里程碑规划
| 阶段 | 目标 | 周期（建议） |
|---|---|---|
| MVP | 视频列表、详情、单/批量下载、单/批量删除、单账号配置 | 2 - 3 周 |
| v0.2 | 多账号切换、分类树、操作日志、只读/管理员权限 | 2 周 |
| v0.3 | 批量编辑、标签管理、下载任务队列、Docker 一键部署 | 2 周 |
| v1.0 | i18n、测试覆盖、文档完善、发布 Release | 2 周 |
8. 风险与规避
| 风险 | 影响 | 规避方案 |
|---|---|---|
| 阿里云 API 限流 | 批量操作失败 | 分页、队列、指数退避重试 |
| AccessKey 泄露 | 账号安全 | 仅后端持有，环境变量注入，最小权限 RAM 用户 |
| 大文件下载超时 | 体验差 | 仅获取临时 URL，由用户自行使用下载工具 |
| 官方 API 变更 | 功能异常 | 封装 SDK 调用层，抽象统一接口 |
9. 附录
9.1 参考文档
9.2 建议的 RAM 最小权限
为了让本工具安全运行，建议为阿里云子账号/用户组授予最小权限策略：
{
"Version": "1",
"Statement": [
{
"Effect": "Allow",
"Action": [
"vod:Get*",
"vod:List*",
"vod:SearchMedia",
"vod:DeleteVideo",
"vod:UpdateVideoInfo",
"vod:GetPlayInfo"
],
"Resource": "*"
}
]
}
注：如果仅需要只读功能，应移除
DeleteVideo与UpdateVideoInfo。
10. 待决策事项
- 是否引入数据库：MVP 阶段建议仅用内存/JSON 配置，v0.2 引入 SQLite。
- 批量下载 URL 过期策略：默认 2 小时，是否允许用户自定义。
- 是否支持阿里云 STS 临时凭证：建议 v0.3 支持，进一步提升安全性。
- 是否支持多云扩展（如腾讯云、AWS）：明确 v1.0 前不支持，保持聚焦。