基于Spring Boot与Docker的YOLOv8检测服务实战

引言：YOLO------目标检测领域的标杆

YOLO（You Only Look Once）是计算机视觉领域最具影响力的目标检测算法之一。自2015年Joseph Redmon首次提出以来，YOLO以其端到端、单阶段、实时检测的特性迅速成为工业界和学术界的热门选择。与传统的两阶段检测器（如Faster R-CNN）不同，YOLO将目标检测视为回归问题，通过一次前向传播即可同时预测目标的类别和边界框，在保证较高精度的同时实现了惊人的检测速度。

YOLO系列经过多次迭代，目前已发展至YOLOv8，由Ultralytics公司维护。YOLOv8在架构上进行了多项优化，支持目标检测、实例分割、姿态估计等多种任务，并提供了简洁的Python接口。然而，在实际生产环境中，我们往往需要将YOLO的能力封装为RESTful API，以便与其他业务系统集成。本文将分享一个基于Spring Boot + Docker容器化YOLOv8的完整实现方案，该方案支持图片、视频和实时流的检测，并提供了多模型切换、断点续传视频播放等企业级特性。

项目背景与设计目标

在传统的YOLO服务化方案中，通常直接在宿主机上安装Python环境和YOLO依赖，然后通过Flask/FastAPI对外提供服务。这种方式存在几个痛点：

环境隔离困难：依赖冲突、Python版本管理复杂。
部署一致性差：不同机器环境差异可能导致运行异常。
资源管理不便：难以限制CPU/GPU资源使用。
多版本模型管理：模型文件散落各处，切换不便。

为此，我们设计了Docker容器化+Spring Boot后端 的方案，将YOLO环境封装在容器中，宿主机仅运行Java应用，通过docker exec命令调用容器内的YOLO命令。这样做的好处是：

环境隔离：YOLO依赖完全封装在镜像中，与宿主无关。
资源管控：可通过Docker限制容器CPU/内存/GPU。
模型即配置：模型文件挂载到容器内，通过配置动态选择。
统一监控：所有业务逻辑集中在Spring Boot层，便于集成日志、鉴权、限流等。

系统架构概览

整体架构如下图所示（文字描述）：

客户端（浏览器/移动端）通过HTTP上传图片、视频文件或提供实时流URL。
Spring Boot控制器接收请求，调用对应的工具类处理。
工具类 负责：
- 将上传的文件保存到Docker挂载目录（宿主机）。
- 执行docker exec命令调用容器内的YOLO命令进行检测。
- 解析容器输出的结果，并将检测结果图片/视频复制到公共访问目录。
Docker容器 （yolo-service）内预装了YOLOv8及依赖，通过挂载卷共享宿主机文件。
前端可通过API获取检测结果，视频支持Range请求实现流式播放。

核心代码分为以下几个模块：

YoloConfig：配置类，从application.yml读取Docker路径、模型映射等。
YoloDetectUtil：图片检测工具，调用YOLO预测图片。
YoloVideoDetectUtil：视频检测工具，支持视频上传、检测结果视频提取。
YoloVideoStreamDetectUtil：实时流检测工具，下载流片段进行检测。
YoloController：REST控制器，暴露API接口。
VideoConverterUtil：视频格式转换工具（基于JavaCV）。

接下来，我们将逐一解析这些核心组件。

1. YoloConfig：配置管理

配置是服务的基石。我们通过@ConfigurationProperties将yolo前缀的配置映射为Java对象，便于代码中使用。

java 复制代码

@Data
@Component
@ConfigurationProperties(prefix = "yolo")
public class YoloConfig {
    private String dockerMountPath;      // 宿主机挂载根目录
    private String containerMountPath;   // 容器内挂载路径（对应dockerMountPath）
    private String containerDataPath;     // 容器内数据目录（如 /ultralytics/yolo_data）
    private String localTempPath;         // 本地临时文件目录（用于存放可公开访问的视频）
    private String dockerImage;            // Docker镜像名
    private String device = "cpu";         // 设备类型 cpu/cuda
    private Map<String, String> models;    // 多模型映射：版本 -> 容器内模型路径
    private String currentModel = "default"; // 当前使用的模型版本

    public String getCurrentModelPath() {
        if (models != null && models.containsKey(currentModel)) {
            return models.get(currentModel);
        }
        // 默认值
        return "/ultralytics/yolov8n.pt";
    }
    // ... 其他辅助方法
}

典型application.yml配置示例：

yaml 复制代码

yolo:
  docker-mount-path: /data/yolo
  container-mount-path: /ultralytics
  container-data-path: /ultralytics/yolo_data
  local-temp-path: /data/temp
  docker-image: ultralytics/ultralytics:latest
  device: cpu
  models:
    default: /ultralytics/yolov8n.pt
    v8s: /ultralytics/yolov8s.pt
    custom: /models/custom.pt
  current-model: default

设计亮点：

通过Map<String,String>支持任意数量的模型版本，前端可指定modelVersion参数进行动态切换。
提供getContainerImagePath、getLocalResultPath等方法，统一路径拼接逻辑，避免硬编码。

2. YoloDetectUtil：图片检测核心

图片检测是最基础的功能。流程如下：

保存上传的图片到dockerMountPath/yolo_data/目录。
设置容器内文件权限（确保容器可读）。
执行Docker命令调用YOLO预测。
解析YOLO输出，提取检测到的物体类别和置信度。
查找生成的带标注的结果图片（位于runs/detect/下）。
清理临时文件。

关键代码片段（省略部分细节）：

java 复制代码

public YoloDetectResult detectImage(MultipartFile file, String modelVersion) {
    // 1. 保存图片
    String fileName = saveFile(file);
    // 2. 调用YOLO
    String dockerOutput = callYoloServer(fileName, modelVersion);
    // 3. 解析输出
    List<DetectObject> objects = parseFromDockerOutput(dockerOutput);
    // 4. 查找结果图片
    String resultImagePath = findResultImage(dockerMountPath, fileName);
    return YoloDetectResult.builder()
            .success(true)
            .detectObjects(objects)
            .resultImagePath(resultImagePath)
            .build();
}

YOLO命令构造

java 复制代码

private String callYoloServer(String fileName, String modelVersion) {
    List<String> cmdList = new ArrayList<>();
    cmdList.add("docker");
    cmdList.add("exec");
    cmdList.add(YOLO_CONTAINER_NAME);
    cmdList.add("yolo");
    cmdList.add("detect");
    cmdList.add("predict");
    
    // 动态选择模型路径
    String modelPath = resolveModelPath(modelVersion);
    cmdList.add(String.format("model=%s", modelPath));
    cmdList.add(String.format("source=%s", containerDataPath + "/" + fileName));
    cmdList.add("project=/ultralytics/yolo_data/runs");
    cmdList.add("name=detect");
    cmdList.add("save=True");
    cmdList.add("verbose=True");
    cmdList.add(String.format("device=%s", yoloConfig.getDevice()));
    // ... 执行ProcessBuilder
}

解析YOLO输出

YOLO的verbose=True会在控制台输出检测结果，格式如：

复制代码

image 1/1 /ultralytics/yolo_data/test.jpg: 640x480 2 persons, 1 car, 45.3ms

我们通过正则表达式提取物体和置信度，并处理多种格式（如cup 0.92、cup (0.92)、2 cups）。解析逻辑在parseFromDockerOutput方法中。

3. YoloVideoDetectUtil：视频检测

视频检测比图片复杂，主要体现在：

文件可能较大，需设置超时。
YOLO输出包含帧数信息。
需要找到生成的结果视频，并转换为前端可播放的MP4格式（支持流式）。

流程概览

验证视频格式和大小（支持常见格式如mp4、avi、mov，限100MB）。
保存视频到挂载目录。
调用docker exec执行视频检测，增加imgsz=320、conf=0.6等参数以平衡速度与精度。
解析输出，获得总帧数和物体统计。
查找结果视频文件（YOLO默认输出在runs/detect/下，命名可能为原文件名或加后缀）。
将结果视频复制到公共目录（localTempPath/videos），并利用VideoConverterUtil转换为MP4（若原格式不是MP4）。
返回可访问的URL路径（如/api/yolo/results/videos/xxx.mp4）。

视频转换与流式播放

VideoConverterUtil基于JavaCV的FFmpeg封装，实现任意格式到MP4的转换：

java 复制代码

public boolean convertToMp4(String inputPath, String outputPath) {
    FFmpegFrameGrabber grabber = new FFmpegFrameGrabber(inputFile);
    FFmpegFrameRecorder recorder = new FFmpegFrameRecorder(outputPath,
            grabber.getImageWidth(), grabber.getImageHeight(), grabber.getAudioChannels());
    recorder.setVideoCodec(avcodec.AV_CODEC_ID_H264);
    recorder.setAudioCodec(avcodec.AV_CODEC_ID_AAC);
    // ... 逐帧录制
}

转换后的MP4文件存放在localTempPath/videos下，通过YoloController的/stream-video/{filename}接口提供流式播放，该接口支持HTTP Range请求，实现视频拖动和断点续传。

4. YoloVideoStreamDetectUtil：实时流检测

对于RTSP/RTMP/HTTP直播流，我们无法直接传给YOLO容器（YOLO虽然支持流地址，但可能会持续检测直到手动停止）。为了控制检测时长，我们采用先下载片段再检测的策略：

验证流地址格式（支持RTSP、RTMP、HTTP/HTTPS）。
在容器内使用ffmpeg下载10秒的视频片段到临时文件。
对该临时文件执行YOLO检测（save=False，不保存视频）。
解析检测结果，统计物体类别。
清理临时文件。

这样既避免了长时间占用，又能快速获得流中的物体信息。

关键代码：

java 复制代码

// 下载10秒流
List<String> downloadCmd = Arrays.asList(
    "docker", "exec", YOLO_CONTAINER_NAME,
    "ffmpeg", "-i", streamUrl, "-t", "10", "-c", "copy", "-y", tempFile
);
// 检测临时文件
List<String> detectCmd = Arrays.asList(
    "docker", "exec", YOLO_CONTAINER_NAME,
    "yolo", "predict", "model=...", "source=" + tempFile,
    "save=False", "verbose=True", "max_det=100", "conf=0.5"
);

5. YoloController：REST API设计

控制器负责接收请求、调用工具类并返回结果。我们通过@CrossOrigin全局配置解决了跨域问题，特别是针对视频流需要暴露Range、Content-Range等头。

主要接口

方法	路径	说明
POST	`/api/yolo/detect`	图片检测，参数`file`，可选`modelVersion`
POST	`/api/yolo/detect/video`	视频检测，参数`file`
POST	`/api/yolo/detect/stream`	流检测，参数`streamUrl`
GET	`/api/yolo/results/videos/{filename}`	获取结果视频（普通下载）
GET	`/api/yolo/stream-video/{filename}`	视频流式播放（支持Range）
GET	`/api/yolo/results/images/{filename}`	获取结果图片

视频流式播放实现

流式播放的核心是处理Range头，返回206 Partial Content，并设置Content-Range。代码中使用RandomAccessFile定位到指定位置并发送数据块。同时，捕获客户端断开连接异常（如Broken pipe），避免服务端报错。

java 复制代码

@GetMapping("/stream-video/{filename:.+}")
public void streamVideo(@PathVariable String filename,
                        HttpServletResponse response,
                        HttpServletRequest request) {
    File videoFile = ...;
    String range = request.getHeader("Range");
    if (range == null) {
        // 返回完整文件
    } else {
        // 解析range，返回部分内容
    }
}

6. 多模型切换支持

在YoloConfig中我们定义了models映射，并在YoloDetectUtil中允许传入modelVersion参数。调用YOLO命令时，根据版本获取对应的容器内模型路径。这样，前端可以轻松切换不同精度的模型，甚至上传自定义模型。

示例：

java 复制代码

// 工具类中
String modelPath = modelVersion != null ? yoloConfig.getModelPath(modelVersion) 
                                         : yoloConfig.getCurrentModelPath();

7. 异常处理与客户端断开

文件上传和视频检测都可能遇到客户端提前断开连接的情况（如用户关闭浏览器）。在Spring Boot中，当客户端断开时，写响应会抛出异常。我们在控制器中捕获这些异常并仅记录为debug级别，避免堆栈污染。

java 复制代码

private boolean isClientDisconnectException(Exception e) {
    String msg = e.getMessage();
    return msg != null && (msg.contains("Broken pipe") || msg.contains("Connection reset"));
}

同时，对于视频检测这样的耗时操作，如果客户端断开，检测任务可能仍在后台进行，我们返回一个提示信息告知用户任务将继续，但结果无法推送（只能后续查询）。

8. 总结与展望

本文详细介绍了如何基于Spring Boot和Docker构建一个企业级的YOLO检测服务。该服务具备以下特点：

容器化部署：环境隔离，简化运维。
多模型支持：灵活切换不同版本的YOLO模型。
视频流式播放：支持Range请求，优化用户体验。
实时流检测：通过下载片段方式实现流内容分析。
完善的异常处理：优雅处理客户端断开。

目前的服务已经可以满足图片、视频和直播流的检测需求。然而，在实际应用中，我们往往还需要根据特定场景对YOLO模型进行二次训练（即微调），以提升特定类别的检测精度。例如，在工业质检中需要检测特定产品缺陷，或在安防场景中需要识别特定行为。

下一章，我们将深入探讨如何使用自己的数据集对YOLOv8进行二次训练，包括数据标注、格式转换、训练参数调优，以及如何将训练好的自定义模型无缝集成到当前的服务体系中。敬请期待！

注：本文所展示代码为实际项目片段，完整源码可参考项目仓库（如果有）。如有疑问，欢迎在评论区留言讨论。