SpringBoot+Vue+MyBatis点播系统后端源码实战解析

两年前我接过一个很折腾的在线点播需求，业务方既要视频能分权限播放，又要管理后台能处理上万个视频的上下架、审核、分类，还要保证开发周期别拖太久。当时定的方案就是现在这套组合：SpringBoot做后端接口，Vue做管理台和播放页，MyBatis管数据库访问，MySQL存数据，前后端分离。如今这套架构已经跑了好几个项目，我把整套点播系统管理后端源码重新梳理了一遍，把最容易卡住人的细节都补上了注释和说明。这份博客就是给你拆解这套源码的完整思路，从表结构、接口设计、播放鉴权到部署上线，全部走一遍。文中的方案和踩坑记录，都来自真实落地的过程，不是拿Demo凑数。

1. 点播系统到底在管什么：业务模型与模块边界

很多人上来就急着写代码，但做点播系统之前，最值得先想清楚的问题其实是：这个系统到底要管哪些事。点播系统和普通的内容管理后台不一样，它核心要解决的矛盾是“视频内容如何安全、稳定地到达用户终端”，业务模型需要围绕视频的生命周期来拆。

1.1 从视频生命周期反推模块

一条视频从进入系统到被用户看完，一般会经历这样的过程：

• 上传：运营人员或管理员把视频文件传上来，这里要处理大文件、断点续传和文件格式校验；
• 处理：视频需要进行格式转码、切片、生成封面图，这是音视频系统的重头戏；
• 入库：视频的元信息（标题、分类、封面、清晰度、时长、标签）写入MySQL，文件则落在存储目录或云存储；
• 审核/上下架：管理员对视频进行状态管理，决定它是否可见、是否可以被搜索到；
• 分发：用户端播放视频，后台控制系统是否允许播放、允许谁播放；
• 统计：记录播放次数、播放时长、用户行为，为后续运营提供数据。

所以我做这套源码时，模块边界就是按照这条链路来划分的：

这样的划分逻辑是：每个模块都对应视频生命周期中的一个阶段，后端代码在结构上也跟着这个边界走，而不是把一堆接口堆在一个Controller里。以后业务扩展时，比如要加专辑、加评论，可以在不破坏现有结构的前提下加模块。

1.2 技术选型不是越新越好，关键是匹配团队认知

这套系统的技术栈是SpringBoot + Vue + MyBatis + MySQL，初学者看到可能会觉得“就是很常见的组合”，但恰恰是这种常见组合最容易落地。我当时做方案时也对比过SpringCloud微服务、前后端一体JSP这类方案，最后选定这套组合是有明确理由的。

• SpringBoot负责后端接口，自动配置非常省心，内嵌Tomcat，打出一个Jar包就能跑；
• Vue负责管理台和播放页，组件化开发对大量表格、弹窗、播放器这类复用场景很友好；
• MyBatis负责持久层，SQL是手写的，遇到复杂报表或性能调优时，DBA和开发都能直接看SQL，排查问题路径短；
• MySQL负责数据存储，开源、稳定、文档多，中小型点播系统的数据量完全扛得住。

如果你问我为什么不选MyBatis-Plus，我的回答是：这个源码项目我会保留MyBatis原生写法，是为了让读者把SQL本身搞透。至于Plus，在你理解了原生MyBatis之后，再去看它，就是一层封装而已，网上随时可以转型。实战中MyBatis-Plus的批量插入、逻辑删除确实方便，但原生MyBatis的foreach、动态SQL、ResultMap映射才是理解底层的关键。

1.3 项目目录结构设计：前期多花十分钟，后期少加三天班

后端目录我采用的是业界常见的分层结构，但做了点微调：

code复制point-vod-server
├── point-vod-common      // 通用工具、统一返回体、异常处理
├── point-vod-admin       // 运营管理端接口
├── point-vod-api         // 用户端接口
├── point-vod-system       // 核心业务模块：视频、分类、用户、统计
└── point-vod-framework   // 配置类、安全、拦截器、切面

多说一句：没必要为了微服务强行拆分多个服务，单模块的单体应用对于多数点播项目完全够用，而且部署、调试都简单。微服务解决的问题是团队协作和独立扩缩容，如果团队只有几个人，强行上微服务只会添加运维负担。

前端目录也做了明确的职责划分：

code复制point-vod-web
├── src/api         // 接口请求模块，按后端模块一一对应
├── src/router      // 路由配置
├── src/store       // 用户状态、全局共享数据
├── src/views       // 页面组件
├── src/components  // 通用组件（上传、播放器、表格封装）
└── src/utils       // 工具函数（token处理、日期格式化等）

这套结构的好处是：前端api目录和后端Controller基本一一对应，前后端联调时，找接口非常快，不会出现“前端随便起名、后端找不到对应代码”的情况。

2. 数据库先行：点播系统的表结构与MySQL初始化细节

写代码之前，我习惯先设计表。表设计定了，接口的出入参基本就有了一半。点播系统的核心表不算多，但每张表的字段都值得认真规划，尤其是状态字段、外键关联和索引设计，直接影响系统后续的性能和扩展性。

2.1 核心表设计解析

这里给出我实际使用的核心表结构，并注释字段含义：

用户表（user）：

sql复制CREATE TABLE `user` (
  `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `username` VARCHAR(50) NOT NULL COMMENT '用户名，唯一',
  `password` VARCHAR(100) NOT NULL COMMENT '密码（BCrypt加密）',
  `nickname` VARCHAR(50) DEFAULT NULL COMMENT '昵称',
  `avatar` VARCHAR(255) DEFAULT NULL COMMENT '头像URL',
  `status` TINYINT NOT NULL DEFAULT 1 COMMENT '状态：1启用，0禁用',
  `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_username` (`username`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';

注意用户名加了唯一索引，这是登录模块的基本保障。密码字段不要存明文，用BCrypt加密。

分类表（video_category）：

sql复制CREATE TABLE `video_category` (
  `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `parent_id` BIGINT NOT NULL DEFAULT 0 COMMENT '父分类ID，0表示顶级',
  `name` VARCHAR(50) NOT NULL COMMENT '分类名称',
  `sort` INT NOT NULL DEFAULT 0 COMMENT '排序值',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='视频分类表';

分类表支持二级甚至多级分类，parent_id为0表示顶级分类。实际开发中，这种无限级分类的查询要么用递归SQL，要么一次性查出来在代码里组装成树形结构，我推荐后者，数据量大时也是可控的。

视频表（video）是整张表的核心，字段相对较多：

sql复制CREATE TABLE `video` (
  `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `title` VARCHAR(200) NOT NULL COMMENT '视频标题',
  `category_id` BIGINT NOT NULL COMMENT '分类ID',
  `cover_url` VARCHAR(255) DEFAULT NULL COMMENT '封面图URL',
  `video_url` VARCHAR(500) DEFAULT NULL COMMENT '视频文件URL，存存储路径',
  `m3u8_url` VARCHAR(500) DEFAULT NULL COMMENT 'HLS播放地址',
  `duration` INT DEFAULT 0 COMMENT '时长（秒）',
  `size` BIGINT DEFAULT 0 COMMENT '文件大小（字节）',
  `status` TINYINT NOT NULL DEFAULT 0 COMMENT '状态：0待审核，1已上架，2已下架',
  `play_count` INT NOT NULL DEFAULT 0 COMMENT '播放次数',
  `create_by` BIGINT DEFAULT NULL COMMENT '上传人ID',
  `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  PRIMARY KEY (`id`),
  KEY `idx_category_status` (`category_id`, `status`),
  KEY `idx_title` (`title`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='视频表';

这块有个细节值得重点说明：视频状态字段status的语义。我见过不少项目把状态简单定为“上架”“下架”，但实际运营时通常还需要“待审核”这个中间态，所以我把0定义为待审核、1为已上架、2为下架。查询前端展示的视频列表时，SQL条件就是 where status = 1，审核后台则查 where status = 0，这样两端的SQL都好写。

另外，针对列表页高频查询，我建了组合索引(category_id, status)。这个细节很重要，点播系统中最常见的查询就是“查某个分类下所有上架视频”，没有这个组合索引，全表扫描在几万条数据时就会明显变慢。标题字段的索引用的是普通索引，虽然不支持前缀索引的优化，但对模糊查询 like '%keyword%' 其实帮助有限，所以我个人更推荐后续用 Elasticsearch 或数据库分词来解决搜索，不在前期过度设计。

播放记录表（play_record）：

sql复制CREATE TABLE `play_record` (
  `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `user_id` BIGINT NOT NULL COMMENT '用户ID',
  `video_id` BIGINT NOT NULL COMMENT '视频ID',
  `progress` INT DEFAULT 0 COMMENT '播放进度（秒）',
  `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  PRIMARY KEY (`id`),
  KEY `idx_user_update` (`user_id`, `update_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='播放记录表';

播放记录表记录了用户的观看历史。这里用(user_id, update_time)做联合索引，因为在“我的观看历史”页面，会经常按用户查最新记录并倒序排列。同理，收藏表直接用user_id + video_id加唯一键，防止重复收藏。

2.2 MySQL 8 初始化与环境坑

关于MySQL的安装配置，其实网上教程很多，但电商、点播类项目要注意几个实操点：

第一，字符集一定要用utf8mb4。MySQL默认的utf8在旧版本里其实是utf8mb3，存不了emoji和部分生僻字，而视频标题、用户昵称中经常会出现特殊符号。建议在my.cnf中配置：

ini复制[mysqld]
character-set-server=utf8mb4
collation-server=utf8mb4_general_ci

然后建库时显式指定：

sql复制CREATE DATABASE point_vod DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

第二，客户端连接时也要防止乱码。使用MySQL Workbench或命令行连接后，先执行 SET NAMES utf8mb4; 再执行SQL，这样能避免从客户端插入的数据因为连接字符集不对导致乱码。

第三，MySQL 8 默认密码加密方式与老客户端不兼容。如果你用旧版客户端连接MySQL 8，可能会报认证失败。在开发环境中，建议这样处理：

sql复制ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY '你的密码';

这是开发环境图省事的做法，生产环境不需要改，直接使用MySQL 8的默认认证方式即可，SpringBoot配置数据源时只要依赖版本匹配就不会有问题。

2.3 初始化脚本和数据准备

源码中我提供了完整的 init.sql 脚本，包含建库、建表、插入初始数据。初始数据会放一个顶级分类和几个二级分类，以及一个测试用户（用户名admin，密码123456）。这类初始化脚本的价值在于：你拿到源码后不用再手动建表，直接执行脚本就可以进入联调阶段，把时间花在主流程上。

我建议你在本地按下面顺序准备环境：

1. 安装MySQL 8，把上述字符集配置配好；
2. 创建数据库并执行 init.sql；
3. 用MySQL Workbench验证数据是否正确插入；
4. 启动SpringBoot应用，配置 application.yml 中的数据库连接；
5. 启动Vue项目，开始联调。

3. 后端从零到跑通：SpringBoot接口分层与MyBatis落地姿势

后端项目的代码量不算大，但每个目录都有明确职责。这一节我会把SpringBoot与MyBatis的关键配置、分层写法、动态SQL、批量插入和播放鉴权接口逐一解释，让你不只是拿到源码能跑，而是能理解为什么这样写。

3.1 application.yml 关键配置

数据源和MyBatis配置是后端的“地基”，配置不对，代码写得再好也起不来。

yaml复制spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/point_vod?useUnicode=true&characterEncoding=utf8mb4&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
    username: root
    password: yourpassword

mybatis:
  mapper-locations: classpath:mapper/*.xml
  type-aliases-package: com.example.pointvod.domain
  configuration:
    map-underscore-to-camel-case: true
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

这里有两个配置项需要特别说明。map-underscore-to-camel-case: true 是MyBatis自动把数据库的下划线字段映射到Java的驼峰属性，比如 create_time 映射到 createTime。这个配置在联调前一定要打开，否则Java实体里的 createTime 查出来全是null，排查起来很迷惑。

log-impl 配置成StdOutImpl是开发阶段用来打印SQL的，所有执行的SQL会直接输出到控制台，方便调试。项目上线前建议改回 org.apache.ibatis.logging.nologging.NoLoggingImpl，避免日志太多刷磁盘，也避免把业务参数打到日志里。

还有allowPublicKeyRetrieval=true这个参数，在MySQL 8 的驱动中，如果连接走的是caching_sha2_password认证，客户端需要先获取公钥，不配置这个参数可能会报安全连接错误。这也是新手最容易踩的坑之一。

3.2 Controller-Service-Mapper 三层结构

我见过很多初学者把所有逻辑都写在Controller里，这对点播系统这种业务稍复杂的项目来说是不合适的。代码分层不是教条，而是为了在业务复杂时让每个层只做一件事。

• Controller层：只负责接收请求、参数校验、调用Service、返回统一Response实体；
• Service层：负责业务逻辑组合，比如视频上下架还要同时更新统计信息，就在这里做事务控制；
• Mapper层：负责数据库的增删改查，一个方法对应一条SQL。

举一个视频列表接口的例子：

java复制@RestController
@RequestMapping("/api/video")
public class VideoController {

    @Autowired
    private VideoService videoService;

    @GetMapping("/list")
    public Result list(@RequestParam(defaultValue = "1") Integer pageNum,
                       @RequestParam(defaultValue = "10") Integer pageSize,
                       @RequestParam(required = false) Long categoryId,
                       @RequestParam(required = false) String keyword) {
        return Result.success(videoService.pageQuery(pageNum, pageSize, categoryId, keyword));
    }
}

Service实现里只做参数整理和调用Mapper：

java复制public PageResult<VideoVO> pageQuery(Integer pageNum, Integer pageSize, Long categoryId, String keyword) {
    // 计算偏移量
    int offset = (pageNum - 1) * pageSize;
    List<VideoVO> list = videoMapper.selectPage(offset, pageSize, categoryId, keyword);
    long total = videoMapper.countPage(categoryId, keyword);
    return PageResult.of(list, total, pageNum, pageSize);
}

注意这里分页我没有用PageHelper插件，而是手写了MySQL的 limit offset。原因有两个：一是这套源码想尽量少依赖插件，让你看到原始SQL；二是在单一数据库场景下，手写limit足够简单、可控，也不容易遇到PageHelper的缓存线程安全问题。如果未来接多数据源或分库分表，再换ShardingSphere也不晚。

3.3 MyBatis XML中的动态SQL与结果映射

MyBatis XML文件是MyBatis的核心优势所在。动态SQL可以让你在一个标签内处理多种查询情况，避免拼接SQL字符串的繁琐。下面是我在视频列表查询里使用的XML：

xml复制<select id="selectPage" resultType="com.example.pointvod.domain.vo.VideoVO">
    SELECT v.id, v.title, v.cover_url AS coverUrl, v.duration,
           v.play_count AS playCount, v.create_time AS createTime,
           c.name AS categoryName
    FROM video v
    LEFT JOIN video_category c ON v.category_id = c.id
    <where>
        <if test="categoryId != null">
            AND v.category_id = #{categoryId}
        </if>
        <if test="keyword != null and keyword != ''">
            AND v.title LIKE CONCAT('%', #{keyword}, '%')
        </if>
        AND v.status = 1
    </where>
    ORDER BY v.create_time DESC
    LIMIT #{offset}, #{pageSize}
</select>

动态SQL的<where>标签会自动处理掉第一个AND，不用你自己拼“where 1=1”。<if>标签则根据是否传入参数来决定条件是否生效。这里我特意用 LEFT JOIN 而不是子查询，是为了减少一次查询，直接拿到分类名称。

注意这个查询里我使用了 v.status = 1 条件放在了动态SQL之外，这是故意为之的。用户端列表永远只展示已上架的视频，这个条件不应该被前端传参控制。如果将来要做管理员可以看到所有状态，就再写一个 selectAdminPage，而不是在同一个查询里加个参数控制，语义清晰。

ResultMap 这块，如果数据库字段和实体属性命名有差异，除了开启驼峰映射外，也可以用显式ResultMap。不过对于大多数情况，驼峰映射已经是够用的。只有当你需要做复杂的多表字段组装时，才需要自定义ResultMap来映射嵌套结果。

3.4 批量插入的正确姿势

视频系统经常需要批量添加视频，比如运营从外部导入一批数据。原生MyBatis实现批量插入，核心是foreach标签：

xml复制<insert id="batchInsert" parameterType="list">
    INSERT INTO video (title, category_id, cover_url, video_url, status, create_time)
    VALUES
    <foreach collection="list" item="item" separator=",">
        (#{item.title}, #{item.categoryId}, #{item.coverUrl}, #{item.videoUrl}, 0, NOW())
    </foreach>
</insert>

批量插入时注意MySQL对SQL语句长度有限制，默认max_allowed_packet是64MB，但实际建议每批不要超过500条，避免一次性拼接出超大SQL。分批插入的逻辑放在Service层：

java复制public void batchInsert(List<Video> videoList) {
    // 每500条执行一次批量插入
    int batchSize = 500;
    for (int i = 0; i < videoList.size(); i += batchSize) {
        int end = Math.min(i + batchSize, videoList.size());
        videoMapper.batchInsert(videoList.subList(i, end));
    }
}

关于批量插入，经常有人问“为什么MyBatis-Plus有批量插入方法，原生MyBatis没有专门的标签”。原因很简单：MyBatis提供的是XML层面的SQL拼接能力，批量插入本身可以用foreach实现；Plus在Service层封装了对批量操作的分批执行、逻辑判断等，属于上层应用封装。理解了原生原理后，无论用不用Plus都游刃有余。

3.5 播放鉴权接口的思路

点播系统对比普通的资源网站，一般多一个播放鉴权需求。什么是播放鉴权？简单说，视频的真实地址不应该暴露在前端页面里，否则别人拷贝页面源码就能拿到视频直链，然后无限下载。一种常见的处理方式是：把视频地址隐藏在鉴权接口后面，只有拥有合法凭证的用户才能获取可播放的地址。

我在源码里实现了一个简单的token鉴权流程：

1. 用户在视频详情页点击播放时，前端将视频ID和用户token发给后端；
2. 后端校验用户是否登录、视频状态是否上架、用户是否有权限；
3. 校验通过后，后端生成一个有时效性的播放签名（playToken），内部包含视频ID、用户ID、过期时间；
4. 前端拿playToken拼接成播放地址，播放器内部再带着token到后端拉取真实的M3U8地址或直接用带签名参数的地址播放；
5. 服务端鉴权过滤器会拦截播放请求，校验playToken，过期或无效直接拒绝。

生成playToken的代码示例：

java复制public String generatePlayToken(Long userId, Long videoId) {
    String source = userId + ":" + videoId + ":" + (System.currentTimeMillis() + 30 * 60 * 1000);
    String sign = DigestUtils.md5Hex(source + secretKey);
    return userId + "." + videoId + "." + (System.currentTimeMillis() + 30 * 60 * 1000) + "." + sign;
}

这里用了MD5签名，虽然不复杂，但足以应付中小型系统的防直链需求。生产环境要更严格，建议使用JWT方式，在token中携带用户信息和过期时间，用公开密钥算法做签名，这样即便token被篡改也无法通过验证。

还有一个常见问题：M3U8的切片文件（.ts）也要做鉴权吗？视情况而定。如果视频是高清资源，建议切片也带上签名参数或使用防盗链Referer校验；如果视频只是公开教学资源，对切片做校验会明显增加CDN回源成本，性能不划算。

4. 前端管理台与播放页：Vue路由、状态管理、M3U8播放器接入

前端这部分，我用的Vue版本是Vue 3，配合Vue Router 4和Pinia做状态管理。很多同学拿到的点播系统源码还是Vue 2的写法，尤其是Vue 2的Options API和Vue 3的Composition API差异比较大，所以这里单独讲清楚。

4.1 Vue项目创建与环境准备

如果你本地还没有Vue环境，按下面几步准备：

1. 安装Node.js（建议去官网下载LTS版本，不要追求最新版，我之前就被Node的版本更新坑过，一些构建工具依赖没跟上，导致试了半天找不到问题）；
2. 安装Vue CLI或者直接用最新的 npm create vue@latest 创建项目：

   bash复制npm create vue@latest
   

   这个命令会问你选择是否配置Router、Pinia、ESLint等，这里全部选是即可，源码项目就是基于这些来写的；
3. 进入项目目录后安装依赖：

   bash复制npm install
   

4. 启动开发服务：

   bash复制npm run dev
   

开发调试时，建议在浏览器安装Vue Devtools插件。这个工具可以实时查看Vue组件树、当前路由、Pinia状态，遇到页面数据不渲染的问题，先打开Devtools看State有没有值、Store有没有被正确注册，效率会高很多。很多“页面白屏”其实都是状态没拿到，不一定是代码逻辑问题。

4.2 路由设计与前端登录守卫

管理后台的典型路由结构：

javascript复制const routes = [
  { path: '/login', component: Login },
  {
    path: '/dashboard',
    component: Layout,
    meta: { requiresAuth: true },
    children: [
      { path: 'video/list', component: VideoList },
      { path: 'video/upload', component: VideoUpload },
      { path: 'category/list', component: CategoryList },
      { path: 'user/list', component: UserList }
    ]
  }
]

在路由守卫里做登录判断：

javascript复制router.beforeEach((to, from, next) => {
  const token = localStorage.getItem('token')
  if (to.meta.requiresAuth && !token) {
    next('/login')
  } else {
    next()
  }
})

这段守卫的逻辑不复杂，但它是整个后台的入口防线。token存在localStorage里，每次请求时通过axios拦截器注入到请求头的Authorization字段。当后端返回401时，前端统一跳转到登录页，并清除本地token。

这样做的考虑是：所有涉及用户信息的接口都由后端校验token，前端只负责把token带到请求头上。路由守卫防止的是“未登录就直接打开后台页面”这种情况，真正安全还是要靠后端接口的权限控制。

4.3 管理后台的核心页面

视频管理列表页是最典型的CRUD页面。我做的列表页包含搜索表单、表格、分页、上下架操作按钮。这里要特别说说表格的“状态”列，我使用el-tag根据不同状态显示不同颜色：

• 待审核：黄色；
• 已上架：绿色；
• 已下架：灰色。

这个设计不只是好看，而是运营人员每天的操作效率都会因为“看一眼颜色就知道状态”而明显提升。源码里写了状态过滤器，前端拿到后端返回的数字状态，转换成对应的文字和颜色。

视频上传页面我做了一个自定义上传组件，支持选择文件后立即向后端发起上传请求，显示进度条。这里用Element Plus的 el-upload 组件就能实现，关键在于 :http-request 覆盖默认上传行为：

javascript复制function customUpload(options) {
  const formData = new FormData()
  formData.append('file', options.file)
  axios.post('/api/upload', formData, {
    headers: { 'Content-Type': 'multipart/form-data' },
    onUploadProgress: (e) => {
      options.onProgress({ percent: Math.round((e.loaded / e.total) * 100) })
    }
  }).then(res => {
    options.onSuccess(res.data)
  }).catch(err => {
    options.onError(err)
  })
}

大文件上传我们后面会专门讲，这里先不展开。上传成功后会拿到文件路径，需要回填到视频信息表单里的“视频地址”字段。

4.4 M3U8播放器接入：从黑屏到能播

点播系统前端最核心的场景，就是播放器播放视频。我们后端的视频处理模块会把上传的视频利用FFmpeg转成HLS切片（也就是生成M3U8索引文件和一串TS切片文件），前端播放器就需要支持M3U8格式。

Vue播放M3U8，我推荐使用 hls.js，轻量、兼容性好，支持点播和直播。如果是iOS Safari，本身原生就支持M3U8，所以要用hls.js时先做能力判断：

javascript复制import Hls from 'hls.js'

function playM3u8(videoElement, url) {
  if (Hls.isSupported()) {
    const hls = new Hls()
    hls.loadSource(url)
    hls.attachMedia(videoElement)
    hls.on(Hls.Events.MANIFEST_PARSED, () => {
      videoElement.play()
    })
  } else if (videoElement.canPlayType('application/vnd.apple.mpegurl')) {
    // Safari原生支持
    videoElement.src = url
    videoElement.play()
  }
}

这里有个极易踩的坑：跨域问题。如果你的前端跑在8080端口，视频文件在9000端口或其他域下，M3U8和TS切片请求同样受浏览器同源策略限制。常见的解决思路两个：

• 生产环境中用Nginx把 /files 路径代理到文件服务器，让前后端和静态资源处于同一个域名下；
• 开发环境中使用Vite或Vue CLI的proxy代理。

Vite开发代理配置：

javascript复制export default defineConfig({
  server: {
    proxy: {
      '/api': 'http://localhost:8080',
      '/files': 'http://localhost:8080'
    }
  }
})

这样前端播放器里的 /files/xxx.m3u8 就通过代理转发到后端服务上，避开了跨域。

播放M3U8黑屏还有一个常见原因：切片地址在M3U8文件里写的是相对路径，但Nginx配置了alias或者location路径不匹配，导致TS切片请求404。处理方式是在播放器里监听错误事件：

javascript复制hls.on(Hls.Events.ERROR, (event, data) => {
  if (data.fatal) {
    switch (data.type) {
      case Hls.ErrorTypes.NETWORK_ERROR:
        hls.startLoad()
        break
      case Hls.ErrorTypes.MEDIA_ERROR:
        hls.recoverMediaError()
        break
      default:
        hls.destroy()
        break
    }
  }
})

加入自动恢复逻辑后，播放体验会稳定很多，尤其是网速波动或服务器短暂卡顿的场景。

4.5 Pinia状态管理与全局数据

在Vue 3中，Pinia取代了Vuex成为官方推荐的状态管理库。在点播系统里，我用Pinia保存用户登录状态、全局配置、侧边栏折叠状态等。

javascript复制export const useUserStore = defineStore('user', {
  state: () => ({
    token: localStorage.getItem('token') || '',
    nickname: '',
    avatar: ''
  }),
  actions: {
    setLoginInfo(data) {
      this.token = data.token
      this.nickname = data.nickname
      this.avatar = data.avatar
      localStorage.setItem('token', data.token)
    },
    logout() {
      this.token = ''
      this.nickname = ''
      this.avatar = ''
      localStorage.removeItem('token')
    }
  }
})

我个人习惯把token直接放到store里统一管理，而不是散落在各个页面。这样任何组件需要判断登录状态，直接引入useUserStore获取即可，比在每个页面读localStorage要清晰得多。

5. 联调与报错现场：跨域、上传、版本问题的完整排查链路

这部分内容是实践中最有价值的部分。源码能跑通，不代表你照着做就能顺风顺水，联调阶段总会遇到各种问题。我把点播系统中出现频率最高的几类报错，按实际排查链路整理成一套“排错手册”，每个问题都告诉你先查什么、再查什么。

5.1 前端跨域：从“Network Error”到接口拉通

现象描述：前端Vue启动后，调用后端接口，浏览器控制台报 Access-Control-Allow-Origin 相关错误，或者axios报 Network Error。

排查链路：

第一步，先确认请求是否真的到达了后端。打开浏览器DevTools的Network面板，看请求状态。如果请求根本没发出，多半是axios配置或路由问题；如果是浏览器拦截了响应，就是CORS问题。

第二步，确认前端开发服务器是否配置了代理。我建议在开发阶段不用CORS，而是直接使用Vite代理，这样前端调 /api 开头的接口会全部代理到后端。代理配置上文已经给出，这同时也是避免M3U8跨域的手段。

第三步，如果你部署时没有用反向代理，而是让前端静态文件和后端接口分开部署在域名或端口的两个源上，那么就必须在后端启用CORS。SpringBoot里的实现：

java复制@Configuration
public class CorsConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOriginPatterns("*")
                .allowedMethods("*")
                .allowedHeaders("*")
                .allowCredentials(true)
                .maxAge(3600);
    }
}

这段配置把原生跨域规则允许全部来源，开发调试时方便。但生产环境不要把 allowedOriginPatterns 设为 *，建议只配置实际前端域名，避免任何站点都能带着用户cookie请求你的后端，引发跨域CSRF风险。

5.2 Maven依赖下载卡在downloading，以及SpringBoot集成MyBatis一直报错

“downloading…”是Maven下载依赖时一种比较典型的状态，依赖从中央仓库下载，由于网络原因或Maven仓库地址不稳定，会一直停留在下载中，或者反复报超时。

这类问题最常见的根源是：你本地Maven配置的中央仓库源太慢。国内开发环境下，把Maven镜像源换成阿里云仓库往往能直接解决。

xml复制<mirror>
  <id>aliyunmaven</id>
  <mirrorOf>*</mirrorOf>
  <name>阿里云公共仓库</name>
  <url>https://maven.aliyun.com/repository/public</url>
</mirror>

配置在~/.m2/settings.xml的<mirrors>节点下。注意每次改完settings.xml，最好重启IDE或执行 mvn clean compile -U 强制更新依赖。

还有一类“SpringBoot集成MyBatis一直报错”的常见原因是版本不匹配。当你新建一个SpringBoot 3.x项目，再用旧的SpringBoot 2.x时代的 mybatis-spring-boot-starter 版本，启动时会报找不到类或自动配置失败。这里给出一套经过验证的稳定性组合：

如果你用SpringBoot 3.x，原来的 javax.servlet 全部变成了 jakarta.servlet，引入依赖时也要留意。MyBatis官方已经发布了适配SpringBoot 3的starter 3.0.x，所以报错时先检查starter版本是不是和SpringBoot大版本对齐。

5.3 大文件上传：分片为什么有必要

视频文件动辄几百MB甚至几个GB，如果只用一次表单提交上传，很容易因为网络抖动导致失败，且失败后要从头再来。我在源码中实现了文件分片上传与后端合并：

• 前端把文件切开，每片大小默认为5MB；
• 每个分片携带文件唯一标识（由文件名、大小、最后修改时间生成的MD5）和分片序号，并发或串行上传；
• 后端按文件标识建立临时目录，逐个接收分片；
• 所有分片传输完成后，前端调用合并接口，后端按序号顺序合并分片，生成完整文件；
• 合并完成后校验文件大小，并删除临时分片目录。

后端的合并核心逻辑：

java复制@PostMapping("/upload/merge")
public Result merge(String identifier, String filename) {
    String tempDir = uploadPath + "/" + identifier;
    File partFiles = new File(tempDir);
    File[] parts = partFiles.listFiles();
    Arrays.sort(parts, Comparator.comparingInt(f -> Integer.parseInt(f.getName())));
    try (FileOutputStream out = new FileOutputStream(uploadPath + "/" + filename)) {
        for (File part : parts) {
            FileInputStream in = new FileInputStream(part);
            byte[] buffer = new byte[1024 * 1024];
            int len;
            while ((len = in.read(buffer)) != -1) {
                out.write(buffer, 0, len);
            }
            in.close();
        }
    }
    // 删除临时目录
    FileUtils.deleteDirectory(partFiles);
    return Result.success();
}

核心注意点：合并时必须按分片序号排序，否则文件就坏了。同时合并过程中考虑磁盘IO压力，建议在Service层对合并操作设计一个最大并发限制，比如单机同时只允许3个合并任务，避免多个大文件同时写入把磁盘IO拖垮。

如果你不想自己实现分片逻辑，也有现成方案，比如引入 tus-js-client 这类断点续传库，配合后端实现tu协议。但作为源码学习项目，手写分片逻辑更能帮助你理解上传链路的细节。

5.4 播放鉴权失败：token过期与播放地址泄露

在实际测试中，播放鉴权最容易出现两类问题：

第一类是token过期。我生成的playToken默认有效期30分钟，用户在页面停留超过30分钟后点击播放，请求会被拒绝。前端碰到403响应时，应该提示用户重新进入页面或刷新token，而不是直接黑屏。

第二类是播放地址绕过鉴权。有的同学直接把视频地址写在video对象的videoUrl字段里，然后前端直接请求/files/xxx.mp4，这样任何人都可以直接看视频，鉴权形同虚设。正确做法是videoUrl只存相对存储路径，不直接暴露给前端，前端能拿到的只有 /api/play/token 接口生成的带签名的播放地址。

5.5 常见错误对照表

这张表可以贴在电脑前面，遇到问题先对号入座，很多时候能省下半小时排查时间。

6. 从开发机到服务器：打包、部署与运行环境配置

很多人在本地能跑起来，一到部署就卡壳。实际上部署并不是多难的事，把下面几个步骤理清，自己也能从容搞定。

6.1 后端打包与启动

后端使用Maven统一管理依赖，打包时跳过测试，避免本地测试环境配置影响打包结果：

bash复制mvn clean package -DskipTests

打出来的Jar包在 target/ 目录下，比如 point-vod-server.jar。上传到服务器后，用命令后台运行：

bash复制nohup java -jar point-vod-server.jar --spring.profiles.active=prod > console.log 2>&1 &

这里的 --spring.profiles.active=prod 用的是项目里的 application-prod.yml，其中数据源、文件上传路径、相关密钥都配置成生产环境值。实际部署时，不要把生产数据库密码写在仓库中，推荐通过环境变量注入：

bash复制export DB_PASSWORD='yourpassword'
java -jar point-vod-server.jar --spring.datasource.password=$DB_PASSWORD

顺便提一个个人习惯：给SpringBoot项目自定义一个启动Banner（终端的字符画），可以用网上常见的 springboot banner生成器 快速生成，把 banner.txt 放到 src/main/resources 下。这虽然不是功能需求，但每次部署看到清晰的版本标识，能直观确认启动的是哪个环境，对于多环境发布的场景还是挺有用的。

6.2 前端打包与Nginx配置

前端开发完毕后，执行构建：

bash复制npm run build

生成的文件在 dist/ 目录下。把整个 dist 目录上传到服务器，例如放到 /usr/share/nginx/point-vod-web/，然后配置Nginx。

Nginx需要做三件事：托管静态文件、反向代理后端API、代理视频文件访问。

一个可复用的Nginx配置：

nginx复制server {
    listen 80;
    server_name your-domain.com;

    # 1. 托管前端静态文件
    root /usr/share/nginx/point-vod-web;
    index index.html;

    # Vue Router history模式，刷新页面时避免404
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 2. 代理后端API
    location /api/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # 3. 代理视频文件访问
    location /files/ {
        alias /data/vod-files/;
        add_header Access-Control-Allow-Origin *;
        add_header Cache-Control "public, max-age=86400";
    }
}

关于Vue Router的history模式，部署时最容易踩的坑就是：直接访问 http://your-domain.com/video/list 会404。原因很简单，服务器上不存在这个物理路径，Nginx需要把不存在的路径都回退到 index.html。上面的 try_files 就是干这个的。如果你开发时用的是默认hash模式（地址栏有 #），则不会遇到这个问题，但用户体验和美观度差一些，所以源码里我用的是history模式。

6.3 视频文件的存储与访问性能

视频文件的存储路径我建议放在应用外部，不要放在Jar包内部或项目目录里。比如 /data/vod-files/，这样应用升级时不会覆盖视频文件，备份也更方便。应用配置文件中的 file.upload-path 指向这个外部目录。

开发时把文件存本地没问题，生产环境则要考虑几点：

• 如果视频量大，优先考虑OSS（对象存储），Nginx只代理前端，视频走CDN回源到OSS，能极大降低应用服务器的带宽压力；
• 如果必须存在本地服务器，视频目录和系统分区最好分开挂载，避免视频文件写满系统盘导致服务器崩溃；
• 对M3U8切片文件，Nginx可以开启 gzip on; 对ts切片有一定压缩收益，但更大的收益是设置合理的缓存时间，减少重复请求。

6.4 数据备份与日常维护

MySQL数据备份是运维的基本功。最简单实用的方式是定时任务执行mysqldump：

bash复制0 2 * * * mysqldump -uroot -p'password' point_vod > /backup/point_vod_$(date +\%Y\%m\%d).sql

注意crontab中，% 需要转义，否则shell会解释成换行符。生产环境我会额外做一个保留策略，比如只保留最近30天的备份：

bash复制find /backup -name "point_vod_*.sql" -mtime +30 -delete

再扩展一点：对于点播类系统，MySQL里存的是元数据，视频文件才是大头。备份方案要区分对待，数据库每天全量备份，视频文件则要评估是否全量备份，如果视频总量太大，也可以只做增量同步或异地冗余。

6.5 后续可以扩展的方向

这套源码结构虽然完整，但距离生产级还要根据你的实际业务场景做扩展。我个人最建议你优先考虑的扩展点有三个：

• 接入对象存储OSS，把本地文件存储替换成云存储，解放服务器磁盘压力；
• 引入Redis缓存视频列表、播放凭证，避免频繁请求MySQL；
• 用FFmpeg做视频转码和切片自动化，而不是只用提前处理好的测试视频。

我在后面的使用中，也确实是把这套源码当成一个“可扩展的脚手架”而非“固定成品”来对待。每当新项目需要点播能力，我都是先从这个骨架里拷贝基础模块，再针对具体需求做加减法，效率比从零开始高得多。这也正是我写这份整理记录的初衷。