Spring Boot + Docker + YOLOv8：构建生产级目标检测服务-代码聚汇网

Spring Boot + Docker + YOLOv8：构建生产级目标检测服务

王子源Aisling·2026-08-29·阅读 22 GEO检测（免费）

Spring BootDockerYOLOv8

|难度：普通|阅读约 48 分钟

1. 整体架构与设计思路

1.1 为什么是“Spring Boot + Docker + YOLOv8”这个组合

做目标检测服务的人越来越多，但真正把模型从训练环境搬到生产环境、做成一个稳定API服务的，比例其实不高。很多人卡在“模型跑通了”和“业务能用上”之间的这段路上。我最早做检测服务时用的是Python的FastAPI，直接加载YOLOv8的PyTorch权重做接口，开发确实快，但项目上线后问题不少：依赖环境太脆弱、版本一换就崩、并发一高GIL卡得难受、部署到别的机器还要重新配CUDA环境。后来我把整个服务重构为Spring Boot + Docker + YOLOv8的组合，这套方案的优势很明显，下面会逐个展开。

先说Spring Boot。Java后端最大的优势是生态成熟、稳定性高、团队协作门槛低。Spring Boot内置Tomcat，自带线程池管理、请求路由、参数校验、统一异常处理等能力，这些都是生产环境下绕不开的基础设施。目标检测服务本质上就是一个“接收图像、返回检测结果”的接口服务，业务逻辑不算复杂，但请求管理、超时控制、日志追踪、鉴权这些外围能力，Spring Boot开箱即用，不用自己造轮子。

再说Docker。Docker解决的是环境一致性问题。YOLOv8的运行环境依赖很多：Python版本、PyTorch版本、CUDA、cuDNN、OpenCV、ONNX Runtime……本地环境装得好好的，换一台机器就翻车是常态。Docker把整个运行环境连同依赖一起打包成镜像，推到服务器上直接docker run就能跑，彻底消灭了“在我机器上是好的”这种问题。

最后是YOLOv8。作为Ultralytics团队推出的目标检测框架，YOLOv8在精度和速度之间取得了很好的平衡，自带训练、验证、导出、部署全流程工具链，而且支持导出ONNX、TensorRT等多种格式，后端推理的选择面很宽。这套组合的实际价值在于：模型训练阶段用Python生态，服务部署阶段用Java生态，两者通过ONNX格式解耦，互不干扰。

1.2 检测服务的核心架构与数据流

整个检测服务从数据流向来看分为三层，我画一个文字版的流程描述：

text复制客户端上传图片/图片URL
    → Spring Boot Controller 接收请求
    → 图片解码与预处理（缩放、归一化、通道交换）
    → ONNX Runtime 调用 YOLOv8 模型推理
    → 后处理（置信度过滤、NMS去重、坐标换算）
    → 返回 JSON 检测结果（类别、置信度、边框）

如果监听的端口在Docker容器里跑，服务对外暴露的端口映射到宿主机，然后通过Nginx或者云负载均衡转发给前端。每一层之间用Docker网络连接，服务间互相隔离，逻辑清晰。

这里有一个关键设计决策：模型推理引擎用ONNX Runtime，而不是直接在Java里调用PyTorch。原因有三个：第一，ONNX Runtime是微软开源的跨平台推理引擎，Java绑定支持很成熟，和Spring Boot的集成几乎没有坑；第二，ONNX格式是模型的中立交换格式，现在用YOLOv8导出ONNX，将来想换其他模型框架，只要导出ONNX即可，服务代码不用大改；第三，ONNX Runtime比直接用PyTorch推理速度更快，内存占用更低，尤其在CPU环境下优势明显。

1.3 方案选型取舍：ONNX Runtime vs OpenCV DNN vs PyTorch Serving

为了帮助大家理解方案选型，我对比一下主流的三种后端推理方案：

方案	优点	缺点	适用场景
ONNX Runtime	跨语言支持好、轻量、CPU/GPU都支持、与Spring Boot集成顺畅	算子覆盖偶有缺失，需确保模型导出的算子兼容	推荐首选，兼顾性能与开发效率
OpenCV DNN	依赖最少、无需额外深度学习框架、部署体积小	算子支持范围有限，YOLOv8解析略繁琐	对镜像体积有强制要求时的妥协方案
PyTorch Serving	与训练框架无缝集成、支持动态图、调试方便	需要Python环境、资源占用大、Java侧调用必须走HTTP/gRPC	已有PyTorch Serving基础设施，或需要动态加载模型热更新

从工程实践来看，绝大多数场景选择ONNX Runtime就对了。我之前踩过OpenCV DNN的坑，YOLOv8导出的时候如果选了opset=17，OpenCV的DNN模块可能解析不了某些新算子，还得费劲换opset重新导出。ONNX Runtime在算子支持上明显更全面，而且官方有自己的算子兼容性列表，可控性好很多。

提示：ONNX Runtime加载模型的方式也简单。Java代码里把ONNX文件放进resources/models/目录，通过InputStream读取，转成OnnxTensor直接推理即可。模型热更新可以通过监听文件变化或定时拉取远端模型实现。

这套架构的另一个好处是“训练”和“部署”完全解耦。算法工程师用Python训练模型，导出ONNX；后端工程师拿到ONNX文件，集成进Spring Boot服务，打包Docker镜像发布。两边只需要约定好模型的输入输出规范，基本可以并行开发，互不阻塞。下面我从环境搭建开始，带你一步步复现这套方案。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 环境准备与基础搭建

2.1 开发机基础环境梳理

在这套技术栈里，开发机环境和生产环境最好是“分开准备，打包统一”。开发阶段我用Windows做训练和服务联调，生产阶段用Linux服务器跑Docker容器。用到的核心工具版本如下：

JDK：17（Spring Boot 3.x要求JDK 17以上，建议直接上21 LTS）
Maven：3.9+
Docker Desktop：Windows上做容器化调试
Python：3.9-3.11（YOLOv8官方推荐）
PyTorch：2.0+
ultralytics：8.0+

值得注意的是Spring Boot版本。如果你还在用Spring Boot 2.x，JDK 8或11也完全可以跑，不需要强制升级。我最后选的是Spring Boot 3.2 + JDK 17，因为Spring Boot 3.x的依赖管理更干净，尤其是springdoc-openapi对API文档的集成体验好很多。不过要提醒一下，Spring Boot 3.x默认使用Jakarta EE命名空间，javax.*要改成jakarta.*，新手容易在这里卡住。

2.2 YOLOv8训练环境准备

训练YOLOv8模型不需要太夸张的硬件。我早期用GTX 1660 Ti跑过YOLOv8s，6GB显存能训练小模型，批量大小设为8没问题，但训练速度确实慢，一个epoch几百张图要几分钟。如果你想认真训练自定义数据集，建议显卡显存至少8GB，如果是企业级项目，直接上RTX 4090或A100云服务器。

安装YOLOv8非常简单，官方提供了一把梭命令：

bash复制pip install ultralytics

这会自动装好PyTorch和OpenCV等依赖。如果你想用GPU，建议先装对应版本的PyTorch，再装ultralytics，避免自动装成CPU版。GPU版PyTorch安装命令参考：

bash复制pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
pip install ultralytics

训练环境准备完毕后，我先用YOLOv8官方预训练权重跑一次推理验证环境是否可用：

python复制from ultralytics import YOLO

model = YOLO("yolov8n.pt")
results = model("bus.jpg")
results[0].show()

能正常弹窗看到检测结果，说明环境没问题。接下来就可以训练自己的数据集了。

2.3 Docker Desktop 相关坑：虚拟化检测失败与 WSL2

Windows安装Docker Desktop时，最常见的报错就是：

text复制Docker Desktop failed to start because virtualisation support wasn't detected

这个报错的意思是：Docker Desktop依赖的虚拟化功能没有开启。解决方案按顺序排查：

进入BIOS/UEFI，开启Intel VT-x或AMD-V虚拟化技术。
在Windows功能中启用“Windows Hypervisor Platform”和“虚拟机平台”。
确保WSL2已安装并设置为默认版本。在PowerShell（管理员）下执行：

powershell复制wsl --install
wsl --set-default-version 2

Docker Desktop的Settings > General中勾选“Use the WSL 2 based engine”，然后在Resources > WSL Integration中把对应的发行版打开。

注意：如果BIOS里虚拟化已经开了，但仍然报这个错，很可能是Windows功能中的“虚拟机平台”没启用，或者WSL2内核没更新。执行wsl --update更新一下WSL内核，通常能解决。

2.4 基础镜像与依赖准备

Docker镜像构建时，我选用eclipse-temurin:17-jdk-alpine作为基础镜像，因为Alpine体积小、JDK 17稳定性好。但要注意的是，如果推理阶段需要OpenCV的Java绑定，单纯的Alpine镜像可能缺少一些系统库，需要额外安装。

dockerfile复制FROM eclipse-temurin:17-jdk-alpine
RUN apk add --no-cache libstdc++ libgomp

libstdc++和libgomp是ONNX Runtime运行所需的C++标准库和OpenMP库。少了这两个库，容器启动后加载模型时会报UnsatisfiedLinkError，排查起来很费时间。这个小坑我特意标出来，希望你能绕过去。

3. YOLOv8模型训练与导出

3.1 准备自己的数据集：标注工具与目录结构

如果你要用YOLOv8训练自己的检测模型，先从数据集准备开始。YOLO格式的数据集目录结构标准如下：

text复制dataset/
├── images/
│   ├── train/
│   └── val/
├── labels/
│   ├── train/
│   └── val/
├── data.yaml

data.yaml内容：

yaml复制train: ./images/train
val: ./images/val
nc: 2
names: ['cat', 'dog']

标注工具方面，个人项目推荐用LabelImg或者Label Studio，官网下载即用。我建议在标注时注意几个细节：目标太小的物体，尽量把边框贴合物体边缘，别留太多背景；遮挡严重的样本要单独归类，避免模型混淆；训练集和验证集的分隔要按文件夹划分，别用随机分割导致同一张图出现在两边。

如果没有现成标注数据，也可以用YOLOv8的预标注功能辅助起步。用预训练权重对未标注图片做推理，生成伪标签，然后再人工修正。这种方式在迁移学习中能省下不少标注时间。

3.2 训练参数选择与增量训练

训练自己的数据集，核心命令如下：

bash复制yolo detect train data=./data.yaml model=yolov8s.pt epochs=100 batch=16 imgsz=640 device=0

参数含义：

model=yolov8s.pt：加载预训练权重，做迁移学习。用yolov8s.pt而不是从零开始，能显著缩短训练时间并提高收敛精度。
epochs=100：一般训练100轮能收敛。先跑50轮看损失曲线趋势，再决定是否继续。
batch=16：根据显存调整。显存不够就降到8或4。
imgsz=640：YOLOv8官方默认训练尺寸，一般不用改。

增量训练是一个很有用的功能。如果你的样本量持续增加，不需要从头训一个模型，而是在现有模型基础上继续训练：

bash复制yolo detect train data=./data.yaml model=./runs/detect/train/weights/best.pt epochs=50

用best.pt作为初始权重加载继续训练，会保留旧模型的检测能力，再在新数据上微调。实测下来，新增类别时把旧模型的最后一层替换掉，前几轮用较低的学习率（比如0.0001），loss下降非常平稳，不会出现灾难性遗忘。

训练完成后，在runs/detect/train/目录下可以找到best.pt，这个就是效果最好的权重文件。我还建议画一下损失函数曲线图：

bash复制yolo detect train data=./data.yaml model=yolov8s.pt epochs=100 ...
# 训练完成后自动生成 results.png，包含 loss、precision、recall、mAP 曲线

results.png就是模型训练过程的可视化报告，里面包含box_loss、cls_loss、dfl_loss的曲线，以及P、R、mAP50、mAP50-95的变化趋势。看到验证集mAP稳步上升、最终趋平，基本就可以判断训练是否收敛了。

3.3 模型导出：从PyTorch权重到ONNX

服务端推理需要的是ONNX格式的模型，不是best.pt。导出的方法很简单：

python复制from ultralytics import YOLO

model = YOLO("runs/detect/train/weights/best.pt")
model.export(format="onnx", opset=12, dynamic=False, simplify=True, imgsz=640)

这里有几个参数值得展开：opset=12是一个兼容性最好的算子集版本，ONNX Runtime对opset 12的支持最稳定。dynamic=False表示固定输入尺寸，如果你的业务场景中图像尺寸变化很大，可以考虑dynamic=True，但动态输入会损失一点推理性能，而且后续处理要额外处理动态维度，建议固定尺寸。simplify=True会调用onnx-simplifier做计算图优化，减小模型体积并提升推理速度。

导出完成后会生成best.onnx文件，文件大小和权重类型有关。YOLOv8s的ONNX模型大约是40-80MB，YOLOv8n的大约是10-20MB。这个文件放到Spring Boot工程的resources/models/目录下，后面加载推理就靠它了。

提示：导出前最好先确认ONNX Runtime能加载成功。可以用Python快速验证一下：
python复制import onnxruntime as ort
sess = ort.InferenceSession("best.onnx")
print("模型加载成功")

4. Spring Boot检测服务核心实现

4.1 工程初始化与依赖引入

Spring Boot工程的创建我用Spring Initializr快速生成，核心依赖如下：

xml复制<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>com.microsoft.onnxruntime</groupId>
        <artifactId>onnxruntime</artifactId>
        <version>1.17.1</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
</dependencies>

注意onnxruntime的groupId是com.microsoft.onnxruntime，不是ai.onnxruntime，网上很多文档写的是后者，会导致Maven找不到依赖。如果你要GPU推理，用onnxruntime_gpu替换onnxruntime，但要注意GPU版对CUDA版本有要求，容器里还要装CUDA运行库，镜像体积会大很多。我建议第一版先上CPU推理，把整个链路跑通后再考虑GPU加速。

4.2 后端推理服务的关键实现

核心类我分成两部分：YoloDetector负责加载模型和推理，DetectionController负责接收HTTP请求。这里给出YoloDetector的完整代码，你可以直接参考：

java复制@Component
public class YoloDetector {

    private static final Logger log = LoggerFactory.getLogger(YoloDetector.class);

    @Value("${yolo.model-path:models/best.onnx}")
    private String modelPath;

    @Value("${yolo.confidence-threshold:0.5}")
    private float confidenceThreshold;

    @Value("${yolo.iou-threshold:0.45}")
    private float iouThreshold;

    @Value("${yolo.input-size:640}")
    private int inputSize;

    private OrtSession session;
    private final List<String> classNames = new ArrayList<>();

    @PostConstruct
    public void init() throws IOException, OrtException {
        try (InputStream is = getClass().getClassLoader().getResourceAsStream(modelPath)) {
            if (is == null) {
                throw new IOException("模型文件不存在: " + modelPath);
            }
            byte[] modelBytes = IOUtils.toByteArray(is);
            OrtEnvironment env = OrtEnvironment.getEnvironment();
            session = env.createSession(modelBytes, new OrtSession.SessionOptions());
            loadClassNames();
            log.info("YOLOv8 模型加载成功，输入节点: {}, 输出节点: {}", 
                session.getInputInfo().keySet(), session.getOutputInfo().keySet());
        }
    }

    public List<DetectionResult> detect(byte[] imageBytes) throws OrtException {
        // 1. 解码图片为Mat
        Mat img = Imgcodecs.imdecode(new MatOfByte(imageBytes), Imgcodecs.IMREAD_COLOR);
        if (img.empty()) {
            throw new IllegalArgumentException("图片解码失败");
        }

        // 2. 预处理：缩放 + 归一化 + BGR → RGB
        Mat resized = new Mat();
        Size size = new Size(inputSize, inputSize);
        Imgproc.resize(img, resized, size);
        float[] rgbData = new float[3 * inputSize * inputSize];
        for (int i = 0; i < inputSize; i++) {
            for (int j = 0; j < inputSize; j++) {
                double[] bgr = resized.get(i, j);
                int idx = i * inputSize + j;
                rgbData[idx] = (float) (bgr[2] / 255.0); // R
                rgbData[idx + inputSize * inputSize] = (float) (bgr[1] / 255.0); // G
                rgbData[idx + 2 * inputSize * inputSize] = (float) (bgr[0] / 255.0); // B
            }
        }

        // 3. 构造输入Tensor (1, 3, 640, 640) NCHW
        long[] shape = {1, 3, inputSize, inputSize};
        OnnxTensor inputTensor = OnnxTensor.createTensor(
            OrtEnvironment.getEnvironment(), 
            ByteBuffer.wrap(toByteBuffer(rgbData)), 
            shape, 
            TensorInfo.OnnxTensorType.ONNX_TENSOR_ELEMENT_DATA_TYPE_FLOAT
        );

        // 4. 推理
        Map<String, OnnxTensor> inputs = Map.of("images", inputTensor);
        try (OrtSession.Result results = session.run(inputs)) {
            OnnxTensor output = (OnnxTensor) results.get(0).getValue();
            float[][][] outputData = toFloatArray(output.getFloatBuffer(), output.getInfo().getShape());

            // 5. 后处理：解析 1×84×8400 输出
            return postProcess(outputData, img.width(), img.height());
        }
    }
}

以上代码中，我简化了Tensor构造过程，实际实现时要把float[]转成ByteBuffer并指定格式。核心代码的注释里已经把每个步骤的功能标清楚了。如果是用onnxruntime的Java API，加载模型的SessionOptions可以设置setOptimizationLevel(ORT_ENABLE_ALL)，能开启图优化提升推理速度。

4.3 后处理逻辑解析：从模型输出到检测框

YOLOv8的输出格式和YOLOv5不完全一样。YOLOv8采用解耦头（Decoupled Head），输出是一个张量，形状是[1, 4 + num_classes, 8400]，其中8400 = 80×80 + 40×40 + 20×20（不同尺度的特征图累加）。在这个张量中，前4个维度是[cx, cy, w, h]（中心点和宽高，注意这里不是xywh的左上角坐标），后面的是每个类别的置信度分数。

java复制private List<DetectionResult> postProcess(float[][][] output, int origW, int origH) {
    List<DetectionResult> detections = new ArrayList<>();
    int numAnchors = output[0][0].length;
    int numClasses = output[0].length - 4;
    float scaleX = (float) origW / inputSize;
    float scaleY = (float) origH / inputSize;

    for (int i = 0; i < numAnchors; i++) {
        float maxScore = 0;
        int maxClassId = -1;
        for (int c = 0; c < numClasses; c++) {
            float score = output[0][c + 4][i];
            if (score > maxScore) {
                maxScore = score;
                maxClassId = c;
            }
        }
        if (maxScore < confidenceThreshold) {
            continue;
        }

        float cx = output[0][0][i];
        float cy = output[0][1][i];
        float w = output[0][2][i];
        float h = output[0][3][i];

        float x1 = (cx - w / 2) * scaleX;
        float y1 = (cy - h / 2) * scaleY;
        float x2 = (cx + w / 2) * scaleX;
        float y2 = (cy + h / 2) * scaleY;

        detections.add(new DetectionResult(classNames.get(maxClassId), maxScore, x1, y1, x2, y2));
    }

    return NMSUtils.nonMaxSuppression(detections, iouThreshold);
}

NMS（非极大值抑制）的逻辑就不贴全代码了，原理很好理解：先按置信度从高到低排序，依次取最高分的框，去掉那些和它IoU（交并比）大于阈值的其他框。iouThreshold一般取0.45，这个值不能设得太高，否则同一个物体可能被检出多个框；也不能太低，否则密集的小物体容易被误删。

这个后处理的细节用白话说就是：模型输出的8400个候选框中，可能有多个框都在检测同一个物体，NMS的作用就是把冗余框去掉，留下最可信的那一个。

4.4 接口设计与参数选择

Controller层提供两个接口：上传图片检测和通过URL检测。

java复制@RestController
@RequestMapping("/api/detect")
public class DetectionController {

    private final YoloDetector detector;

    public DetectionController(YoloDetector detector) {
        this.detector = detector;
    }

    @PostMapping("/upload")
    public Result<List<DetectionResult>> detectImage(@RequestParam("file") MultipartFile file) 
            throws IOException, OrtException {
        if (file.isEmpty()) {
            return Result.error("文件为空");
        }
        if (file.getSize() > 5 * 1024 * 1024) {
            return Result.error("图片大小不能超过5MB");
        }
        long start = System.currentTimeMillis();
        List<DetectionResult> detections = detector.detect(file.getBytes());
        long cost = System.currentTimeMillis() - start;
        return Result.success(detections).addMeta("cost_ms", cost);
    }
}

参数选择方面，confidence-threshold和iou-threshold放在了application.yml配置文件中：

yaml复制yolo:
  model-path: models/best.onnx
  confidence-threshold: 0.5
  iou-threshold: 0.45
  input-size: 640

这两个阈值的选择讲究：置信度设得高，误检少但漏检多；设得低，漏检少但误检多。我通常建议0.5起步，业务方反馈误检多就升高到0.6-0.7，反馈漏检多就降到0.3-0.4。NMS阈值0.45是经验值，一般不用改。生产环境中，最好给每个业务方单独配置一套阈值参数，而不是全局固定。

提示：接口要做超时控制。ONNX Runtime在CPU上跑一张640×640的图，YOLOv8s大概需要100-300ms，如果图片过大或者并发过高，一个请求可能被拖很久。建议给Controller层的处理加上@Transactional超时是不合适的，应该用统一拦截器或配置spring.mvc.async.request-timeout来控制接口的最大响应时间，避免请求堆积导致服务雪崩。

5. Docker镜像构建与部署

5.1 为什么用多阶段构建

构建Spring Boot + ONNX Runtime的Docker镜像时，我强烈推荐多阶段构建（multi-stage build）。第一阶段用Maven镜像编译Java代码，第二阶段用轻量级JRE镜像运行。这样做有两个明显的好处：一是编译工具（JDK、Maven）不会打进最终镜像，镜像体积能减少200-300MB；二是编译过程中的中间产物不会暴露到生产环境，安全性和整洁度都更好。

下面是完整的Dockerfile参考：

dockerfile复制# 第一阶段：构建
FROM maven:3.9-eclipse-temurin-17 AS build
WORKDIR /app
COPY pom.xml .
RUN mvn dependency:go-offline

COPY src ./src
RUN mvn package -DskipTests

# 第二阶段：运行
FROM eclipse-temurin:17-jre-alpine
RUN apk add --no-cache libstdc++ libgomp

WORKDIR /app
COPY --from=build /app/target/detect-service-*.jar app.jar
COPY models/best.onnx /app/models/best.onnx

EXPOSE 8080
ENTRYPOINT ["java", "-XX:+UseG1GC", "-Xmx512m", "-jar", "app.jar"]

RUN mvn dependency:go-offline的作用是先把所有依赖下载缓存好，后续如果只是改动源码重新构建，能利用Docker的缓存层，不用每次重复下载依赖。这个优化在CI/CD中效果非常明显，构建时间能从5分钟降到1分钟以内。

5.2 环境变量与配置注入

Spring Boot应用打包进容器后，配置信息不要硬编码在application.yml里，通过环境变量注入是最佳实践：

yaml复制spring:
  datasource:
    url: jdbc:mysql://${DB_HOST:localhost}:${DB_PORT:3306}/${DB_NAME:detect}

在docker run的时候传入环境变量：

bash复制docker run -d --name detect-service \
  -p 8080:8080 \
  -e DB_HOST=mysql-server \
  -e DB_PORT=3306 \
  -e DB_NAME=detect \
  detect-service:v1.0

有一点容易被忽略：当模型文件和JAR包在一起打进镜像后，如果模型更新频繁，每次都要重新构建镜像，操作成本比较高。我的做法是把模型文件挂载到宿主机目录，容器启动时从宿主机载入模型：

bash复制docker run -d --name detect-service \
  -p 8080:8080 \
  -v /opt/models:/app/models \
  detect-service:v1.0

这样模型更新后只需要重启容器，不用重新构建镜像，比打进镜像要灵活多了。但要注意，模型热更新还是要重启容器。要实现真正的不停机热更新，可以考虑把模型放到对象存储，服务启动后自动拉取最新版本，这块后面再讲。

5.3 Docker Compose 编排多服务

如果你还要同时运行MySQL、Redis等依赖服务，推荐用docker-compose.yml做统一编排：

yaml复制version: '3.8'
services:
  detect-service:
    build: .
    ports:
      - "8080:8080"
    environment:
      - SPRING_PROFILES_ACTIVE=prod
    volumes:
      - /opt/models:/app/models
    networks:
      - app-network

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

docker compose up -d一条命令拉起所有服务，开发和测试环境的搭建效率直线上升。这里用到的networks配置保证服务之间通过容器名互相访问，而不是通过IP，避免了容器重启后IP变化导致的服务断连。

6. 常见问题与排查技巧

6.1 模型推理结果明显不准，怎么排查

模型推理结果不准确，绝大多数情况不是模型本身的问题，而是预处理和后处理没对齐。我总结了一套排查顺序：

先确认预处理是否正确：YOLOv8训练时用的是RGB格式、0-1归一化，服务端解码是BGR（OpenCV默认），必须做BGR到RGB的通道交换，并将像素值除以255。漏掉任何一步，检测效果都会大幅下降。
再确认坐标缩放是否正确：模型输出的坐标是基于640×640尺寸的，要换算回原图尺寸，必须用scaleX = origW / 640和scaleY = origH / 640，不能用同一个比例。
然后检查置信度阈值：如果检测不到任何物体，先把阈值降到0.1，确认模型确实有输出，再逐步调高。

我在开发中遇到过最经典的一个问题：预处理漏了归一化，导致检测结果里所有类别的置信度都是0.8以上，但边框位置全部偏移。排查了半天，原因是像素值没有除以255，模型输入的值域不对。

6.2 容器内存占用过高，频繁被杀

JVM默认的堆内存大小是物理内存的1/4，如果你在Docker容器里没限制内存，JVM可能会尝试申请过大的堆内存，导致容器被杀或被系统OOM kill。解决方案是在启动参数里显式指定堆内存：

bash复制java -Xmx512m -Xms256m -jar app.jar

在Dockerfile里我已经加上了-Xmx512m。如果检测服务并发请求量不大，512MB堆内存绰绰有余，ONNX Runtime原生内存和JVM堆是分开的，留出系统层面的余量即可。

还要注意，ONNX Runtime有intra_op_num_threads和inter_op_num_threads两个线程配置。如果宿主机是8核，容器内默认会占用全部核心去跑推理，可能影响同机其他服务。建议在初始化Session时显式设置线程数：

java复制SessionOptions options = new SessionOptions();
options.setIntraOpNumThreads(4);
options.setInterOpNumThreads(1);

6.3 Docker镜像构建慢、依赖下载慢

我遇到过很多次，docker build的时候卡在RUN mvn dependency:go-offline这一步，或者apt-get install非常慢。这通常是网络问题。解决方案是配置国内镜像源：

Maven：在pom.xml的<repositories>中添加阿里云镜像，或者在settings.xml中配置mirror。
Docker：在/etc/docker/daemon.json中配置镜像加速器，然后systemctl restart docker。
Alpine的apk源：修改/etc/apk/repositories，换成国内镜像。

另外，docker build时尽量把COPY pom.xml .和COPY src ./src分开写。因为Docker的缓存机制是按层判断的，只要pom.xml没变，依赖下载层就可以复用，不用每次都重新下载依赖。反之，如果写在一起，每次改源码都会导致依赖层失效，构建时间暴涨。

6.4 Docker Desktop无法启动

这个问题在2.3节已经详细展开过，这里再补充一个容易被忽略的排查点：Windows下安装了VMware或VirtualBox等虚拟化软件，可能会和Hyper-V/WSL2冲突，导致Docker Desktop启动失败。如果你发现BIOS虚拟化已开启、Windows功能也正常，但Docker还是起不来，可以检查一下是否安装了老版本的VMware，把它卸载后重启通常能解决。

另一个相关报错是：

text复制We've detected that you have an incompatible version of Windows

这个说明Windows版本太旧，Docker Desktop不支持。Windows 10 2004及以上、Windows 11基本没问题，老版本系统建议升级系统，或者换用Docker Toolbox（不推荐，兼容性极差）。

7. 印象最深的一次部署与调优记录

最后讲一个真实案例。我们给一个质检项目做检测服务，最初方案是Python Flask + YOLOv8，开发速度很快，但上线后遇到两个问题：并发超过20时响应时间从200ms暴涨到2秒以上；每次模型更新都要动整个Python环境，运维成本很高。后来迁移到Spring Boot + ONNX Runtime + Docker这套方案后，同样的硬件环境下，单次推理耗时200-350ms，并发40时响应时间依然稳定在400ms以内。这个提升主要来自两方面：一是ONNX Runtime的CPU推理优化确实强于直接用PyTorch；二是Spring Boot的线程池调度比Python的多线程方式更可控，不会出现GIL导致的性能悬崖。

模型迭代也顺畅了很多。算法团队训练好新模型，导出ONNX，传到服务器挂载目录，重启容器，整个流程不超过5分钟。对比之前要登录服务器改Python环境、装依赖、重启服务，效率提升非常明显。

部署时我还做过一次极简优化：把results.png和训练指标放到一个单独的运维接口里，用Spring Boot的Actuator做健康检查，配合Prometheus监控推理耗时和QPS。这套组合对线上问题定位帮助很大，强烈推荐你去试试。

如果你也是第一次做检测服务部署，按这个流程走一遍应该能少走很多弯路。先跑通最小闭环，再考虑GPU加速、模型量化、分布式部署这些进阶方向。遇到问题的时候，优先检查输入输出的尺寸和格式对不对，这是一半以上问题的根源。