342 lines
13 KiB
Markdown
342 lines
13 KiB
Markdown
# 阿里云 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 参考文档
|
||
|
||
- [阿里云 VOD 开发指南](https://help.aliyun.com/document_detail/60574.html)
|
||
- [阿里云 OpenAPI 门户 - VOD](https://next.api.aliyun.com/api/Vod)
|
||
- [RAM 最小权限策略最佳实践](https://help.aliyun.com/document_detail/58932.html)
|
||
|
||
### 9.2 建议的 RAM 最小权限
|
||
|
||
为了让本工具安全运行，建议为阿里云子账号/用户组授予最小权限策略：
|
||
|
||
```json
|
||
{
|
||
"Version": "1",
|
||
"Statement": [
|
||
{
|
||
"Effect": "Allow",
|
||
"Action": [
|
||
"vod:Get*",
|
||
"vod:List*",
|
||
"vod:SearchMedia",
|
||
"vod:DeleteVideo",
|
||
"vod:UpdateVideoInfo",
|
||
"vod:GetPlayInfo"
|
||
],
|
||
"Resource": "*"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
> 注：如果仅需要只读功能，应移除 `DeleteVideo` 与 `UpdateVideoInfo`。
|
||
|
||
---
|
||
|
||
## 10. 待决策事项
|
||
|
||
1. 是否引入数据库：MVP 阶段建议仅用内存/JSON 配置，v0.2 引入 SQLite。
|
||
2. 批量下载 URL 过期策略：默认 2 小时，是否允许用户自定义。
|
||
3. 是否支持阿里云 STS 临时凭证：建议 v0.3 支持，进一步提升安全性。
|
||
4. 是否支持多云扩展（如腾讯云、AWS）：明确 v1.0 前不支持，保持聚焦。
|