Docker Compose cp 怎样在服务容器和本地之间复制目录

排查容器里的导出文件、取回生成报告，或者把本地准备好的配置放进正在运行的服务时，最容易出错的不是路径本身，而是把复制方向写反。docker compose cp 用服务名加冒号区分容器路径：SERVICE:SRC_PATH DEST_PATH 表示从服务容器复制到本地，反过来写成 SRC_PATH SERVICE:DEST_PATH 就是从本地复制到容器。

官方地址：https://docs.docker.com/reference/cli/docker/compose/cp/

先确认“源路径在哪一侧”，再写目标路径；有多个服务副本时补上 --index，需要保留元数据或跟随符号链接时再分别考虑 --archive 和 -L。

先把服务路径和本地路径分开

Compose 的服务名不是容器名。命令中的 app:/workspace/export 表示服务 app 对应容器里的路径，./backup 则是当前项目目录下的本地路径。可以先列出服务状态，确认名称和副本数量，再决定复制方向。

# 先确认 Compose 项目中的服务名称和运行状态
docker compose ps

# 语法：容器到本地，源路径带 SERVICE:
docker compose cp app:/workspace/export ./backup

# 语法：本地到容器，目标路径带 SERVICE:
docker compose cp ./seed-data app:/workspace/import

判断口诀是“冒号跟着哪一侧，哪一侧就是容器”。如果把本地路径误写成服务路径，Compose 会把它当成服务名解析；如果把容器路径漏掉服务名，命令也不会知道应该连接哪个服务。

从服务容器复制目录到本地

取回日志、导出文件或临时生成物时，先确定容器内目录确实是要保留的内容，再选择本地落点。目标目录可以是项目下的相对路径，也可以是绝对路径；为了让脚本和人工操作一致，通常建议把它放在项目的备份目录中。

# 把 app 服务中的导出目录复制到项目下的 backup 目录
docker compose cp app:/workspace/export ./backup

# 只取目录中的某个文件，避免把整个目录一起复制
docker compose cp app:/workspace/export/report.json ./backup/report.json

如果本地目标目录不存在，先创建目录能让意图更清楚，也便于后续比较文件树。复制完成后，不要只看命令是否返回成功，还要确认本地目录下的层级是否符合预期：目录复制可能保留源目录名，单文件复制则直接落到指定文件名。

把本地目录放回服务容器

配置导入、种子数据和一次性修复文件通常采用反方向写法。源路径不带服务前缀，目标路径才带 SERVICE:。目标目录已经存在时，应先确认里面是否有需要保留的文件，再决定是否覆盖。

# 把本地种子目录复制到 app 服务的导入目录
docker compose cp ./seed-data app:/workspace/import

# 把单个配置文件复制到容器中的明确文件位置
docker compose cp ./settings.local.json app:/etc/demo/settings.json

这种方式适合临时数据交换，不等于修改镜像，也不等于创建持久化卷。容器被重新创建后，手工复制进去的内容是否还在，取决于目标路径是否由卷或其他持久化机制管理；本文只聚焦 cp 本次传输的方向和结果。

服务有多个副本时先选定容器

当同一个服务运行多个副本时，服务名本身不能表达你想访问哪一个容器。Docker 文档为 docker compose cp 提供了 --index，可以按副本索引指定目标。取回某个副本的文件时，把索引放在命令选项中，而不是拼接到服务名后面。

# 查看服务副本，先确认需要复制的实例序号
docker compose ps worker

# 从 worker 服务的第 2 个副本取回结果目录
docker compose cp --index 2 worker:/var/lib/worker/result ./backup/worker-2

# 把本地修复文件只放入第 1 个副本
docker compose cp --index 1 ./hotfix.json worker:/var/lib/worker/hotfix.json

副本选择是一次操作的边界，不会把文件同步到所有副本。如果你的目标是让每个副本都得到同一份文件，需要在脚本或编排层逐个处理，并为每个副本保留清晰的结果记录。

按需要处理归档和符号链接

普通复制关注文件内容；当你还关心 UID、GID 等归档信息时，可以使用 -a 或 --archive。如果源路径中包含符号链接，想让复制操作跟随链接指向的目标，则使用 -L 或 --follow-link。这两个选项解决的是不同问题，不要因为复制失败就无条件全部开启。

# 归档模式：复制时尽量保留源文件的 UID/GID 信息
docker compose cp --archive app:/workspace/export ./backup/export

# 跟随源路径中的符号链接，复制链接指向的内容
docker compose cp --follow-link app:/workspace/current-report ./backup/report

# 需要同时处理两个边界时显式写出选项，方便审查脚本含义
docker compose cp --archive --follow-link app:/workspace/release ./backup/release

权限信息被保留后，本地用户未必能直接编辑文件；跟随符号链接后，复制的内容也可能不再是链接本身。生产脚本中应把这两个选择写成明确的注释或参数，而不是依赖操作者记忆。

用文件树和路径核对复制结果

验收时重点核对三件事：目标方向是否正确、目录层级是否多了一层、多个副本是否选中了预期索引。还可以比较文件数量和关键文件名；如果任务对权限敏感，再单独检查 UID/GID 是否符合预期。

# 查看本地目标目录的层级，确认没有多出一层目录
find ./backup -maxdepth 2 -type f -print

# 查看容器内目标路径，确认文件已经进入预期位置
docker compose exec app sh -c 'find /workspace/import -maxdepth 2 -type f -print'

# 多副本场景中，显式检查同一个索引对应的目标路径
docker compose exec --index 2 worker sh -c 'find /var/lib/worker/result -maxdepth 2 -type f -print'

如果复制命令成功但文件看起来“不见了”，先回到源和目标两侧检查路径，再确认是否把服务副本选错。若是权限异常，区分“文件已复制但当前用户无法读取”和“文件根本没有复制”这两类问题，不要直接重复写入。

常见误区

• 把服务名当成容器名：docker compose cp 使用 Compose 服务语义，先从 docker compose ps 确认服务名。
• 复制方向写反：容器侧路径带 SERVICE:；容器到本地时它在源参数，本地到容器时它在目标参数。
• 多副本没有加索引：需要固定实例时显式使用 --index，不要把结果依赖在默认选择上。
• 把 cp 当成持久化方案：它只完成一次文件传输，容器重建后的保留行为要看卷或其他持久化配置。
• 看到权限变化就重复复制：先判断是否需要 --archive，并单独核对 UID/GID 和当前用户权限。

小结

docker compose cp 的核心是把服务路径和本地路径写在正确的一侧：SERVICE:SRC_PATH DEST_PATH 用于取出，SRC_PATH SERVICE:DEST_PATH 用于放回。多个副本用 --index，权限元数据用 --archive，需要跟随源符号链接时用 -L。最后通过两侧文件树、目录层级和副本索引核对结果，能覆盖大多数复制目录问题。

相关问题

问：可以复制正在运行的服务容器里的目录吗？
答：可以，命令针对 Compose 服务对应的容器路径进行文件复制；先确认服务状态和源路径即可。

问：多个副本能一次复制到所有容器吗？
答：一次命令只针对选定的服务容器。需要全部副本都处理时，应按索引逐个执行并分别记录结果。

问：为什么复制后本地文件不能编辑？
答：可能是归档模式保留了源 UID/GID，或者源文件本身权限较严格。先查看权限和归属，再决定是否需要调整本地文件权限。