# 阿里云 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 前不支持，保持聚焦。