docker repositories.json 文件学习

Docker 的 repositories.json 是 Docker 引擎中用于记录本地镜像标签和引用关系的核心元数据文件。

1. 文件作用

• 记录镜像标签与 ID 的映射：
  存储本地镜像的标签（如 nginx:latest）与镜像实际存储的哈希值（如 sha256:abcdef…）之间的对应关系。
• 快速定位镜像：
  当用户通过镜像名称（如 docker pull nginx）操作镜像时，Docker 通过该文件快速找到对应的镜像层数据。

2. 文件路径

Docker 的 repositories.json 位于 Docker 的镜像存储目录中，路径如下：

/var/lib/docker/image/[驱动类型]/repositories.json
# 例如（默认驱动为 overlay2）：
/var/lib/docker/image/overlay2/repositories.json

3. 文件内容示例

{
  "library/nginx": {
    "latest": "sha256:1a2b3c4d5e6f7890...",
    "1.23": "sha256:deadbeefcafe...",
    "alpine": "sha256:feedfaceb00b..."
  },
  "my-registry.com/my-image": {
    "v1": "sha256:1337...",
    "latest": "sha256:ffffffff..."
  }
}

4. 关联文件

Docker 的镜像数据存储结构包含以下关键文件：

repositories.json：标签与镜像 ID 的映射。

• 镜像层文件：实际镜像层存储在 docker/image/[驱动类型]/imagedb/content/ 目录下，按 sha256 哈希值命名。
• 元数据文件：如 imagedb/immutable 记录镜像元数据。

5、FAQ

5.1、文件变成乱码如何操作

repositories.json 是 Docker 存储本地镜像标签与 ID 映射关系的核心文件，若文件内容变乱码，通常由以下原因导致：

• 文件损坏：Docker 异常退出（如强制关闭、崩溃）导致文件未正确写入。
• 编码问题：文件被非文本编辑器（如二进制工具）修改，或编码格式被错误转换（如 UTF-8 被改为 GBK）。
• 权限错误：Docker 无权读写该文件（如文件被其他用户/进程锁定）。
• 磁盘错误：存储该文件的磁盘出现坏扇区或文件系统损坏。
  修复办法如下：

# 备份
sudo cp /var/lib/docker/image/overlay2/repositories.json /var/lib/docker/image/overlay2/repositories.json.bak 

# 删除文件
sudo rm -rf /var/lib/docker/image/overlay2/repositories.json

# 重启dockerd,会重新创建文件
systemctl restart docker 

参考文档

1、https://docs.docker.com/docker-hub/repos/