Docker system prune 使用指南：一键清理无用缓存 – wiki基地

---

深度解析 Docker system prune：高效清理无用资源，释放宝贵磁盘空间

随着容器化技术的普及，Docker 已成为现代软件开发、测试和部署不可或缺的工具。然而，正如任何工具一样，长时间使用后，Docker 也会在您的系统中留下“数字垃圾”。构建过程中产生的中间镜像层、停止但未移除的容器、不再使用的网络以及悬空（dangling）的镜像等都会逐渐蚕食宝贵的磁盘空间，甚至可能影响 Docker 自身的性能。

面对日益增长的磁盘占用，手动逐一查找并删除这些无用资源既繁琐又容易出错。幸运的是，Docker 官方提供了一个强大而便捷的命令来解决这个问题——docker system prune。

本文将带您深入了解 docker system prune 命令的方方面面，包括它清理的内容、不同的选项、使用场景、潜在风险以及最佳实践，帮助您一键高效地管理 Docker 资源，释放磁盘空间，保持开发环境的整洁与高效。

第一部分：为什么需要清理 Docker 资源？Docker 垃圾的来源

在使用 Docker 的过程中，以下几种类型的资源最容易积累并占用空间：

1. 停止的容器 (Stopped Containers)： 当您运行一个容器并停止它时，容器本身的文件系统层并不会立即被删除。如果长时间不移除，这些停止的容器会保留其元数据、日志以及对其构建时所用镜像层的引用。
2. 悬空镜像 (Dangling Images)： 悬空镜像通常是由于构建了新版本的镜像，旧版本的镜像层不再被任何带标签的镜像引用，但其自身并没有被删除。想象一下您修改了 Dockerfile 后重新 build 镜像，新的镜像有了新的 ID，而旧的中间层或最终镜像层如果没有任何标签指向它，就会变成“悬空”状态。它们是构建过程中留下的孤儿。
3. 未使用（Untagged）但非悬空的镜像 (Unused but Non-Dangling Images)： 这是通过 docker images -a 才能看到的一些镜像。它们可能没有标签，但其层可能被其他带标签的镜像共享或引用。在默认的 prune 行为中，这类镜像不会被删除。
4. 未使用的网络 (Unused Networks)： 当您创建自定义网络用于容器间通信，但在容器停止或移除后，网络本身可能依然存在。虽然网络占用的空间相对较小，但清理它们有助于保持网络列表的整洁。
5. 悬空卷 (Dangling Volumes)： 卷（Volumes）用于持久化存储容器产生的数据。当容器被移除时，默认情况下其关联的卷并不会被删除，以防止数据丢失。如果一个卷不再被任何容器引用，它就变成了“悬空卷”。悬空卷是占用磁盘空间的罪魁祸首之一，特别是当容器写入大量数据时。
6. 构建缓存 (Build Cache)： 在使用 docker build 命令时，Docker 会缓存构建过程中的每一层结果。这大大加快了后续构建速度，但缓存本身会占用大量磁盘空间。

这些积累的资源不仅占用磁盘空间，使得 docker ps -a、docker images 等命令的输出变得冗长混乱，有时甚至可能对 Docker daemon 的性能产生轻微影响。因此，定期进行清理是保持 Docker 环境健康运行的重要环节。

第二部分：docker system prune 命令简介

docker system prune 命令是 Docker 官方提供的一个高级清理工具，它的主要目的是删除停止的容器、悬空镜像、未使用的网络以及构建缓存。通过添加不同的选项，您还可以扩展其清理范围，例如包含未使用卷和所有未使用的镜像。

该命令设计得非常方便，执行时会提示您确认，从而提供了一层安全保障，避免误删重要资源。

第三部分：docker system prune 的默认行为

在不带任何选项的情况下，直接运行 docker system prune 命令，它将执行以下清理操作：

• 删除所有已停止的容器 (Remove all stopped containers)
• 删除所有悬空镜像 (Remove all dangling images)
• 删除所有未使用的网络 (Remove all unused networks)
• 删除所有构建缓存 (Remove all build cache)

让我们逐一解释这些默认清理的对象：

• 停止的容器： 任何状态为 Exited 的容器都将被移除。这清除了容器的文件系统差异层、元数据和日志。
• 悬空镜像： 任何镜像层，如果它没有关联的名称和标签，并且没有被任何现有容器或任何带标签的镜像引用，就会被认为是悬空镜像并被删除。这主要释放了构建过程中产生的未被最终镜像引用的中间层和孤儿镜像。
• 未使用的网络： 任何由用户创建的自定义网络，如果当前没有容器连接到它，就会被视为未使用并被删除。默认的 bridge, host, none 网络不会被删除。
• 构建缓存： Docker 的构建缓存会缓存每一层构建的结果。这部分缓存虽然提高了构建效率，但会占用大量空间。system prune 会清理不再被任何现有镜像引用的构建缓存。

当您运行 docker system prune 时，您会看到类似以下的提示信息（具体内容可能因 Docker 版本和待清理资源而异）：

“`bash
WARNING! This will remove:
– all stopped containers
– all networks not used by at least one container
– all dangling images
– all build cache

Are you sure you want to continue? [y/N]
“`

这个提示清晰地列出了即将被删除的资源类型。只有在您输入 y 并按回车键后，清理操作才会真正执行。

第四部分：深入探索 docker system prune 的选项

docker system prune 提供了几个有用的选项，可以修改其默认行为，以实现更全面或更精确的清理。

1. -a 或 --all：删除所有未使用的镜像

这是 system prune 最常用的一个重要选项，它扩展了镜像的清理范围。

• 默认行为： 只删除“悬空”镜像。
• 使用 -a： 删除所有未使用的镜像。这里“未使用”的定义更广泛，包括了悬空镜像，以及没有任何容器引用的、没有任何标签的镜像（即使它们的层可能被其他带标签的镜像共享）。简单来说，它会删除所有不被当前运行或停止的容器引用的镜像，以及没有标签的镜像（无论是否被容器引用，只要无标签且无容器引用，或者有标签但该标签对应的是一个完全不同的镜像，原无标签镜像就会被移除，除非它的层被其他带标签的镜像完全依赖）。

使用 -a 时的注意事项：

• -a 会比默认清理释放更多空间，但也更激进。
• 它可能会删除您可能认为“未使用”但实际上是作为其他镜像基础的无标签中间层（如果该层不是悬空层，默认 prune 不会删）。更重要的是，它可能删除您之前构建但现在没有任何容器使用的，并且没有标签的镜像。
• 如果您依赖于某些特定的、无标签的、但未被当前容器使用的镜像进行后续操作，使用 -a 需要谨慎。

当使用 -a 运行时，提示信息会变成：

“`bash
WARNING! This will remove:
– all stopped containers
– all networks not used by at least one container
– all unused images (both dangling and unreferenced)
– all build cache

Are you sure you want to continue? [y/N]
“`

注意其中的 all *unused* images 表述，它涵盖了比“dangling”更广的范围。

2. --volumes：删除所有未使用的本地卷

默认情况下，docker system prune 不会删除卷，即使它们不再被任何容器使用。这是为了保护用户的数据，因为卷通常用于持久化存储重要信息。

使用 --volumes 选项可以指示 docker system prune 同时删除所有未被任何容器引用的本地卷（Named Volumes 和 Anonymous Volumes）。

• 未使用卷的定义： 一个卷如果当前没有被任何容器以“使用中”的状态引用，就被认为是未使用的。
• 风险提示： 删除卷将永久丢失存储在其中的所有数据！这是使用 --volumes 选项最大的风险所在。在执行带有 --volumes 的 prune 之前，务必确认您不需要这些卷中的数据，或者已经做好了备份。

当使用 --volumes 运行时，提示信息会变成：

“`bash
WARNING! This will remove:
– all stopped containers
– all networks not used by at least one container
– all dangling images
– all build cache
– all unused local volumes

Are you sure you want to continue? [y/N]
“`

如果您同时使用了 -a 和 --volumes，提示信息将包含这两者的清理范围。

3. --filter：通过过滤条件进行选择性清理

--filter 选项提供了更精细的控制，允许您根据特定条件（如时间戳或标签）选择要保留或删除的资源。这个选项非常强大，可以在一定程度上降低误删的风险，实现更智能的清理策略。

--filter 支持多种过滤条件，但最常用且对 system prune 特别有用的包括 until 和 label。

• until=<timestamp>： 只删除在指定时间戳之前创建的资源。这是一种非常有用的策略，可以只清理旧的、不太可能再使用的资源，而保留近期创建的资源。

  • 时间戳格式可以是 Unix timestamp (秒数)，也可以是 RFC3339 格式 (例如 2023-10-27T10:00:00Z)。更常用的可能是相对时间，如 24h (24小时前), 7d (7天前)。
  • 示例：
    • docker system prune --filter "until=24h"：删除创建时间超过24小时的停止容器、悬空镜像、未使用网络和构建缓存。
    • docker system prune -a --filter "until=2023-01-01T00:00:00Z"：删除在2023年1月1日零点之前创建的所有未使用资源（包括所有未使用镜像）。
    • docker system prune --volumes --filter "until=48h"：删除创建时间超过48小时的停止容器、悬空镜像、未使用网络、构建缓存以及未使用卷。

• label=<label> 或 label=<key>=<value>： 根据资源的标签进行过滤。这可以用来保留特定标签的资源，或者删除带有特定标签的资源。过滤规则支持 label=<key> (资源必须有指定的 key 标签，值不限), label=<key>=<value> (资源必须有指定的 key=value 标签), label!=<key> (资源不能有指定的 key 标签), label!=<key>=<value> (资源不能有指定的 key=value 标签)。

  • 注意： system prune 的 label 过滤器通常用于决定保留哪些资源。换句话说，它会清理不匹配指定标签的资源。
  • 示例：
    • 假设您希望保留所有带有 project=critical 标签的容器和镜像。您可以尝试使用过滤条件来清理其他资源。然而，system prune 的过滤逻辑是清理不匹配过滤条件的资源。所以，如果你只想清理掉那些没有 project=critical 标签的资源，这个过滤器的作用是清理没有这个标签的资源。例如，docker system prune --filter "label!=project=critical" 会尝试删除没有 project=critical 标签的资源。但这在使用时需要非常小心，确保您的重要资源都打上了正确的标签。更安全的做法可能是结合其他过滤条件或使用更精细的命令（如 docker container prune --filter "label!=keep"）。
    • 一个更直接的应用场景是，您给一些临时性的容器或镜像打上了 temporary=true 的标签，然后在清理时指定删除带有这个标签的资源（虽然 system prune 的 label 过滤更倾向于保留未过滤的，但可以通过 docker container prune 或 docker image prune 结合 label 过滤器来删除特定标签的资源）。对于 system prune 整体而言，label 过滤器通常用来定义一组要保护起来不被清理的资源。比如 docker system prune --filter "label=always_keep" 会保留带有 always_keep 标签的资源，而清理其他符合默认或 -a, --volumes 条件的无标签或标签不匹配的资源。理解这一点非常关键。

--filter 总结： --filter 提供了强大的灵活性，特别是 until 过滤器，可以有效地清理旧资源而保护新资源。label 过滤器则适用于有明确标签管理策略的场景，可以用来标记需要保留的特定资源。

4. -f 或 --force：跳过确认提示

默认情况下，docker system prune 会提示您确认操作。使用 -f 或 --force 选项可以跳过这个确认步骤，直接执行清理。

强烈建议不要在生产环境或不确定清理后果时使用 -f 选项。 确认提示是防止误删的重要安全网。只有当您完全清楚该命令将删除什么，并且希望自动化清理过程（例如在脚本中）时，才考虑使用此选项。

第五部分：docker system prune 的详细使用示例

以下是 docker system prune 命令的一些常见使用示例，结合了上述选项：

1. 最基本的清理 (默认行为)：
   bash
docker system prune

   • 作用：删除停止的容器、悬空镜像、未使用网络和构建缓存。
   • 安全性：高，会提示确认。

2. 清理所有未使用的镜像 (包括非悬空的无标签镜像)：
   bash
docker system prune -a

   • 作用：在默认清理范围基础上，额外删除所有未使用的（包括悬空和非悬空无标签）镜像。
   • 安全性：中等，会提示确认，但清理范围更广，可能删除您认为“无害”的无标签镜像。

3. 清理未使用的卷：
   bash
docker system prune --volumes

   • 作用：在默认清理范围基础上，额外删除所有未使用的本地卷。
   • 安全性：低，会提示确认，但删除卷会永久丢失数据，风险最高。使用前务必确认。

4. 最激进的清理 (删除所有未使用资源，包括所有未使用镜像和所有未使用卷)：
   bash
docker system prune -a --volumes

   • 作用：删除所有停止的容器、所有未使用网络、所有未使用镜像（包括悬空和非悬空无标签），以及所有未使用卷。
   • 安全性：最低，会提示确认，但清理范围最大，数据丢失风险最高。仅在确实需要完全清空无用资源时谨慎使用。

5. 清理创建时间超过 7 天的资源 (不含卷，不含所有未使用镜像)：
   bash
docker system prune --filter "until=7d"

   • 作用：只删除在7天前创建的停止容器、悬空镜像、未使用网络和构建缓存。
   • 安全性：较高，会提示确认，且仅针对较旧的资源。

6. 清理创建时间超过 30 天的所有未使用资源 (包括所有未使用镜像和未使用的卷)：
   bash
docker system prune -a --volumes --filter "until=30d"

   • 作用：删除在30天前创建的所有符合 -a --volumes 条件的资源。
   • 安全性：取决于对30天前资源的保留需求。会提示确认，但删除卷仍有数据丢失风险。

7. 清理时不删除带有 keep=true 标签的容器和镜像：
   bash
docker system prune --filter "label!=keep=true"

   • 作用：清理所有符合默认清理条件的资源，除了那些带有 keep=true 标签的资源。这是一种保护特定资源不被误删的策略。请注意，这个过滤器的意思是清理那些不匹配 label=keep=true 的资源。
   • 安全性：较高，提供了基于标签的保护机制。需要事先对要保留的资源打上标签。

8. 在脚本中执行默认清理并跳过确认：
   bash
docker system prune -f

   • 作用：立即执行默认清理操作，不进行确认。
   • 安全性：低，无确认提示，仅限自动化或非常确定的场景。

第六部分：docker system prune 与其他清理命令的区别

Docker 还提供了一些更细粒度的清理命令：

• docker container prune：只删除停止的容器。
• docker image prune：默认只删除悬空镜像；加 -a 选项可以删除所有未使用的镜像。
• docker volume prune：删除所有未使用的本地卷。
• docker network prune：删除所有未使用的网络。
• docker builder prune：删除构建缓存 (BuildKit 构建器)。

docker system prune 相当于执行了 docker container prune、docker image prune (默认行为)、docker network prune 和 docker builder prune (对于 BuildKit)。当加上 --volumes 选项时，它还包含了 docker volume prune 的功能。

命令	清理对象	默认行为	--all 选项	--volumes 选项	--filter 选项
docker system prune	停止容器, 悬空镜像, 未使用网络, 构建缓存	是	影响镜像	包含卷	是
docker container prune	停止容器	是	无	无	是
docker image prune	悬空镜像	是	包含所有未使用	无	是
docker volume prune	未使用卷	是	无	无 (自身即清理卷)	是
docker network prune	未使用网络	是	无	无	是
docker builder prune	构建缓存	是	无 (BuildKit)	无	是

可以看出，docker system prune 是一个组合命令，旨在提供一站式的系统级清理。如果您只想清理特定类型的资源（例如，只想删除停止的容器），那么使用更具体的 docker container prune 会更安全、更精确。只有当您需要进行全面的系统清理时，docker system prune 才是最佳选择。

第七部分：何时使用 docker system prune？最佳实践与建议

• 磁盘空间不足时： 这是最直接的信号。当您发现磁盘空间持续减少，且通过 docker system df 或 docker image ls 等命令发现大量未使用资源时，立即执行 docker system prune 是释放空间的有效手段。
• 定期维护： 将 docker system prune 加入到您的日常或每周维护计划中。例如，可以每周执行一次 docker system prune，每月执行一次 docker system prune -a，每隔一段时间（或在确认不再需要任何旧数据后）谨慎执行 docker system prune --volumes。
• 大型构建或项目切换后： 在完成一个大型项目或切换到新的开发任务后，通常会产生大量的中间镜像层和停止的容器。此时运行 docker system prune 可以有效地清理掉这些不再需要的资源。
• 在脚本中自动化清理 (谨慎使用 -f)： 如果您有自动化的构建或部署流程，并且希望在特定阶段自动清理环境，可以在脚本中使用 docker system prune -f。但请务必确保脚本的逻辑是正确的，并且清理操作不会影响到正在运行或即将需要的服务。结合 --filter "until=..." 是在自动化场景中保证安全性的常见方法。
• 使用 --filter "until=..." 策略： 对于大多数用户来说，定期清理老旧资源是一种安全且有效的策略。例如，每月运行 docker system prune -a --filter "until=30d" 可以删除一个月前创建的所有未使用资源，保留近期的，从而兼顾了清理和保留的需求。
• 使用 docker system df 检查效果： 在执行 prune 命令前后，可以使用 docker system df 命令来查看 Docker 资源的磁盘使用情况，从而了解清理的效果。
• 慎用 --volumes： 重复强调，删除卷会导致数据丢失。在运行 docker system prune --volumes 之前，务必先运行 docker volume ls 查看当前有哪些卷是未使用的，并确认这些卷的数据确实不需要了。如果只是少量未使用的卷，可以考虑手动使用 docker volume rm <volume_name> 进行删除，而不是 blanket 地使用 --volumes。
• 理解 dangling 和 unused 镜像的区别： 理解 docker image prune 和 docker image prune -a (以及 docker system prune 和 docker system prune -a) 在清理镜像上的差异，有助于您选择合适的命令。如果只想清理构建失败或更新后留下的悬空层，默认的 prune 或 docker image prune 即可。如果想清理所有没有容器引用且无标签的镜像，则需要 -a。
• 为重要资源打标签： 如果您有某些容器、镜像或卷希望绝对不会被 prune --filter "label!=..." 类型的命令删除，请务必为它们打上清晰的标签。

第八部分：docker system prune 可能遇到的问题

• 长时间无响应： 在资源非常多或磁盘 IO 性能较差的情况下，docker system prune 命令可能需要一些时间才能完成。请耐心等待。如果长时间卡住，可以尝试重启 Docker daemon。
• 提示某些资源无法删除： 有时 prune 命令会报告某些资源（例如，一个卷）无法删除，通常是因为该资源仍然被某些进程或容器（即使是已停止的）引用。您可以尝试先手动移除这些特定的资源（例如，使用 docker volume rm），或者确保没有其他程序在使用 Docker 资源。
• 误删重要数据： 这是最严重的问题，通常是由于在未完全理解命令，特别是 --volumes 和 -a 选项的作用的情况下，盲目执行命令造成的。始终建议先仔细阅读确认提示，并理解每个选项的含义。

结论

docker system prune 是一个极其强大和方便的 Docker 资源清理工具。它可以帮助您一键清理掉停止的容器、悬空镜像、未使用网络和构建缓存，有效释放磁盘空间，并保持 Docker 环境的整洁。

通过熟练掌握 docker system prune 的不同选项，特别是 -a、--volumes 和 --filter，您可以根据自己的需求进行更全面或更精确的清理。然而，权力越大，责任越大。在使用 prune 命令，尤其是涉及到删除所有未使用镜像 (-a) 或删除卷 (--volumes) 时，务必谨慎操作，仔细阅读确认提示，并在必要时结合 --filter 选项来降低风险。

将 docker system prune 纳入您的 Docker 工作流程中，并结合定期维护和对关键资源的理解，将有助于您更好地管理 Docker 环境，确保其稳定、高效地运行。告别手动清理的烦恼，享受 docker system prune 带来的一键便捷体验吧！

---