docker cp — копирование файлов между хостом и контейнером

Иллюстрация: логотип Docker

Кратко

docker cp позволяет быстро переносить файлы и каталоги между вашей локальной системой и файловой системой запущенного контейнера. Используйте его для отладки, временных исправлений и извлечения логов; для долговременного хранения и синхронизации предпочитайте тома и bind-монты.

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

Базовый синтаксис
Копирование целых директорий
Поведение при копировании
Ограничения команды
Использование bind-монтов для обмена файлами
Разница с COPY в Dockerfile
Когда использовать docker cp
Резюме

Нужно переместить файлы внутрь контейнера или извлечь их наружу? Команда docker cp копирует между файловыми системами хоста и контейнера, позволяя добавить конфигурацию, создать резервную копию или восстановить данные без перестройки образа.

Базовый синтаксис

Команда принимает два аргумента — исходный путь и путь назначения:

docker cp example.txt my-container:/example.txt

В этом примере файл example.txt из текущей рабочей директории копируется в контейнер с именем my-container в путь /example.txt. Поменяйте аргументы местами, чтобы извлечь файл из контейнера на хост.

Путь, относящийся к контейнеру, должен быть предварён идентификатором контейнера или его именем с двоеточием :. Найти ID или имя запущенного контейнера можно через docker ps.

Вывод команды docker ps — список контейнеров с ID, именами и статусом

Каждый запуск docker cp требует одного локального пути и одного пути контейнера — нельзя напрямую копировать между двумя контейнерами. Для этого используйте двухшаговый подход: сначала из исходного контейнера на хост, затем с хоста в целевой контейнер.

Копирование целых директорий

docker cp умеет рекурсивно копировать каталоги:

docker cp /home/demo/website apache-container:/var/www/html/.

Команда скопирует все содержимое /home/demo/website в /var/www/html внутри контейнера apache-container.

Поведение при копировании

При копировании файлов Docker создаёт новый файл в месте назначения, если он отсутствует. Существующие файлы перезаписываются. Если целью является директория, файл будет скопирован внутрь неё под исходным именем.

Есть тонкость: если путь назначения заканчивается слэшем (/) и этот путь не существует, будет ошибка.

Для каталогов поведение чуть сложнее. Если путь назначения не существует, Docker создаст новый каталог со всем содержимым источника. Если путь существует, результат зависит от наличия компонентa /. на конце источника или назначения:

Если в конце указан /. — содержимое исходной директории копируется внутрь существующей директории назначения.
Если /. не указан — сам каталог-источник копируется как поддиректория внутри назначения.

Примеры:

# создаст /var/www/html/website с содержимым сайта
docker cp /home/demo/website apache-container:/var/www/html

# скопирует содержимое website прямо в /var/www/html
docker cp /home/demo/website/. apache-container:/var/www/html

Эта тонкая разница определяет, будет ли создана дополнительная подпапка или только её содержимое окажется в целевом каталоге.

Ограничения команды

Несмотря на название, docker cp не реализует все возможности системной утилиты cp. Большинство флагов cp не поддерживается — исключения:

-a — архивный режим; пытается сохранить информацию о владельцах и группах, метаданные файлов.
-L — следование символическим ссылкам: копируются целевые файлы, а не сами ссылки.

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

Использование bind-монтов для копирования файлов

Тома и bind-монты часто заменяют необходимость в docker cp. Bind-монт локальной директории в контейнер даёт прямой доступ к тем же файлам с обеих сторон:

docker run -v /example/host/directory:/container/path my-image:latest

Содержимое /example/host/directory будет доступно внутри контейнера по пути /container/path. На хосте можно работать с этими файлами средствами cp, rsync или графическим файловым менеджером.

Когда это удобно:

Если вам нужен постоянный доступ к определённой директории контейнера.
Если вы хотите редактировать файлы локально и видеть изменения сразу в контейнере (полезно при разработке).

Ограничения bind-монтов:

Требуется заранее знать пути, которые будут смонтированы при создании контейнера.
Внимание к правам доступа: файлы, созданные внутри контейнера, часто принадлежат пользователю root на хосте. Это может привести к невозможности редактирования или удаления файлов на хосте.

Рекомендации при проблемах с правами:

Используйте chown внутри контейнера или на хосте.
Применяйте пользовательские маппинги UID/GID при запуске контейнера.
В production среде рассмотрите запуск процессов в контейнере от непривилегированного пользователя.

Разница между docker cp и COPY в Dockerfile

Команду docker cp иногда путают с инструкцией COPY в Dockerfile. Это разные задачи:

COPY добавляет файлы в образ на этапе сборки docker build:

COPY /home/me/my-website /var/www/html/.

Такие файлы становятся частью образа и будут одинаковыми во всех контейнерах, созданных из него.

docker cp работает с уже запущенными контейнерами — это способ изменить файл в состоянии runtime.

Иными словами: COPY формирует статичный образ; docker cp модифицирует живой контейнер.

Когда использовать docker cp

Использование docker cp должно быть редким при корректном применении практик контейнеризации. Общие рекомендации:

Предпочитайте тома (volumes) для долговременного хранения и переноса данных.
Используйте переменные окружения, конфигурационные файлы в образе и секреты для настройки приложений.
Применяйте docker cp для быстрого отладки, восстановления логов или внесения временных правок.

docker cp удобен в разработке и при экстренной диагностике: вы можете быстро извлечь лог, временно заменить конфигурацию или восстановить отдельные файлы. Но помните: изменения внутри контейнера пропадут, если контейнер будет удалён и создан заново из образа.

Практические приёмы и примеры

Короткие рабочие примеры:

Копирование файла внутрь контейнера:

docker cp ./config.yml my-app:/app/config.yml

Извлечение файла:

docker cp my-app:/var/log/app.log ./app.log

Копирование каталога целиком с сохранением структуры:

docker cp /home/user/site my-app:/var/www/

Копирование содержимого каталога (без создания дополнительной поддиректории):

docker cp /home/user/site/. my-app:/var/www/

Копирование между контейнерами через хост (двухшаговый метод):

# сначала из контейнера A на хост
docker cp containerA:/data/dump.sql ./dump.sql

# затем с хоста в контейнер B
docker cp ./dump.sql containerB:/data/dump.sql

Копирование с сохранением владельцев/атрибутов (если поддерживается):

docker cp -a /home/user/data container:/backup/data

Дополнительный трюк с tar для сохранения прав и спецфайлов (на случай сложных деревьев):

# на хосте упаковка и передача в контейнер
tar -C /path/to/dir -c . | docker exec -i container bash -c "tar -C /target/dir -x"

# или обратный поток из контейнера на хост
docker exec container tar -C /target/dir -c . | tar -C /local/dir -x

Этот подход полезен, если нужно аккуратно перенести права доступа, устройства или сокеты.

Когда docker cp не подходит

Если нужно синхронизировать большие объёмы данных по сети с минимальными изменениями — лучше rsync или внешняя синхронизация.
Если нужна атомарная и воспроизводимая сборка — добавьте файлы в образ через COPY и управляйте версиями образов.
Для постоянного хранения и совместного использования между контейнерами используйте Docker volumes.

Чек-лист перед копированием

Убедитесь, что контейнер запущен: docker ps.
Проверьте путь назначения в контейнере и права доступа.
Подумайте, нужен ли вам -a или -L.
Для больших деревьев подумайте о tar/streaming, чтобы сохранить атрибуты.
Если копируете конфигурацию в production, задокументируйте изменения или применяйте их через CI.

Плейбук: простой SOP для копирования конфигурации в контейнер

Остановите сервис внутри контейнера, если это требуется для согласованности данных.
Проверите и сделайте бэкап текущего файла:

docker cp my-app:/app/config.yml ./config.yml.bak

Скопируйте новую конфигурацию:

docker cp ./config.new.yml my-app:/app/config.yml

Проверите права и при необходимости скорректируйте:

docker exec my-app chown appuser:appgroup /app/config.yml

Перезапустите сервис внутри контейнера или сам контейнер.
Проверите логи и работоспособность.

План действий при ошибке (Runbook)

Сценарий: после копирования приложение не стартует.

Откат: восстановите бэкап

docker cp ./config.yml.bak my-app:/app/config.yml

Проверка прав и SELinux (если применимо):

docker exec my-app ls -l /app/config.yml

Просмотрите логи приложения:

docker logs my-app --tail 200

Если проблема в формате файла, откатите изменения в системе контроля версий и повторите процесс через CI/CD.

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

Файл успешно доступен по ожидаемому пути внутри контейнера.
Приложение распознаёт новую конфигурацию и стартует без ошибок.
Права доступа и владельцы соответствуют ожиданиям окружения.
Изменение задокументировано, и при необходимости есть резервная копия.

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

Treat images as immutable artifacts: внесение изменений в запущенный контейнер — временное решение.
Если вам приходится часто копировать файлы вручную — подумайте о лучшем проектировании CI/CD и используйте тома.
Для единоразовых задач и отладки docker cp — простой и быстрый инструмент.

Короткая справка по командам

docker cp [SRC] [CONTAINER:DEST] — копирует файл или директорию.
docker exec -i container tar -C /src -c . | tar -C /dst -x — потоковое копирование с сохранением атрибутов.
docker run -v /host/dir:/container/dir — bind-монт для постоянного обмена файлами.

Глоссарий (в 1 строку)

Контейнер — изолированный процесс с собственной файловой системой, созданный из образа.
Образ — слоистый шаблон, используемый для запуска контейнеров.
Тома — способ хранения данных, независимый от жизненного цикла контейнера.
Bind-монт — привязка директории хоста к пути внутри контейнера.
COPY — инструкция Dockerfile для добавления файлов в образ во время сборки.

Резюме

docker cp — удобный инструмент для простой передачи файлов между хостом и запущенным контейнером. Он не заменяет тома, bind-монты или воспроизводимую сборку образов, но незаменим при отладке, извлечении логов и экстренных правках. Всегда учитывайте права доступа и длительность жизни контейнера: если изменения должны пережить перезапуск, используйте тома или интегрируйте изменения в процесс сборки образа.

Важно

Регулярное использование docker cp в production сигнализирует о недостатках процесса развёртывания или управления данными. Планируйте миграцию к более устойчивым схемам хранения и доставки конфигураций.