命令定位
kubectl cp 在本地与容器之间复制文件或目录，底层是把数据打成 tar 流经 kubelet 转发，因此容器镜像里必须有 tar（busybox 精简镜像、distroless 镜像通常没有）。适用平台为 Kubernetes。它的典型用途是取日志、导出临时配置、塞一个排查脚本进容器，属于排障期的一次性手段，不适合当常规文件同步通道。
基本信息
| 适用平台 | Kubernetes，目标容器内需存在 tar |
|---|---|
| 语法 | kubectl cp <pod>:<路径> <本地路径> [-c 容器] [-n 命名空间]，反向同理 |
| 命名空间写法 | 在 pod 前加命名空间，形如 prod/web-x:/path |
| 权限要求 | 对目标 Pod 的 exec（pods/exec）权限，容器内可写目标目录 |
典型使用场景
- 拉取日志与堆栈：容器不挂持久卷、日志又没进日志系统时，先把文件拷出来分析
- 导出运行中的配置：把容器内已生效的配置文件备份到本地做差异比对
- 投放排查脚本：把一个临时诊断脚本推进去执行，避免改镜像重新发布
- 多容器场景取侧车数据：用 -c 指定容器，拿 Envoy、日志代理产生的文件
- 小规模数据搬运：几十兆以内的 CSV、证书文件临时互传
常用示例
常用示例
kubectl cp prod/web-x:/var/log/app.log ./app.log # 从容器取日志
kubectl cp prod/web-x:/etc/app/conf.d ./conf-backup # 整个目录拷回本地
kubectl cp ./hotfix.sh web-x:/tmp/hotfix.sh # 上传脚本到容器
kubectl cp ./data.csv web-x:/tmp/data.csv -c sidecar # 指定容器
kubectl cp web-x:/tmp/out.tar - | tar -tvf - # 流式查看，不落盘
kubectl exec -it web-x -- ls -l /tmp # 复制前后核对文件与权限常见报错读法
| 报错 | 原因 | 处理 |
|---|---|---|
| tar: not found | 容器内没有 tar | 改用 exec 配 cat，或换含 tar 的调试镜像 |
| No such file or directory | 源路径写错或容器内确实不存在 | 先 exec ls 确认路径 |
| unexpected EOF | 传输中断或文件过大超时 | 分片复制，或改走对象存储 |
| 本地文件已存在 | cp 会直接覆盖同名文件 | 先备份目标文件再执行 |
本地路径是目录时，行为与 scp 类似：会把来源放到该目录下；用相对路径可以先 cd 到目标目录再执行，避免路径拼接歧义。
kubectl cp 不校验文件权限与属主，拷进去的文件默认属当前用户，脚本可能因缺执行位而跑不起来，需要补 chmod +x。