Docker镜像打包规范

针对“Docker镜像打包应该搞个规范，加上点元数据，例如谁打包的、来自哪一个代码库。如果使用流水线操作，那么就记录下是谁触发的流水线。”这一需求，指定一个可行的规范

Docker 镜像元数据规范目标：

在不需要进入容器、不改业务代码的前提下，就能知道： 这个镜像是谁打的、从哪里来的、怎么触发的、是否可信。

---

一、总体设计思路

1. 用 OCI 标准 Label + 可选 OCI Artifact 存“人类可读、机器可查”的元数据
2. 用镜像 Tag + Digest 解决“定位”问题

---

二、推荐方案：OCI Image Label

为什么选 Label？

• Docker / containerd / Kubernetes 全兼容
• docker inspect / crane config / skopeo 可直接查看
• 不依赖额外存储系统
• 符合 OCI Image Spec

---

三、标准 Label 规范（强制字段）

基础标识

Label Key	含义	示例
org.opencontainers.image.title	镜像/服务名	user-service
org.opencontainers.image.version	语义化版本	1.2.3
org.opencontainers.image.revision	Git Commit ID	9fceb02
org.opencontainers.image.source	代码仓库地址	https://git.example.com/backend/user-service.git
org.opencontainers.image.created	镜像构建时间（ISO8601）	2026-01-15T10:20:30Z

这些是 OCI 官方推荐字段，必须填

---

团队自定义字段

统一前缀：

io.company.image.*

Label Key	含义	示例
io.company.image.built-by	构建执行主体	ci-runner / zhangsan / tekton
io.company.image.builder-type	构建方式	pipeline / local / github-actions
io.company.image.pipeline	流水线地址	https://ci.example.com/job/123
io.company.image.pipeline-trigger	触发人	zhangsan
io.company.image.pipeline-trigger-type	触发方式	manual / push / tag / schedule
io.company.image.branch	代码分支	release/1.2
io.company.image.commit-message	提交说明（可选）	fix: login bug
io.company.image.environment	目标环境	prod / staging / dev
io.company.image.audit-id	审计编号（可选）	BLD-20260115-001

---

四、Dockerfile 示例（规范写法）

ARG GIT_COMMIT
ARG GIT_REPO
ARG BUILD_USER
ARG PIPELINE_URL
ARG TRIGGER_USER
LABEL org.opencontainers.image.title="user-service" \
      org.opencontainers.image.version="1.2.3" \
      org.opencontainers.image.revision="${GIT_COMMIT}" \
      org.opencontainers.image.source="${GIT_REPO}" \
      org.opencontainers.image.created="2026-01-15T10:20:30Z" \
      io.company.image.built-by="${BUILD_USER}" \
      io.company.image.builder-type="pipeline" \
      io.company.image.pipeline="${PIPELINE_URL}" \
      io.company.image.pipeline-trigger="${TRIGGER_USER}"

所有变量由 CI 自动注入

---

五、CI 流水线注入示例（伪代码）

docker build \
  --build-arg GIT_COMMIT=$CI_COMMIT_SHA \
  --build-arg GIT_REPO=$CI_REPOSITORY_URL \
  --build-arg BUILD_USER=$RUNNER_NAME \
  --build-arg PIPELINE_URL=$CI_PIPELINE_URL \
  --build-arg TRIGGER_USER=$CI_PIPELINE_TRIGGERED_BY \
  -t registry.example.com/user-service:1.2.3 .

禁止本地手动 build 并 push 到生产仓库

---

六、镜像 Tag 规范

建议：

<image>:<major>.<minor>.<patch>-<env>.<git-short>

示例：

user-service:1.2.3-prod.9fceb02

生产镜像必须：

1. 使用 immutable tag
2. 以 Git Commit 为唯一来源
3. 禁止使用 latest