一、起源

1.1 本地存储的五类问题

问题 表现 原因
多实例不一致 上传到实例 A 的文件在实例 B 上读取不到 文件只存在单节点磁盘,缺少共享
容器重建丢失 容器重启或重新调度后文件消失 容器文件系统随容器生命周期销毁
容量与配额失控 磁盘被上传内容写满,影响应用本身 应用与文件竞争同一磁盘空间
与发布耦合 发布需要迁移文件,回滚需要回滚文件 文件与应用绑定在同一份介质上
扩展成本高 扩容需要同步历史文件,备份需要单独处理 缺少独立的存储层次

1.2 对象存储的定位

对象存储把文件从应用服务器中剥离出来,成为独立的存储层次:

特点 含义
无目录层级 用键名表达路径语义,实际是扁平命名空间
按对象读写 不支持在对象中间修改,更新即整体覆盖
通过 HTTP 访问 可用签名授权客户端直接读写,不经应用服务器
弹性容量 容量与吞吐按需扩展,不需要应用侧规划磁盘

1.3 取舍

选择 获得 付出
对象存储 与实例解耦、容量弹性、可直连、天然支持大文件分段 引入外部依赖与鉴权配置,成本按用量计算,不支持部分更新
本地存储 实现简单、无额外依赖 上述五类问题,只适用于单实例与临时场景

二、原理

2.1 对象模型

概念 含义 设计要点
桶 对象的容器 按环境与用途划分,权限与生命周期按桶配置
键 对象的唯一名称 用前缀表达业务归属与时间,便于按前缀清理与批量操作
内容 对象的数据本体 更新即整体覆盖,不支持部分修改
元数据 内容类型、长度、摘要等 摘要可用于校验与断点续传的一致性判断
存储类别 访问频率对应的存储层级 与生命周期策略配合,降低冷数据成本

键的设计需要满足三个要求:全局唯一、能表达业务归属(便于按前缀清理与统计)、不包含用户可控的原始文件名(避免路径穿越与注入)。常见做法是"业务前缀加日期加随机标识加扩展名",原始文件名保存在元数据表中。

2.2 两条上传路径

路径 数据流向 优点 代价
服务端中转 客户端到应用再到对象存储 可在服务端做统一校验、加水印、记录审计 占用应用出口带宽与内存,大文件会显著增加资源消耗
客户端直传 客户端凭签名直接到对象存储 不占用应用带宽,天然支持大文件与并发分片 校验时机后置,需要回调或轮询确认,签名必须限制范围

选择依据是文件大小与是否需要服务端处理:小文件且需要即时处理时用中转,大文件与高并发上传场景用直传加确认回调。

2.3 预签名机制

预签名是服务端用密钥对一次具体操作生成有时效的授权,客户端凭该授权直接访问对象存储。

要点 说明
签名由服务端生成 密钥不出应用,客户端只拿到有期限的授权
绑定具体操作 签名与目标桶、键、操作类型绑定,不能挪作他用
有效期 越短越安全,但需覆盖客户端上传耗时;大文件要按分片时长评估
约束条件 可附加长度范围与内容类型约束,防止上传超出预期
键的确定 中转模式可让服务端先分配键再签名,避免客户端自定键造成覆盖

常见的错误是签名时未限定键或未加约束,客户端的签名一旦泄露即可上传任意内容到任意位置。

2.4 分段上传与断点续传

大文件上传需要拆分为多个分片,流程为三段:

1. 初始化 -> 获得上传标识
2. 上传各分片(可并发,失败的分片可单独重传)
3. 完成 -> 服务端按分片编号合并为完整对象
要点 说明
分片大小与数量存在上限 需按所选服务的限制设计,单片过小会导致分片数超限
断点续传 客户端或服务端记录上传标识与已完成分片编号,重试时跳过已上传分片
未完成的上传 已上传的分片会占用存储,必须在超时后主动中止,否则形成垃圾
分片摘要 各分片的摘要用于在合并时校验,避免拼接出错
并发度 并发上传可提升速率,但需与应用出口带宽和客户端带宽平衡

断点续传的可靠性依赖于"上传标识可被恢复":进程或客户端重启后,若上传标识只保存在内存中,上传只能从头开始。

2.5 下载与范围请求

下载侧的关键机制是范围请求,它同时是断点续传与在线播放的基础:

机制 请求与响应 作用
范围请求 请求带范围头,响应返回部分内容状态码与内容范围 只取所需片段,支持续传
接收范围声明 响应声明支持范围与内容长度 客户端据此决定是否分片下载
摘要校验 响应返回对象摘要 续传前确认对象未变化,避免拼接出错误结果

服务端中转下载时需要处理两个细节:按客户端请求的范围转发范围头并原样返回部分内容状态码与范围头;不要忽略范围头而整体返回,否则大文件下载会占用完整带宽且在断点续传时从头传输。

2.6 一致性边界

主流对象存储对同一区域内的新建与覆盖写已提供写后读一致,但设计时仍需注意:

场景 注意点
跨区域复制 复制存在延迟,读取远端副本可能出现旧数据
列表操作 部分实现对列表的一致性弱于点读,刚写入的对象可能暂时不在列表中
删除 删除后短时间内的读取结果需要按实现确认
覆盖写 覆盖后读取到旧内容的窗口需要按实现确认

结论:判断"文件是否已上传成功"应基于完成上传的返回值或回调,而不是通过列表查询;跨区域场景不应依赖强一致。

2.7 大文件与内存控制

反模式 后果 正确做法
把上传文件整体读入字节数组 堆内存随文件大小增长,大文件直接触发内存告警 使用流式读写,按块转发
先落临时磁盘再上传 占用磁盘、增加一次写放大,且多实例下临时目录可能写满 获取输入流后直接转发到对象存储
下载时先全部读入内存再写响应 同上,且并发下载时内存成倍增长 以流式响应逐块写出
服务端拼接分片 无必要,对象存储的合并由服务端完成 由客户端或服务端触发合并,不搬运数据

请求体大小限制与超时必须随之调整,否则大文件上传会在中途被拒绝,相关配置见 Tomcat 部署与配置 与 Nginx 安全加固与防护。

2.8 元数据表与状态机

文件服务需要一张元数据表记录业务与对象的关联:

字段 用途
标识 对外暴露的文件标识,与对象键分离,避免直接暴露存储结构
桶与键 定位真实对象
原始文件名与内容类型 展示与下载时的响应头
大小与摘要 校验与统计
状态 区分上传中与已完成
业务类型与业务标识 与业务数据关联,支持级联清理
创建人与创建时间 审计与归属

状态机建议为"初始化、已上传、已确认"三态:初始化时写入记录并获得对外标识,上传完成后由回调或客户端确认置为已确认。未进入已确认状态且超过时限的记录,由清理任务删除对应对象并标记记录失败。

2.9 与业务数据的关联与删除

策略 做法 适用
引用计数 记录被引用次数,减到零时删除对象 同一文件可能被多处引用
归属单一 对象只属于一条业务数据,业务删除即删除对象 文件与业务一对一
逻辑删除加延迟清理 业务标记删除,对象由延迟任务清理 需要保留恢复窗口

删除需要保证幂等:对象可能已被删除,删除不存在的对象应视为成功。此外,删除业务数据与删除对象不在同一事务中,需要补偿手段处理"业务已删而对象未删"的情况。

2.10 安全要点

项 要求
桶权限 私有桶为默认,禁止公开可写
访问方式 通过签名授权,签名有效期尽量短
内容校验 按内容特征判断类型,不依赖扩展名与客户端声明的内容类型
大小限制 在签名约束与服务端校验两处同时限制
键生成 由服务端生成,不使用客户端提供的路径
恶意内容 对可执行内容与脚本类文件做类型拦截或隔离存储
敏感文件 加密存储或限制下载来源
审计 记录上传与下载的主体、时间与对象标识

把客户端提供的文件名直接作为对象键会带来路径穿越与覆盖风险,这是文件服务中最常见的安全缺陷。

三、实现

3.1 服务端签名与直传

@Service
public class FileUploadService {

    private final S3Presigner presigner;                 // 以兼容对象存储的接口为例
    private final FileMetaRepository metaRepository;
    private static final String BUCKET = "app-files";

    // 第一步:服务端分配文件标识与对象键,写入元数据表并返回签名
    public UploadTicket createTicket(UploadRequest request, String userId) {
        String fileId = UUID.randomUUID().toString().replace("-", "");
        // 键由服务端生成:业务前缀 + 日期 + 随机标识,不采用客户端文件名
        String objectKey = "upload/%s/%s".formatted(
                LocalDate.now().format(DateTimeFormatter.ofPattern("yyyyMMdd")), fileId + extensionOf(request));

        metaRepository.insert(FileMeta.initiated(fileId, BUCKET, objectKey,
                request.originalName(), request.size(), userId));

        PresignedPutObjectRequest signed = presigner.presignPutObject(b -> b
                .signatureDuration(Duration.ofMinutes(15))            // 有效期覆盖上传耗时即可
                .putObjectRequest(p -> p
                        .bucket(BUCKET)
                        .key(objectKey)                               // 绑定具体键
                        .contentType(request.contentType())
                        .contentLength(request.size())));             // 绑定约束,杜绝超限上传

        return new UploadTicket(fileId, signed.url().toString(), objectKey);
    }

    // 第三步:客户端上传完成后确认,服务端校验对象确实存在并更新状态
    public FileMeta confirm(String fileId, String userId) {
        FileMeta meta = metaRepository.findByFileId(fileId)
                .orElseThrow(() -> new NotFoundException("文件记录不存在"));
        requireOwner(meta, userId);

        HeadObjectResponse head = s3Client.headObject(h -> h.bucket(meta.bucket()).key(meta.objectKey()));
        meta.markConfirmed(head.contentLength(), head.eTag());
        metaRepository.update(meta);
        return meta;
    }

    private String extensionOf(UploadRequest request) {
        String name = request.originalName();
        int dot = name.lastIndexOf('.');
        // 扩展名只取白名单内的值,未在白名单内则不带扩展名
        return dot > 0 && ALLOWED_EXTENSIONS.contains(name.substring(dot + 1).toLowerCase())
                ? name.substring(dot).toLowerCase() : "";
    }
}

要点:签名只授权"以指定键、指定长度、指定类型上传一次",因此客户端无法覆盖其他文件或超出大小限制。

3.2 分段上传与合并

// 初始化分段上传,返回上传标识与对象键
public MultipartTicket initiateMultipart(String fileName, long size, String userId) {
    String fileId = UUID.randomUUID().toString().replace("-", "");
    String objectKey = "upload/%s/%s".formatted(today(), fileId);

    CreateMultipartUploadResponse created = s3Client.createMultipartUpload(c -> c
            .bucket(BUCKET).key(objectKey));
    String uploadId = created.uploadId();

    // 上传标识必须持久化,否则进程重启后无法续传
    multipartRepository.insert(new MultipartSession(fileId, objectKey, uploadId, userId, size,
            MultipartStatus.IN_PROGRESS, Instant.now()));
    return new MultipartTicket(fileId, uploadId, objectKey);
}

// 为每个分片生成签名,客户端并发上传;分片编号需在重试时保持一致
public List<PartUrl> signParts(String fileId, int partCount, String userId) {
    MultipartSession session = multipartRepository.find(fileId, userId);
    return IntStream.rangeClosed(1, partCount)
            .mapToObj(partNumber -> {
                String url = presigner.presignUploadPart(b -> b
                        .signatureDuration(Duration.ofMinutes(30))
                        .uploadPartRequest(p -> p.bucket(BUCKET).key(session.objectKey())
                                .uploadId(session.uploadId()).partNumber(partNumber)))
                        .url().toString();
                return new PartUrl(partNumber, url);
            })
            .toList();
}

// 完成合并:需要按编号提交各分片摘要,服务端据此校验并合并
public void completeMultipart(String fileId, List<PartETag> parts, String userId) {
    MultipartSession session = multipartRepository.find(fileId, userId);
    s3Client.completeMultipartUpload(c -> c.bucket(BUCKET).key(session.objectKey())
            .uploadId(session.uploadId())
            .multipartUpload(m -> m.parts(parts.stream()
                    .map(p -> CompletedPart.builder().partNumber(p.partNumber()).eTag(p.eTag()).build())
                    .toList())));
    multipartRepository.markCompleted(fileId);
}
// 清理任务:中止超时未完成的分段上传,释放已占用空间
@Scheduled(cron = "0 30 3 * * ?")
public void abortStaleUploads() {
    multipartRepository.findStale(Duration.ofHours(24)).forEach(session -> {
        try {
            s3Client.abortMultipartUpload(a -> a.bucket(BUCKET)
                    .key(session.objectKey()).uploadId(session.uploadId()));
        } catch (NoSuchUploadException ignored) {
            // 已被中止,视为成功,保证清理幂等
        } finally {
            multipartRepository.markFailed(session.fileId());
        }
    });
}

3.3 流式下载与范围请求

@GetMapping("/files/{fileId}")
public void download(@PathVariable String fileId,
                     @RequestHeader(value = HttpHeaders.RANGE, required = false) String range,
                     HttpServletResponse response) throws IOException {
    FileMeta meta = fileService.findConfirmed(fileId);

    GetObjectRequest.Builder<?> request = GetObjectRequest.builder()
            .bucket(meta.bucket()).key(meta.objectKey());
    if (range != null) {
        request.range(range);                     // 原样转发范围头,不要忽略
    }

    try (ResponseInputStream<GetObjectResponse> in = s3Client.getObject(request.build())) {
        GetObjectResponse object = in.response();
        response.setStatus(object.contentRange() != null
                ? HttpStatus.PARTIAL_CONTENT.value()          // 范围请求返回部分内容状态码
                : HttpStatus.OK.value());
        response.setContentType(contentTypeOrOctet(meta.contentType()));
        response.setHeader(HttpHeaders.ACCEPT_RANGES, "bytes");
        if (object.contentRange() != null) {
            response.setHeader(HttpHeaders.CONTENT_RANGE, object.contentRange());
        }
        response.setHeader(HttpHeaders.CONTENT_LENGTH,
                String.valueOf(object.contentLength() == null ? meta.size() : object.contentLength()));

        // 流式转发:不把对象读入内存
        in.transferTo(response.getOutputStream());
    }
}

要点:中间代理需要关闭响应缓冲并放宽读写超时,否则大文件下载会被缓冲或中途断开,配置见 Nginx 反向代理与负载均衡实践 与 Nginx 安全加固与防护。

3.4 元数据表

CREATE TABLE `file_meta`
(
    `id`            BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '主键',
    `file_id`       CHAR(32)        NOT NULL COMMENT '对外文件标识',
    `bucket`        VARCHAR(64)     NOT NULL COMMENT '桶名称',
    `object_key`    VARCHAR(512)    NOT NULL COMMENT '对象键,由服务端生成',
    `original_name` VARCHAR(255)    NOT NULL DEFAULT '' COMMENT '原始文件名,仅用于展示',
    `content_type`  VARCHAR(128)    NOT NULL DEFAULT 'application/octet-stream' COMMENT '内容类型',
    `size`          BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '字节数',
    `checksum`      VARCHAR(128)    NOT NULL DEFAULT '' COMMENT '内容摘要',
    `status`        TINYINT         NOT NULL DEFAULT 0 COMMENT '状态:0 上传中 1 已确认 2 失败',
    `biz_type`      VARCHAR(64)     NOT NULL DEFAULT '' COMMENT '业务类型',
    `biz_id`        VARCHAR(64)     NOT NULL DEFAULT '' COMMENT '业务标识',
    `owner_id`      BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '上传人标识',
    `created_at`    DATETIME(3)     NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
    `updated_at`    DATETIME(3)     NOT NULL DEFAULT CURRENT_TIMESTAMP(3)
                                    ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_file_id` (`file_id`),
    KEY `idx_biz` (`biz_type`, `biz_id`),
    KEY `idx_status_created` (`status`, `created_at`)
) ENGINE = InnoDB
  DEFAULT CHARSET = utf8mb4 COMMENT ='文件元数据';

3.5 验证与排查

# 确认对象已存在及其元数据(内容类型、长度、摘要)
aws s3api head-object --bucket app-files --key "upload/20260921/xxx.pdf"

# 校验上传内容与本地文件一致
md5sum local.pdf
aws s3api head-object --bucket app-files --key "upload/20260921/xxx.pdf" --query 'ETag'

# 验证范围请求(应返回 206 与内容范围头)
curl -sI -H 'Range: bytes=0-1023' http://localhost:8080/files/7f3c9a2b

# 验证未完成的分段上传是否被清理
aws s3api list-multipart-uploads --bucket app-files

# 确认桶权限未公开(应无公开读写的策略)
aws s3api get-bucket-policy --bucket app-files 2>/dev/null || echo "无桶策略,即私有"

# 检查元数据表中未确认的记录与对象是否对应
mysql -e "SELECT file_id, object_key, status, created_at FROM file_meta
          WHERE status = 0 AND created_at < NOW() - INTERVAL 24 HOUR LIMIT 20;"

3.6 常见问题对照

现象 常见原因 处置
多实例下部分请求读不到文件 文件保存在本地磁盘 迁移到对象存储或共享存储
容器重建后文件丢失 未挂载持久卷且未使用对象存储 改用对象存储
上传大文件时应用内存告警 把文件读入内存或落临时盘 改为流式转发
上传中途失败需从头重传 未实现分段与断点续传 引入分段上传并持久化上传标识
存储中出现无法删除的垃圾 分段上传未完成且未中止 增加中止任务并定期清理
客户端可上传到任意键 签名未绑定键或未加约束 签名时固定键并附加长度与类型约束
下载大文件时断点续传无效 服务端忽略范围头 转发范围头并返回部分内容状态码与范围头
上传的图片无法预览 内容类型缺失或被统一设为二进制流 记录并在下载响应中返回正确内容类型
上传了危险类型文件 仅按扩展名校验 按内容特征判断类型并拦截可执行内容
业务数据已删而对象残留 删除不在同一事务,缺少补偿 引入引用计数或延迟清理任务
文件列表看不到刚上传的对象 依赖列表查询判断上传结果 以完成上传的返回值或确认回调为准

四、总结

  1. 本地存储在多实例一致性、容器重建、容量治理、发布耦合与扩容成本五处失效,对象存储把文件从应用服务器中剥离以解决这些问题。
  2. 对象模型由桶、键、内容与元数据构成,键由服务端生成并表达业务归属,原始文件名只作为展示用元数据保存。
  3. 上传路径分为服务端中转与客户端直传:直传不占应用带宽且天然支持大文件,中转便于统一校验与审计,选择依据是文件大小与是否需要服务端处理。
  4. 预签名把授权限定到具体键、操作与有效期,并可附加长度与类型约束;签名未绑定键是客户端可任意上传的根因。
  5. 分段上传的流程是初始化、并发上传分片、合并;上传标识必须持久化才能断点续传,未完成的上传需要主动中止以免形成垃圾。
  6. 下载侧依赖范围请求实现续传与片段读取,服务端中转必须转发范围头并返回部分内容状态码与范围头。
  7. 一致性判断应基于上传完成的返回值或确认回调,而不是列表查询;跨区域复制不应作为强一致来依赖。
  8. 大文件处理必须全程流式,避免读入内存或落临时磁盘;请求体大小与超时限制需要同步调整。
  9. 元数据表采用初始化、已上传、已确认三态,并配套未完成记录的清理任务;对外的文件标识与对象键分离,避免暴露存储结构。
  10. 安全要求集中在私有桶、短有效期签名、按内容判断类型、服务端生成键与上传下载审计五项,其中键的生成方式是最容易被忽略的一项。