7.5 KiB
7.5 KiB
视频转码配置说明
概述
由壹点3D素材平台支持视频素材的自动转码功能，可以将上传的视频转换为适合在线预览的格式。
环境要求
1. FFmpeg
视频转码需要 FFmpeg 工具。在 Docker 环境中，FFmpeg 已经在 Dockerfile 中安装：
RUN apk add --no-cache ffmpeg
2. 环境变量配置
在 docker-compose.yml 或 .env 文件中配置以下环境变量：
# 视频转码编码器（推荐使用 libx265，压缩率更高）
VIDEO_TRANSCODE_CODEC=libx265
# 转码预设（速度与质量的平衡）
# 可选值：ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow
# 推荐：medium（平衡速度和质量）
VIDEO_TRANSCODE_PRESET=medium
# 恒定质量因子（CRF，控制视频质量）
# 范围：0-51，数值越小质量越高，文件越大
# 推荐：22-28（22 为高质量，28 为较低质量）
VIDEO_TRANSCODE_CRF=22
# 音频比特率
# 推荐：128k-192k（128k 为标准质量，192k 为高质量）
VIDEO_AUDIO_BITRATE=160k
3. Redis 配置（可选）
如果需要使用 Redis 管理转码队列（推荐用于生产环境），需要配置：
# 启用 Redis
USE_REDIS=true
# Redis 连接地址
REDIS_URL=redis://localhost:6379
注意：
- 如果不配置 Redis，系统会使用内存队列（重启后队列会丢失）
- 生产环境强烈推荐使用 Redis，确保转码任务不会因为重启而丢失
转码流程
1. 上传视频
用户上传视频素材时，系统会：
- 保存原始视频文件到 S3
- 创建素材记录，设置
videoProcessingStatus = 'pending' - 将转码任务加入队列
2. 转码处理
转码队列会自动处理待转码的视频：
- 从队列中取出任务
- 下载原始视频
- 使用 FFmpeg 转码：
- 生成 540p 预览视频（
videoPreview540Url） - 生成 10 秒预览片段（
videoPreviewClipUrl） - 提取视频封面（
videoCoverUrl）
- 生成 540p 预览视频（
- 上传转码后的文件到 S3
- 更新素材记录，设置
videoProcessingStatus = 'completed'
3. 转码失败处理
如果转码失败：
- 系统会记录错误信息到
transcodeLastError字段 - 增加重试次数（
transcodeAttempts） - 如果重试次数超过限制（默认 3 次），标记为
failed - 用户可以在前端手动重试转码
API 接口
查询转码状态
GET /api/materials/transcode?materialId=xxx
响应示例：
{
"status": "processing",
"progress": 45,
"message": "正在转码中..."
}
启动转码任务
POST /api/materials/transcode
Content-Type: application/json
{
"materialId": "xxx"
}
响应示例：
{
"message": "转码任务已启动",
"status": "processing"
}
转码参数说明
VIDEO_TRANSCODE_CODEC
libx264（H.264）：
- 优点：兼容性好，几乎所有设备都支持
- 缺点：文件较大
- 适用场景：需要最大兼容性的场景
libx265（H.265/HEVC）：
- 优点：压缩率高，文件小，画质好
- 缺点：编码速度较慢，部分老设备不支持
- 适用场景：追求高画质和小文件的场景（推荐）
VIDEO_TRANSCODE_PRESET
速度从快到慢：
ultrafast：最快，质量最差superfast：很快，质量较差veryfast：快，质量一般faster：较快，质量较好fast：快，质量好medium：平衡（推荐）slow：慢，质量很好slower：很慢，质量极好veryslow：最慢，质量最好
推荐配置：
- 开发环境：
fast或faster（快速测试） - 生产环境：
medium（平衡速度和质量） - 高质量需求：
slow（追求极致画质）
VIDEO_TRANSCODE_CRF
CRF（Constant Rate Factor）控制视频质量：
0：无损（文件极大，不推荐）18-22：高质量（推荐用于重要视频）23-28：标准质量（推荐用于一般视频）29-35：较低质量（不推荐）51：最低质量（不推荐）
推荐配置：
- 高质量：
20-22 - 标准质量：
23-25（推荐） - 节省空间：
26-28
VIDEO_AUDIO_BITRATE
音频比特率控制音频质量：
96k：低质量（不推荐）128k：标准质量160k：较高质量（推荐）192k：高质量256k：极高质量（文件较大）
生产环境配置示例
正式系统（docker-compose.yml）
environment:
# 视频转码配置
- VIDEO_TRANSCODE_CODEC=libx265
- VIDEO_TRANSCODE_PRESET=medium
- VIDEO_TRANSCODE_CRF=22
- VIDEO_AUDIO_BITRATE=160k
# Redis 配置（可选）
- USE_REDIS=true
- REDIS_URL=redis://redis:6379
影子系统（docker-compose.shadow.yml）
影子系统已经配置了完整的视频转码环境，包括：
- 独立的 Redis 实例（端口 6380）
- 完整的转码环境变量
- 独立的 uploads 目录
监控和排查
查看转码统计
管理员可以访问以下 API 查看转码统计：
GET /api/admin/video-transcode-stats
响应示例：
{
"pending": 5,
"processing": 2,
"completed": 150,
"failed": 3,
"recentFailures": [
{
"id": "xxx",
"productModel": "产品名称",
"transcodeLastError": "FFmpeg 转码失败：...",
"transcodeAttempts": 3,
"createdAt": "2025-12-20T10:00:00Z"
}
]
}
常见问题
1. 转码失败：FFmpeg not found
原因：Docker 镜像中没有安装 FFmpeg
解决：
- 确认 Dockerfile 中已添加
ffmpeg到 apk 安装列表 - 重新构建镜像：
docker compose build - 重启容器：
docker compose up -d
2. 转码速度很慢
原因：转码预设太慢（如 slow 或 slower）
解决：
- 调整
VIDEO_TRANSCODE_PRESET为medium或fast - 重启容器使配置生效
3. 转码后文件太大
原因：CRF 值太小（质量太高）
解决：
- 调整
VIDEO_TRANSCODE_CRF为25-28 - 或使用
libx265编码器（压缩率更高）
4. 转码队列卡住
原因：
- 转码任务失败但状态未更新
- Redis 连接失败
- 内存队列因重启丢失
解决：
- 查看转码统计 API，确认是否有
processing状态的任务 - 如果有卡住的任务，可以手动重置状态：
UPDATE materials SET "videoProcessingStatus" = 'pending' WHERE "videoProcessingStatus" = 'processing'; - 重启容器，队列会自动恢复
性能优化建议
1. 使用 Redis
生产环境强烈推荐使用 Redis：
- 转码任务持久化，重启不丢失
- 支持分布式部署（多个转码节点）
- 更好的队列管理和监控
2. 调整转码参数
根据实际需求调整参数：
- 如果用户主要在移动端观看：使用
libx265+CRF 25 - 如果追求极致画质：使用
libx265+CRF 20+slow - 如果需要快速转码：使用
libx264+CRF 23+fast
3. 分离转码服务
如果转码任务很多，可以考虑：
- 部署独立的转码服务器
- 使用消息队列（如 RabbitMQ）管理任务
- 使用 GPU 加速转码（需要支持 NVENC 的 FFmpeg）
总结
视频转码功能已经完整实现，包括：
- ✅ FFmpeg 已在 Dockerfile 中安装
- ✅ 环境变量已在 docker-compose.yml 中配置
- ✅ 转码 API 已实现（查询状态、启动任务）
- ✅ 转码队列已实现（支持 Redis 和内存队列）
- ✅ 错误处理和重试机制已实现
- ✅ 管理员监控 API 已实现
下一步：
- 重新构建 Docker 镜像（包含 FFmpeg）
- 部署到正式环境
- 测试视频上传和转码功能
- 监控转码队列状态