Windows 下用 Docker 部署 YOLOv8 并集成到 Spring Boot 项目

结果图默认保存在容器内 /ultralytics/runs/detect/predict，本地是看不到的。我习惯在命令里直接指定输出到挂载目录：

yolo detect predict model=yolov8n.pt source=/yolo_data/test.jpg save=True project=/yolo_data/runs name=detect

这样结果就会直接写到 D:\yolo_test\runs\detect 下。

常见问题

1. FileNotFoundError: /yolo_data/test.jpg does not exist

原因通常是：

• 本地目录没有 test.jpg，或者文件名大小写不匹配
• 目录挂载失败（在容器内 ls /yolo_data 为空）

解决：检查路径写法，确认 Docker Desktop 文件共享已添加对应目录。

2. 本地看不到检测结果图片

因为默认保存路径在容器内。要么用上面指定 project 的方式，要么在容器内手动拷贝：

cp -r /ultralytics/runs/detect/predict /yolo_data/

集成到 Spring Boot

Docker 里的 YOLO 能跑通了，剩下的就是让 Java 代码去调它。我用的是已有的 Spring Boot 项目，额外加几个类和配置就行，不用从头搭。

新增依赖

在 pom.xml 里加文件上传和命令执行相关的工具包，原来的依赖不动：

<properties>
    <commons-io.version>2.15.1</commons-io.version>
    <commons-lang3.version>3.14.0</commons-lang3.version>
</properties>

<dependencies>
    <!-- 文件处理 -->
    <dependency>
        <groupId>commons-io</groupId>
        <artifactId>commons-io</artifactId>
        <version>${commons-io.version}</version>
    </dependency>
    <!-- 字符串等工具 -->
    <dependency>
        <groupId>org.apache.commons</groupId>
        <artifactId>commons-lang3</artifactId>
        <version>${commons-lang3.version}</version>
    </dependency>
    <!-- SSH 工具（虽然这里没用到 SSH，但保留原项目依赖） -->
    <dependency>
        <groupId>ch.ethz.ganymed</groupId>
        <artifactId>ganymed-ssh2</artifactId>
        <version>262</version>
    </dependency>
</dependencies>

配置文件

在 application.yml 里加入 YOLO 相关配置，同时限制一下上传文件大小：

yolo:
  docker-mount-path: D:\yolo_test
  container-mount-path: /yolo_data
  model-name: yolov8n.pt
  container-result-path: /yolo_data/runs/detect
  local-temp-path: D:\yolo_test\temp
  docker-image: ultralytics/ultralytics:latest

spring:
  servlet:
    multipart:
      max-file-size: 10MB
      max-request-size: 50MB

核心代码

四个类就够：配置读取、结果实体、检测工具类、控制器。

1. YoloConfig.java – 用 @ConfigurationProperties 把上面配置读进来

package com.ruoyi.config;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Data
@Component
@ConfigurationProperties(prefix = "yolo")
public class YoloConfig {
    private String dockerMountPath;
    private String containerMountPath;
    private String modelName;
    private String containerResultPath;
    private String localTempPath;
    private String dockerImage;
}

2. YoloDetectResult.java – 封装返回给前端的检测信息

package com.ruoyi.entity;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;
import java.util.List;

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class YoloDetectResult {
    private boolean success;
    private String errorMsg;
    private List<DetectObject> detectObjects;
    private long costTime;
    private String resultImagePath;

    @Data
    @Builder
    @NoArgsConstructor
    @AllArgsConstructor
    public static class DetectObject {
        private String className;
        private int count;
        private float confidence;
    }
}

3. YoloDetectUtil.java – 核心逻辑：接收 MultipartFile，存到挂载目录，拼 Docker 命令，解析输出，返回结果。注意 Windows 路径要转换成 / 格式。

package com.ruoyi.util;

import com.ruoyi.config.YoloConfig;
import com.ruoyi.entity.YoloDetectResult;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;
import org.springframework.web.multipart.MultipartFile;

import java.io.File;
import java.io.IOException;
import java.util.*;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

@Slf4j
@Component
@RequiredArgsConstructor
public class YoloDetectUtil {
    private final YoloConfig yoloConfig;
    private static final Pattern DETECT_PATTERN = Pattern.compile("(\\d+)\\s+([a-zA-Z_]+)");

    public YoloDetectResult detectImage(MultipartFile file) {
        long startTime = System.currentTimeMillis();
        try {
            if (file.isEmpty()) {
                return YoloDetectResult.builder().success(false).errorMsg("上传的图片文件为空").build();
            }
            String originalFilename = file.getOriginalFilename();
            if (originalFilename == null || !originalFilename.matches(".*\\.(jpg|jpeg|png|bmp)$")) {
                return YoloDetectResult.builder().success(false).errorMsg("仅支持 jpg/jpeg/png/bmp 格式").build();
            }

            File tempDir = new File(yoloConfig.getLocalTempPath());
            if (!tempDir.exists() && !tempDir.mkdirs()) {
                log.error("创建临时目录失败：{}", yoloConfig.getLocalTempPath());
                return YoloDetectResult.builder().success(false).errorMsg("创建临时目录失败").build();
            }

            String fileName = UUID.randomUUID() + "_" + originalFilename;
            String localImagePath = yoloConfig.getDockerMountPath() + File.separator + fileName;
            File localImageFile = new File(localImagePath);
            file.transferTo(localImageFile);
            log.info("图片保存至：{}", localImagePath);

            String containerImagePath = yoloConfig.getContainerMountPath() + "/" + fileName;
            String dockerCmd = String.format(
                "docker run --rm -v %s:%s %s yolo detect predict model=%s source=%s save=True project=%s name=detect",
                yoloConfig.getDockerMountPath().replace("\\", "/"),
                yoloConfig.getContainerMountPath(),
                yoloConfig.getDockerImage(),
                yoloConfig.getModelName(),
                containerImagePath,
                yoloConfig.getContainerResultPath()
            );
            log.info("执行 Docker 命令：{}", dockerCmd);

            Process process = Runtime.getRuntime().exec(new String[]{"cmd", "/c", dockerCmd});
            int exitCode = process.waitFor();
            if (exitCode != 0) {
                String errorMsg = new String(process.getErrorStream().readAllBytes());
                log.error("YOLO 检测失败，exitCode={}，错误信息：{}", exitCode, errorMsg);
                return YoloDetectResult.builder().success(false).errorMsg("执行检测失败：" + errorMsg).build();
            }

            String output = new String(process.getInputStream().readAllBytes());
            log.info("YOLO 输出：{}", output);
            List<YoloDetectResult.DetectObject> detectObjects = parseDetectResult(output);

            String resultImagePath = yoloConfig.getDockerMountPath() + File.separator
                    + "runs" + File.separator + "detect" + File.separator + "detect" + File.separator + fileName;
            long costTime = System.currentTimeMillis() - startTime;

            return YoloDetectResult.builder()
                    .success(true)
                    .detectObjects(detectObjects)
                    .costTime(costTime)
                    .resultImagePath(resultImagePath)
                    .build();
        } catch (IOException e) {
            log.error("IO 异常", e);
            return YoloDetectResult.builder().success(false).errorMsg("IO 异常：" + e.getMessage()).build();
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            return YoloDetectResult.builder().success(false).errorMsg("检测被中断").build();
        } catch (Exception e) {
            log.error("检测异常", e);
            return YoloDetectResult.builder().success(false).errorMsg("检测异常：" + e.getMessage()).build();
        }
    }

    private List<YoloDetectResult.DetectObject> parseDetectResult(String output) {
        List<YoloDetectResult.DetectObject> result = new ArrayList<>();
        if (output == null || output.isEmpty()) return result;
        Matcher matcher = DETECT_PATTERN.matcher(output);
        Map<String, Integer> countMap = new HashMap<>();
        while (matcher.find()) {
            int count = Integer.parseInt(matcher.group(1));
            String className = matcher.group(2);
            countMap.put(className, countMap.getOrDefault(className, 0) + count);
        }
        for (Map.Entry<String, Integer> entry : countMap.entrySet()) {
            result.add(YoloDetectResult.DetectObject.builder()
                    .className(entry.getKey())
                    .count(entry.getValue())
                    .confidence(0.9f)
                    .build());
        }
        return result;
    }
}

4. YoloController.java – 对外暴露 POST /api/yolo/detect 接口

package com.ruoyi.controller;

import com.ruoyi.entity.YoloDetectResult;
import com.ruoyi.util.YoloDetectUtil;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;

@Slf4j
@RestController
@RequestMapping("/api/yolo")
@RequiredArgsConstructor
public class YoloController {
    private final YoloDetectUtil yoloDetectUtil;

    @PostMapping("/detect")
    public ResponseEntity<YoloDetectResult> detectImage(@RequestParam("file") MultipartFile file) {
        try {
            YoloDetectResult result = yoloDetectUtil.detectImage(file);
            return ResponseEntity.ok(result);
        } catch (Exception e) {
            log.error("接口异常", e);
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body(YoloDetectResult.builder().success(false).errorMsg("接口异常：" + e.getMessage()).build());
        }
    }
}

启动类记得扫描 com.ruoyi 包：

@SpringBootApplication(scanBasePackages = "com.ruoyi")
@EnableConfigurationProperties
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

测试接口

项目启动后（我用的端口 8889），用 Postman 发一个 POST 请求到 http://localhost:8889/api/yolo/detect，form-data 里 key 填 file，选择一张 jpg 图片上传。返回 JSON 大概像这样：

{
  "success": true,
  "errorMsg": null,
  "detectObjects": [
    {"className": "cup", "count": 1, "confidence": 0.9},
    {"className": "tv", "count": 1, "confidence": 0.9},
    {"className": "mouse", "count": 1, "confidence": 0.9}
  ],
  "costTime": 1200,
  "resultImagePath": "D:\\yolo_test\\runs\\detect\\detect\\xxx_test.jpg"
}

可能遇到的坑

• Docker 命令执行失败：检查 Docker Desktop 是否启动，文件共享目录是否添加。
• 检测速度慢：yolov8n 已经是 nano 尺寸，纯 CPU 推理慢是正常的。如果业务有实时性要求，要么换 GPU（需要 nvidia-docker），要么在接收端做异步处理，不要阻塞 HTTP 请求。
• 结果图片路径不对：确认 docker run 命令里的 project 参数有没有写对，最好用绝对路径挂载目录。
• 文件大小限制：可以在 application.yml 里调大 max-file-size，但注意 Docker 容器内处理大图也会更耗时。

整个方案谈不上完美，但胜在快，拿来对接个管理后台、小程序图片检测什么的完全够用。如果需要批量处理或视频流，可以在此基础上加队列和异步逻辑，基本思路是一样的。