Docuum: LRU淘汰Docker镜像

Docuum 通过执行最少最近未使用（LRU）淘汰来保持磁盘使用率低于指定阈值。

Docker内置的 docker image prune --all --filter until=… 命令具有类似的功能。然而，内置解决方案并不理想，因为它使用镜像创建时间而不是最后使用时间来确定要删除的镜像。这意味着它可能会删除频繁使用的镜像，而这些镜像重建成本高昂或下载耗时。

Docuum非常适合用于持续集成（CI）工作者、开发者工作站或任何其他随着时间的推移在磁盘上积累Docker镜像的环境。Docuum与Toast和Docker Compose等工具配合使用得很好。

Netflix（在其生产Kubernetes节点上）和Airbnb（在其1.5k+ CI工作者CI集群上）使用Docuum。

工作原理

Docker不记录镜像最后使用时间。 为了解决这个问题，Docuum通过监听docker events来接收通知以了解何时使用镜像。它在本地数据目录中保持一小部分状态（有关此目录在各种平台上的详细信息，请参阅此处）。该持久状态允许您在不丢失镜像使用时间戳数据的情况下自由重启Docuum（或整个机器）。

当Docuum第一次启动以及随后每当有新的Docker事件到来时，将执行LRU淘汰，直到Docker镜像导致的总磁盘使用率低于给定阈值。这种设计相比于基于固定生存时间（TTL）的淘汰有几个优点，这是Docker生态系统中其他各种工具所采用的

1. 无需配置和调整间隔来运行。Docuum在磁盘使用量超过阈值时立即驱逐镜像，无需等待任何计时器。
2. Docuum在没有Docker活动时不会使用CPU资源。您可以在笔记本电脑上运行它而不用担心耗尽电池。
3. 为了防止您的磁盘被填满，基于磁盘使用量设置阈值比猜测合适的最大镜像年龄更直接。

Docuum还尊重镜像之间的父子关系。特别是，在删除父镜像之前，它将删除父镜像的子镜像（即使子镜像比父镜像使用得更频繁），因为Docker不允许删除具有子镜像的镜像。

用法

安装完成Docuum后，您可以从命令行手动运行，如下所示

docuum --threshold '10 GB'

然后Docuum将开始监听Docker事件。您可以使用Ctrl+C来停止它。

您可能希望将Docuum作为守护进程运行，例如使用launchd、systemd等。有关说明，请参阅下面的配置操作系统以作为守护进程运行二进制文件部分。

以下是支持的命令行选项

USAGE:
    docuum

OPTIONS:
    -d, --deletion-chunk-size <DELETION CHUNK SIZE>
            Removes specified quantity of images at a time (default: 1)

    -h, --help
            Prints help information

    -k, --keep <REGEX>...
            Prevents deletion of images for which repository:tag matches <REGEX>

    -m, --min-age <MIN AGE>
            Sets the minimum age of images to be considered for deletion

    -t, --threshold <THRESHOLD>
            Sets the maximum amount of space to be used for Docker images (default: 10 GB)

    -v, --version
            Prints version information

--threshold标志接受多种表示，例如10 GB、10 GiB或10GB。在Linux上，也支持基于百分比的阈值，如50%。

您可以通过设置名为LOG_LEVEL的环境变量来更改日志详细程度，该变量可以是trace、debug、info、warning或error之一。默认值是debug。

Docker的构建缓存

旧版本的Docker会在您的Dockerfile中的每个步骤创建一个中间镜像，Docuum会在需要时愉快地清除它们。自从引入BuildKit以来，Docker不再生成这些中间镜像，而是使用单独的“构建缓存”。BuildKit为其构建缓存有自己的垃圾收集器，默认阈值为总磁盘容量的10%。

Docuum不会清除BuildKit的构建缓存，BuildKit的垃圾收集器也不会清除镜像。两者可以一起使用。

安装说明

安装包括两个步骤

1. 安装二进制文件
2. 配置操作系统以作为守护进程运行二进制文件

安装二进制文件

在macOS或Linux（AArch64或x86-64）上的安装

如果您正在运行macOS或Linux（AArch64或x86-64），可以使用以下命令安装Docuum

curl https://raw.githubusercontent.com/stepchowfun/docuum/main/install.sh -LSfs | sh

可以使用相同的命令再次更新到最新版本。

安装脚本支持以下可选环境变量

• VERSION=x.y.z（默认为最新版本）
• PREFIX=/path/to/install（默认为/usr/local/bin）

例如，以下命令将Docuum安装到工作目录

curl https://raw.githubusercontent.com/stepchowfun/docuum/main/install.sh -LSfs | PREFIX=. sh

如果您不希望使用此安装方法，您可以从发布页面下载二进制文件，将其设置为可执行文件（例如，使用chmod），并将其放置在您的PATH中的某个目录下（例如，/usr/local/bin）。

Windows上的安装（AArch64或x86-64）

如果您正在运行Windows（AArch64或x86-64），请从发布页面下载最新的二进制文件，并将其重命名为docuum（如果您已显示文件扩展名，则为docuum.exe）。在您的%PROGRAMFILES%目录下创建一个名为Docuum的目录（例如，C:\Program Files\Docuum），并将重命名的二进制文件放入其中。然后，在控制面板“系统属性”部分的“高级”选项卡中，点击“环境变量...”，并将新Docuum目录的完整路径添加到“系统变量”下的PATH变量中。请注意，如果Windows配置了除英语以外的语言，则Program Files目录可能有不同的名称。

要更新现有安装，只需替换现有二进制文件即可。

使用Homebrew进行安装

如果您有Homebrew，可以按照以下方式安装Docuum

brew install docuum

您可以使用brew upgrade docuum更新现有安装。

使用Cargo进行安装

如果您有Cargo，可以按照以下方式安装Docuum

cargo install docuum

您可以使用--force运行该命令以更新现有安装。

在支持运行Linux容器的主机上运行Docker容器中的Docuum

如果您不希望在系统上安装Docuum，并且您正在运行macOS或Linux（AArch64或x86-64），您可以在容器中运行它

docker run \
  --init \
  --rm \
  --tty \
  --name docuum \
  --mount type=bind,src=/var/run/docker.sock,dst=/var/run/docker.sock \
  --mount type=volume,source=docuum,target=/root \
  stephanmisc/docuum --threshold '10 GB'

如果您在配置为运行Linux容器的Windows系统上，请使用以下命令

docker run `
  --init `
  --rm `
  --tty `
  --name docuum `
  --mount type=bind,src=//var/run/docker.sock,dst=/var/run/docker.sock `
  --mount type=volume,source=docuum,target=/root `
  stephanmisc/docuum --threshold '10 GB'

我们目前没有发布基于Windows的镜像，因为一些Windows机器（尤其是那些使用进程隔离而不是Hyper-V运行容器的机器）只能运行为主机运行的Windows（例如，1809）构建的Windows容器。这使得基于Windows的镜像不太便携，因此我们需要为每个我们希望支持的Windows构建发布一个单独的基于Windows的镜像。目前，我们没有这样做的基础设施。

以下说明配置操作系统以作为守护程序运行Docuum假设它已作为可执行二进制文件安装。如果您希望将其作为Docker容器运行，请将相关的服务定义更改为运行以下类似的Docker命令，并进行以下调整

• 省略--tty标志。这可以防止Docuum打印彩色日志，您可能不需要守护程序这样做。
• 将Docker配置为硬依赖项。通常，Docuum和Docker可以按任何顺序启动，如果需要，Docuum将耐心等待Docker启动。但是，当Docuum作为Docker容器运行时，当然必须首先启动Docker。

配置操作系统以作为守护进程运行二进制文件

在macOS上创建launchd服务

在macOS上，可以使用launchd将Docuum作为守护程序运行。创建一个名为/Library/LaunchDaemons/local.docuum.plist的文件（属于root用户），并使用以下内容，根据需要调整参数

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "https://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>Label</key>
        <string>local.docuum</string>
        <key>Program</key>
        <string>/usr/local/bin/docuum</string>
        <key>ProgramArguments</key>
        <array>
            <string>/usr/local/bin/docuum</string>
            <string>--threshold</string>
            <string>10 GB</string>
        </array>
        <key>StandardOutPath</key>
        <string>/var/log/docuum.log</string>
        <key>StandardErrorPath</key>
        <string>/var/log/docuum.log</string>
        <key>EnvironmentVariables</key>
        <dict>
            <key>PATH</key>
            <string>/bin:/usr/bin:/usr/local/bin</string>
        </dict>
        <key>KeepAlive</key>
        <true/>
    </dict>
</plist>

运行 sudo launchctl load /Library/LaunchDaemons/local.docuum.plist 来启动服务。您可以使用以下命令查看日志：tail -F /var/log/docuum.log。

在 Linux 上创建 systemd 服务

在大多数 Linux 发行版中，可以使用 systemd 将 Docuum 作为守护进程运行。创建一个名为 /etc/systemd/system/docuum.service 的文件（属于 root 用户），内容如下，根据需要调整参数：

[Unit]
Description=Docuum
After=docker.service
Wants=docker.service

[Service]
Environment='THRESHOLD=10 GB'
ExecStart=/usr/local/bin/docuum --threshold ${THRESHOLD}
Restart=on-failure

[Install]
WantedBy=multi-user.target

运行 sudo systemctl enable docuum --now 以启用并启动服务。您可以使用以下命令查看日志：sudo journalctl --follow --unit docuum。

在 Windows 上创建 NSSM 服务

在 Windows 上，可以使用 "Non-Sucking Service Manager"（即 NSSM）将 Docuum 作为守护进程运行。通过下载二进制文件并将其添加到您的 PATH（请参阅 Windows (x86-64) 的安装 部分了解如何配置此环境变量）来安装 NSSM，然后以管理员身份运行 Windows Terminal 并输入以下命令：

nssm install Docuum

NSSM 将打开一个配置窗口。配置以下内容：

• 在 应用程序 选项卡中，选择 Docuum 二进制文件的路径。您可以选择性地添加参数，如 --threshold "10 GB"。
• 可选地，在 I/O 选项卡中，选择您想要将日志写入的位置。

然后单击 安装服务 按钮。返回 Windows Terminal，运行以下命令以启动服务：

nssm start Docuum

如果您在安装窗口的 I/O 选项卡中配置了日志文件路径，您可以使用以下命令查看这些日志：Get-Content -Wait docuum.log（根据需要调整文件路径）。

要求

• Docuum 需要 Docker Engine 17.03.0 或更高版本。