248 lines
10 KiB
Markdown
248 lines
10 KiB
Markdown
# 设计：特殊文件夹视频媒体（上传后服务器压缩）
|
||
|
||
> 在特殊文件夹共享照片墙（`#<文件夹名>`）里支持视频作为墙上媒体元素。
|
||
> 视频上传后先显示处理中占位卡，服务器用 `ffmpeg` 压缩为低带宽 MP4，完成后在墙上播放。
|
||
> 本设计只开放给特殊文件夹；个人 `#photo` 暂不开放视频入口。
|
||
>
|
||
> 状态：规划中，当前代码尚未实现 `/media*` 接口、视频上传、转码和视频卡片渲染。
|
||
|
||
前置阅读：
|
||
- [photo-wall.md](../../photo-wall.md)
|
||
- [2026-06-24-special-folders-design.md](2026-06-24-special-folders-design.md)
|
||
- [2026-06-24-photo-wall-server-storage-design.md](2026-06-24-photo-wall-server-storage-design.md)
|
||
|
||
## 1. 目标与范围
|
||
|
||
目标：
|
||
- 特殊文件夹支持图片和视频混合展示。
|
||
- 视频像照片一样可以上传、拖拽、缩放、置顶/置底、删除。
|
||
- 视频上传后不阻塞页面等待转码；墙上立即出现“thinking”风格的处理中卡片。
|
||
- 服务器将常见视频格式统一压缩为适合 3M 带宽播放的 MP4。
|
||
- 不提供显式视频下载入口，不添加下载按钮；这不是防下载安全边界。
|
||
|
||
非目标：
|
||
- 个人 `#photo` 视频上传。
|
||
- 多清晰度转码、自适应码率、HLS/DASH。
|
||
- 视频封面生成、时间轴截图、在线播放统计。
|
||
- 大视频断点续传。
|
||
|
||
## 2. 总体架构
|
||
|
||
前端把 `PhotoWallPage` 从“照片元素”扩展为“媒体元素”，新增 `video` 类型。特殊文件夹使用新的媒体 API 加载图片和视频；图片仍按现有视觉展示，视频按状态渲染为处理中卡片、失败卡片或 `<video controls preload="metadata">` 播放器。
|
||
|
||
后端把特殊文件夹存储从“图片列表”升级为“媒体列表”。图片可以同步保存并立即进入 `ready` 状态。视频上传后先写入临时文件，创建状态文件，后台调用 `ffmpeg` 转码；转码完成后只保留压缩后的 `.mp4` 和状态文件，删除原始临时文件。
|
||
|
||
`ffmpeg -movflags +faststart` 只用于优化浏览器在线播放体验：把 MP4 索引移动到文件开头，让 `<video>` 不必等完整文件下载完才开始播放。UI 不提供显式下载按钮；浏览器原生视频控件仍需加 `controlsList="nodownload"` 降低下载入口暴露，但这不构成防下载或防复制安全边界。
|
||
|
||
## 3. 媒体模型
|
||
|
||
特殊文件夹媒体项：
|
||
|
||
```ts
|
||
type MediaType = 'image' | 'video'
|
||
type MediaStatus = 'ready' | 'processing' | 'failed'
|
||
|
||
interface FolderMediaItem {
|
||
id: string
|
||
type: MediaType
|
||
status: MediaStatus
|
||
}
|
||
```
|
||
|
||
服务器为视频维护状态文件，建议路径为 `SPECIAL_DIR/<folder>/media/<id>.json`：
|
||
|
||
```json
|
||
{
|
||
"id": "a1b2c3d4e5f60708",
|
||
"type": "video",
|
||
"status": "processing",
|
||
"originalName": "trip.mov",
|
||
"createdAt": "2026-06-29T12:34:56Z",
|
||
"outputFile": "a1b2c3d4e5f60708.mp4",
|
||
"error": null
|
||
}
|
||
```
|
||
|
||
状态语义：
|
||
- `processing`：原视频已接收，后台正在转码。前端显示处理中占位卡并轮询状态。
|
||
- `ready`：媒体可通过 `GET /media/{id}` 读取。图片返回原图，视频返回压缩后的 MP4。
|
||
- `failed`：转码失败。前端显示失败卡片，允许删除后重传。
|
||
|
||
## 4. 后端接口
|
||
|
||
新增特殊文件夹媒体接口，旧 `/photos*` 接口先保留，前端特殊文件夹切到 `/media*`：
|
||
|
||
| 方法 | 路径 | 鉴权 | 行为 |
|
||
|---|---|---|---|
|
||
| GET | `/api/web/folder/{name}/media` | AuthUser + 白名单 | 列出图片和视频，返回 `{ items, max, totalBytes, overQuota }` |
|
||
| POST | `/api/web/folder/{name}/media` | AuthUser + 白名单 | multipart 上传一个图片或视频 |
|
||
| GET | `/api/web/folder/{name}/media/{id}` | AuthUser + 白名单 | 读取 `ready` 媒体字节 |
|
||
| GET | `/api/web/folder/{name}/media/{id}/status` | AuthUser + 白名单 | 读取单个媒体状态 |
|
||
| DELETE | `/api/web/folder/{name}/media/{id}` | AuthUser + 白名单 | 删除媒体文件、临时文件和状态文件 |
|
||
|
||
上传响应：
|
||
|
||
```json
|
||
{
|
||
"id": "a1b2c3d4e5f60708",
|
||
"type": "video",
|
||
"status": "processing"
|
||
}
|
||
```
|
||
|
||
错误码：
|
||
- `403`：用户无权访问该特殊文件夹。
|
||
- `404`：文件夹或媒体不存在。
|
||
- `409`：达到特殊文件夹元素上限。
|
||
- `413`：上传体或文件过大。
|
||
- `415`：不支持的媒体格式。
|
||
- `500`：IO 或转码任务启动失败。
|
||
|
||
## 5. 上传与格式
|
||
|
||
视频上传使用 multipart，而不是 data URL。原因是视频文件可能很大，data URL 会额外增加约三分之一体积，并迫使前后端把大文件整体放进内存。multipart 更适合 500MB 级文件。
|
||
|
||
支持的输入：
|
||
- 图片：沿用现有 `jpg/png/gif/webp`。
|
||
- 视频：支持常见格式，至少包括 `mp4/mov/m4v/webm/avi/mkv`。
|
||
|
||
约束：
|
||
- 单个原始视频最大 500MB。
|
||
- 单个图片仍沿用 8MiB 上限。
|
||
- 同一个特殊文件夹仍受总元素上限约束，图片、视频、装饰合计不超过当前 `MAX_ITEMS`。
|
||
- 视频上传不限制时长。
|
||
|
||
## 6. 视频转码
|
||
|
||
运行时依赖：服务器必须安装 `ffmpeg`，并保证 Rust 服务进程可以调用。
|
||
|
||
转码目标适配 3M 服务器带宽：
|
||
- 容器：MP4。
|
||
- 视频编码：H.264。
|
||
- 音频编码：AAC。
|
||
- 输出限制到 720p 档：横屏最大 1280x720，竖屏最大 720x1280，保持原方向，不放大小视频。
|
||
- 帧率限制到 24fps。
|
||
- 视频码率目标约 900kbps，缓冲 1800kbps。
|
||
- 音频码率 96kbps。
|
||
- `+faststart` 优化在线播放。
|
||
|
||
建议 ffmpeg 参数方向：
|
||
|
||
```bash
|
||
ffmpeg -y -i input \
|
||
-vf "scale='min(iw,if(gte(iw,ih),1280,720))':'min(ih,if(gte(iw,ih),720,1280))':force_original_aspect_ratio=decrease:force_divisible_by=2,fps=24" \
|
||
-c:v libx264 -preset veryfast -crf 30 -maxrate 900k -bufsize 1800k \
|
||
-c:a aac -b:a 96k \
|
||
-movflags +faststart output.mp4
|
||
```
|
||
|
||
实现计划必须用横屏、竖屏和近正方形视频测试该 filter，确认不会放大小视频，且输出不会超过
|
||
1280x720 或 720x1280 的目标边界。
|
||
|
||
并发策略：
|
||
- Rust 进程内视频转码并发限制为 1。
|
||
- 上传请求只负责接收文件、创建状态、启动后台任务，然后立即返回。
|
||
- 后台任务成功后把状态改为 `ready`，删除临时原视频。
|
||
- 后台任务失败后把状态改为 `failed`，删除临时原视频，保留短错误摘要。
|
||
|
||
## 7. 前端交互
|
||
|
||
特殊文件夹工具栏把“上传照片”改为“上传媒体”。选择文件、拖拽文件都支持图片和视频；剪贴板仍只要求保持图片粘贴可用，视频粘贴不是本期目标。
|
||
|
||
渲染规则：
|
||
- `image + ready`：沿用当前照片卡片。
|
||
- `video + processing`：显示软木板风格占位卡，文案为“thinking”。
|
||
- `video + ready`：显示带控件的 `<video controls preload="metadata">`，不自动播放。
|
||
- `video + failed`：显示“视频处理失败”，允许右键删除。
|
||
|
||
视频卡片行为：
|
||
- 支持拖拽、缩放、旋转、置顶/置底、删除。
|
||
- 双击编辑说明文字，逻辑与照片 caption 一致。
|
||
- 用户主动点击才播放，避免多个视频同时消耗 3M 带宽。
|
||
- 不显示显式下载按钮；`<video>` 使用 `controlsList="nodownload"`。该属性只是 UI 降噪，
|
||
不能当成安全控制。
|
||
|
||
轮询：
|
||
- 上传视频返回 `processing` 后，前端创建本地元素并开始轮询 `/status`。
|
||
- 轮询间隔建议 3 秒。
|
||
- 状态变为 `ready` 后获取 object URL 并替换播放器。
|
||
- 状态变为 `failed` 后停止轮询并显示失败卡。
|
||
- 组件卸载时停止轮询并释放 object URL。
|
||
|
||
## 8. 布局与状态兼容
|
||
|
||
当前特殊文件夹共享状态使用 `photoLayout`。本功能升级为通用 `mediaLayout`：
|
||
|
||
```ts
|
||
interface MediaLayout {
|
||
x: number
|
||
y: number
|
||
rot: number
|
||
scale: number
|
||
z: number
|
||
w: number
|
||
caption: string
|
||
}
|
||
|
||
interface WallState {
|
||
bgIndex: number
|
||
decorations: El[]
|
||
mediaLayout: Record<string, MediaLayout>
|
||
}
|
||
```
|
||
|
||
兼容策略：
|
||
- 前端读取状态时，如果存在 `mediaLayout`，优先使用。
|
||
- 如果只有旧的 `photoLayout`，前端把它当作 `mediaLayout` 读取。
|
||
- 保存状态时写 `mediaLayout`；可以同时保留 `photoLayout` 一段时间以兼容旧前端，但新前端不再依赖它。
|
||
- 后端 state 接口必须同步迁移：`PUT /api/web/folder/{name}/state` 需要接受
|
||
`mediaLayout` 和旧 `photoLayout`；`GET` 返回 `mediaLayout`，并在兼容期同时返回
|
||
`photoLayout`。仅改前端类型不够。
|
||
- 已有图片布局不丢失；新视频布局按同一媒体 id 保存。
|
||
|
||
## 9. 删除与清理
|
||
|
||
删除媒体时：
|
||
- `ready image`：删除图片文件。
|
||
- `ready video`：删除压缩后的 `.mp4` 和状态文件。
|
||
- `processing video`：写入删除标记或直接删除状态文件；后台任务结束后发现状态不存在即清理输出。
|
||
- `failed video`：删除状态文件和可能残留的临时文件。
|
||
|
||
列表接口不返回孤儿临时文件。启动时不要求恢复未完成任务；若服务重启导致任务中断，残留 `processing` 可以在下一次列表时标记为 `failed` 或由清理逻辑处理。
|
||
|
||
## 10. 测试策略
|
||
|
||
后端：
|
||
- 媒体 MIME/扩展名识别。
|
||
- 视频 id 与图片 id 的路径安全校验。
|
||
- 状态文件 `processing -> ready -> failed` 读写。
|
||
- 特殊文件夹权限：未注册 404、无权 403、有权通过。
|
||
- 删除会清理成品、状态和临时文件。
|
||
- ffmpeg 命令构造包含 720p、24fps、900k、96k、`+faststart`。
|
||
- ffmpeg 缩放测试覆盖横屏、竖屏、正方形/近正方形和小尺寸输入，确认不超过目标尺寸且不放大。
|
||
|
||
前端：
|
||
- 特殊文件夹图片上传和显示仍可用。
|
||
- 上传视频后立即出现“thinking”占位。
|
||
- 轮询到 `ready` 后替换为播放器。
|
||
- `failed` 状态显示失败卡并可删除。
|
||
- 视频拖拽、缩放、删除、caption、保存布局不破坏图片和装饰。
|
||
- `<video>` 渲染包含 `controlsList="nodownload"`，且产品文案只承诺不提供下载入口，
|
||
不承诺防下载。
|
||
|
||
端到端：
|
||
- 在本地安装 `ffmpeg` 后上传一个小视频，确认转码完成、播放不卡、刷新后布局保留。
|
||
- 生产部署后用特殊文件夹验证上传视频、等待处理、播放、删除。
|
||
|
||
## 11. 部署与文档
|
||
|
||
这是后端改动，需要全量重部署：重编 Rust、上传二进制和前端静态文件、重启 Rust 服务。
|
||
|
||
服务器新增运行时依赖：
|
||
- `ffmpeg`。
|
||
|
||
文档需要更新：
|
||
- `docs/photo-wall.md`：说明特殊文件夹支持视频媒体，个人墙暂不支持。
|
||
- `docs/superpowers/plans/2026-06-18-deploy.md`：补充安装 `ffmpeg` 和视频转码部署注意事项。
|
||
- `docs/superpowers/specs/2026-06-24-special-folders-design.md`：标注媒体接口和视频扩展已由本设计接续。
|