面向中文开发者的 AWS 实战知识库 代维服务
上云咨询

S3 前缀最佳实践:一次 503 SlowDown 的实战教训

导出 PDF 浅色排版、带版权水印,可在打印窗口另存为 PDF
S3 前缀最佳实践:一次 503 SlowDown 的实战教训

摘要

  • 一个扁平的 uploads/ 前缀承载约 2,800 PUT/s,再加上一次生命周期 COPY 突发流量,突破了官方文档记录的每前缀上限(每秒 3,500 次 PUT/COPY/POST/DELETE 和 5,500 次 GET/HEAD),并在 UTC 02:47 开始返回 503 SlowDown。
  • 修复方案并不花哨:使用按日期分片、再加 16 路哈希分片的键,并配合 botocore 自适应重试。p99 PutObject 延迟在约 40 分钟内从 1,900 ms 降至 120 ms。
  • 一半的压力来自一条我们早已忘记的生命周期规则——转换操作在同一前缀上会按 COPY 请求计费并受到限流。仅靠分片只会掩盖这个问题。

凌晨 2:47 的告警:单一扁平前缀上的 503 SlowDown

告警来自一个上传用户照片的 Lambda。以下错误文本直接摘自 CloudWatch Logs:

An error occurred (SlowDown) when calling the PutObject operation (reached max retries: 4):
Please reduce your request rate.

存储桶是 us-east-1 中的 media-uploads-prod,共 4.1 TB、3,100 万个对象,每个键都直接位于 uploads/ 下——uploads/9f2c1a7e-....jpg、uploads/1b8dd0f4-....png。没有日期文件夹,没有分片,什么都没有。

正常周二的峰值流量约为 600 PUT/s。那天晚上一次营销推广上线,摄取集群扩展到 800 个并发 Lambda worker,在 19 分钟内维持约 2,800 PUT/s。低于 3,500/s,所以本应没问题。但事实并非如此,原因在下一节说明。

诊断:CloudWatch 和 CLI 实际显示了什么

最先做的是成本最低的检查:问题究竟出在请求速率本身,还是另有原因?

aws s3api put-object 
  --bucket media-uploads-prod 
  --key healthcheck/probe.txt 
  --body /dev/null 
  --region us-east-1


第一次尝试就成功了。所以凭证、存储桶策略和端点都没问题——这是速率信号,不是权限信号。第二项检查:是否所有请求都打在同一个前缀上?

```bash
aws s3api list-objects-v2 
  --bucket media-uploads-prod 
  --delimiter '/' 
  --max-keys 100 
  --query 'CommonPrefixes[].Prefix' 
  --output text


输出为空,`KeyCount` 为 100。单个分隔符层级完全没有返回任何公共前缀,这证实只有一个扁平命名空间。如果你运行该命令只得到一行结果,你的布局也是一样的。

第三项检查:启用并读取 S3 请求指标。我们很幸运——几个月前因无关原因启用了 `EntireBucket` 过滤器,所以存在 1 分钟粒度的指标。

```bash
aws cloudwatch get-metric-statistics 
  --namespace AWS/S3 
  --metric-name 5xxErrors 
  --dimensions Name=BucketName,Value=media-uploads-prod Name=FilterId,Value=EntireBucket 
  --start-time 2026-01-14T01:30:00Z 
  --end-time 2026-01-14T03:30:00Z 
  --period 60 
  --statistics Sum 
  --region us-east-1


`5xxErrors` 从 0 升至每分钟 1,840,从 02:47 开始,到 03:06 停止攀升。没有该过滤器,CloudWatch 什么也不会给你——S3 请求指标是选择性启用的,并且按指标计费。在假定它们免费之前,请查看你所在区域的定价页面。

最后一块拼图来自 02:00 时段的服务器访问日志:

```bash
aws s3 cp s3://media-logs-prod/s3/2026-01-14-02-00-00-0000/ . --recursive --quiet
zcat *.log | awk '{print $7}' | sort | uniq -c | sort -rn | head -5



  48921 REST.PUT.OBJECT
  11044 REST.COPY.OBJECT_GET
   8802 REST.GET.OBJECT
    331 REST.HEAD.OBJECT


一小时内 11,044 次 COPY 操作,发生在同一前缀上,来自一条将超过 30 天的对象转换为 Standard-IA 的生命周期规则。该规则已运行八个月,从未造成问题,因为 600 PUT/s 加 200 COPY/s 远未接近上限。在营销推广期间加上 2,800 PUT/s,共享的每前缀预算就耗尽了。

这就是惨痛教训:限流并非由单一工作负载造成,而是由两个互不知晓的工作负载共同造成。任何单前缀设计都会静默累积这类问题。

## 修复方案:日期分片加哈希分片

我们无法以低成本重命名 3,100 万个现有对象——S3 没有重命名操作,只能复制加删除,每个对象大约需要一对请求,而且在此期间我们要为存储支付两次费用。所以我们把历史数据留在原处。旧前缀上的读取约为 400 GET/s,远低于 5,500/s,因此读路径从未有问题。

新写入通过上传服务中的键构建器完成:

```python
import hashlib
from datetime import datetime, timezone

def build_key(asset_id: str, ext: str, shards: int = 16, when: datetime | None = None) -> str:
    now = when or datetime.now(timezone.utc)
    shard = int(hashlib.md5(asset_id.encode()).hexdigest()[:8], 16) % shards
    return f"uploads/{now:%Y/%m/%d/%H}/s{shard:02d}/{asset_id}.{ext}"


生成的键:`uploads/2026/01/14/03/s07/9f2c1a7e.jpg`。按当前流量,此布局下的计数:每个小时分片约 11,000 个键,每天 180,000 个。这是不会发生冲突的数量级。

重试配置与键布局同样重要。默认的 `legacy` 重试模式按固定曲线退避,让每个 worker 几乎同步重试——这是一场自己造成的惊群:

```python
from botocore.config import Config

cfg = Config(
    retries={"max_attempts": 10, "mode": "adaptive"},
    max_pool_connections=50,
    connect_timeout=3,
    read_timeout=10,
)


生命周期规则则完全移出了热前缀。新规则作用于 `archive/`,转换窗口设为 45 天,并有单独的 `ExpiredObjectDeleteMarker` 清理。生命周期规则是基于前缀过滤器评估的,因此一个指向 `uploads/`、另一个指向 `archive/` 是两条规则,而不是一条——这一点值得记下来。

## 弯路:三件没有帮助的事

在访问日志给出答案之前,我们在这上面花了大约 90 分钟。

**在存储桶前面加 CloudFront。** 对本次事件毫无用处。CloudFront 吸收读流量;我们的故障完全在写路径上。几周后它确实改善了欧洲用户的 `GET` 延迟,但那是另一个项目。

**只增加 `max_attempts` 而不改变重试模式。** 我们在 legacy 模式下从 3 次尝试增加到 10 次,错误率反而在约四分钟内*上升*了,因为全部 800 个 worker 都在按相同时间表重试。真正让它平静下来的是 `adaptive` 模式加抖动。如果你只改一个设置,改 `mode`。

**完全关闭生命周期规则。** 这确实有效,也正是我们差点止步于此的原因。该规则在做真实的成本优化——对冷照片应用 Standard-IA——当晚禁用它只是把 COPY 突发推迟到第二天。正确的修复是将其作用域改到不同前缀,而不是杀掉它。

这三件事的共同模式:我们一直在处理症状(错误),而不是共享资源(一个前缀的请求预算)。

## 通用操作手册,以及何时不该分片

下次存储桶开始抛出 `SlowDown` 时,这是我执行的顺序。

1. 确认是限流而非认证问题:`aws s3api put-object --bucket <b> --key healthcheck/probe.txt --body /dev/null`。成功意味着是速率问题,不是策略问题。
2. 检查命名空间形态:`aws s3api list-objects-v2 --bucket <b> --delimiter '/' --max-keys 100 --query 'CommonPrefixes[].Prefix'`。只有一个条目或没有条目意味着是扁平的。
3. 如果存在请求指标过滤器,以 1 分钟粒度拉取 `5xxErrors` 和 `PutRequests`。如果没有,这就是你的首要预防任务。
4. 从峰值小时的服务器访问日志中按操作类型计数——对第 7 个字段执行 `awk '{print $7}'`。COPY 和 PUT 共享同一预算;隐藏的工作负载就是在这里暴露的。
5. 只有到这时才更改键布局。向已经出问题的存储桶中分片是可以的;在不知道负载来源之前就分片则不行。

| 布局 | 每前缀键数 | 热点风险 | 列举易用性 | 迁移成本 |
|---|---|---|---|---|
| 扁平 `uploads/<uuid>` | 3,100 万 | 超过约 3,500 PUT/s 后高 | 差——`ls` 返回不了有用内容 | 无(当前) |
| 仅日期 `uploads/2026/01/14/` | 约 18 万/天 | 中——每小时突发仍会冲突 | 好 | 仅新写入 |
| 日期 + 哈希 `.../03/s07/` | 约 1.1 万/小时 | 低 | 好,分片对人员不可见 | 仅新写入 |
| 随机首字符 `uploads/7/...` | 约 12 万/字符 | 低 | 差——破坏任何自然顺序 | 仅新写入 |

### 何时完全不应分片前缀

如果你将前缀用作 Athena、Spectrum 或分区投影的 Hive 风格分区,就不要添加哈希分片。`s3://bucket/events/year=2026/month=01/` 是分区布局,中间插入 `s07` 段会破坏每个读取它的工具的 `LOCATION` 路径。同样:在持续低于约 1,000 PUT/s 时,分片不会带来任何好处,却会牺牲可浏览性——凌晨 3 点运行 `aws s3 ls` 的支持工程师会在意这一点。而且如果你的工作负载是按时间顺序读取(日志回放、重放一天的事件),请保留时间戳优先的布局;它远比你可能永远用不到的分片余量更有价值。

## 预防:告警、Storage Lens 和命名规则

我们第一天就该有的告警:

```bash
aws cloudwatch put-metric-alarm 
  --alarm-name s3-media-uploads-5xx 
  --namespace AWS/S3 
  --metric-name 5xxErrors 
  --dimensions Name=BucketName,Value=media-uploads-prod Name=FilterId,Value=EntireBucket 
  --statistic Sum --period 60 --evaluation-periods 2 
  --threshold 10 --comparison-operator GreaterThanThreshold 
  --alarm-actions arn:aws:sns:us-east-1:111122223333:ops-pager 
  --region us-east-1


连续两分钟超过 10 个错误,足以在客户端察觉之前捕获爬升。如果你需要在不启用所有访问日志的情况下,在上百个存储桶中找出热前缀,Storage Lens 高级指标可提供前缀级细分——这会产生额外费用,因此请限定在重要的账户上。

命名规则是最便宜的控制手段:生产存储桶不接受不匹配 `^<domain>/d{4}/d{2}/d{2}/d{2}/sd{2}/` 的键。在共享上传辅助函数中强制执行,而不是在代码审查中——人们会忘记。我们通过 awsgood.com 的托管服务对少量存储桶运行这组告警和 Storage Lens 审查,主要是因为当没有紧急问题时,季度检查是最先被搁置的事。

从请求指标过滤器开始。启用只需 30 秒,而它决定了诊断是 40 分钟还是三个小时。

## 常见问题

**S3 是否仍然强制每前缀请求速率?**

AWS 文档记录的每前缀上限为每秒 3,500 次 PUT/COPY/POST/DELETE 和 5,500 次 GET/HEAD,虽然 S3 在吸收突发方面已大幅改善,但接近这些数字的持续负载加上后台作业仍会产生 `503 SlowDown`。把这些数字视为所有写入方共享的预算,而不是可以试探的硬墙。

**是否应该对每个新存储桶都做哈希分片?**

不应该。当持续写入接近每秒四位数,或当后台进程(生命周期、复制、批处理重处理)与实时流量共享前缀时才分片。低于此,`yyyy/mm/dd` 布局可免费为你提供生命周期定位和人类可读的列举。

## 来源

- [最佳实践设计模式:优化 Amazon S3 性能](https://docs.aws.amazon.com/AmazonS3/latest/userguide/optimizing-performance.html)
- [Amazon S3 错误响应 — SlowDown](https://docs.aws.amazon.com/AmazonS3/latest/API/ErrorResponses.html)
- [管理存储生命周期](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)
-

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注