Laravel SQS 扩展

介绍

Laravel SQS 扩展是一个 Laravel 队列驱动，旨在绕过 AWS SQS 负载大小限制。这个队列驱动将自动将大型负载序列化到磁盘（通常是 S3），并在运行时反序列化。该包的灵感来自于 https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-s3-messages.html。

从简单 SQS 扩展客户端迁移

从项目中移除 simplesoftwareio/simple-sqs-extended-client 包。
安装 defectivecode/laravel-sqs-extended 包。

旧的配置与新包向后兼容。唯一的变化是包名称。

安装

首先创建一个存储所有大型 SQS 负载的桶。

我们强烈建议您在存储 SQS 负载时使用私有桶。负载可能包含敏感信息，并且永远不应公开共享。

运行 composer require defectivecode/laravel-sqs-extended 来安装队列驱动。
然后，在 queue.php 文件中添加以下默认队列设置。

Laravel Vapor 用户必须将连接名称设置为 sqs。在 Vapor Core 中寻找 sqs 连接，如果您使用不同的连接名称，此库将无法按预期工作。

/*
|--------------------------------------------------------------------------
| SQS 磁盘队列配置
|--------------------------------------------------------------------------
|
| 在这里您可以配置 SQS 磁盘队列驱动。它共享内置 Laravel SQS 队列驱动的所有相同
| 配置选项。唯一添加的选项是 `disk_options`，在下面进行说明。
|
| always_store: 确定是否应在磁盘上存储所有负载，即使队列的大小限制也是如此。
| cleanup:      确定处理完作业后是否应从磁盘上删除负载文件。保留文件在调试时可以用于随后重复队列作业。
| disk:         保存 SQS 负载的磁盘。此磁盘应在您的 Laravel filesystems.php 配置文件中进行配置。
| max_size:     可选。将离线阈值固定为一定的字节数。当省略时，阈值从
|                 队列本身读取。请参阅下面的“负载大小阈值”。
| prefix        存储负载的前缀（文件夹）。如果您与其他 SQS 队列共享磁盘，这一点非常有用。
|                 使用前缀允许 queue:clear 命令在销毁与其他基于 SQS 磁盘的队列共享同一磁盘的文件时分开处理。
|
*/
'sqs' => [
    'driver' => 'sqs-disk',
    'key' => env('AWS_ACCESS_KEY_ID'),
    'secret' => env('AWS_SECRET_ACCESS_KEY'),
    'prefix' => env('SQS_PREFIX', 'https://sqs.us-east-1.amazonaws.com/your-account-id'),
    'queue' => env('SQS_QUEUE', 'default'),
    'suffix' => env('SQS_SUFFIX'),
    'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
    'after_commit' => false,
    'disk_options' => [
        'always_store' => false,
        'cleanup' => false,
        'disk' => env('SQS_DISK'),
        'prefix' => 'bucket-prefix',
    ],
],

启动您的队列，放心利用 SQS 的负载限制 🥳

负载大小阈值

AWS 在 2025 年 8 月将最大 SQS 负载从 256 KiB 提高到 1 MiB，但 MaximumMessageSize 是每个队列的属性 — 在该更改之前创建的队列将保持旧的 262144 字节值，直到您将其提高。该包不会假设任何限制，而是从队列读取属性，仅卸载那些确实无法容纳的内容。

阈值按照以下顺序解析，并且第一个匹配的胜出。当负载的长度大于或等于解析的阈值时，它将存储在磁盘上。

条件	阈值	读取队列属性
`always_store` 为 `true`	每个负载都存储	否
设置了 `max_size`	配置的值	否
队列报告 `262144`（2025 年前的默认值）	250000	是
队列报告 `1048576`（提高到最大值）	1036432	是
无法读取属性	250000	尝试一次

预留的 12144 字节的余量覆盖每个消息的开销，并且大小被设置为，当队列保持在 262144 字节的默认值时，解析为早期版本的该包所使用的 250000 字节的阈值。升级不会更改行为，直到您提高队列自己的限制。

权限

读取属性需要 sqs:GetQueueAttributes。结果在每个队列的内存中缓存，因此这会消耗每个队列一次调用的成本，而不是每个作业一次调用。

如果无法读取属性 — 由于狭窄的 IAM 策略，或不实现的 SQS 模拟器 — 驱动程序将回退到 250000 字节的阈值并继续调度。如果您希望跳过查找而不授予权限，请设置 max_size。

提高队列的限制

aws sqs set-queue-attributes \
    --queue-url https://sqs.us-east-1.amazonaws.com/your-account-id/your-queue \
    --attributes MaximumMessageSize=1048576

注意，SQS 按 64KB 的块计量使用量，因此单个 1 MiB 消息的收费为 16 个请求。在磁盘上存储大型负载通常仍然是更具成本效益的路径。

支持指南

感谢您选择我们的开源包！请花一点时间查看这些支持指南。它们将帮助您充分利用我们的项目。

社区驱动支持

我们的开源项目得益于我们出色的社区。如果您有问题或需要帮助，StackOverflow 和其他在线资源是您最好的选择。

错误和功能优先级

管理一个开源项目的现实是我们不能立即解决每一个报告的错误或功能请求。我们按以下顺序优先处理问题：

1. 影响我们付费产品的错误

影响我们付费产品的错误将始终是我们的首要任务。在某些情况下，我们可能只会处理直接影响我们的错误。

2. 社区拉取请求

如果您发现了一个错误并且有解决方案，请提交拉取请求。在影响我们产品的问题之后，我们给这些社区驱动的修复分配下一个最高优先级。经过审查和批准后，我们将合并您的解决方案并给予贡献者信用。

3. 财务支持

对于不属于上述类别的问题，您可以选择为其解决提供资金支持。每个开放问题都与一个订单表相关联，您可以在上面提供财务支持。我们根据提供的资金金额优先处理这些问题。

社区贡献

开源的蓬勃发展依赖于社区的积极参与。即使您不是在修复错误，也可以通过代码改进、文档更新、教程或在社区频道帮助他人来贡献。我们非常鼓励大家作为一个社区共同支持开源工作。

重申一下，DefectiveCode 将根据错误对我们付费产品的影响、社区拉取请求以及收到的财务支持来优先处理问题.

许可 - MIT 许可

特此免费授权任何获得此软件及相关文档文件（“软件”）副本的人，允许在软件中自由处理，包括不限于使用、复制、修改、合并、发布、分发、再授权和/或销售软件副本的权利，并允许被提供软件的人这样做，前提是满足以下条件：

软件按“原样”提供，不提供任何种类的保证，明示或暗示，包括但不限于对适销性、特定用途适用性和不侵权的保证。在任何情况下，作者或版权持有者均不对因软件或软件的使用或其他交易而引起的任何索赔、损害或其他责任负责，无论是在合同诉讼、侵权或其他方面。

🔗Laravel SQS 扩展

🔗介绍

🔗从简单 SQS 扩展客户端迁移

🔗安装

🔗负载大小阈值

权限