github/docker-login

docker-login-tool 镜像文档

一、镜像概述和主要用途

docker-login-tool 是一个轻量级Docker镜像，内置Docker CLI工具，专为在容器环境中执行Docker仓库登录操作设计。该镜像基于Alpine Linux构建，体积小巧且功能完整，可帮助用户在CI/CD流水线、容器化环境或临时场景中快速完成与Docker仓库（如Docker Hub、私有仓库）的身份验证，为后续镜像推送、拉取等操作提供前置认证支持。

二、核心功能和特性

核心功能

1. 内置Docker CLI：包含完整Docker客户端工具，支持标准docker login命令
2. 多仓库支持：兼容Docker Hub及各类私有Docker仓库（如Harbor、AWS ECR等）
3. 灵活认证方式：支持用户名密码、访问令牌（Token）等多种认证凭证
4. 配置持久化：可将认证信息写入宿主机Docker配置文件，实现跨容器复用

特性

• 轻量级：基于Alpine Linux，镜像体积<20MB
• 跨平台：支持amd64/arm64等主流架构
• 安全隔离：容器内执行登录操作，避免直接暴露宿主机环境
• 环境变量注入：支持通过环境变量传递敏感认证信息，无需硬编码

三、使用场景和适用范围

典型使用场景

1. CI/CD流水线：在Jenkins、GitLab CI等自动化流程中，作为前置步骤完成仓库登录，确保后续镜像推送权限
2. 多仓库管理：同一环境下需要登录多个私有仓库时，通过参数快速切换仓库地址
3. 临时环境认证：开发/测试环境中临时登录仓库，避免在宿主机残留认证信息
4. 容器化工具链：作为基础组件集成到需要与Docker仓库交互的容器化工具中（如镜像构建工具、部署脚本等）

适用范围

• 需自动化执行Docker仓库登录的场景
• 对环境隔离有要求的敏感操作（如生产环境认证）
• 资源受限环境（如边缘设备、轻量级CI节点）
• 跨平台Docker仓库交互需求

四、详细使用方法和配置说明

前提条件

• 宿主机已安装Docker Engine（19.03+）
• 目标Docker仓库账号（用户名/密码或访问令牌）
• 若使用私有仓库，需提前获取仓库完整URL（如https://registry.example.com/v2/）

核心配置参数

环境变量

基础使用流程

1. 拉取镜像（可选，docker run会自动拉取）：

   bash
   docker pull docker-login-tool:latest
   

2. 执行登录命令：通过docker run启动容器，注入环境变量并挂载宿主机Docker配置目录，完成登录后容器自动退出。

五、Docker部署方案示例

1. 基础登录Docker Hub（命令行参数模式）

直接通过命令行传递用户名和密码，登录Docker Hub：

bash
docker run --rm \
  -v $HOME/.docker:/root/.docker \  # 挂载宿主机Docker配置目录，持久化认证信息
  docker-login-tool:latest \
  docker login -u myusername -p mypassword

2. 登录私有仓库（环境变量模式）

通过环境变量指定私有仓库地址和认证信息（推荐生产环境使用，避免命令行暴露密码）：

bash
docker run --rm \
  -v $HOME/.docker:/root/.docker \
  -e DOCKER_REGISTRY=https://registry.example.com/v2/ \  # 私有仓库地址
  -e DOCKER_USERNAME=admin \                             # 私有仓库用户名
  -e DOCKER_PASSWORD=private-registry-token \            # 私有仓库访问令牌
  docker-login-tool:latest \
  docker login $DOCKER_REGISTRY -u $DOCKER_USERNAME -p $DOCKER_PASSWORD

3. docker-compose配置示例（CI/CD集成）

在docker-compose.yml中定义登录服务，用于CI流水线前置步骤：

yaml
version: '3.8'
services:
  docker-login:
    image: docker-login-tool:latest
    volumes:
      - $HOME/.docker:/root/.docker  # 挂载宿主机Docker配置
    environment:
      - DOCKER_REGISTRY=${REGISTRY_URL}  # 从CI环境变量注入仓库地址
      - DOCKER_USERNAME=${REGISTRY_USER} # 从CI环境变量注入用户名
      - DOCKER_PASSWORD=${REGISTRY_PWD}  # 从CI环境变量注入密码/令牌
    command: docker login $DOCKER_REGISTRY -u $DOCKER_USERNAME -p $DOCKER_PASSWORD

使用方式：在CI脚本中执行docker-compose run docker-login，完成登录后自动退出。

六、注意事项

1. 敏感信息安全：

   • 避免在命令行直接传递密码（可被ps命令捕获），优先使用环境变量或CI/CD的"保密变量"功能
   • 访问令牌应遵循最小权限原则（如仅授予push/pull权限）

2. 配置文件权限：

   • 宿主机挂载目录$HOME/.docker需确保读写权限（容器内默认以root用户执行，宿主机对应目录权限需允许root访问）

3. 仓库地址格式：

   • 私有仓库地址需包含协议（http://或https://）和版本路径（如/v2/），示例：https://registry.example.com:5000/v2/

4. 镜像更新：

   • 建议固定镜像标签（如docker-login-tool:1.0.0），避免自动拉取最新版导致兼容性问题

七、验证登录结果

登录成功后，可通过以下方式验证：

1. 检查宿主机Docker配置文件：

   bash
   cat $HOME/.docker/config.json | grep "auth"  # 若存在对应仓库的auth字段，说明登录成功
   

2. 容器内验证（需保留容器，移除--rm参数）：

   bash
   docker run -it --name temp-login \
     -v $HOME/.docker:/root/.docker \
     -e DOCKER_REGISTRY=... \
     docker-login-tool:latest \
     sh -c "docker login $DOCKER_REGISTRY -u $DOCKER_USERNAME -p $DOCKER_PASSWORD && cat /root/.docker/config.json"
   

八、版本信息

• 最新稳定版：docker-login-tool:1.0.0
• 基础镜像：alpine:3.18
• Docker CLI版本：24.0.6