计算机视觉 / 系统课时

配置生产运行参数

配置生产运行参数

本课将把 YOLOv5 推理容器需要的端口、模型路径、日志轮转、文件描述符限制、健康检查和资源上限集中到生产配置中,并通过 Docker Compose 完成解析、启动与健康状态验证。

学习目标

  • 区分镜像默认值、环境变量和编排层参数的职责
  • 编写可复用的生产环境变量与 Compose 配置
  • 验证容器端口、健康状态、日志限制和模型挂载是否生效

设计参数覆盖顺序

生产配置应遵循“镜像提供安全默认值,环境文件保存环境差异,Compose 负责主机资源”的分层方式。镜像内的默认端口和模型路径保证容器可独立启动,环境变量负责覆盖路径与日志级别,Compose 再决定宿主机端口、卷、资源限制和重启策略。

生产运行参数的覆盖与生效关系

不要把密码、访问密钥或内部地址写进镜像。环境文件可保存非敏感运行参数,但包含敏感值时也必须限制文件权限,并避免提交到代码仓库。

准备生产环境变量

创建 .env.production,统一保存主机端口、模型位置和服务运行参数。WORKERS 建议从 1 开始,因为每个工作进程通常都会加载一份模型,盲目增加进程会快速放大显存或内存占用。

bash
HOST_PORT=8080
MODEL_PATH=/models/best.pt
LOG_LEVEL=INFO
WORKERS=1

这些值会在 Compose 解析阶段替换 ${...}。环境文件本身不会自动进入容器,只有在 Compose 的 environment 或其他字段中引用后才会生效。

编写生产 Compose 配置

下面的配置假设镜像已提供 curl,服务在容器内监听 8000,并实现 GET /health 健康接口。模型目录以只读方式挂载,日志目录单独持久化,容器根文件系统保持只读。

yaml
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 展开环境变量并校验语法,确认没有空值或路径拼写错误,再后台启动服务。

bash
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

预期输出

text
配置解析成功,没有出现变量缺失或 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 一次检查健康状态、文件描述符限制和模型挂载。输出中的宿主机绝对路径会因部署目录不同而变化。

bash
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}}'

预期输出

text
health=healthy nofile=65535/65535 model=<PATH>:false

false 表示 /models 在容器中不可写。若容器因权限问题无法写日志,应检查宿主机 ./logs 的所有者是否允许 UID 10001 写入;不要为了省事改成特权容器。若出现 OOM,先降低输入尺寸、批量大小或工作进程数,再评估是否提高内存上限。

本课总结

  • 镜像默认值、环境变量和 Compose 参数应分层管理,避免把环境差异写死在镜像中
  • 健康检查必须覆盖模型可用性,并为首次加载设置合理的启动宽限时间
  • 日志轮转、nofile、只读模型卷和资源上限共同决定服务能否长期稳定运行

下一课预告

下一课将继续处理服务上线后的发布与运维流程,包括镜像版本管理、滚动替换、失败回滚和基础监控指标。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置生产运行参数

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通