计算机视觉 / 系统课时
配置生产运行参数
配置生产运行参数
本课将把 YOLOv5 推理容器需要的端口、模型路径、日志轮转、文件描述符限制、健康检查和资源上限集中到生产配置中,并通过 Docker Compose 完成解析、启动与健康状态验证。
学习目标
- 区分镜像默认值、环境变量和编排层参数的职责
- 编写可复用的生产环境变量与 Compose 配置
- 验证容器端口、健康状态、日志限制和模型挂载是否生效
设计参数覆盖顺序
生产配置应遵循“镜像提供安全默认值,环境文件保存环境差异,Compose 负责主机资源”的分层方式。镜像内的默认端口和模型路径保证容器可独立启动,环境变量负责覆盖路径与日志级别,Compose 再决定宿主机端口、卷、资源限制和重启策略。

不要把密码、访问密钥或内部地址写进镜像。环境文件可保存非敏感运行参数,但包含敏感值时也必须限制文件权限,并避免提交到代码仓库。
准备生产环境变量
创建 .env.production,统一保存主机端口、模型位置和服务运行参数。WORKERS 建议从 1 开始,因为每个工作进程通常都会加载一份模型,盲目增加进程会快速放大显存或内存占用。
HOST_PORT=8080
MODEL_PATH=/models/best.pt
LOG_LEVEL=INFO
WORKERS=1这些值会在 Compose 解析阶段替换 ${...}。环境文件本身不会自动进入容器,只有在 Compose 的 environment 或其他字段中引用后才会生效。
编写生产 Compose 配置
下面的配置假设镜像已提供 curl,服务在容器内监听 8000,并实现 GET /health 健康接口。模型目录以只读方式挂载,日志目录单独持久化,容器根文件系统保持只读。
services:
detector:
image: yolov5-api:1.0.0
container_name: yolov5-api
restart: unless-stopped
init: true
ports:
- "${HOST_PORT}:8000"
environment:
PORT: "8000"
MODEL_PATH: "${MODEL_PATH}"
LOG_LEVEL: "${LOG_LEVEL}"
WORKERS: "${WORKERS}"
volumes:
- ./models:/models:ro
- ./logs:/app/logs
read_only: true
tmpfs:
- /tmp:size=256m
ulimits:
nofile:
soft: 65535
hard: 65535
cpus: "2.0"
mem_limit: 4g
stop_grace_period: 30s
healthcheck:
test:
- CMD-SHELL
- curl -fsS http://127.0.0.1:8000/health || exit 1
interval: 30s
timeout: 5s
retries: 3
start_period: 60s
logging:
driver: json-file
options:
max-size: "20m"
max-file: "5"start_period 为首次模型加载预留时间;超过该时间后,连续三次检查失败才会标记为不健康。max-size 与 max-file 将单个容器日志控制在约 100 MB 以内,但应用若写入 /app/logs,仍需为文件日志配置独立轮转策略。
解析并启动配置
先让 Compose 展开环境变量并校验语法,确认没有空值或路径拼写错误,再后台启动服务。
docker compose \
--env-file .env.production \
-f compose.production.yml \
config
docker compose \
--env-file .env.production \
-f compose.production.yml \
up -d
docker compose \
--env-file .env.production \
-f compose.production.yml \
ps预期输出
配置解析成功,没有出现变量缺失或 YAML 语法错误。
NAME IMAGE SERVICE STATUS
yolov5-api yolov5-api:1.0.0 detector Up <TIME> (healthy)
端口列应显示 0.0.0.0:8080->8000/tcp;<TIME> 会随实际启动时间变化。若状态长期停留在 starting,先确认模型加载时间是否超过 60 秒;若变为 unhealthy,再进入容器执行同一条 curl 命令,区分是接口未实现、监听地址错误,还是模型初始化失败。
验证关键运行参数
使用 docker inspect 一次检查健康状态、文件描述符限制和模型挂载。输出中的宿主机绝对路径会因部署目录不同而变化。
docker inspect yolov5-api \
--format 'health={{.State.Health.Status}} nofile={{range .HostConfig.Ulimits}}{{if eq .Name "nofile"}}{{.Soft}}/{{.Hard}}{{end}}{{end}} model={{range .Mounts}}{{if eq .Destination "/models"}}{{.Source}}:{{.RW}}{{end}}{{end}}'预期输出
health=healthy nofile=65535/65535 model=<PATH>:falsefalse 表示 /models 在容器中不可写。若容器因权限问题无法写日志,应检查宿主机 ./logs 的所有者是否允许 UID 10001 写入;不要为了省事改成特权容器。若出现 OOM,先降低输入尺寸、批量大小或工作进程数,再评估是否提高内存上限。
本课总结
- 镜像默认值、环境变量和 Compose 参数应分层管理,避免把环境差异写死在镜像中
- 健康检查必须覆盖模型可用性,并为首次加载设置合理的启动宽限时间
- 日志轮转、
nofile、只读模型卷和资源上限共同决定服务能否长期稳定运行
下一课预告
下一课将继续处理服务上线后的发布与运维流程,包括镜像版本管理、滚动替换、失败回滚和基础监控指标。