muidea/magicfile

magicFile Docker镜像文档

镜像概述

magicFile是一个专注于文件存储与管理的Docker镜像，提供文件详情的结构化存储能力，并支持按日期组织文件存储目录，旨在帮助应用规范文件存储结构，提升文件管理效率。

核心功能与特性

1. 文件详情结构化存储

定义FileDetail结构体用于标准化文件元数据管理，包含以下字段：

• ID：文件唯一标识（自增主键）
• FileToken：文件访问令牌
• FileName：文件名
• FilePath：文件存储路径
• UploadDate：上传时间戳（Unix时间）
• Validity：有效期时间戳（Unix时间，过期后可自动清理）
• ReserveFlag：保留标志（true表示永久保留，不受Validity限制）
• Source：文件来源标识（如上传渠道、系统模块等）

2. 优化的存储目录结构

• 原目录结构：./static/{uuid}/{file}（按UUID随机生成子目录）
• 调整后目录结构：./static/{YYYYMMDD}/{file}（按日期组织子目录，格式为年-月-日）

使用场景与适用范围

• 需要按日期归档文件的应用（如日志系统、每日备份文件）
• 需管理文件生命周期的服务（如临时文件存储、定期清理系统）
• 要求规范文件存储路径的文档管理系统
• 需要记录文件元数据的上传服务

使用方法与配置说明

基本部署命令

bash
docker run -d \
  --name magicFile \
  -v /host/path/to/static:/app/static \
  docker.xuanyuan.run/magicFile:latest

docker-compose配置示例

yaml
version: '3'
services:
  magicfile-service:
    image: docker.xuanyuan.run/magicFile:latest
    volumes:
      - ./static_data:/app/static  # 主机目录映射，确保文件持久化
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai  # 设置时区，确保日期目录生成准确

关键配置说明

• 存储目录映射：必须通过-v参数将主机目录挂载到容器内/app/static路径，避免容器重启导致文件丢失
• 日期目录生成：系统根据文件的UploadDate字段自动创建YYYYMMDD格式的子目录
• 元数据管理：FileDetail结构体数据通常存储于数据库（需额外配置数据库连接），用于文件检索与生命周期管理
• 有效期控制：结合Validity和ReserveFlag字段可实现自动清理过期文件（需配合定时任务）