Windows环境下Docker部署YOLOv8并集成Spring Boot的完整步骤记录_Java

前言

在 ai 目标检测领域，yolo（you only look once）系列模型以其高效、精准的特点成为主流选择，而 spring boot 作为 java 生态最流行的 web 开发框架，能轻松将 yolo 的检测能力封装为可复用的接口。本文将全程还原 windows 环境下，通过 docker 部署 yolov8 模型，并集成到 spring boot 项目的完整流程，包含环境准备、问题排查、代码集成、接口测试，适合有一定 java 和 docker 基础的开发者参考。

一、前言：为什么选择 docker + spring boot + yolov8？

在本地部署 yolo 模型时，常常会遇到环境依赖复杂、版本冲突、跨平台兼容性差等问题，而 docker 能完美解决这些痛点——通过容器化封装 yolo 运行所需的所有依赖，实现“一次构建，到处运行”。

结合 spring boot 的优势，我们可以将 yolo 的图片检测能力封装为 http 接口，支持前端上传图片、后端返回检测结果，轻松集成到小程序、app、管理系统等各类业务场景中，实现“检测能力接口化、业务集成轻量化”。

本文核心目标：在 windows 环境下，完成 docker 部署 yolov8 → 解决部署过程中的常见问题 → 将 yolo 检测能力集成到 spring boot 项目 → 提供可直接调用的图片检测接口。

二、环境准备（必看）

2.1 基础环境清单

操作系统：windows 10/11（建议开启 wsl2，提升 docker 性能）
docker：docker desktop（版本 20.0 以上）
jdk：17（spring boot 3.2.x 要求）
maven：3.6+（项目构建）
spring boot：3.2.4
yolo 模型：yolov8n（轻量版，适合 cpu 运行，无需 gpu 加速）

2.2 前置环境配置

2.2.1 docker desktop 配置（关键）

安装 docker desktop 后，开启 wsl2 后端（性能优于 hyper-v）：
- 打开 docker desktop → settings → general → 勾选 “use the wsl 2 based engine”
- 重启 docker desktop，确保服务正常启动（右下角 docker 图标显示绿色）
配置文件共享（避免挂载目录权限问题）：
- 打开 docker desktop → settings → resources → file sharing
- 点击 “+” 按钮，添加本地目录 d:\yolo_test（用于挂载 docker 容器，存储图片和检测结果），保存后重启 docker

2.2.2 项目基础准备

本文基于已有的 spring boot 项目（原有功能包含 ollama 大模型集成、pgvector 向量存储、阿里云语音识别等），核心是在原有项目基础上新增 yolo 图片检测模块，无需从零搭建 spring boot 项目。

三、docker 部署 yolov8 模型（全程实操+问题排查）

这一步是核心基础，我们将通过 docker 拉取 yolov8 官方镜像，运行容器并完成图片检测，解决部署过程中最常见的“文件找不到”“挂载失败”等问题。

3.1 拉取 yolov8 官方 docker 镜像

打开 powershell（管理员模式），执行以下命令拉取官方镜像（内置 yolov8 所有依赖，无需手动配置）：

docker pull ultralytics/ultralytics:latest

镜像拉取完成后，执行 docker images 可查看镜像是否存在。

3.2 运行 docker 容器并挂载本地目录

核心命令（挂载本地 d:\yolo_test 到容器内 /yolo_data，实现本地与容器文件互通）：

docker run -it --rm -v /d/yolo_test:/yolo_data ultralytics/ultralytics:latest

命令说明：

-it：交互式终端，方便在容器内执行命令
--rm：容器退出后自动删除，避免残留
-v /d/yolo_test:/yolo_data：目录挂载（windows 路径需用 /d/ 替代 d:\，docker 才能识别）

3.3 执行 yolov8 图片检测（首次实操）

3.3.1 准备测试图片

在本地 d:\yolo_test 目录下，放入一张测试图片，命名为 test.jpg（注意：文件名和后缀必须完全匹配，避免大小写错误，如 test.jpg、test.jpeg 都会导致失败）。

3.3.2 执行检测命令

在容器内（命令行显示 root@xxx:/ultralytics#），执行以下命令：

yolo detect predict model=yolov8n.pt source=/yolo_data/test.jpg save=true

命令说明：

model=yolov8n.pt：使用 yolov8 轻量版模型（n=纳米版，适合 cpu 运行，体积小、速度快）
source=/yolo_data/test.jpg：检测源为容器内挂载目录下的 test.jpg
save=true：保存检测结果（带检测框的图片）

3.4 常见问题排查（重点！）

首次运行大概率会遇到以下问题，本文全程还原排查过程，帮你快速解决。

问题1：filenotfounderror: /yolo_data/test.jpg does not exist

报错原因：容器内找不到指定图片，核心是两个原因之一：

本地 d:\yolo_test 目录下没有 test.jpg，或文件名/后缀错误
目录挂载失败，容器内 /yolo_data 目录为空

解决步骤：

先在容器内执行 ls /yolo_data，查看挂载目录是否有文件：
- 如果输出为空：说明挂载失败，重新执行容器运行命令（确保路径是 /d/yolo_test，而非 d:\yolo_test）
- 如果输出 yolo_data（子目录）：说明图片放在了 d:\yolo_test\yolo_data 下，需修改命令为 source=/yolo_data/yolo_data/test.jpg
确认本地 d:\yolo_test 下有 test.jpg，重新执行检测命令

问题2：检测结果保存到容器内，本地看不到

报错现象：检测成功，但本地 d:\yolo_test 目录下没有检测结果

原因：yolo 默认将结果保存到容器内 /ultralytics/runs/detect/predict，而非挂载目录

解决方法：

手动复制结果到挂载目录（容器内执行）：
```
cp -r /ultralytics/runs/detect/predict /yolo_data/
```
下次检测直接指定保存路径（推荐），修改命令为：
```
yolo detect predict model=yolov8n.pt source=/yolo_data/test.jpg save=true project=/yolo_data/runs name=detect
```
这样结果会直接保存到 /yolo_data/runs/detect，对应本地 d:\yolo_test\runs\detect

3.5 检测成功验证

检测成功后，容器内会输出类似以下日志：

image 1/1 /yolo_data/test.jpg: 640x480 1 cup, 1 tv, 1 mouse, 1 refrigerator, 1 book, 63.4ms
speed: 4.6ms preprocess, 63.4ms inference, 8.6ms postprocess per image at shape (1, 3, 640, 480)
results saved to /yolo_data/runs/detect

此时打开本地 d:\yolo_test\runs\detect 目录，会看到带检测框的 test.jpg，图片上会标注出识别到的物体（如杯子、电视、鼠标等），说明 docker 部署 yolov8 成功！

四、spring boot 集成 yolov8 检测能力（完整代码）

docker 部署 yolov8 成功后，我们将其集成到 spring boot 项目，提供 http 接口，支持前端上传图片、后端返回检测结果（识别的物体、数量、耗时、结果图片路径）。

4.1 项目改造：pom.xml 依赖新增

在原有 pom.xml 基础上，新增文件操作、命令执行相关依赖（用于处理图片上传、调用 docker 命令）：

<!-- 新增依赖版本定义 -->
<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>
    
    <!-- 命令执行相关 -->
    <dependency>
        <groupid>ch.ethz.ganymed</groupid>
        <artifactid>ganymed-ssh2</artifactid>
        <version>262</version>
    </dependency>
</dependencies>

注：原有依赖（spring boot web、ollama、pgvector、阿里云语音等）全部保留，无需修改。

4.2 项目改造：application.yml 配置新增

在原有配置基础上，新增 yolo 和 docker 相关配置，同时补充文件上传限制：

# 新增 yolo 配置
yolo:
  # docker 本地挂载目录（对应本地 d:\yolo_test）
  docker-mount-path: d:\yolo_test
  # 容器内挂载路径
  container-mount-path: /yolo_data
  # yolo 模型名称（默认 yolov8n.pt）
  model-name: yolov8n.pt
  # 检测结果保存目录（容器内）
  container-result-path: /yolo_data/runs/detect
  # 本地临时文件存储目录
  local-temp-path: d:\yolo_test\temp
  # docker 镜像名称
  docker-image: ultralytics/ultralytics:latest

# 原有配置保留，补充文件上传配置
spring:
  servlet:
    multipart:
      max-file-size: 10mb  # 单文件最大10mb
      max-request-size: 50mb  # 总请求最大50mb

4.3 新增核心代码（可直接复制使用）

新增 4 个核心类，实现图片上传、docker 命令调用、检测结果解析、接口提供，全部放在 com.ruoyi 包下（与原有项目包结构一致）。

4.3.1 配置类：yoloconfig.java（读取 yolo 配置）

package com.ruoyi.config;

import lombok.data;
import org.springframework.boot.context.properties.configurationproperties;
import org.springframework.stereotype.component;

/**
 * yolo 配置类，读取 application.yml 中的 yolo 相关配置
 */
@data
@component
@configurationproperties(prefix = "yolo")
public class yoloconfig {
    /**
     * docker 本地挂载目录
     */
    private string dockermountpath;

    /**
     * 容器内挂载路径
     */
    private string containermountpath;

    /**
     * yolo 模型名称
     */
    private string modelname;

    /**
     * 容器内检测结果保存路径
     */
    private string containerresultpath;

    /**
     * 本地临时文件存储目录
     */
    private string localtemppath;

    /**
     * docker 镜像名称
     */
    private string dockerimage;
}

4.3.2 实体类：yolodetectresult.java（封装检测结果）

package com.ruoyi.entity;

import lombok.allargsconstructor;
import lombok.builder;
import lombok.data;
import lombok.noargsconstructor;

import java.util.list;

/**
 * yolo 检测结果返回实体，用于接口返回 json 格式数据
 */
@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 {
        /**
         * 目标类别（如 cup、tv、mouse）
         */
        private string classname;

        /**
         * 目标数量
         */
        private int count;

        /**
         * 置信度（0-1），越大越精准
         */
        private float confidence;
    }
}

4.3.3 工具类：yolodetectutil.java（核心检测逻辑）

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;

/**
 * yolo 图片检测工具类，封装 docker 命令调用、结果解析逻辑
 */
@slf4j
@component
@requiredargsconstructor
public class yolodetectutil {
    private final yoloconfig yoloconfig;

    // 匹配检测结果的正则表达式（如：1 cup, 1 tv, 1 mouse）
    private static final pattern detect_pattern = pattern.compile("(\\d+)\\s+([a-za-z_]+)");

    /**
     * 上传图片并执行 yolo 检测
     * @param file 上传的图片文件
     * @return 检测结果（包含识别的物体、耗时、结果路径）
     */
    public yolodetectresult detectimage(multipartfile file) {
        long starttime = system.currenttimemillis();
        try {
            // 1. 校验文件是否为空
            if (file.isempty()) {
                return yolodetectresult.builder()
                        .success(false)
                        .errormsg("上传的图片文件为空")
                        .build();
            }

            // 2. 校验图片格式（仅支持 jpg/jpeg/png/bmp）
            string originalfilename = file.getoriginalfilename();
            if (originalfilename == null || !originalfilename.matches(".*\\.(jpg|jpeg|png|bmp)$")) {
                return yolodetectresult.builder()
                        .success(false)
                        .errormsg("仅支持 jpg/jpeg/png/bmp 格式的图片")
                        .build();
            }

            // 3. 创建临时目录（用于存储上传的图片）
            file tempdir = new file(yoloconfig.getlocaltemppath());
            if (!tempdir.exists()) {
                boolean mkdirs = tempdir.mkdirs();
                if (!mkdirs) {
                    log.error("创建临时目录失败：{}", yoloconfig.getlocaltemppath());
                    return yolodetectresult.builder()
                            .success(false)
                            .errormsg("创建临时目录失败")
                            .build();
                }
            }

            // 4. 保存上传的图片到本地挂载目录（docker 可访问）
            string filename = uuid.randomuuid() + "_" + originalfilename;
            string localimagepath = yoloconfig.getdockermountpath() + file.separator + filename;
            file localimagefile = new file(localimagepath);
            file.transferto(localimagefile);
            log.info("上传的图片已保存到：{}", localimagepath);

            // 5. 构建 docker 命令（调用 yolo 检测）
            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("\\", "/"), // windows 路径转换为 docker 可识别格式
                    yoloconfig.getcontainermountpath(),
                    yoloconfig.getdockerimage(),
                    yoloconfig.getmodelname(),
                    containerimagepath,
                    yoloconfig.getcontainerresultpath()
            );
            log.info("执行 docker 命令：{}", dockercmd);

            // 6. 执行 docker 命令，获取输出结果
            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, errormsg);
                return yolodetectresult.builder()
                        .success(false)
                        .errormsg("执行检测失败：" + errormsg)
                        .build();
            }

            // 7. 解析命令输出，提取检测到的物体信息
            string output = new string(process.getinputstream().readallbytes());
            log.info("yolo 检测命令输出：{}", output);
            list<yolodetectresult.detectobject> detectobjects = parsedetectresult(output);

            // 8. 拼接检测结果图片路径（本地可访问）
            string resultimagepath = yoloconfig.getdockermountpath() + file.separator + "runs" + file.separator + "detect" + file.separator + "detect" + file.separator + filename;
            long costtime = system.currenttimemillis() - starttime;

            // 9. 返回成功结果
            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) {
            log.error("检测命令执行被中断", e);
            thread.currentthread().interrupt();
            return yolodetectresult.builder()
                    .success(false)
                    .errormsg("检测被中断：" + e.getmessage())
                    .build();
        } catch (exception e) {
            log.error("图片检测异常", e);
            return yolodetectresult.builder()
                    .success(false)
                    .errormsg("检测异常：" + e.getmessage())
                    .build();
        }
    }

    /**
     * 解析 yolo 检测命令输出，提取目标信息（类别、数量）
     * @param output 命令输出字符串
     * @return 检测目标列表
     */
    private list<yolodetectresult.detectobject> parsedetectresult(string output) {
        list<yolodetectresult.detectobject> result = new arraylist<>();
        if (output == null || output.isempty()) {
            return result;
        }

        // 匹配 "1 cup, 1 tv, 1 mouse" 格式的字符串
        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);
        }

        // 转换为 detectobject 列表（置信度默认 0.9，可根据实际输出优化）
        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.3.4 控制器：yolocontroller.java（提供 http 接口）

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.postmapping;
import org.springframework.web.bind.annotation.requestmapping;
import org.springframework.web.bind.annotation.requestparam;
import org.springframework.web.bind.annotation.restcontroller;
import org.springframework.web.multipart.multipartfile;

/**
 * yolo 图片检测控制器，提供 http 接口供前端调用
 */
@slf4j
@restcontroller
@requestmapping("/api/yolo")
@requiredargsconstructor
public class yolocontroller {
    private final yolodetectutil yolodetectutil;

    /**
     * 图片目标检测接口
     * @param file 上传的图片文件
     * @return 检测结果（json 格式）
     */
    @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());
        }
    }
}

4.4 启动类验证（确保组件扫描）

确保 spring boot 启动类扫描到新增的配置类、控制器等组件，修改启动类（如已有则无需新增）：

package com.ruoyi;

import lombok.extern.slf4j.slf4j;
import org.springframework.boot.springapplication;
import org.springframework.boot.autoconfigure.springbootapplication;
import org.springframework.boot.context.properties.enableconfigurationproperties;

@slf4j
@springbootapplication(scanbasepackages = "com.ruoyi") // 扫描 com.ruoyi 下所有组件
@enableconfigurationproperties
public class application {
    public static void main(string[] args) {
        springapplication.run(application.class, args);
        log.info("spring boot 应用启动成功，端口：8889");
    }
}

五、接口测试（验证集成效果）

项目启动成功后，我们通过 postman 测试图片检测接口，验证集成效果。

5.1 测试准备

启动 docker desktop（确保 docker 服务正常运行）
启动 spring boot 应用（端口 8889）
准备一张测试图片（jpg/png 格式）

5.2 postman 测试步骤

新建 post 请求，地址：http://localhost:8889/api/yolo/detect
请求类型选择 form-data，key 填写 file，value 选择“文件”，上传测试图片
点击发送请求，查看返回结果

5.3 成功返回示例

{
    "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"
}

返回结果说明：

success: true：检测成功
detectobjects：识别到的物体列表（类别、数量、置信度）
costtime：检测耗时（毫秒）
resultimagepath：本地带检测框的图片路径，可直接打开查看结果

六、常见问题与优化建议

6.1 常见问题

问题	可能原因	解决方案
接口调用失败，提示“docker 命令执行失败”	docker 未启动	检查 docker desktop 是否正常运行
接口调用失败，提示“执行检测失败”	挂载目录权限问题	检查 docker desktop 文件共享配置是否正确
检测速度慢	模型较大或 cpu 性能不足	使用更轻量的 yolov8n 模型，或考虑开启 gpu 加速
结果图片无法打开	结果图片路径不正确	检查 resultimagepath 是否正确，确认 docker 检测结果已保存到挂载目录
图片上传失败，提示文件过大	文件大小超出限制	调整 application.yml 中的 max-file-size 配置

6.2 优化建议

1. 优化检测速度

开启 docker gpu 加速（需安装 nvidia 显卡驱动和 docker gpu 插件）
使用更轻量的 yolo 模型（如 yolov8n 已是最轻量，可考虑模型量化压缩）
图片预处理：上传前对图片进行压缩，减小分辨率

2. 增强接口安全性

添加 api key 权限校验，防止匿名调用
添加接口限流，避免 docker 容器被压垮
文件类型严格校验，防止恶意文件上传

3. 拓展功能

支持批量图片检测（上传压缩包，异步处理）
检测结果持久化：将检测结果存入数据库（如 postgresql），支持历史记录查询
前端可视化：新增前端页面，实现图片上传、检测结果可视化
视频流检测：支持 rtsp 视频流实时目标检测

七、总结

本文全程还原了 windows 环境下，通过 docker 部署 yolov8 模型，并集成到 spring boot 项目的完整流程，从环境准备、问题排查到代码集成、接口测试，每一步都提供了详细的实操步骤和解决方案。

核心亮点

通过 docker 容器化部署 yolov8，避免环境依赖冲突，实现快速部署
完整解决了 windows 下 docker 挂载目录、文件找不到等常见问题
将 yolo 检测能力封装为 spring boot 接口，可直接集成到各类业务系统
代码可直接复用，适配原有 spring boot 项目（无需从零搭建）

后续拓展方向

基于本文的基础，可以进一步拓展：

视频流实时目标检测
批量图片异步处理
检测结果可视化 dashboard
模型训练与迭代优化

让 yolo 目标检测能力更好地服务于实际业务场景。如果在实操过程中遇到问题，可参考本文的问题排查部分，或留言交流。

到此这篇关于windows环境下docker部署yolov8并集成spring boot的完整步骤的文章就介绍到这了,更多相关docker部署yolov8集成springboot内容请搜索代码网以前的文章或继续浏览下面的相关文章希望大家以后多多支持代码网！


验证码：

Windows环境下Docker部署YOLOv8并集成Spring Boot的完整步骤记录

2026年07月24日 • Java •我要评论

前言