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

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

• Вход в Docker Hub
• Токены доступа для 2FA
• Без‑интерактивный вход
• Вход в приватные реестры
• Ручное добавление учётных данных
• Несколько аккаунтов для одного реестра
• Помощники учётных данных
• Выход из системы
• Частые проблемы
• Рекомендации по безопасности
• Итог

Что такое аутентификация Docker

Аутентификация Docker — это процесс, при котором Docker CLI получает токен доступа для взаимодействия с реестром образов. Токен хранится локально и используется при push/pull операциях. Краткое определение: токен — временный ключ доступа, связанный с вашей учётной записью.

Вход в Docker Hub

Вход в Docker Hub даёт доступ к приватным репозиториям, привязанным к вашей учётной записи. Также аутентифицированные клиенты получают более высокий порог запросов к API: 200 загрузок образов за шесть часов вместо 100 для неавторизованных.

Чтобы войти, выполните команду:

$ docker login

Вас попросят ввести имя пользователя и пароль:

Username:

Password:

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

Login Succeeded

Docker сохранит выданный токен в файле ~/.docker/config.json.

Важно: если у вас включена двухфакторная аутентификация, пароль не подойдёт. Читайте раздел про токены доступа ниже.

Токены доступа при 2FA

Если на аккаунте Docker Hub включена двухфакторная аутентификация, используйте Personal Access Token вместо пароля. Создать токен можно в веб‑интерфейсе Docker Hub: профиль → Account Settings → Security → New Access Token.

Скопируйте токен сразу после создания — в интерфейсе он показывается только один раз. При входе в CLI вставляйте токен вместо пароля.

Без‑интерактивный вход

Для автоматизации и CI используйте флаги или чтение пароля из STDIN.

Наиболее простой, но менее безопасный способ:

$ docker login --username demo --password example

Более безопасно читать пароль из STDIN, чтобы не оставлять его в истории команд:

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

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

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

Вы можете логиниться в самописные (self-hosted) реестры. Передайте hostname (и порт, если нужен) как аргумент:

$ docker login registry.example.com

Также доступны флаги --username, --password, --password-stdin. Docker поддерживает одновременную аутентификацию в нескольких реестрах — повторите docker login для каждого.

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

В CI иногда удобнее заранее добавить токен в config.json. Структура файла содержит поле auths. Пример (сохраняйте этот файл с правами доступа 600):

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

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

Важно: auth — это base64‑строка вида username:token. Не храните незашифрованные пароли в репозиториях.

Несколько аккаунтов для одного реестра

Ограничение: Docker связывает один набор учётных данных с одним ключом реестра в config.json. Поэтому одновременно быть залогиненным под двумя разными пользователями в одном реестре нельзя в рамках одного файла конфигурации.

Решение: используйте несколько файлов конфигурации и флаг --config или переменную DOCKER_CONFIG для каждой операции.

Пример сценария:

# Authenticate as user-1
$ docker --config ~/docker/user-1.conf login registry.example.com --username user-1 --password foobar

# Authenticate as user-2
$ docker --config ~/docker/user-2.conf login registry.example.com --username user-2 --password foobar

# Pull as user-1
$ docker --config ~/docker/user-1.conf pull my-team/my-project:latest

# Push as user-2
$ docker --config ~/docker/user-2.conf push my-team/my-project:latest

Для удобства можно завести alias или функцию, которая подставляет нужный --config на основе каталога проекта:

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

Помощники для учётных данных (Credential helpers)

По умолчанию Docker сохраняет данные в ~/.docker/config.json в открытом виде. Для лучшей защиты используйте credential helper. В config.json можно привязать конкретный реестр к помощнику через поле credHelpers:

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

Доступные помощники: pass (Linux), osxkeychain (macOS), wincred (Windows) и другие из пакета docker-credential-helpers.

Как это работает: при выполнении команд Docker вызывает помощник для операций store/get/erase. Сам файл config.json тогда не содержит auth для этих реестров.

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

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

Чтобы удалить учётные данные с локальной машины, используйте:

$ docker logout

По умолчанию лог-аут происходит из Docker Hub. Для приватного реестра передайте hostname:

$ docker logout registry.example.com

Или удалите соответствующую секцию вручную из ~/.docker/config.json.

Частые проблемы и шаги устранения

1. Неверные или устаревшие токены

   • Проверьте, не истёк ли токен.
   • Для 2FA‑аккаунтов убедитесь, что используете Personal Access Token.

2. Неправильный файл config

   • Убедитесь, что используете верный --config или DOCKER_CONFIG.
   • Проверьте права доступа к файлу (chmod 600).

3. Проблемы с помощниками учётных данных

   • Проверьте, установлен ли сам помощник и доступен ли он в PATH.
   • На macOS и Windows используйте системные ключницы и убедитесь, что они работают корректно.

4. Ошибки сети и TLS

   • Для самописных реестров проверьте сертификаты. При использовании самоподписанных TLS‑сертификатов настройте доверие на клиенте.

Быстрая последовательность действий при проблеме:

$ docker logout
$ docker login --username  --password-stdin

Если не помогает, проверьте содержимое ~/.docker/config.json и логи реестра.

Рекомендации по безопасности

• Используйте Personal Access Token вместо пароля. Токены можно ограничить по правам и сроку жизни.
• Не храните пароли в репозиториях. Для CI используйте защищённые переменные окружения.
• Применяйте credential helper для интеграции с хранилищем ключей ОС.
• Ограничьте права токенов до необходимого минимума (read/pull или write/push).
• Ротация токенов: планируйте регулярную смену ключей и автоматический откат при компрометации.

Практические чек‑листы

Чек‑лист для разработчика:

• Есть доступ к нужному реестру
• [ ] Выполнен docker login с правильным профилем
• Используется token при 2FA
• [ ] Проверен docker pull нужного образа

Чек‑лист для CI‑оператора:

• Секреты сохранены в защищённых переменных
• [ ] Используется --password-stdin в скриптах
• Параллельные конфиги для разных учётных записей
• Логи не содержат секретов

Чек‑лист для администратора реестра:

• Настроены роли и scoped accounts
• TLS сертификаты корректны
• Логи аутентификации доступны для аудита
• Ограничены rate limits и мониторинг

Шпаргалка команд (Cheat sheet)

Входы и выходы:

# Вход в Docker Hub (интерактивно)
$ docker login

# Без‑интерактивный вход (STDIN)
$ echo $DOCKER_PASS | docker login --username $DOCKER_USER --password-stdin

# Вход в приватный реестр
$ docker login registry.example.com

# Выход из реестра
$ docker logout registry.example.com

# Использование отдельного конфига
$ docker --config ~/docker/user-1.conf pull my-team/my-project:latest

Когда это не работает — типичные причины

• Токен был отозван или истёк. Решение: сгенерировать новый.
• Пароль заменён на токен для 2FA. Решение: используйте токен.
• Неправильный файл конфигурации загружается. Решение: проверка DOCKER_CONFIG и --config.
• Помощник учётных данных отсутствует или несовместим с ОС. Решение: установить соответствующий помощник.
• Проблемы TLS в самописном реестре. Решение: добавить доверенный сертификат или настроить CA.

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

1. Использовать прокси‑реестр (например, Harbor, Nexus) для централизованной аутентификации.
2. В CI вместо docker login использовать облачные интеграции (GitHub Packages, GitLab Registry) и их токены доступа.
3. Для автоматизированных билдов применять ephemeral tokens (короткоживущие ключи).

Каждый подход меняет модель безопасности и удобство. Выберите тот, который соответствует требованиям вашей инфраструктуры.

Совместимость и миграция

• macOS: используйте osxkeychain helper.
• Windows: применяйте wincred или встроенный Credential Manager.
• Linux: используйте pass или secretservice (D‑Bus).

При миграции с одного помощника на другой экспортируйте/удалите учётные записи из старого хранилища и добавьте их через новый.

Часто задаваемые вопросы

Какой формат у поля auth в config.json?

auth — это base64 от строки username:password_or_token. Docker использует её для аутентификации, но при наличии credential helper этот поля обычно нет.

Можно ли дать токен с чтением только для одного репозитория?

Да, в Docker Hub можно создавать токены с ограниченным набором прав и доступом к конкретным организациям или репозиториям, если аккаунт и план это поддерживают.

Что делать, если docker login пишет “Login Succeeded”, но docker pull выдаёт 401?

Проверьте, что конфиг используется тот же самый, что и при логине (--config/DOCKER_CONFIG). Убедитесь, что токен не отозван и что реестр распознаёт права этого токена.

Можно ли автоматизировать ротацию токенов?

Да. Настройте процесс в CI/CD, который создаёт новый токен, обновляет секреты в системе секретного хранилища, и периодически удаляет старые токены.

FAQ (структурированные ответы)

Перед применением изменений в продакшн проверьте процедуру в тестовой среде и убедитесь, что права токенов корректны.

Итог

docker login — основной инструмент для подключения Docker CLI к Docker Hub и приватным реестрам. Для 2FA используйте Personal Access Token. Для нескольких учётных записей на одном реестре применяйте разные файлы конфигурации или credential helpers. Обязательно храните секреты безопасно и автоматизируйте процесс в CI с учётом ротации токенов.

Ключевые команды напоминание: docker login, docker logout, --password-stdin, --config, credential helpers.