benzino77/clamav-rest-api

ClamAV REST API 镜像文档

镜像概述

ClamAV REST API镜像是一个将ClamAV反病毒引擎封装为RESTful API服务的Docker镜像，旨在提供便捷的文件扫描接口。通过HTTP POST请求即可实现文件上传与病毒扫描，简化了反病毒功能的集成流程，适用于各类需要病毒检测能力的应用场景。

核心功能与特性

• RESTful API接口：提供标准HTTP接口，支持文件上传扫描，返回清晰的JSON格式结果
• ClamAV引擎集成：内置ClamAV反病毒引擎，具备高效的***软件检测能力
• 病毒库自动更新：支持ClamAV病毒库定时自动更新，确保检测规则时效性
• 轻量级设计：基于Alpine或类似轻量基础镜像构建，资源占用低，部署高效
• 易于集成：无需深入了解ClamAV复杂配置，通过HTTP请求即可快速集成到现有系统

使用场景与适用范围

• 文件上传服务：集成到Web应用的文件上传模块，对用户上传文件进行实时病毒扫描
• 邮件服务器：扫描邮件附件中的***文件，提升邮件系统安全性
• 云存储服务：对用户存储的文件进行定期或触发式病毒检测
• 内网文件共享：为企业内部文件共享系统提供安全检查能力
• 自动化工作流：在CI/CD流程中集成病毒扫描，确保交付物安全性

使用方法与配置说明

快速启动（Docker Run）

bash
docker run -d -p 8080:8080 --name clamav-rest-api benzino77/clamav-rest-api

Docker Compose配置

yaml
version: '3'
services:
  clamav-rest-api:
    image: benzino77/clamav-rest-api
    ports:
      - "8080:8080"
    environment:
      - PORT=8080
      - CLAMAV_UPDATE_FREQ=24h  # 病毒库更新频率，支持h(小时)/m(分钟)单位
      - LOG_LEVEL=info  # 日志级别：debug/info/warn/error
    restart: unless-stopped

API使用示例

文件扫描请求

通过POST请求上传文件进行扫描：

bash
curl -X POST -F "file=@/path/to/local/file" http://localhost:8080/scan

响应示例

• 无病毒文件响应：

json
{
  "status": "clean",
  "filename": "testfile.txt",
  "size": 1234,
  "scan_time": "2024-05-20T12:34:56Z"
}

• 感染文件响应：

json
{
  "status": "infected",
  "filename": "malware.exe",
  "size": 5678,
  "virus": "EICAR-Test-Signature",
  "scan_time": "2024-05-20T12:35:10Z"
}

环境变量配置

注意事项

• 首次启动时，ClamAV需要下载初始病毒库，可能导致服务启动延迟，请耐心等待
• 建议根据实际需求调整MAX_FILE_SIZE和CLAMAV_TIMEOUT参数，避免资源过度消耗
• 生产环境中建议配合反向代理（如Nginx）使用，添加HTTPS加密和访问控制
• 病毒库更新依赖网络连接，请确保容器可访问ClamAV更新服务器（database.clamav.net）

更多详细信息请参考项目GitHub页面：https://github.com/benzino77/clamav-rest-api