用编排文件管住单机多服务
单机部署推理服务时，引擎、网关、监控导出器往往要一起起。用编排文件把这些服务写在一个文件里，启动顺序、端口映射、卷挂载与依赖关系都有据可查。显卡通过资源声明段申请，写对之后容器才能拿到设备；写错时容器会以「找不到设备」失败。
编排片段（GPU 声明）
编排片段（GPU 声明）
services:
vllm:
image: vllm/vllm-openai:v0.6.0 # 固定版本，便于回滚
command: ["--model", "/models/Qwen", "--max-model-len", "8192"]
ports: ["127.0.0.1:8000:8000"] # 只绑本机，对外经网关
volumes: ["/data/models:/models"]
ipc: host
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1 # 申请的卡数
capabilities: [gpu]启停与查看
启停与查看
docker compose up -d # 后台启动全部服务
docker compose logs -f vllm # 跟踪引擎日志
docker compose ps # 查看服务状态与端口
docker compose down # 停止并移除容器要点与代价
| 要点 | 说明 | 写错的后果 |
|---|---|---|
| 版本声明 | 镜像 tag 固定到具体版本 | 重建后行为变化，不可回归 |
| 设备段 | 按卡数或设备编号声明 | 容器拿不到卡，启动失败 |
| 端口绑定 | 绑定到本机或内网地址 | 服务直接暴露在公网 |
| 卷挂载 | 权重与缓存目录挂进来 | 容器内找不到权重，反复下载 |
| 共享内存 | 按引擎要求配置 | 批量稍大就报共享内存错误 |
典型使用场景
- 单机一体化部署：引擎加网关加监控一个文件管住
- 开发环境搭建：一条命令拉起整套依赖，减少手工步骤
- 测试环境复现：编排文件入库，环境差异显著减小
- 版本回滚：改回旧 tag 后重建即可切回上一个版本
- 多实例同机：用不同端口与设备声明把实例隔开
新版编排规范也支持简写的设备声明写法，以所用版本的规范为准：写法不生效时先确认版本支持的语法。
编排文件要入库并纳入变更记录：手工改过又没留痕的配置，会在下次重建时被静默覆盖，实例之间也可能因此不一致。
只写资源声明段而本机编排版本过旧时容器起不来：确认版本支持该段落再排查别的原因。