revoltchat/autumn Docker 镜像 - 轩辕镜像 | Docker 镜像高效稳定拉取服务

文件上传与元数据代理微服务镜像文档

1. 镜像概述

本镜像是一个轻量级的微服务，专注于提供文件上传处理和元数据代理功能。它作为中间层服务，接收客户端的文件上传请求，处理文件存储逻辑，并同步管理文件的元数据信息（如名称、大小、类型、上传时间等），同时支持将文件代理转发至多种后端存储系统。

2. 核心功能与特性

2.1 文件上传处理

• 支持多种文件上传方式（如表单上传、流式上传）
• 提供文件大小限制、格式校验功能
• 支持断点续传（如配置启用）

2.2 元数据管理

• 自动记录文件基础元数据：名称、大小、MIME类型、上传时间、存储路径
• 支持自定义元数据字段扩展（如通过API添加额外属性）
• 元数据持久化存储（支持数据库或文件系统存储）

2.3 存储代理能力

• 支持多种后端存储系统代理：本地文件系统、S3兼容对象存储、FTP/SFTP服务器、云存储服务（如AWS S3、Azure Blob）
• 动态路由上传请求至指定后端存储
• 存储路径规范化与管理

2.4 API接口支持

• RESTful API设计，提供文件上传、元数据查询、文件删除等标准接口
• 支持API密钥认证（如配置启用）
• 详细的错误码与日志输出

3. 使用场景与适用范围

3.1 适用场景

• 内容管理系统（CMS）的文件上传模块
• 用户生成内容（UGC）平台的文件接收服务
• 企业内部文档管理系统的文件存储代理
• 多存储后端的统一文件上传入口

3.2 适用范围

• 中小型应用的文件上传需求
• 需要集中管理文件元数据的系统
• 需对接多种存储后端的微服务架构

4. 使用方法与配置说明

4.1 基本使用（Docker Run）

bash
docker run -d \
  --name file-upload-proxy \
  -p 8080:8080 \
  -e PORT=8080 \
  -e STORAGE_BACKEND=s3 \
  -e S3_ENDPOINT=[***] \
  -e S3_BUCKET=my-upload-bucket \
  -e METADATA_STORAGE=sqlite \
  -e METADATA_DB_PATH=/data/metadata.db \
  -v /local/data:/data \
  file-upload-metadata-proxy:latest

4.2 环境变量配置

4.3 Docker Compose示例

yaml
version: '3'
services:
  file-upload-proxy:
    image: file-upload-metadata-proxy:latest
    ports:
      - "8080:8080"
    environment:
      - PORT=8080
      - STORAGE_BACKEND=local
      - LOCAL_STORAGE_PATH=/uploads
      - METADATA_STORAGE=postgres
      - METADATA_DB_URL=postgres://user:pass@postgres:5432/metadata
      - MAX_FILE_SIZE=200
      - ALLOWED_FILE_TYPES=image/*,application/pdf
    volumes:
      - ./uploads:/uploads
    depends_on:
      - postgres

  postgres:
    image: postgres:14
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
      - POSTGRES_DB=metadata
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:

4.4 API接口示例

文件上传（POST）

bash
curl -X POST http://localhost:8080/upload \
  -H "Content-Type: multipart/form-data" \
  -F "file=@localfile.txt" \
  -F "custom_meta={\"owner\":\"user123\"}"

查询文件元数据（GET）

bash
curl http://localhost:8080/metadata?file_id=123e4567-e89b-12d3-a456-426614174000

5. 注意事项

• 生产环境中建议启用API密钥认证（设置API_KEY环境变量）
• 敏感配置（如存储密钥、数据库密码）建议通过Docker Secrets或环境变量注入，避免硬编码
• 大文件上传场景下建议配置断点续传功能（需通过额外环境变量ENABLE_RESUME_UPLOAD=true启用）
• 元数据存储建议使用关系型数据库（如PostgreSQL）以提高并发读写性能