tinkerbell37745/clamav-timedock repository overview

⁠ClamAV-Web

为 ClamAV⁠ 容器提供的 Web 管理、任务调度与多用户工作台

GitHub⁠ · Docker Hub⁠ · 快速开始⁠ · 开发⁠ · API⁠

ClamAV-Web 将 ClamAV 的扫描能力、定时任务和结果处理整合为一个浏览器可用的管理界面。它以单个 Docker 镜像运行：内含 ClamAV、Go 后端、React 前端和 cron 调度服务，适合家庭服务器、小型团队与NAS场景。

⁠📸 界面预览

ClamAV 状态与扫描统计

文件浏览与扫描提交

cron 规则管理

历史任务记录

隔离区

⁠✨ 功能一览

⁠🧱 工作方式

浏览器
  │ React + Vite 构建的单页界面
  ▼
Go HTTP 服务（认证、权限、队列、API、SQLite 索引）
  ├── /scan_once.sh ──► clamd / ClamAV
  ├── /cron.sh ───────► Debian cron
  ├── /config         ──► 规则、白名单、服务配置
  └── /data /state /log /quarantine ──► 持久化数据与运行产物

生产构建会先编译 ClamAV-Web/，再将静态文件嵌入 Go 可执行程序；容器启动后由 startup.sh 协调 ClamAV、cron 和 Web 服务。扫描全局串行执行，防止多个任务同时挤占扫描引擎。

⁠🚀 快速开始

⁠1. 构建镜像

docker build -t tinkerbell37745/clamav-timedock .

⁠2. 准备持久化目录

mkdir -p config data scan quarantine log state

将需要扫描的内容放入 scan/。默认情况下，Web 界面只能浏览和操作容器内的 /scan；文件浏览会隐藏符号链接，相关 API 也会拒绝包含符号链接的路径。

⁠3. 启动服务

首次注册管理员必须设置一个非空的 ADMIN_REGISTER_TOKEN。请替换示例中的随机值，并妥善保管。

docker run -d \
  --name clamav-web \
  --restart unless-stopped \
  -p 8080:8080 \
  -e TZ=Asia/Shanghai \
  -e ADMIN_REGISTER_TOKEN='replace-with-a-long-random-token' \
  -v "$(pwd)/config:/config" \
  -v "$(pwd)/data:/data" \
  -v "$(pwd)/scan:/scan" \
  -v "$(pwd)/quarantine:/quarantine" \
  -v "$(pwd)/log:/log" \
  -v "$(pwd)/state:/state" \
  tinkerbell37745/clamav-timedock

访问 http://<主机地址>:8080。首次打开时，使用你设置的令牌注册首个账户；该账户会自动成为管理员。完成首次运行流程后，管理员可在界面中创建其他账户。

⁠📦 持久化目录

六个目录都建议挂载到宿主机；容器需要读取 /scan，而隔离、删除和恢复还需要对它写入。

⁠🔐 安全与权限

• 密码以带独立随机 salt 的 Argon2id 哈希保存；认证使用 HttpOnly、SameSite=Strict 的 Cookie session。
• session 的绝对有效期为 24 小时，空闲有效期为 2 小时；登录接口有单 IP 与全局限流。
• 除首次状态、首次管理员注册和登录外，所有 API 都要求登录；浏览器中的写操作还必须同源。
• 用户的扫描队列、规则、信任区、历史、日志、查询任务和隔离区相互隔离。admin 只拥有用户与全局服务管理权，不能查看其他用户的业务数据。
• move、remove、清空历史与清空隔离区会修改或删除数据。建议先使用“仅告警”，并使用 EICAR 等安全测试样本验证流程。

如在 HTTPS 反向代理后部署，请设置 SCANNER_COOKIE_SECURE=true；若需要读取真实客户端 IP，只能在可信代理前提下配置 SERVER_TRUSTED_REVERSEPROXY。完整语义见 服务端配置⁠。

⁠⚙️ 常用配置

服务配置保存在 /config/clamavweb.conf，管理 API 可调整登录限制、历史索引间隔和 ClamAV 自动休眠时间，供前端设置页接入；日志配置需手工修改并重启服务，不通过界面或 API 暴露。配置项范围、默认值及反向代理规则见 server/server_conf.md⁠。

⁠📖 使用要点

• 处理方式：warn 只记录威胁；move 移至隔离区并可恢复；remove 直接删除，不能恢复。
• 定时规则：使用五段 cron（分 时 日 月 周），支持范围、步长与逗号列表；保存后会校验并重载。
• 信任区：白名单按内容 SHA-256 生效。文件变更后需重新添加；扫描执行时不能修改信任区。
• 队列：等待任务可调整顺序或取消；容器重启后，内存中尚未开始的手动任务不会恢复。
• 隔离恢复：若原路径已有同名文件，恢复会拒绝覆盖；恢复出的文件仍可能有风险。

⁠🛠️ 开发与接口

前端源码位于 ClamAV-Web/，后端源码位于 server/。本地前端开发服务器监听 http://127.0.0.1:5174，并默认将 /api 代理到 http://127.0.0.1:8080。

cd ClamAV-Web
npm ci
npm run dev

cd server
go test ./...

更完整的架构、开发流程、测试与扩展约定，请阅读 DEV.md⁠。请求与响应详情请阅读 server/api.md⁠。

⁠🙏 致谢

本项目开发中使用到了以下数个项目/开源仓库，致谢

• shadcn/ui⁠ - 前端组件
• Cisco-Talos/clamav⁠ - 杀毒引擎

⁠📄 License

本项目采用 MIT License⁠。