dicetechnology/dice-where-downloader

dice-where's downloader Docker镜像技术文档

一、镜像概述和主要用途

1.1 镜像概述

dice-where's downloader Docker镜像是一个轻量级的下载工具容器化实现，基于Alpine Linux构建，集成了高效的下载核心组件。镜像设计旨在提供开箱即用的下载能力，简化跨环境的部署和使用流程。

1.2 主要用途

该镜像主要用于自动化或手动执行文件下载任务，支持从各类网络资源（如HTTP/HTTPS服务器、FTP服务器、文件共享平台等）下载文件，并提供灵活的任务管理能力。适用于个人、企业或开发场景中对下载任务的标准化、隔离化需求。

二、核心功能和特性

2.1 核心功能

• 支持多协议下载：兼容HTTP/HTTPS、FTP、SFTP等主流网络协议
• 断点续传：支持因网络中断或容器重启后的任务恢复
• 批量任务管理：支持通过配置文件或命令行参数定义多个下载任务
• 下载限速：可配置最大下载带宽，避免占用过多网络资源

2.2 镜像特性

• 轻量级：基于Alpine Linux，镜像体积小于50MB
• 无状态设计：任务配置通过外部参数或文件注入，容器本身不存储持久数据
• 多架构支持：兼容amd64、arm64等主流架构
• 低资源占用：运行时内存占用≤50MB，CPU使用率可控

三、使用场景和适用范围

3.1 适用场景

• 服务器自动化下载：作为后台服务运行，定期执行预设下载任务（如每日同步远程资源）
• 本地下载管理：个人用户通过容器化方式隔离下载环境，避免本地依赖冲突
• CI/CD流程集成：在自动化部署流程中下载依赖资源（如安装包、配置文件）
• 边缘设备部署：在资源受限的边缘节点（如树莓派）中执行轻量级下载任务

3.2 适用范围

• 个人开发者、企业IT运维、自动化工程师
• 需跨平台（Linux/macOS/Windows）统一下载工具的场景
• 对容器资源占用敏感的环境（如嵌入式设备、轻量服务器）

四、使用方法和配置说明

4.1 前提条件

• 已安装Docker Engine（20.10+版本）
• 网络环境可访问目标下载资源（如需代理，需配置Docker网络代理）

4.2 获取镜像

从Docker Hub拉取最新版本镜像：

bash
docker pull docker.xuanyuan.run/dicewheres/downloader:latest

如需指定版本，替换latest为具体版本号（如v1.2.0）。

4.3 基本使用

4.3.1 单次下载任务

通过命令行参数指定下载URL，将文件下载至本地目录（需挂载宿主机目录至容器内下载路径）：

bash
docker run --rm -v /本地下载目录:/app/downloads \
  docker.xuanyuan.run/dicewheres/downloader:latest \
  download --url "https://example.com/file.zip" --output "/app/downloads"

• --rm：任务完成后自动删除容器
• -v /本地下载目录:/app/downloads：挂载宿主机目录至容器内/app/downloads（下载文件输出路径）
• download：镜像内置的下载命令
• --url：目标文件URL
• --output：容器内输出路径（需与挂载路径一致）

4.3.2 批量下载任务

通过挂载配置文件定义批量任务。创建本地配置文件tasks.json：

json
{
  "tasks": [
    {
      "url": "https://example.com/file1.iso",
      "output": "/app/downloads/file1.iso",
      "resume": true
    },
    {
      "url": "ftp://ftp.example.com/file2.tar.gz",
      "output": "/app/downloads/file2.tar.gz",
      "timeout": 3600
    }
  ]
}

运行容器并挂载配置文件：

bash
docker run --rm -v /本地下载目录:/app/downloads \
  -v $(pwd)/tasks.json:/app/config/tasks.json \
  docker.xuanyuan.run/dicewheres/downloader:latest \
  batch --config /app/config/tasks.json

• batch：批量任务命令
• --config：指定配置文件路径

4.4 配置参数说明

4.4.1 环境变量

通过-e指定环境变量调整运行时行为：

4.4.2 命令行参数

下载命令（download）支持的核心参数：

4.5 Docker Compose部署示例

创建docker-compose.yml配置文件，定义持久化下载目录和固定配置：

yaml
version: '3.8'
services:
  downloader:
    image: docker.xuanyuan.run/dicewheres/downloader:latest
    volumes:
      - ./local_downloads:/app/downloads  # 宿主机下载目录
      - ./config:/app/config              # 挂载配置文件目录
    environment:
      - LOG_LEVEL=debug                   # 开启调试日志
      - CONCURRENT_LIMIT=3                # 限制并发任务数为3
    command: batch --config /app/config/tasks.json  # 启动时执行批量任务
    restart: unless-stopped               # 任务失败后自动重启（可选）

启动服务：

bash
docker-compose up -d

查看日志：

bash
docker-compose logs -f

五、注意事项

1. 权限问题：宿主机挂载目录需确保Docker用户有读写权限，避免因权限不足导致下载失败。可通过chmod 775 ./local_downloads调整目录权限。
2. 网络代理：如需通过代理访问外部资源，可在docker run时添加--env HTTP_PROXY=http://proxy:port或配置Docker全局代理。
3. 资源限制：通过--memory和--cpus参数限制容器资源占用，例如docker run --memory 256m --cpus 0.5 ...。
4. 数据安全：敏感配置（如FTP账号密码）建议通过环境变量注入，避免明文存储在配置文件中。

六、故障排除