Вход в Docker CLI: Docker Hub и приватные реестры

Docker

Быстрые ссылки

Logging Into Docker Hub
Access Tokens for 2FA Logins
Non-Interactive Logins
Logging Into Private Registries
Manually Adding Credentials
Multiple Accounts For One Registry
Credential Helpers
Logging Out
Common Problems
Summary

Зачем входить в Docker

Вход в Docker CLI позволяет:

Доступ к приватным образам вашего аккаунта.
Получить более высокий предел частоты запросов: аутентифицированные клиенты обычно имеют более щадящий лимит (в источнике указано 200 загрузок образов за шесть часов для авторизованных пользователей против 100 для анонимных).
Использовать операции push/pull в приватных реестрах и интеграцию CI.

Кратко: без логина у вас ограниченный доступ и более строгие лимиты.

Как работает аутентификация в Docker — модель в одной строке

Docker CLI хранит токен аутентификации в файле конфигурации (~/.docker/config.json) или доверяет внешнему помощнику по хранению секретов (credential helper). Для каждого реестра Docker запоминает только одну учётную запись по умолчанию.

Вход в Docker Hub

Чтобы войти в Docker Hub вручную, выполните:

$ docker login

Вам будет предложено ввести логин и пароль:

Username:

Password:

Если данные корректны, вы увидите:

Login Succeeded

Docker сохранит выданный токен в файле ~/.docker/config.json. Этот токен используется вместо передачи логина/пароля при последующих операциях.

Важно: для аккаунтов с двухфакторной аутентификацией (2FA) нельзя использовать обычный пароль — применяйте персональный токен доступа.

Персональные токены для аккаунтов с 2FA

Если в Docker Hub включен 2FA, создайте Personal Access Token в веб-интерфейсе. Перейдите в профиль → Account Settings → Security и создайте новый токен.

Создание токена доступа Docker Hub

Важно: при создании токена сохраните его отдельно. Веб-интерфейс покажет токен только один раз.

Используйте этот токен вместо пароля при docker login.

Непрерывный и безинтерактивный вход

Для автоматизации и CI удобно передавать имя пользователя и пароль через флаги:

$ docker login --username demo --password example

Но это рискованно: параметры командной строки могут остаться в истории оболочки или логах CI. Безопаснее читать пароль из STDIN:

$ cat password.txt | docker login --username demo --password-stdin

Рекомендации:

В CI храните токен в зашифрованном секретном хранилище и не выводите его в логи.
Не храните пароли в открытом виде в репозитории.

Вход в приватный реестр

По умолчанию docker login обращается к Docker Hub. Чтобы войти в собственный реестр, укажите его адрес:

$ docker login registry.example.com

Ввод тех же полей Username и Password применим и к кастомным реестрам. Вы можете одновременно быть авторизованы в нескольких реестрах — повторите команду для каждого реестра.

Ручное добавление учётных данных в конфиг

Иногда полезно добавить заранее получённый токен в ~/.docker/config.json, например в CI, где токен передаётся как переменная окружения.

Файл config.json содержит поле auths, где ключи — адреса реестров, а значение — объект с полем auth, содержащим Base64-значение токена. Пример структуры:

{
  "auths": {
    "registry.example.com": {
      "auth": "aWxtaW9ud..."
    }
  }
}

Для Docker Hub используйте ключ https://index.docker.io/v1/.

Примечание: вручную редактировать config.json безопасно, если вы контролируете права доступа к файлу и источник токена.

Несколько учётных записей для одного реестра

Ограничение: конфигурация по умолчанию предполагает одну учётную запись на реестр. Если вам нужно работать с разными пользователями в одном реестре, примените один из подходов:

Разделить конфигурации по файлам и выбирать нужный через –config или переменную DOCKER_CONFIG. Пример:

# Аутентификация как user-1
$ docker --config ~/docker/user-1.conf login registry.example.com --username user-1 --password foobar

# Аутентификация как user-2
$ docker --config ~/docker/user-2.conf login registry.example.com --username user-2 --password foobar

# Скачивание как user-1
$ docker --config ~/docker/user-1.conf pull my-team/my-project:latest

# Отправка как user-2
$ docker --config ~/docker/user-2.conf push my-team/my-project:latest

Сценарии/алиасы, которые автоматически подставляют нужный –config в зависимости от каталога или переменной окружения. Пример простого алиаса:

alias docker="docker --config ~/docker/$(basename $PWD).conf"

Настроить реестр так, чтобы в нём были проектные или сервисные аккаунты с нужными правами, и использовать их по назначению.

Совет: для CI используйте отдельный сервисный аккаунт с минимально необходимыми правами.

Credential helpers — безопасное хранение

По умолчанию Docker хранит креденшалы в виде токенов в ~/.docker/config.json, что считается менее безопасным. Credential helpers позволяют делегировать хранение паролей внешним менеджерам: Pass, macOS keychain, Windows Credentials Manager, Secret Service (Linux).

Настройка в config.json выглядит так:

{
  "credHelpers": {
    "registry.example.com": "pass"
  }
}

Когда включён helper, Docker вызывает его для команд store, get и erase. Это избавляет от хранения токенов в открытом виде в config.json и повышает безопасность локальной машины и CI-агентов.

Рекомендации:

На персональных машинах используйте системный менеджер секретов (keychain/credential manager).
В Linux рассмотрите pass или Secret Service (gnome-keyring).
В CI используйте механизмы провайдера (GitHub Actions Secrets, GitLab CI variables) и не храните токен в файле репозитория.

Выход из системы

Чтобы выйти из Docker Hub по умолчанию:

$ docker logout

Чтобы выйти из конкретного реестра:

$ docker logout registry.example.com

Альтернативно можно вручную удалить секцию реестра из ~/.docker/config.json или убрать запись в хранилище credential helper.

Частые проблемы и runbook устранения неполадок

Ниже — пошаговый план для устранения проблем с аутентификацией.

Проверка базовых вещей:

Убедитесь, что у вас правильный логин и токен/пароль.
Если включён 2FA, используйте Personal Access Token.
Проверьте, не истёк ли токен или не отозван ли он в интерфейсе реестра.

Выход и повторный вход:

$ docker logout
$ docker login

или для приватного реестра:

$ docker logout registry.example.com
$ docker login registry.example.com

Проверка файла конфигурации:

Откройте ~/.docker/config.json и убедитесь, что записи в auths или credHelpers соответствуют ожидаемым.
Проверьте, что права доступа к файлу корректны (обычно 600).

Несколько конфигураций:

Если вы используете –config или DOCKER_CONFIG, убедитесь, что команда запускается с нужной конфигурацией.
В CI проверьте, что переменные окружения и рабочие каталоги соответствуют ожидаемым.

Логи и диагностика:

Запустите docker pull/push с переменной окружения DOCKER_CLI_DEBUG=1 или используйте системные логи для получения дополнительной информации.
На уровне сети проверьте доступность реестра и корректность DNS/TLS.

Критерии приёмки

Успешный docker pull приватного образа требует, чтобы docker login возвращал Login Succeeded.
В CI job: образ можно скачать без ошибок доступа с учётом используемой конфигурации.

Ментальные модели и эвристики

Реестр ↔ одна учётная запись: если вам нужно переключать роли — используйте отдельные конфиги.
Токен = временный ключ доступа: относитесь к нему как к секрету.
CI = сервисный аккаунт с минимальными правами — не используйте личные токены.

Альтернативные подходы

Прокси-реестр: поставить прокси (например, Artifactory, Nexus, Harbor) и централизовать аутентификацию.
Использовать облачные реестры с интегрированной авторизацией (ECR, GCR, ACR) и их токены/ролики.
Использовать Kubernetes imagePullSecrets для деплоев в кластере.

Ролевые чеклисты

Разработчик:

Имею рабочий Docker Hub или реестр.
Установлен credential helper на локальной машине.
Не храню пароли в репозитории.

CI-инженер:

Использую сервисный аккаунт с минимальными правами.
Секреты хранятся в защищённом хранилище CI.
Скрипты используют –password-stdin или переменные среды.

Администратор реестра:

Настроены проекты/разрешения для команд.
Отслеживаются и ротацируются токены сервисных аккаунтов.
Предоставлены инструкции по добавлению credential helper.

SOP для безопасного подключения в CI

Создать сервисный аккаунт в реестре с нужными правами.
Сгенерировать персональный токен или ключ для этого аккаунта.
Поместить токен в защищённое хранилище CI (Secrets).
В job подтянуть токен как переменную среды.
Выполнить вход безопасно:

echo "$DOCKER_PASSWORD" | docker login --username "$DOCKER_USERNAME" --password-stdin registry.example.com

Выполнить операции push/pull.
Очистить сессии при необходимости: docker logout.

Тесты приёмки

Команда docker login возвращает Login Succeeded.
docker pull приватного образа проходит без ошибок.
В CI job логин проходит без вывода токена в логах.

Безопасность и приватность

Не храните токены в репозитории.
Ротация токенов: обновляйте сервисные токены по расписанию.
Ограничьте права сервисных аккаунтов по принципу наименьших привилегий.
В корпоративной среде интегрируйте реестр с IAM/SSO, если возможно.

Примечание о GDPR: персональные данные в токенах минимальны; тем не менее храните и обрабатывайте секреты в соответствии с корпоративными политиками и требованиями защиты данных.

Примеры ошибок и решения

Ошибка: unauthorized: authentication required

Проверьте, что вошли в нужный реестр (адрес совпадает).
Убедитесь, что токен не отозван.

Ошибка: denied: requested access to the resource is denied

Проверьте права пользователя на репозиторий.
Возможно, вы используете аккаунт без права push.

Ошибка: 401 Unauthorized с credential helper

Убедитесь, что helper установлен и доступен в PATH.
Проверьте, что конфигурация credHelpers указывает на корректный helper.

Decision flow для выбора метода логина

flowchart TD
  A[Нужен доступ к образам?] --> B{Приватный или публичный?}
  B -->|Публичный| C[Не требуется логин]
  B -->|Приватный| D{Где используется?}
  D -->|Локально| E[Использовать docker login + credential helper]
  D -->|CI| F[Использовать сервисный аккаунт + секрет CI]
  D -->|Множественные учётные записи| G[Разделить config через --config]
  E --> H[Ротировать токены, настроить helper]
  F --> H
  G --> H

Краткое резюме

Используйте docker login для доступа к приватным образам и для повышения лимитов запросов.
Для аккаунтов с 2FA применяйте Personal Access Token.
Для автоматизации используйте –password-stdin и безопасные секреты CI.
Для нескольких пользователей в одном реестре используйте отдельные файлы конфигурации или прокси-реестр.
Внедрите credential helpers для безопасного хранения токенов.

Важно: храните токены как секреты и периодически меняйте их.

Ресурсы и дальнейшие шаги

Настройте credential helper на вашей ОС.
Пересмотрите политику прав доступа в реестре и внедрите сервисные аккаунты для CI.
Добавьте проверки логина в ваши CI-пайплайны, чтобы заранее обнаруживать проблемы.