config.json

~/.docker/config.json 是 Docker 客户端（不是Docker守护进程）的核心配置文件，主要用于存储与镜像仓库交互的认证信息和部分客户端设置

通常情况下，不建议手动编辑或创建这个文件。执行 docker login <仓库地址> 命令是更安全、可靠的方式，Docker客户端会自动处理格式并更新此文件。同时，请确保文件权限设置为 600，以防其他用户读取敏感信息：chmod 600 ~/.docker/config.json。

{
  "auths": {
    "https://index.docker.io/v1/": {
      "auth": "dXNlcm5hbWU6cGFzc3dvcmQ="
    },
    "your.private.registry": {
      "username": "your_name",
      "password": "your_password",
      "email": "email@example.com"
    }
  },
  "credsStore": "desktop",
  "experimental": "enabled",
  "stackOrchestrator": "kubernetes",
  "HttpHeaders": {
    "User-Agent": "Docker-Client"
  },
  "psFormat": "table {{.ID}}\\t{{.Names}}\\t{{.Status}}"
}

机制原理

凭证管理机制

当执行 docker login 命令时，Docker 客户端会将输入的用户名和密码进行 Base64 编码，并写入 config.json 的 auths 字段。后续与对应 Registry 通信时，CLI 自动读取该凭据完成认证。在执行 docker logout 命令时，Docker 删除对应仓库的 auths 字段。`

凭证信息存储支持两种方式：

传统方式：auth 字段，其值是 用户名:密码 经过Base64编码后的字符串。这不是加密，仅是一种编码，可以轻易解码还原，因此存在安全风险。

分离方式：使用独立的 username 和 password 字段。

使用凭证存储（如 Docker Desktop 集成的密钥链 ）可提升安全性，防止敏感信息以明文形式暴露在文件系统中。开发者可通过修改 credsStore 值切换不同的凭据辅助程序。如："credsStore": "desktop"。

credsStore

Docker 配置文件中的 credsStore 与 credHelpers 字段用于管理镜像仓库的认证信息，二者通过外部程序实现凭据的安全存储与调用。

与 credHelpers 的优先级：如果同时配置了 credHelpers（为特定仓库指定助手）和 credsStore，对于在 credHelpers 中列出的仓库，会优先使用 credHelpers 指定的助手。

credsStore 它用来指定一个系统级的凭据管理工具，将所有镜像仓库的登录凭证加密存储在操作系统的安全服务中，而不是以明文或 Base64 编码形式保存在 config.json 文件里。

在操作系统层面管理密钥：

不同的操作系统有不同的内置助手：

对于 Linux 系统，如果没有 pass，常用的替代品还有 secretservice (兼容 GNOME Keyring、KWallet 等)。

而 desktop 仅在有 Docker Desktop 环境才可用， 而 Docker Desktop 可能涉及商业收费。

使用凭据助手提升密钥安全性（以ecr-login为例）

在容器化部署中，安全访问私有镜像仓库是关键环节。AWS ECR 通过 Docker 凭据助手简化身份验证流程，避免明文暴露长期凭证。

在云平台管理密钥：

不同的公有云厂商提供了不同的方式来管理密钥， 可以通过通过 credsstore管理，但是更推荐使用下文的 credHelpers 管理。

例如 AWS 提供 ecr-login 的方式支持

首先需安装 apt/yum/dnf install amazon-ecr-credential-helper 并配置 Docker 客户端：

{
  "credsStore": "ecr-login"
}

该配置位于 ~/.docker/config.json，指示 Docker 使用 ecr-login 工具自动获取临时令牌。

1. 当执行 docker pull/push 时，Docker 调用凭据助手
2. 助手通过 AWS SDK 获取 STS 临时凭证，有效期通常为12小时
3. 自动生成 Base64 编码的认证信息供 Docker 使用

此机制实现最小权限原则，显著降低密钥泄露风险。

credHelpers

Docker 配置文件中的 credsStore 与 credHelpers 字段用于管理镜像仓库的认证信息，二者通过外部程序实现凭据的安全存储与调用。

credHelpers 个比 credsStore 更精细、优先级更高的配置项，它允许你为不同的镜像仓库指定不同的专用凭证助手。

在大型企业中，容器镜像的拉取频繁且涉及多个私有仓库，手动管理认证信息既低效又存在安全风险。凭据助手通过与操作系统级密钥链或企业身份系统集成，实现安全、自动化的凭据获取。

在云平台，例如，在 Amazon ECR 的上有个私有的镜像 123456789.dkr.ecr.us-east-1.amazonaws.com/my-image:latest

1. 需要首先需安装 apt/yum/dnf install amazon-ecr-credential-helper
2. 编辑配置文件：编辑 ~/.docker/config.json 添加 credHelpers 字段。

{
  "credHelpers": {
    "123456789.dkr.ecr.us-east-1.amazonaws.com": "ecr-login", // AWS 私有镜像仓库
    "gcr.io": "gcloud", // Google容器注册表
    "asia.gcr.io": "gcloud", // Google亚洲镜像
    "my.private.registry:5000": "pass" // 私有仓库，使用pass助手
  }
}

3. 无需运行 docker login，直接执行 docker pull 123456789.dkr.ecr.us-east-1.amazonaws.com/my-image:latest。助手会自动调用 AWS API 获取临时令牌。适用于 AWS ECR 等需动态认证的场景。后者通过 IAM 角色获取签名的登录密码，避免长期凭证暴露。

企业集成优势:

• 支持单点登录（SSO）与 OAuth2 集成，提升安全性
• 动态生成短期凭据，符合最小权限原则
• 集中审计凭据使用行为，满足合规要求

HttpHeaders

HTTP请求中的headers用于传递客户端与服务器之间的元数据，广泛应用于身份验证、内容协商和缓存控制等场景。

常见使用场景

• 认证授权：通过Authorization头携带JWT或Basic认证信息
• 内容类型标识：使用Content-Type告知服务器请求体格式（如application/json）
• 跨域控制：服务端通过Access-Control-Allow-Origin响应头管理CORS策略