Laravel SQS Extended
Hướng Dẫn Hỗ Trợ
- Hỗ Trợ Được Điều Hành Bởi Cộng Đồng
- Lỗi và Ưu Tiên Tính Năng
Giấy phép - Giấy phép MIT

Laravel SQS Extended

Giới thiệu

Laravel SQS Extended là một driver hàng đợi Laravel được thiết kế để làm việc xung quanh giới hạn kích thước payload của AWS SQS. Driver hàng đợi này sẽ tự động tuần tự hóa các payload lớn vào một đĩa (thường là S3) và sau đó giải tuần tự chúng khi chạy. Gói này lấy cảm hứng từ https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-s3-messages.html.

Di chuyển từ Simple SQS Extended Client

Xóa gói simplesoftwareio/simple-sqs-extended-client khỏi dự án của bạn.
Cài đặt gói defectivecode/laravel-sqs-extended.

Cấu hình cũ tương thích ngược với gói mới. Thay đổi duy nhất là tên gói.

Cài đặt

Đầu tiên, tạo một bucket sẽ chứa tất cả các payload SQS lớn của bạn.

Chúng tôi rất khuyến nghị bạn sử dụng một bucket riêng tư khi lưu trữ các payload SQS. Các payload có thể chứa thông tin nhạy cảm và không bao giờ nên được chia sẻ công khai.

Chạy composer require defectivecode/laravel-sqs-extended để cài đặt driver hàng đợi.
Sau đó, thêm các cài đặt hàng đợi mặc định sau vào tệp queue.php của bạn.

Người dùng Laravel Vapor phải đặt tên kết nối thành sqs. Kết nối sqs được tìm kiếm trong Vapor Core và thư viện này sẽ không hoạt động như mong đợi nếu bạn sử dụng tên kết nối khác.

/*
|--------------------------------------------------------------------------
| Cấu hình hàng đợi SQS Disk
|--------------------------------------------------------------------------
|
| Tại đây bạn có thể cấu hình driver hàng đợi SQS disk. Nó chia sẻ tất cả các
| tùy chọn cấu hình từ driver hàng đợi SQS tích hợp sẵn của Laravel. Tùy chọn duy nhất được thêm vào
| là `disk_options` sẽ được giải thích bên dưới.
|
| always_store: Xác định xem tất cả các payload có nên được lưu trữ trên đĩa bất kể giới hạn kích thước hàng đợi hay không.
| cleanup:      Xác định xem các tệp payload có nên bị xóa khỏi đĩa sau khi công việc được xử lý hay không. Để lại
|                 các tệp bên cạnh có thể hữu ích để phát lại các công việc hàng đợi sau này vì lý do gỡ lỗi.
| disk:         Đĩa để lưu SQS payload. Đĩa này nên được cấu hình trong tệp cấu hình filesystems.php của Laravel.
| max_size:     Tùy chọn. Ghi lại ngưỡng chuyển tải thành một số byte cố định. Khi không có, ngưỡng sẽ được đọc từ
|                 chính hàng đợi. Xem "Ngưỡng kích thước payload" bên dưới.
| prefix        Tiền tố (thư mục) để lưu trữ các payload. Điều này hữu ích nếu bạn đang chia sẻ một đĩa với các hàng đợi SQS khác.
|                 Sử dụng tiền tố cho phép lệnh queue:clear xóa các tệp riêng biệt khỏi các hàng đợi được hỗ trợ bởi sqs-disk
|                 chia sẻ cùng một đĩa.
|
*/
'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',
    ],
],

Khởi động các hàng đợi của bạn và thu lợi mà không cần phải lo lắng về giới hạn payload của SQS 🥳

Ngưỡng kích thước payload

AWS đã nâng giới hạn tối đa của payload SQS từ 256 KiB lên 1 MiB vào tháng 8 năm 2025, nhưng MaximumMessageSize là một thuộc tính per-hàng đợi — các hàng đợi được tạo ra trước thay đổi đó sẽ giữ giá trị cũ 262144 byte cho đến khi bạn nâng nó lên. Thay vì giả định bất kỳ giới hạn nào, gói này đọc thuộc tính từ hàng đợi và chỉ tải xuống những gì thực sự không vừa.

Ngưỡng được giải quyết theo thứ tự sau, và phép so sánh đầu tiên thắng. Một payload được lưu trên đĩa khi chiều dài của nó lớn hơn hoặc bằng ngưỡng đã được giải quyết.

Điều kiện	Ngưỡng	Đọc thuộc tính hàng đợi
`always_store` là `true`	Mỗi payload được lưu	Không
`max_size` được thiết lập	Giá trị cấu hình	Không
Hàng đợi báo cáo `262144` (giá trị mặc định trước 2025)	250000	Có
Hàng đợi báo cáo `1048576` (nâng lên tối đa)	1036432	Có
Không thể đọc thuộc tính	250000	Đã thử một lần

Không gian dự trữ 12144 byte bao gồm overhead trên mỗi thông điệp và kích thước này để một hàng đợi để lại ở giá trị mặc định 262144 byte giải quyết thành ngưỡng 250000 byte được sử dụng bởi các phiên bản trước của gói này. Việc nâng cấp không thay đổi hành vi cho đến khi bạn tăng giới hạn của chính hàng đợi.

Quyền

Đọc thuộc tính yêu cầu sqs:GetQueueAttributes. Kết quả được lưu trong bộ nhớ cho mỗi hàng đợi, vì vậy điều này tốn một cuộc gọi cho mỗi hàng đợi trong suốt thời gian của quy trình thay vì một cuộc gọi cho mỗi công việc.

Nếu thuộc tính không thể được đọc - một chính sách IAM hẹp, hoặc một trình giả lập SQS không thực hiện điều đó - driver sẽ quay trở lại ngưỡng 250000 byte và tiếp tục phát. Đặt max_size để bỏ qua hoàn toàn việc tìm kiếm nếu bạn không muốn cấp quyền này.

Nâng giới hạn của hàng đợi

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

Lưu ý rằng SQS đo lường mức sử dụng theo các khối 64 KB, vì vậy một thông điệp 1 MiB duy nhất được tính là 16 yêu cầu. Việc lưu trữ các payload lớn trên một đĩa thường vẫn là con đường rẻ hơn.

Hướng Dẫn Hỗ Trợ

Cảm ơn bạn đã chọn gói mã nguồn mở của chúng tôi! Vui lòng dành chút thời gian để xem qua các hướng dẫn hỗ trợ này. Chúng sẽ giúp bạn tận dụng tối đa dự án của chúng tôi.

Hỗ Trợ Được Điều Hành Bởi Cộng Đồng

Dự án mã nguồn mở của chúng tôi được thúc đẩy bởi cộng đồng tuyệt vời của chúng tôi. Nếu bạn có câu hỏi hoặc cần trợ giúp, StackOverflow và các tài nguyên trực tuyến khác là lựa chọn tốt nhất của bạn.

Lỗi và Ưu Tiên Tính Năng

Thực tế khi quản lý một dự án mã nguồn mở có nghĩa là chúng tôi không thể giải quyết ngay lập tức mọi lỗi hoặc yêu cầu tính năng được báo cáo. Chúng tôi ưu tiên các vấn đề theo thứ tự sau:

1. Lỗi Ảnh Hưởng Đến Sản Phẩm Trả Phí Của Chúng Tôi

Các lỗi ảnh hưởng đến sản phẩm trả phí của chúng tôi luôn là ưu tiên hàng đầu. Trong một số trường hợp, chúng tôi có thể chỉ giải quyết các lỗi ảnh hưởng trực tiếp đến chúng tôi.

2. Yêu Cầu Kéo Của Cộng Đồng

Nếu bạn đã xác định một lỗi và có giải pháp, vui lòng gửi yêu cầu kéo. Sau các vấn đề ảnh hưởng đến sản phẩm của chúng tôi, chúng tôi dành ưu tiên cao nhất tiếp theo cho các sửa lỗi do cộng đồng thực hiện. Sau khi được xem xét và phê duyệt, chúng tôi sẽ hợp nhất giải pháp của bạn và ghi nhận đóng góp của bạn.

3. Hỗ Trợ Tài Chính

Đối với các vấn đề ngoài các danh mục đã nêu, bạn có thể chọn tài trợ cho việc giải quyết của chúng. Mỗi vấn đề mở đều liên kết với một mẫu đơn đặt hàng nơi bạn có thể đóng góp tài chính. Chúng tôi ưu tiên các vấn đề này dựa trên số tiền tài trợ được cung cấp.

Đóng Góp Của Cộng Đồng

Mã nguồn mở phát triển mạnh khi cộng đồng của nó hoạt động tích cực. Ngay cả khi bạn không sửa lỗi, hãy cân nhắc đóng góp thông qua cải tiến mã, cập nhật tài liệu, hướng dẫn, hoặc bằng cách hỗ trợ những người khác trong các kênh cộng đồng. Chúng tôi rất khuyến khích mọi người, với tư cách là một cộng đồng, giúp đỡ trong công việc mã nguồn mở.

Nhấn mạnh lại, DefectiveCode sẽ ưu tiên các lỗi dựa trên cách chúng ảnh hưởng đến các sản phẩm trả phí của chúng tôi, yêu cầu kéo của cộng đồng và sự hỗ trợ tài chính nhận được cho các vấn đề.

Giấy phép - Giấy phép MIT

Permission là được cấp miễn phí, cho bất kỳ người nào nhận được một bản sao của phần mềm này và các tài liệu liên quan (gọi là "Phần mềm"), được phép sử dụng Phần mềm mà không có hạn chế, bao gồm nhưng không giới hạn các quyền sử dụng, sao chép, chỉnh sửa, hợp nhất, công bố, phân phối, cấp phép lại, và/hoặc bán các bản sao của Phần mềm, và cho phép những người mà Phần mềm được cung cấp có thể làm như vậy, với điều kiện là:

Thông báo bản quyền ở trên và thông báo phép này sẽ được bao gồm trong tất cả các bản sao hoặc phần đáng kể của Phần mềm.

PHẦN MỀM ĐƯỢC CUNG CẤP "NHƯ THẾ", KHÔNG CÓ BẢO ĐẢM DƯỚI BẤT KỲ HÌNH THỨC NÀO, RÕ RÀNG HAY NGỤ Ý, BAO GỒM NHƯNG KHÔNG GIỚI HẠN ĐẾN CÁC BẢO ĐẢM VỀ THƯƠNG MẠI, PHÙ HỢP CHO MỘT MỤC ĐÍCH CỤ THỂ VÀ KHÔNG XÂM PHẠM. TRONG BẤT KỲ TRƯỜNG HỢP NÀO, CÁC TÁC GIẢ HOẶC CÁC CHỦ SỞ HỮU BẢN QUYỀN KHÔNG CHỊU TRÁCH NHIỆM VỀ BẤT KỲ KHIẾU NẠI, THIỆT HẠI HOẶC TRÁCH NHIỆM KHÁC, DÙ TRONG MỘT HÀNH ĐỘNG HỢP ĐỒNG, LỖI HOẶC CÁC HÌNH THỨC KHÁC, PHÁT SINH TỪ, RA HOẶC LIÊN QUAN ĐẾN PHẦN MỀM HOẶC VIỆC SỬ DỤNG HAY CÁC GIAO DỊCH KHÁC LIÊN QUAN ĐẾN PHẦN MỀM.

🔗Laravel SQS Extended

🔗Giới thiệu

🔗Di chuyển từ Simple SQS Extended Client

🔗Cài đặt

🔗Ngưỡng kích thước payload