hescc/void

Void

镜像概述

Void是一款用于自动清理PT/BT下载目录中未做种（冗余）文件的工具。它通过API连接qBittorrent或Transmission下载客户端，获取当前做种文件列表，与本地下载目录比对后，自动删除不在做种列表中的文件及空文件夹，有效释放磁盘空间。

核心功能

• 双扫描模式：普通模式（单下载器独立扫描）、全局模式（跨多下载器共享目录扫描）；
• 跨平台支持：兼容Windows和Linux操作系统；
• 多客户端适配：支持qBittorrent与Transmission；
• 智能路径映射：处理Docker容器路径与本地路径转换，支持跨平台路径映射；
• 安全保护机制：可设置文件大小阈值（仅删除大于指定大小的文件）、排除路径（保护重要文件）；
• 灵活配置：支持输出检查报告或自动删除；
• 多渠道通知：Email、Webhook（/Slack/）、企业微信Webhook发送清理报告；
• 定时任务：自定义检查频率；
• Docker化部署：提供Dockerfile与docker-compose一键部署。

使用场景

• PT/BT爱好者管理下载目录，自动清理冗余未做种文件；
• 多下载器共享存储目录时，统一维护文件整洁；
• 定期自动化清理，释放磁盘空间，避免存储浪费。

配置说明

配置文件结构

配置文件为config.yaml，包含全局设置、通知配置、下载器配置三部分：

1. 全局设置：check_interval（执行频率，分钟）、enable_auto_remove（是否自动删除）、notification_type（通知类型）、checkfile_size（文件大小阈值，MB）、excluded_paths（排除路径列表）；
2. 通知配置：支持Email、Webhook、企业微信Webhook；
3. 下载器配置：支持多个qBittorrent/Transmission实例，需配置地址、端口、用户名、密码及路径映射。

Docker部署示例

1. 准备配置

bash
mkdir -p /opt/void/config
cp config/config-examples.yaml /opt/void/config/config.yaml
nano /opt/void/config/config.yaml # 编辑配置

2. Docker Compose启动

yaml
version: '3.8'
services:
  void:
    image: hescc/void:latest
    container_name: void
    network_mode: host
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - /opt/void/config:/app/config
      - /data:/data # 映射下载目录

执行：docker-compose up -d

3. Docker CLI启动

bash
docker run -d \
  --name void \
  --restart always \
  -e TZ=Asia/Shanghai \
  -v /opt/void/config:/app/config \
  -v /data:/data \
  hescc/void:latest

注意事项

1. 路径映射正确性：确保配置中path_mapping准确映射下载器路径与本地/容器路径，避免误删或漏删；
2. 初次使用建议：先设置enable_auto_remove: False查看报告，确认无误后再开启自动删除；
3. 数据安全：重要文件需加入excluded_paths排除列表。

本地开发

1. 拉取仓库：git clone https://github.com/Hesccc/void.git；
2. 安装依赖：uv sync；
3. 运行：uv run main.py。