# Docker 模型目录外置方案

## 可行性分析

当前镜像通过 `COPY . .` 把 `model/` 一并打入镜像，模型文件会直接放大构建上下文和最终镜像。改为宿主机 volume 挂载后，应用仍在容器内读取 `/app/model`，代码侧路径保持稳定；只要宿主机目录内容完整，运行时行为不变。

性能方面，构建和镜像分发会明显变快，因为大体积模型不再进入镜像层。推理读取模型时会从宿主机挂载目录加载，Linux/Docker Desktop 常规 volume 的读取开销相对模型加载和推理耗时可以忽略。安全方面，模型文件不再固化到镜像仓库和离线包，减少误分发风险；同时需要对宿主机 `model/` 目录做好访问权限控制。运维方面，模型更新可以只替换宿主机文件并重启服务，不必重建镜像；代价是部署前必须确认模型目录已经同步到目标机器。

## 迁移步骤

1. 在部署目录创建或确认 `model/` 目录，与 `docker-compose.yml`、`app.env` 同级。
2. 从旧镜像、旧部署包或模型归档中复制模型文件到宿主机 `model/` 下，保持原有文件名，例如 `biaochezhajiev2.pt`、`yolov8s-worldv2.pt`、`det_10g.onnx`。
3. 如需使用非默认路径，在 `.env` 或启动环境中设置 `MULTI_RIDER_MODEL_ROOT=/absolute/path/to/model`。
4. 使用新版镜像和新版 `docker-compose.yml` 启动服务，确认 compose volumes 中存在 `${MULTI_RIDER_MODEL_ROOT:-./model}:/app/model`。
5. 启动后检查日志和接口，确认模型路径仍解析到 `/app/model/...`，再执行一次核心识别或健康检查。

## 回退方案

如外置目录缺文件或权限异常，优先补齐宿主机 `model/` 并重启容器。如果必须回退到旧打包方式，可以临时移除 `.dockerignore` 末尾的 `model/*` 和 `!model/README.md`，删除 compose 中的 `/app/model` 挂载行，重新构建包含模型文件的镜像。代码侧仍支持默认 `BASE_DIR/model`，因此回退不需要改业务代码；如果设置过 `MODEL_DIR`，需要同步取消或改回容器内路径。

## 性能基准

粗略估算：旧方案镜像大小约为“应用依赖 + 代码 + model 目录”。如果 `model/` 为 1.5GB，镜像和离线包会额外增加约 1.5GB，并且每次模型变更都会产生新的大镜像层。新方案中模型文件不进入镜像，镜像体积可减少约 `model/` 的实际大小；按 1.5GB 模型目录估算，构建上下文、镜像导出和内网分发都可减少约 1.5GB 数据传输。