devpedrois/Dredge

# 🚢 Dredge — 智能型 Docker 垃圾回收器 [](https://github.com/user/dredge/actions) [](LICENSE) [](https://golang.org) Dredge 检查您的 Docker 守护进程，根据可配置的策略评估资源，并安全、按正确顺序、附带完整审计日志地移除您不需要的资源。 ## 工作原理 ``` [Docker Daemon] | [Collector] ---> containers, images, volumes, networks | [Policy Engine] ---> evaluate rules + protections + dependency graph | [Planner] ---> ordered execution plan (dry-run output) | [Sweeper] ---> safe deletion with TOCTOU re-check + audit log ``` 每个阶段都是独立的。`dredge plan` 在规划器之后停止。`dredge sweep` 运行全部四个阶段。 ## 要求 - Go 1.22+ - Docker 引擎在本地运行（socket 位于 `/var/run/docker.sock` 或可配置） - Linux 或 macOS ## 安装 ### 选项 1 — 从源代码构建 ``` git clone https://github.com/user/dredge cd dredge make build # 二进制文件位于 bin/dredge — 复制到 PATH： sudo cp bin/dredge /usr/local/bin/dredge ``` 或者使用 `make install`（自动复制到 `/usr/local/bin`）： ``` make install ``` ### 选项 2 — go install ``` go install github.com/user/dredge/cmd/dredge@latest ``` ### 选项 3 — 下载预构建二进制文件 从[发布页面](https://github.com/user/dredge/releases)下载，解压，并放置在您的 PATH 中： ``` tar -xzf dredge_v0.1.0_linux_amd64.tar.gz sudo mv dredge /usr/local/bin/ dredge --help ``` ## 快速入门 ### 1. 创建配置文件 ``` # 将示例配置复制到您的主目录 cp config.example.yaml ~/.dredge.yaml # 或系统范围 sudo mkdir -p /etc/dredge sudo cp config.example.yaml /etc/dredge/config.yaml ``` 默认从 `~/.dredge.yaml` 加载配置。可通过 `--config /path/to/config.yaml` 覆盖。 ### 2. 检查 Dredge 会清理什么（安全模式 — 不做任何更改） ``` dredge plan ``` ### 3. 审查输出，然后进行清理 ``` # 交互模式 — 删除前提示输入 y/N dredge sweep # 或非交互模式（CI、脚本） dredge sweep --yes ``` ### 4. 保护您关心的资源 ``` # 标记容器 — dredge 将永远不会触碰它 docker run -d --label dredge.keep=true --name my-db postgres:16 # 或添加到配置文件的 protection.name_patterns： # name_patterns: # - "postgres*" # - "production-*" ``` ### 5. 作为守护进程运行（可选） ``` # 每 6 小时清理一次（或配置 watch.interval） dredge watch ``` ## 命令 ### `dredge plan` 干运行。显示将被移除的内容及原因。不做任何更改。 ``` $ dredge plan +--------------------+-------------+--------+----------------------+------------------+ | NAME | TYPE | SIZE | AGE | REASON | +--------------------+-------------+--------+----------------------+------------------+ | old-worker | container | 12 MB | 3 days | exited > 24h | | build-cache | container | 4 MB | 5 days | exited > 24h | | : | image | 220 MB | 8 days | dangling image | | data-migration-vol | volume | 0 B | 14 days | orphaned volume | +--------------------+-------------+--------+----------------------+------------------+ 4 resources | 236 MB recoverable ``` ### `dredge sweep` 执行清理操作。需要 `--yes` 参数或交互式确认。 ``` # 交互模式（提示输入 y/N） dredge sweep # 非交互模式（脚本、CI） dredge sweep --yes ``` 删除顺序始终为：**容器 → 镜像 → 卷 → 网络**。这可以防止因悬空引用导致的级联故障。 ### `dredge stats` 只读模式。显示当前资源使用情况。绝不修改任何内容。 ``` $ dredge stats Containers: 12 total (3 running, 7 exited, 2 created) Images: 24 total (4 dangling, 20 tagged) Volumes: 8 total Networks: 5 total (3 default, 2 custom) Disk Usage: Images: 4.2 GB Containers: 320 MB Volumes: 1.1 GB Total: 5.6 GB ``` ### `dredge watch` 守护进程模式。按配置间隔自动运行 plan+sweep。 ``` # 使用配置中的间隔（默认：6 小时） dredge watch # 覆盖间隔 dredge watch --interval 30m ``` 响应 `SIGTERM`/`SIGINT` 信号，优雅关闭（完成当前删除操作，不启动新的操作）。 ## 全局参数 | 参数 | 描述 | 默认值 | |------|-------------|---------| | `--config ` | 配置文件路径 | `~/.dredge.yaml`, `/etc/dredge/config.yaml` | | `--socket ` | Docker socket 路径 | 从配置读取 | | `--log-level ` | `debug`, `info`, `warn`, `error` | `info` | | `--format ` | `table` 或 `json` | `table` | ## 配置 ``` # ~/.dredge.yaml # Docker 连接 docker: socket: "/var/run/docker.sock" timeout: "30s" # 清理策略 policies: containers: - status: "exited" older_than: "24h" - status: "created" older_than: "48h" - status: "dead" older_than: "0s" images: dangling: true unused_older_than: "168h" # 7 days volumes: orphaned: true networks: unused: true # 保护 — 这些资源绝不会被删除 protection: label: "dredge.keep=true" name_patterns: - "postgres*" - "redis*" - "production-*" - "*-db" # 监控模式（守护进程） watch: interval: "6h" # cron: "0 */6 * * *" # 日志记录 logging: level: "info" format: "json" output: "stderr" ``` ### 标记资源为受保护状态 为任何资源添加标签 `dredge.keep=true`。Dredge 将永远不会触碰它。 ``` docker run -d --label dredge.keep=true --name my-db postgres:16 docker volume create --label dredge.keep=true my-data ``` 配置还支持对名称使用 glob 模式： ``` protection: name_patterns: - "production-*" - "*-db" ``` ## 安全特性 Dredge 实现了 10 层独立的保护。任何单一层的缺陷都会被其他层捕获。 | 层级 | 作用 | |-------|--------------| | **1. Docker Socket 安全** | Socket 路径可配置，永不硬编码。所有操作都有超时。 | | **2. 运行中容器保护** | 状态为 `running` 的容器 **绝不** 被触碰。硬编码 — 不可配置。 | | **3. 标签保护 (3 层)** | `dredge.keep=true` 被策略引擎、规划器和清理器独立检查。 | | **4. 依赖关系图** | 如果任何引用容器被保留，则镜像也不会被删除。 | | **5. 删除顺序** | 容器优先于镜像，镜像优先于卷，卷优先于网络 — 防止级联故障。 | | **6. 干运行一致性** | `plan` 和 `sweep` 使用完全相同的代码路径。`plan` 显示的内容正是 `sweep` 移除的内容。 | | **7. 需要确认** | 不带 `--yes` 的 `sweep` 需要交互式确认（默认：N）。不带 `--yes` 的管道 stdin 会报错。 | | **8. TOCTOU 防护** | 每次删除前，资源会被重新检查。在 plan 和 sweep 之间启动的容器会被跳过。 | | **9. 配置验证** | 未知的 YAML 字段、负持续时间、无效状态 — 在启动时立即拒绝。 | | **10. 审计日志** | 每次删除都被记录为结构化 JSON：类型、ID、名称、大小、原因、时间戳。不记录密钥。 | ### 常见问题解答 **这会删除我正在运行的容器吗？** 永远不会。正在运行的容器受策略引擎中硬编码检查的保护，无法通过任何配置覆盖。 **如果我误删了需要的东西怎么办？** 容器和镜像：彻底丢失。卷：数据永久丢失。这就是为什么 `dredge plan` 存在 — 请务必先审查它。如果某个资源很重要，请为其添加 `dredge.keep=true`。 **如果删除失败会怎样？** Dredge 会记录错误并继续处理下一个资源（失败继续）。单次失败不会中止整个清理过程。 **`bridge`、`host` 和 `none` 网络安全吗？** 是的。默认 Docker 网络始终受保护，无论您的网络清理策略如何。 **可以在 CI/CD 中使用吗？** 可以。使用 `dredge sweep --yes` 进行非交互式执行。 ## 依赖关系图 在任何删除之前，Dredge 会构建一个镜像 → 引用容器的映射。如果任何引用容器被保留，则该镜像也会被保留 — 即使该镜像原本符合删除条件。 ``` Image: my-app:v1.2 <--- referenced by: [worker-1 (exited, kept by label), batch-job (exited, to delete)] ^ kept container → image is protected ``` 这可以防止删除容器下次启动时仍然需要的镜像的情况发生。 ## 以守护进程运行 Watch 模式 ### systemd 单元文件 ``` # /etc/systemd/system/dredge.service [Unit] Description=Dredge Docker Garbage Collector After=docker.service Requires=docker.service [Service] Type=simple ExecStart=/usr/local/bin/dredge watch --config /etc/dredge/config.yaml Restart=on-failure RestartSec=30s StandardOutput=journal StandardError=journal [Install] WantedBy=multi-user.target ``` ``` systemctl enable --now dredge journalctl -u dredge -f ``` ### Docker Compose ``` services: dredge: image: ghcr.io/user/dredge:latest volumes: - /var/run/docker.sock:/var/run/docker.sock:ro - ./dredge.yaml:/etc/dredge/config.yaml:ro command: watch restart: unless-stopped ``` ## 输出格式 ``` dredge plan --format json | jq '.deletions[] | select(.type == "volume")' dredge stats --format json | jq '.disk_usage.total' ``` ## 构建 ``` # 要求：Go 1.22+、Docker（用于集成测试） make build # build to bin/dredge make test # unit tests make test-integration # integration tests (requires running Docker) make test-all # unit + integration make lint # golangci-lint make vet # go vet make fmt # gofmt ``` ## 许可证 MIT — 参见 [LICENSE](LICENSE)。

标签：Docker, EVTX分析, Go语言, 依赖图, 依赖清理, 卷管理, 垃圾收集, 守护进程模式, 安全防御评估, 审计日志, 容器技术, 干运行, 日志审计, 标签保护, 程序破解, 网络清理, 请求拦截, 资源优化, 镜像清理