简介

本开发文档面向 DouPHP 的视频管理模块，覆盖后台管理、前台展示与 API 端能力。重点说明：

• 视频资源的 CRUD 操作与分类体系
• 播放控制、SEO 优化与统计（观看次数）
• 视频上传流程、转码处理、封面生成等高级功能
• 播放器集成、流媒体传输、缓存策略等技术实现
• 存储策略、CDN 加速、带宽优化等最佳实践
• 面向开发者的 API 参考与扩展指南

项目结构

视频模块采用前后端分离的控制器分层设计：

• 后台管理：admin/controller/video/* 提供视频与分类的增删改查与批量操作
• 前台展示：front/controller/video/* 负责列表、详情、导航与 SEO
• API 接口：api/controller/video/* 暴露列表与详情查询
• 路由声明：各端 route/video.php 将 URL 映射到对应控制器
• 配置：module.php 启用 video 为栏目模块；file.php 定义文件系统与上传默认限制

graph TB
subgraph "后台管理"
A["admin/controller/video/VideoController"]
B["admin/controller/video/CategoryController"]
R1["admin/route/video.php"]
end
subgraph "前台展示"
C["front/controller/video/VideoController"]
R2["front/route/video.php"]
S1["front/service/video/VideoService"]
end
subgraph "API 接口"
D["api/controller/video/VideoController"]
R3["api/route/video.php"]
end
CFG["config/module.php<br/>config/file.php"]
R1 --> A
R1 --> B
R2 --> C
R3 --> D
C --> S1
A --> S1
D --> S1
CFG -.-> A
CFG -.-> C
CFG -.-> D

图表来源

• admin/route/video.php:31-38
• front/route/video.php:29-30
• api/route/video.php:29-32
• config/module.php:4-17
• config/file.php:43-60

章节来源

• admin/route/video.php:31-38
• front/route/video.php:29-30
• api/route/video.php:29-32
• config/module.php:4-17
• config/file.php:43-60

核心组件

• 后台视频控制器：提供视频列表、新增、编辑、删除、批量操作；表单校验由请求对象完成，业务逻辑委托服务层。
• 后台分类控制器：提供分类树形列表、新增、编辑、删除；支持多语言字段。
• 前台视频控制器：提供视频列表（含分类与归档）、详情页；集成导航、面包屑、SEO 与 Schema。
• API 视频控制器：提供视频列表与详情 JSON 接口，复用前台服务。
• 前台视频服务：封装视频数据构建、分类信息、内容 Markdown 转换、点击量记录等。
• 路由与配置：声明式路由将 URL 映射到控制器；模块配置启用 video；文件配置定义上传限制与磁盘根。

章节来源

• admin/controller/video/VideoController.php:65-217
• admin/controller/video/CategoryController.php:65-180
• front/controller/video/VideoController.php:83-214
• api/controller/video/VideoController.php:55-137
• front/service/video/VideoService.php:120-153
• config/module.php:4-17
• config/file.php:43-60

架构总览

视频模块遵循“控制器-服务-模型”的分层架构：

• 控制器负责接收请求、参数校验、调用服务并返回视图或响应
• 服务封装业务规则与数据组装（如列表构建、详情构建、点击量记录）
• 模型负责数据访问（通过 ORM 或仓库模式）
• 路由与配置驱动模块行为与资源路径

sequenceDiagram
participant U as "用户/客户端"
participant FRC as "前台控制器<br/>front/controller/video/VideoController"
participant SVC as "前台服务<br/>front/service/video/VideoService"
participant MOD as "模型/ORM"
participant V as "视图/模板"
U->>FRC : GET /video/category/{id}
FRC->>SVC : buildVideoListData(catId, page, pageSize, archive)
SVC->>MOD : 查询视频列表与分页
MOD-->>SVC : 数据集
SVC-->>FRC : 列表数据 + 分页
FRC->>V : 渲染 video_category.dwt
V-->>U : HTML 页面
U->>FRC : GET /video/{id}
FRC->>SVC : buildVideoShowData(id)
SVC->>MOD : 查询详情
MOD-->>SVC : 详情数据
SVC->>SVC : recordVideoView(id)
SVC-->>FRC : 详情数据
FRC->>V : 渲染 video.dwt
V-->>U : HTML 页面

图表来源

• front/controller/video/VideoController.php:83-214
• front/service/video/VideoService.php:120-153

详细组件分析

后台视频管理（CRUD 与批量）

• 列表：支持按分类与关键词筛选，分页展示
• 新增/编辑：表单校验由 VideoFormRequest 完成；支持草稿 token；提交后跳转至编辑页
• 删除：参数校验后调用服务执行删除
• 批量操作：统一 action 入口，根据 post 数据执行批量任务

flowchart TD
Start(["进入后台视频控制器"]) --> List["列表 index()"]
List --> Create["新增 create()"]
Create --> Store["提交 store()"]
Store --> Edit["编辑 edit()"]
Edit --> Update["更新 update()"]
Update --> Destroy["删除 destroy()"]
Destroy --> Action["批量 action()"]
Action --> End(["结束"])

图表来源

• admin/controller/video/VideoController.php:65-217

章节来源

• admin/controller/video/VideoController.php:65-217

后台视频分类管理

• 列表：树形结构展示，便于层级管理
• 新增/编辑：支持多语言字段（名称、关键词、描述）
• 删除：级联检查与清理

章节来源

• admin/controller/video/CategoryController.php:65-180

前台视频展示与 SEO

• 列表：支持分类与归档（年/月），分页大小来自配置
• 详情：加载详情、记录观看次数、注入 SEO 标题/关键词/描述与 Schema
• 导航与面包屑：基于 NavigationBuilder 与 BreadcrumbBuilder 构建

sequenceDiagram
participant Client as "浏览器"
participant Ctrl as "前台控制器"
participant Service as "前台服务"
participant Model as "模型"
participant View as "模板"
Client->>Ctrl : GET /video/detail?id=xxx
Ctrl->>Service : buildVideoShowData(id)
Service->>Model : 查询详情
Model-->>Service : 详情数据
Service->>Service : recordVideoView(id)
Service-->>Ctrl : 详情数据
Ctrl->>View : 渲染 video.dwt含 SEO/Schema
View-->>Client : HTML

图表来源

• front/controller/video/VideoController.php:157-214
• front/service/video/VideoService.php:120-153

章节来源

• front/controller/video/VideoController.php:83-214
• front/service/video/VideoService.php:120-153

API 视频接口

• 列表：支持分类与归档，返回结构化 JSON
• 详情：返回视频详情与自定义字段，自动累加点击数

sequenceDiagram
participant App as "第三方应用"
participant ApiCtrl as "API 控制器"
participant Service as "前台服务"
participant Resp as "ApiResponse"
App->>ApiCtrl : GET /api/?route=video&id=xxx
ApiCtrl->>Service : buildVideoShowData(id)
Service->>Service : recordVideoView(id)
Service-->>ApiCtrl : 详情数据
ApiCtrl->>Resp : success(result)
Resp-->>App : JSON 响应

图表来源

• api/controller/video/VideoController.php:110-137

章节来源

• api/controller/video/VideoController.php:55-137

视频上传与封面生成

• 上传入口：后台模板使用大文件上传控件，触发 fileBig 方法，支持进度条与草稿 token
• 存储与校验：遵循 config/file.php 的 upload_defaults 与 disks 配置；建议通过 attachment()->store(...) 进行安全上传
• 封面生成：模板中提供 image 字段用于封面图；可在服务层结合缩略图生成逻辑实现

flowchart TD
UploadStart["选择视频文件"] --> Validate["校验类型/大小/白名单"]
Validate --> |通过| Store["attachment()->store(...)<br/>写入 images/upload/..."]
Validate --> |失败| Error["返回错误提示"]
Store --> Thumb["生成封面缩略图可选"]
Thumb --> Draft["保存草稿/正式数据"]
Draft --> Done["完成"]

图表来源

• admin/view/video.htm:137-169
• config/file.php:43-60

章节来源

• admin/view/video.htm:137-169
• config/file.php:43-60

播放控制与流媒体传输

• 播放源：服务层在详情构建时会将本地相对路径转换为完整 URL，便于前端播放器直接引用
• 流媒体：建议配合 Web 服务器（如 Nginx/Apache）开启 Range 请求以支持断点续播；可结合 CDN 加速静态视频文件
• 播放器集成：前端模板可使用 HTML5 <video> 或第三方播放器（如 hls.js、flv.js）适配不同格式

章节来源

• front/service/video/VideoService.php:120-153

SEO 优化与统计

• SEO：前台控制器集成 SeoResolver 与 SchemaService，动态生成标题、关键词、描述与结构化数据
• 统计：详情页调用 recordVideoView 累计观看次数，并在返回数据中体现

章节来源

• front/controller/video/VideoController.php:157-214
• front/service/video/VideoService.php:120-153

依赖关系分析

• 控制器依赖服务：所有控制器均依赖 VideoService 完成数据构建与业务规则
• 路由与控制器：各端 route/video.php 将 URL 映射到具体控制器
• 配置影响：module.php 启用 video 为栏目模块；file.php 控制上传限制与存储路径

graph LR
R_Admin["admin/route/video.php"] --> C_Admin["admin/controller/video/*"]
R_Front["front/route/video.php"] --> C_Front["front/controller/video/VideoController"]
R_Api["api/route/video.php"] --> C_Api["api/controller/video/VideoController"]
C_Front --> S_Video["front/service/video/VideoService"]
C_Admin --> S_Video
C_Api --> S_Video
M["config/module.php"] -.-> C_Admin
M -.-> C_Front
M -.-> C_Api
F["config/file.php"] -.-> C_Admin

图表来源

• admin/route/video.php:31-38
• front/route/video.php:29-30
• api/route/video.php:29-32
• config/module.php:4-17
• config/file.php:43-60

章节来源

• admin/route/video.php:31-38
• front/route/video.php:29-30
• api/route/video.php:29-32
• config/module.php:4-17
• config/file.php:43-60

性能与扩展性

• 分页与配置：列表分页大小来自 Config::get('pagination.video')，可按需调整
• 存储与 CDN：视频文件建议部署至 CDN，减少源站带宽压力；本地存储根由 file.php 配置
• 缓存策略：可对分类树、热门视频列表进行缓存；详情页统计可通过异步队列降低主流程开销
• 扩展点：
  • 转码处理：在服务层插入转码任务（如 FFmpeg 异步转码），生成多清晰度版本
  • 缩略图：在上传完成后生成多尺寸封面，提升首屏加载速度
  • 防盗链：结合签名 URL 与 Referer 校验保护视频资源

故障排查指南

• 页面错误：当路由解析失败或数据不存在时，控制器抛出 DomainException，全局处理器统一输出错误消息
• 上传失败：检查 file.php 中的 allow_extensions 与 upload_max_kb；确认磁盘 root 路径权限
• 播放异常：确认视频 URL 是否完整；检查服务器是否允许 Range 请求；验证 MIME 类型
• 统计未增加：确认详情页是否调用 recordVideoView；检查数据库字段与事务一致性

章节来源

• front/controller/video/VideoController.php:157-174
• config/file.php:43-60

结论

DouPHP 视频模块通过清晰的分层架构与声明式路由，提供了完整的视频管理能力。开发者可基于现有控制器与服务快速扩展转码、封面生成、CDN 加速等功能，并结合 SEO 与统计提升用户体验与运营效果。

附录：API 参考与最佳实践

API 参考

• 列表接口
  • 路径：/api/?route=video
  • 方法：GET
  • 参数：id（分类 ID）、category_slug、page、year、month
  • 返回：title、category_id、video_list、video_category、cate_info、pager
• 详情接口
  • 路径：/api/?route=video&id={id}
  • 方法：GET
  • 返回：title、video、defined、cate_info

章节来源

• api/controller/video/VideoController.php:55-137
• api/route/video.php:29-32

代码示例（路径指引）

• 上传视频：参考后台模板中的大文件上传控件与回调
  • admin/view/video.htm:137-169
• 设置播放参数：在前台模板中使用 video 对象的 file 字段作为播放源
  • front/service/video/VideoService.php:120-153
• 统计观看次数：详情页调用记录方法
  • front/controller/video/VideoController.php:171-177

最佳实践

• 存储策略：使用 CDN 托管视频文件，源站仅保留原始文件与元数据
• 带宽优化：启用 HTTP Range 与 Gzip/Brotli 压缩静态资源；合理设置缓存头
• 转码与多清晰度：上传后异步转码为多种分辨率，提升兼容性与播放体验
• 安全与合规：严格校验上传文件类型与大小；对敏感内容进行审核；防盗链与签名 URL