凭据助手（Credential Helper）是 Docker 提供的安全机制，用于将认证凭据交由系统级密钥管理器（如 macOS 的 osxkeychain、Linux 的 pass 或 Windows 的 wincred）处理，避免 Base64 编码的明文凭据直接写入 ~/.docker/config.json。

什么是凭据助手（Credential Helper）

凭据助手是 docker 提供的一种安全机制，用于替代将 base64 编码的用户名密码直接写入 ~/.docker/config.json 的做法。它把敏感凭证交由操作系统级密钥管理器处理——比如 macos 的 osxkeychain、linux 的 pass 或 windows 的 wincred，避免明文或可逆编码凭据长期落盘。

如何启用凭据助手

启用前需先安装对应平台的 helper 工具，再在 Docker 配置中声明使用：

• macOS：通常已预装 osxkeychain，无需额外安装；确认配置中包含：
  "credsStore": "osxkeychain"
• Linux（Ubuntu/Debian）：
  安装 pass 和 gnupg：
  sudo apt install pass gnupg
  初始化 GPG 密钥并配置 pass：
  gpg2 --generate-key → 按提示完成 → pass init <your-gpg-id></your-gpg-id>
  再安装 docker-credential-pass 并软链：
  sudo mv docker-credential-pass /usr/local/bin/
sudo chmod +x /usr/local/bin/docker-credential-pass
• Windows（Docker Desktop）：默认启用 wincred，无需手动配置；如需验证，检查 config.json 中是否有 "credsStore": "wincred"

配置生效与验证方法

修改或生成 ~/.docker/config.json，确保结构类似：

Docker Image Puller

使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。

下载

{
  "credsStore": "osxkeychain",
  "auths": {
    "my-registry.example.com": {}
  }
}

执行登录命令后，Docker 不再往 auths 下写 auth 字段，而是调用 helper 存储凭证：

• 运行 docker login my-registry.example.com，输入账号密码
• 成功后，auths 中该 registry 对应值为空对象（{}），表示凭据已交由系统密钥环管理
• 验证是否生效：尝试拉取私有镜像，如 docker pull my-registry.example.com/app:latest，若成功即说明 helper 正常工作

常见问题与注意事项

启用 helper 后仍需注意以下几点：

• 不要手动编辑 config.json 中的 auth 字段——这会绕过 helper，导致混合存储，降低安全性
• CI/CD 环境中慎用 helper：多数流水线节点无图形界面或密钥环服务，建议改用短期 Token 或服务账户 + --password-stdin 方式临时登录
• 云厂商专用 helper（如 ecr-login）需单独安装并注册：
  aws configure 设置好权限 → 安装 amazon-ecr-credential-helper → 在 config.json 中添加：
  "credHelpers": { "123456789012.dkr.ecr.us-east-1.amazonaws.com": "ecr-login" }