# 镜像构建时添加元数据
#### 概述
在构建镜像时，建议嵌入必要的元数据信息，如镜像版本、构建时间、维护者等。这能够方便后续的镜像识别、版本控制以及运维管理。
使用 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 镜像规范注解](https://specs.opencontainers.org/image-spec/annotations/?v=v1.1.1)。
#### 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"
```
表1OCI 标准 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"
```
![](https://support.huaweicloud.com/bestpractice2-swr/public_sys-resources/note_3.0-zh-cn.png)
用户可根据业务需求自定义标签（Label），以更灵活地分类和管理资源。
#### 查看镜像元数据
镜像在构建时增加了Labels之后，推到SWR企业仓上，在制品的详情中，可以查看相关的元数据信息（包括 Labels、构建时间、版本等），便于后续的版本管理和资源调度。详情请参见查看制品基本信息（后面加用户指南的超链接）。