文件上传分布式限流如何做？

在微服务与云原生架构中，文件上传是典型的网络密集型（Network-Intensive）与 IO 密集型（IO-Intensive）业务。传统的 API 限流手段通常基于请求频次（QPS）进行控制，这在普通 JSON/Form 接口场景下效果显著。然而在文件上传场景中，仅仅限制 QPS 存在致命盲区：一个 1KB 的元数据查询请求与一个 2GB 的高清视频上传请求，对系统网卡带宽、内存缓冲区、磁盘 IOPS 以及后端对象存储造成的压力相差数百万倍。

如果仅按请求数限流，黑客或突发大流量只需发起少数几个百兆大文件上传请求，就能瞬间打满集群网卡入口带宽（Ingress Bandwidth），导致同节点上的其他微服务因网络拥塞而雪崩。

实现高可用、高扩展的文件上传分布式限流，必须建立结合"请求频次（QPS）、瞬时并发连接数（Concurrent Connections）、网络带宽吞吐量（Upload Bandwidth MB/s）"的三维立体防护体系。

一、 文件上传场景限流的核心挑战与三维防护模型

文件上传的分布式限流远比普通接口复杂，其核心挑战体现在三个维度：

1.1 文件上传的特殊性与防护盲区

• 流量体积不对称：普通 API 请求体通常在几 KB 级别，而文件上传请求体可达几十 MB 甚至数 GB。

• 资源消耗持续时间长：大文件上传需要建立长连接，持续占用网关层 worker 线程、内存 Buffer 及网络 Socket 资源。

• 分片上传（Multipart Chunked Upload）状态同步：大文件普遍采用分片上传，一个大文件被拆分为数十甚至上千个 Chunk 请求，不同 Chunk 可能落到分布式集群的不同节点，状态难以实时原子化聚合。

1.2 三维限流防护模型

为了全面保护系统，必须构建涵盖三个维度的防护网：

限流维度	控制目标	衡量单位	核心保护资源	典型配置阈值示例
请求频次限流	限制特定用户/IP 在单位时间发起的上传请求次数	QPS / QPM	API 网关 CPU、数据库写入 QPS	10 次/分钟
并发连接限流	限制特定用户/IP 实时处于传输状态的长连接数量	Active Connections	网关 Worker 线程、Socket 连接数	5 个并发连接
带宽吞吐限流	限制集群或单用户在单位时间内上传的字节总数	MB/s (Bytes/sec)	服务器网卡带宽、磁盘 IOPS、流缓冲区	单用户 5MB/s，集群 1GB/s

                       文件上传三维限流模型
                       
              ┌─────────────────────────────────┐
              │ 1. 频次控制 (QPS / QPM)          │
              │    防止频繁触发上传初始化与元数据写入│
              └────────────────┬────────────────┘
                               │
                               ▼
              ┌─────────────────────────────────┐
              │ 2. 并发控制 (Active Connections)│
              │    防止长连接打爆线程池与 Socket │
              └────────────────┬────────────────┘
                               │
                               ▼
              ┌─────────────────────────────────┐
              │ 3. 带宽控制 (Bytes/sec / MB/s)  │
              │    防止大文件流量拖垮集群网卡带宽│
              └─────────────────────────────────┘

二、 分布式限流四大算法在文件场景的深度适配

选择合适的限流算法是构建稳定限流系统的第一步。常见的四种限流算法在文件上传场景下的表现存在显著差异：

2.1 固定窗口算法（Fixed Window Counter）

• 原理：将时间划分为固定周期（如 1 秒），维护一个计数器。超过阈值直接拒绝，周期结束重置计数器。

• 局限：存在严重的"临界突发问题"（Boundary Burst）。例如在第 0.9 秒传入 100MB 流量，第 1.1 秒又传入 100MB 流量，短时间内网卡承受了 200MB 的冲击，瞬间打爆带宽。

2.2 滑动窗口算法（Sliding Window Log / Counter）

• 原理：将时间划分为更细粒度的格（Grid），随着时间推移动态滑动窗口，累加窗口内的请求数。

• 局限：对请求数的限制极其精准，但由于文件大小不一，即使精准限制了请求数，也无法限制上传的字节总量。

2.3 漏桶算法（Leaky Bucket）

• 原理：请求如水般注入桶中，桶以绝对恒定的速率"漏出"流量进行处理。若注入速率过快溢出，则直接拒绝或排队。

• 文件场景适配 ：天然适合字节流平滑打限（Bandwidth Throttling）。无论前端传输多快，服务端以固定速率（如 2MB/s）从 Socket 缓冲区读取 InputStream，实现绝对平滑的网络流量整形。

2.4 令牌桶算法（Token Bucket）

• 原理：系统以恒定速率向桶中放入令牌，桶满则溢出。请求处理时需从桶中领取指定数量的令牌。

• 文件场景适配 ：最适合字节级（Byte-level）分布式限流与分片上传。将"令牌"的物理含义定义为"允许上传的字节数（Bytes）"。上传 5MB 的分片，需一次性扣减 5 * 1024 * 1024 个令牌。既允许合理的突发传输（由桶容量决定），又能精准控制平均带宽。

算法选型对比矩阵

算法类型	时间复杂度	空间复杂度	突发流量支持	流量平滑度	文件上传场景适合度
固定窗口	O(1)	O(1)	不可控（存在临界突发）	差	极低
滑动窗口	O(1) ~ O(N)	O(N)	部分支持	中等	低（仅适合限制上传次数）
漏桶算法	O(1)	O(1)	不支持（强行抹平）	极高	高（适合网关层物理限速）
令牌桶算法	O(1)	O(1)	支持（在桶容量范围内）	高	极高（金标准，适合分布式配额）

三、 分层分级分布式限流架构设计

针对文件上传，单靠某一层的限流无法兼顾性能与安全。生产级架构必须采用"网关接入层 -> 微服务网关层 -> 业务应用层 -> 对象存储层"的纵深防御体系。

[ 客户端 / APP / Web ]
          │
          ▼
┌────────────────────────────────────────────────────────┐
│ 1. Nginx / OpenResty 网关接入层                        │
│    - limit_conn (限制单 IP 并发连接数)                  │
│    - limit_rate (网络层物理限速 B/s)                   │
└────────────────────────┬───────────────────────────────┘
                         │
                         ▼
┌────────────────────────────────────────────────────────┐
│ 2. 微服务网关层 (Spring Cloud Gateway / Envoy)         │
│    - 请求 Header (Content-Length) 预检与阻断          │
│    - 全局/租户级上传 QPS 限制                           │
└────────────────────────┬───────────────────────────────┘
                         │
                         ▼
┌────────────────────────────────────────────────────────┐
│ 3. 业务应用层 (Spring Boot + Redis + Lua)             │
│    - 字节级分布式令牌桶 (Byte-level Token Bucket)      │
│    - 动态配额与套餐鉴权 (Free 用户 vs VIP 用户)         │
└────────────────────────┬───────────────────────────────┘
                         │
                         ▼
┌────────────────────────────────────────────────────────┐
│ 4. 对象存储层 (MinIO / Ceph / AWS S3)                  │
│    - 直传 Presigned URL 签名有效期与配额限制            │
│    - 存储后端 Multipart 分片校验                         │
└────────────────────────────────────────────────────────┘

3.1 Nginx / OpenResty 接入层（物理防爆）

在流量最前沿，必须阻断恶意的连接爆破与绝对带宽挤占。OpenResty 能在请求未经 JVM 内存缓冲前直接裁决。

Nginx

# Nginx 配置文件示例
http {
    # 1. 定义并发连接数限流区域 (以客户端 IP 为 Key，分配 10MB 内存区域)
    limit_conn_zone $binary_remote_addr zone=upload_conn_zone:10m;

    server {
        listen 80;
        server_name upload.example.com;

        location /api/v1/files/upload {
            # 限制单个 IP 同时只能建立 3 个上传连接
            limit_conn upload_conn_zone 3;

            # 静态限制单连接最大上传传输速率为 2MB/s (超出部分被平滑延迟)
            limit_rate 2m;

            # 设置客户端最大请求体大小为 100MB，超过直接返回 413 Payload Too Large
            client_max_body_size 100m;

            proxy_pass http://gateway_backend;
        }
    }
}

3.2 微服务网关层（Content-Length 快速预检）

微服务网关（如 Spring Cloud Gateway）应拦截非法的头信息，在无需读取完整 Request Body 的情况下实现毫秒级快速拒绝。

Java

// Spring Cloud Gateway 文件上传 Content-Length 预检过滤器
@Component
public class UploadPreCheckFilter implements GlobalFilter, Ordered {

    private static final long MAX_ALLOWED_BYTES = 100 * 1024 * 1024; // 100MB

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        ServerHttpRequest request = exchange.getRequest();
        
        // 仅拦截文件上传接口
        if (request.getURI().getPath().contains("/files/upload")) {
            long contentLength = request.getHeaders().getContentLength();
            
            // 校验 Content-Length 请求头
            if (contentLength > MAX_ALLOWED_BYTES) {
                ServerHttpResponse response = exchange.getResponse();
                response.setStatusCode(HttpStatus.PAYLOAD_TOO_LARGE);
                response.getHeaders().setContentType(MediaType.APPLICATION_JSON);
                
                String errorBody = "{\"code\": 413, \"message\": \"上传文件大小超出系统限制\"}";
                DataBuffer buffer = response.bufferFactory().wrap(errorBody.getBytes(StandardCharsets.UTF_8));
                return response.writeWith(Mono.just(buffer));
            }
        }
        return chain.filter(exchange);
    }

    @Override
    public int getOrder() {
        return -100; // 高优先级执行
    }
}

四、 核心实战：基于 Redis + Lua 实现字节级分布式令牌桶

在分布式环境中，多个应用实例共享限流状态。使用 Redis + Lua 脚本 能够保证多节点并发扣减令牌时的原子性（Atomicity）与高性能。

这里的创新点在于：我们将令牌桶中的"令牌（Token）"映射为"允许消耗的字节数（Bytes）"。

4.1 字节级令牌桶数学模型

设定参数：

• Capacity：令牌桶最大容量（字节数，例如 50MB，允许突发传输）。

• Refill_Rate：令牌填充速率（字节/秒，例如 5MB/s，控制平均带宽）。

• Requested_Bytes：本次上传请求所需的字节数（如文件或分片大小）。

• Last_Updated：上次更新令牌桶的时间戳。

生成公式（采用懒加载计算，无需后台定时线程）：

当前时间 = Current_Time
时间差 Δt = Max(0, Current_Time - Last_Updated)
新生成的令牌数 Generated_Tokens = Δt × Refill_Rate
当前实际可用令牌数 Current_Tokens = Min(Capacity, Tokens + Generated_Tokens)

如果 Current_Tokens >= Requested_Bytes:
    Current_Tokens = Current_Tokens - Requested_Bytes
    放行 (Allowed)
否则:
    拒绝 (Rejected)

4.2 高并发无锁 Lua 脚本实现

在 Redis 中使用 Hash 结构存储桶状态，Lua 脚本保证"读取-计算-更新"全流程原子的。

Lua

-- KEYS[1]: 限流 Key (例如: ratelimit:upload:bytes:user_10086)
-- ARGV[1]: 本次请求消耗的字节数 (Requested_Bytes)
-- ARGV[2]: 令牌填充速率 (Bytes/sec)
-- ARGV[3]: 桶最大容量 (Capacity in Bytes)
-- ARGV[4]: 当前 UNIX 时间戳 (单位: 秒，可包含小数表示毫秒)

local key = KEYS[1]
local requested_bytes = tonumber(ARGV[1])
local refill_rate = tonumber(ARGV[2])
local capacity = tonumber(ARGV[3])
local now = tonumber(ARGV[4])

-- 从 Redis Hash 中获取当前桶状态
local data = redis.call('HMGET', key, 'tokens', 'last_updated')
local tokens = tonumber(data[1])
local last_updated = tonumber(data[2])

if not tokens then
    -- 首次初始化：桶处于满状态
    tokens = capacity
    last_updated = now
else
    -- 计算自上次请求以来生成的令牌数量
    local delta_time = math.max(0, now - last_updated)
    local generated_tokens = delta_time * refill_rate
    -- 补充令牌，但不能超过桶的最大容量
    tokens = math.min(capacity, tokens + generated_tokens)
    last_updated = now
end

-- 判断令牌是否足够本次文件/分片扣减
if tokens >= requested_bytes then
    tokens = tokens - requested_bytes
    -- 保存更新后的状态
    redis.call('HMSET', key, 'tokens', tokens, 'last_updated', last_updated)
    -- 设置 Key 的动态 TTL (防止冷数据长期占用空间，TTL 设为填满桶所需时间的 2 倍)
    local ttl = math.ceil(capacity / refill_rate) * 2
    redis.call('EXPIRE', key, math.max(ttl, 60))
    
    -- 返回 1 表示放行，并返回剩余令牌数
    return {1, math.floor(tokens)}
else
    -- 令牌不足，保存补充后的状态，但不扣减
    redis.call('HMSET', key, 'tokens', tokens, 'last_updated', last_updated)
    local ttl = math.ceil(capacity / refill_rate) * 2
    redis.call('EXPIRE', key, math.max(ttl, 60))
    
    -- 返回 0 表示限流拒绝，并返回当前剩余令牌数及建议等待秒数
    local needed_bytes = requested_bytes - tokens
    local wait_time = needed_bytes / refill_rate
    return {0, math.floor(tokens), math.ceil(wait_time)}
end

4.3 Spring Boot + AspectJ 切面全落地

1. 自定义限流注解

Java

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface ByteRateLimit {

    /**
     * 限流 Key 前缀
     */
    String keyPrefix() default "ratelimit:upload:";

    /**
     * 令牌填充速率（MB/s）
     */
    double rateInMBPerSec() default 5.0;

    /**
     * 桶最大容量（MB），允许突发传输的峰值
     */
    double capacityInMB() default 20.0;

    /**
     * 限流维度类型 (IP / USER / TENANT)
     */
    LimitType limitType() default LimitType.USER;

    enum LimitType {
        IP, USER, TENANT
    }
}

2. Redis 限流切面实现

Java

@Aspect
@Component
@Slf4j
public class ByteRateLimitAspect {

    @Autowired
    private StringRedisTemplate stringRedisTemplate;

    private DefaultRedisScript<List> redisScript;

    @PostConstruct
    public void init() {
        redisScript = new DefaultRedisScript<>();
        redisScript.setLocation(new ClassPathResource("scripts/byte_token_bucket.lua"));
        redisScript.setResultType(List.class);
    }

    @Around("@annotation(byteRateLimit)")
    public Object intercept(ProceedingJoinPoint joinPoint, ByteRateLimit byteRateLimit) throws Throwable {
        HttpServletRequest request = getHttpServletRequest();
        
        // 1. 获取上传文件大小 (Content-Length)
        long requestedBytes = request.getContentLengthLong();
        if (requestedBytes <= 0) {
            // 若 Header 中缺失 Content-Length，按默认单分片最大值预扣（如 5MB）
            requestedBytes = 5 * 1024 * 1024;
        }

        // 2. 解析限流 Key
        String limitKey = buildLimitKey(request, byteRateLimit);

        // 3. 单位换算：MB 转为 Bytes
        long refillRateInBytes = (long) (byteRateLimit.rateInMBPerSec() * 1024 * 1024);
        long capacityInBytes = (long) (byteRateLimit.capacityInMB() * 1024 * 1024);
        double nowTimestamp = System.currentTimeMillis() / 1000.0;

        // 4. 执行 Lua 脚本
        List<Long> result = stringRedisTemplate.execute(
                redisScript,
                Collections.singletonList(limitKey),
                String.valueOf(requestedBytes),
                String.valueOf(refillRateInBytes),
                String.valueOf(capacityInBytes),
                String.valueOf(nowTimestamp)
        );

        if (result != null && !result.isEmpty() && result.get(0) == 1L) {
            log.info("上传限流放行: Key={}, 请求字节={}, 桶内剩余字节={}", limitKey, requestedBytes, result.get(1));
            return joinPoint.proceed();
        } else {
            long remainingTokens = (result != null && result.size() > 1) ? result.get(1) : 0L;
            long waitSeconds = (result != null && result.size() > 2) ? result.get(2) : 1L;

            log.warn("触发上传字节限流: Key={}, 请求字节={}, 剩余令牌={}, 建议重试等待={}s",
                    limitKey, requestedBytes, remainingTokens, waitSeconds);

            HttpServletResponse response = getHttpServletResponse();
            response.setHeader("X-RateLimit-Limit-MB/s", String.valueOf(byteRateLimit.rateInMBPerSec()));
            response.setHeader("Retry-After", String.valueOf(waitSeconds));
            
            throw new BusinessException(429, "当前上传流量过大，请在 " + waitSeconds + " 秒后重试。");
        }
    }

    private String buildLimitKey(HttpServletRequest request, ByteRateLimit byteRateLimit) {
        String identifier;
        switch (byteRateLimit.limitType()) {
            case IP:
                identifier = getClientIp(request);
                break;
            case USER:
                identifier = getCurrentUserId(request);
                break;
            case TENANT:
                identifier = getTenantId(request);
                break;
            default:
                identifier = getClientIp(request);
        }
        return byteRateLimit.keyPrefix() + byteRateLimit.limitType().name().toLowerCase() + ":" + identifier;
    }

    private HttpServletRequest getHttpServletRequest() {
        ServletRequestAttributes attributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
        return attributes.getRequest();
    }

    private HttpServletResponse getHttpServletResponse() {
        ServletRequestAttributes attributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
        return attributes.getResponse();
    }

    private String getClientIp(HttpServletRequest request) {
        String ip = request.getHeader("X-Forwarded-For");
        if (ip == null || ip.isEmpty() || "unknown".equalsIgnoreCase(ip)) {
            ip = request.getRemoteAddr();
        }
        return ip.split(",")[0];
    }

    private String getCurrentUserId(HttpServletRequest request) {
        // 从 JWT Token 或 Session 获取 UserId，此处为示意
        String userId = request.getHeader("X-User-Id");
        return userId != null ? userId : getClientIp(request);
    }

    private String getTenantId(HttpServletRequest request) {
        String tenantId = request.getHeader("X-Tenant-Id");
        return tenantId != null ? tenantId : "default_tenant";
    }
}

五、 大文件分片上传（Chunked Upload）分布式限流与配额管控

对于超大文件（如 1GB~100GB），前端普遍采用 Multipart Chunked Upload（分片上传）。分片上传的生命周期通常包含三个阶段：

1. 初始化分片任务 (Init Multipart) ──> 生成 UploadID
2. 并行上传分片 (Upload Part 1..N) ──> 扣减动态令牌
3. 合并完成上传 (Complete Multipart) ──> 最终校验与归档

针对分片上传的分布式限流，工程落地时需采用分阶段混合控制策略：

5.1 分阶段限流控制策略

1. 初始化阶段（Init Upload）：

   • 对 /upload/init 接口执行 QPS 限流 （如单用户 5 次/分钟）。防止恶意请求大量生成 UploadID，造成对象存储上的碎片垃圾（Uncompleted Multipart Uploads）。

2. 分片传输阶段（Upload Part）：

   • 对 /upload/part 接口执行 字节级令牌桶限流（如上述 Lua 实现）。

   • 每个分片（一般为 5MB ~ 10MB）独立扣减令牌。即使前端开启 10 个并发线程同时上传分片，分布式令牌桶也能在总流量维度精准拉平。

3. 完成合并阶段（Complete Upload）：

   • 执行 用户日/月度总存储配额（Quota） 的原子校验。

5.2 断点续传（Resumable Upload）中的令牌扣减策略

分片上传可能因网络中断而触发重试。如果网络失败导致分片没有完整接收，已扣减的令牌是否需要退还？

• 预扣减模式（Pre-Deduction）：在分片传输前扣减令牌。优点是保护极严；缺点是若网络中途断开，会导致用户令牌被"误扣"。

• 后扣减 / 流式实时扣减模式（Post/Streaming Deduction）：

  在应用层以包装类（ThrottledInputStream）的方式，在真实从 Socket 读取数据流时边读边扣减。

Java

// 基于流式（Streaming）读取的网速限制装饰器
public class ThrottledInputStream extends FilterInputStream {

    private final BandwidthLimiter bandwidthLimiter;

    public ThrottledInputStream(InputStream in, BandwidthLimiter bandwidthLimiter) {
        super(in);
        this.bandwidthLimiter = bandwidthLimiter;
    }

    @Override
    public int read() throws IOException {
        bandwidthLimiter.acquire(1); // 阻塞等待获取 1 字节许可
        return super.read();
    }

    @Override
    public int read(byte[] b, int off, int len) throws IOException {
        int bytesRead = super.read(b, off, len);
        if (bytesRead > 0) {
            bandwidthLimiter.acquire(bytesRead); // 根据实际读取到的字节数阻塞/限流
        }
        return bytesRead;
    }
}

六、 高并发与高可用生产落地避坑指南

6.1 Redis 热点 Key（Hot Key）性能倾斜与解决

当数万个用户同时上传文件时，所有请求都会打到同一个 Redis Key（例如集群总带宽 Key ratelimit:upload:global），导致该 Key 所在的 Redis 节点 CPU 飙升至 100%。

解决方案：分片 Key 散列 + 本地二级缓存预扣

1. Key 哈希分片（Key Sharding）：

   将全局 Key 拆分为 N 个子桶（例如 ratelimit:upload:global:1 到 ratelimit:upload:global:16）。客户端请求时随机选择一个子桶进行扣减。子桶配额为 Total_Capacity / N。

2. 本地内存二级预扣（Local Guava/Caffeine Batching）：

   应用节点批量向 Redis 申请令牌（如一次性申请 50MB 批次），在本地 JVM 内存中进行细粒度分片扣减。扣减完后再异步向 Redis 续租。显著降低 Redis 的 RTT 网络开销。

6.2 Redis 集群故障降级（Fail-Open vs Fail-Closed）

当 Redis 发生网络分区、主从切换或宕机时，限流系统该如何应对？

• Fail-Open（降级放行 - 推荐用于核心业务）：

  若 Redis 调用超时或报错，捕获 RedisConnectionException 异常，记录 ERROR 日志，直接放行请求。优先保障用户上传功能的可用性，防守退化至 Nginx 接入层。

• Fail-Closed（降级拒绝 - 适用于强安全/成本敏感场景）：

  若 Redis 异常，直接拒绝上传，防止公网恶意爆破瞬间打垮按流量计费的第三方对象存储（如 AWS S3 / 阿里云 OSS）。

Java

try {
    // 执行 Redis Lua 限流
    return executeRedisRateLimit(...);
} catch (RedisException ex) {
    log.error("Redis 限流服务异常，触发熔断降级策略", ex);
    if (isFailOpenConfigured()) {
        // 放行逻辑
        return true; 
    } else {
        throw new BusinessException(503, "限流服务暂不可用，请稍后重试");
    }
}

6.3 避免 JVM 内存爆破：零拷贝与非阻塞长连接

在大文件上传过程中，严禁在 Java 应用层将整个文件加载为 byte[] 或 ByteArrayOutputStream，这会导致 JVM 频繁发生 Full GC 甚至 OOM。

• 使用 NIO / Zero-Copy 传输 ：使用 Spring WebFlux（基于 Netty）或 Servlet 3.1+ 的异步非阻塞 IO (ReadListener)，以小 Chunk 管道（Pipeline）流式转发至存储后端。

• JVM 堆外内存管控 ：限制 Netty DirectByteBuffer 的最大堆外内存，防止高速网络下 InputStream 堆积在内存缓冲区。

6.4 规范化 HTTP 响应头交互

遵从 RFC 6585 标准，当触发限流时，服务器应返回 HTTP Status 429 Too Many Requests，并在 Header 中附带明确的指示：

HTTP

HTTP/1.1 429 Too Many Requests
Content-Type: application/json;charset=UTF-8
X-RateLimit-Limit-MB/s: 5.0
X-RateLimit-Remaining-Bytes: 1048576
Retry-After: 3

{
  "code": 429,
  "message": "上传流量已触发系统限流保护，建议在 3 秒后重试",
  "data": {
    "retry_after_seconds": 3
  }
}

七、 监控告警与可观测性体系构建

完善的可观测性体系是保证分布式限流系统持续稳定的最后一道防线。必须对限流指标进行实时采集并搭建 Grafana 大盘。

                     Prometheus 指标采集架构
                     
 ┌─────────────────┐      /metrics      ┌─────────────────┐
 │ Spring Boot App ├───────────────────►│ Prometheus Server│
 └─────────────────┘                    └────────┬────────┘
                                                 │
                                                 ▼
                                        ┌─────────────────┐
                                        │ Grafana Dashboard│
                                        └─────────────────┘

7.1 核心 Prometheus 监控指标设计

在应用切片中通过 Micrometer 暴露埋点数据：

Java

// 定义 Prometheus Counter 和 Timer 监控指标
Counter.builder("upload_ratelimit_requests_total")
       .tag("status", "allowed") // allowed 或 rejected
       .tag("limit_type", "byte_bucket")
       .register(meterRegistry);

DistributionSummary.builder("upload_bytes_consumed")
       .baseUnit("bytes")
       .register(meterRegistry);

关键监控指标盘点：

1. upload_ratelimit_requests_total{status="rejected"}：限流拒绝请求总数（增长速率陡增说明系统遭受攻击或配额设置过小）。

2. upload_bytes_consumed_total：系统消耗的总上传字节数（可实时换算为集群物理网卡吞吐率 MB/s）。

3. upload_ratelimit_lua_latency_seconds：Redis 限流 Lua 脚本执行耗时（正常应低于 2ms，若升高说明 Redis 存在阻塞）。

7.2 告警规则配置示例（PromQL）

groups:
  - name: UploadRateLimitAlerts
    rules:
      # 告警规则 1: 拒绝率超过 30% 触发预警
      - alert: HighUploadRateLimitRejectionRate
        expr: |
          sum(rate(upload_ratelimit_requests_total{status="rejected"}[5m])) 
          / 
          sum(rate(upload_ratelimit_requests_total[5m])) > 0.3
        for: 2m
        labels:
          severity: warning
        annotations:
          summary: "文件上传限流拒绝率异常偏高 (>30%)"
          description: "当前集群文件上传限流拒绝率达到 {{ $value | humanizePercentage }}，请检查是否有异常流量爆破或配额过低。"

      # 告警规则 2: Redis 限流延迟过高
      - alert: RedisRateLimitLuaLatencyTooHigh
        expr: histogram_quantile(0.99, sum(rate(upload_ratelimit_lua_latency_seconds_bucket[5m])) by (le)) > 0.010
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Redis 限流脚本 P99 耗时超过 10ms"
          description: "限流 Lua 脚本 P99 执行延迟为 {{ $value | humanizeDuration }}，可能存在 Hot Key 或 Redis 节点 CPU 瓶颈。"

构建生产级的文件上传分布式限流系统，绝非简单的"写个计数器"即可解决。通过物理层接入网速限制、网关层 Payload 预检、应用层字节级 Redis+Lua 动态令牌桶，以及对分片上传生命周期的精心设计，才能够在大流量冲击下确保整个微服务集群的网络与存储基础设施稳如磐石。