文档首页/ 容器镜像服务 SWR/ 最佳实践（企业版）/ 镜像构建时添加元数据
更新时间：2026-08-26 GMT+08:00
查看PDF
分享

镜像构建时添加元数据

概述

在构建镜像时，建议嵌入必要的元数据信息，如镜像版本、构建时间、维护者等。这能够方便后续的镜像识别、版本控制以及运维管理。

使用 LABEL或者--label（构建命令行）添加自定义信息，比如作者、构建时间、Git 提交号、描述等。

方法一：在 Dockerfile 里添加

FROM alpine:latest

# 固定元数据
LABEL maintainer="dev@example.com"
LABEL description="Images used in the production environment."
LABEL org.opencontainers.image.title="my-app"
LABEL org.opencontainers.image.version="1.0.0"

# 业务代码
WORKDIR /app
COPY . .

方法二： 构建命令中增加Label信息

docker build \
  -t my-app:v1.0.0 \
  --label maintainer="dev@example.com" \
  --label description="Images used in the production environment." \
  --label org.opencontainers.image.title="my-app" \
  --label org.opencontainers.image.version="1.0.0" \
  .

OCI 标准 Lables

OCI 规范定义了一系列标准的 Lables，在构建镜像时建议注入相关 Labels，例如 org.opencontainers.image.version、org.opencontainers.image.created 等。这有助于统一镜像元数据格式，提升跨平台兼容性和管理效率。详情参考： OCI 镜像规范注解。

OCI 标准 Labels 示例

LABEL org.opencontainers.image.title="demo-app"
LABEL org.opencontainers.image.description="业务服务"
LABEL org.opencontainers.image.version="2.3.0"
LABEL org.opencontainers.image.vendor="CompanyName"
LABEL org.opencontainers.image.licenses="Apache-2.0"
LABEL org.opencontainers.image.authors="dev@xxx.com"
LABEL org.opencontainers.image.url="https://xxx.com"
LABEL org.opencontainers.image.documentation="https://doc.xxx.com"
表1 OCI 标准 Labels 说明

OCI 标准 KEY

含义

格式示例

org.opencontainers.image.created

镜像构建时间

RFC3339 2026-06-03T10:30:00Z

org.opencontainers.image.source

源码 Git 仓库

https://git.xxx.com/demo/app.git

org.opencontainers.image.revision

Git Commit SHA

git rev-parse HEAD

org.opencontainers.image.version

应用版本

v1.2.5

org.opencontainers.image.title

镜像名称

order-service

org.opencontainers.image.description

描述

agent运行的镜像

org.opencontainers.image.vendor

厂商 / 团队

DevTeam

org.opencontainers.image.licenses

开源协议

MIT/Apache-2.0

org.opencontainers.image.authors

联系人

ops@xxx.com

org.opencontainers.image.url

项目主页

官网地址

org.opencontainers.image.documentation

文档地址

文档链接

GPU Labels 建议

除 OCI 官方定义的标准 Labels 外，业界还推荐了一些 GPU 相关 Labels，可用于在 OCI 元数据中扩展 GPU 软硬件信息（如GPU 型号、驱动版本等）。此类注解有助于在全容器生态内统一识别 GPU 资源，提升异构计算场景下的兼容性和调度效率。

NVIDIA GPU Labels 示例

# GPU软硬件 OCI扩展标注
LABEL org.opencontainers.image.cuda.version="11.8"
LABEL org.opencontainers.image.cudnn.version="8.9.7.29"
LABEL org.opencontainers.image.tensorrt.version="8.6.1"

# 硬件算力(Compute Capability)：8.0(A100)、8.6(3090/A30)、9.0(H100)
LABEL org.opencontainers.image.gpu.compute_capability="8.0,8.6,9.0"

# 最低驱动版本（CUDA→Driver兼容对照表）
LABEL org.opencontainers.image.gpu.min_driver="520.61.05"

# 芯片架构代号:Ampere/Hopper/Turing
LABEL org.opencontainers.image.gpu.arch="Ampere,Hopper"

# 显存最低需求 GB
LABEL org.opencontainers.image.gpu.min_mem="16GB"

# 是否支持MIG切分
LABEL org.opencontainers.image.gpu.mig_support="true"

# 推理/训练场景
LABEL org.opencontainers.image.gpu.usage="inference,train"

对华为昇腾 NPU，可通过以下 Labels 扩展硬件和软件栈信息：

# NPU硬件&软件栈OCI扩展
LABEL org.opencontainers.image.cann.version="8.3.RC1"
LABEL org.opencontainers.image.npu.chip="Ascend310P,A2,Snt9B(A3),910B"
LABEL org.opencontainers.image.npu.min_driver="23.0.RC1"
LABEL org.opencontainers.image.npu.arch="Ascend-L2(A2)/Ascend-L3(A3)/Ascend-L1(310P)"

# NPU算力规格、最小物理显存
LABEL org.opencontainers.image.npu.min_mem="16GB"
LABEL org.opencontainers.image.npu.usage="inference/train"

# 依赖昇腾runtime
LABEL org.opencontainers.image.runtime.require="ascend-docker-runtime"

用户可根据业务需求自定义标签（Label），以更灵活地分类和管理资源。

查看镜像元数据

镜像在构建时增加了Labels之后，推到SWR企业仓上，在制品的详情中，可以查看相关的元数据信息（包括 Labels、构建时间、版本等），便于后续的版本管理和资源调度。详情请参见查看制品基本信息（后面加用户指南的超链接）。

相关文档