Đi tới nội dung chính
System Design Lab
Microservice Patterns

Valet Key

Cấp cho client một token ngắn hạn, phạm vi hẹp để đọc hoặc ghi đúng một tài nguyên ngay trên storage, để các lượt truyền file lớn đi vòng qua server của bạn mà không phải giao thông tin đăng nhập thật.

Cơ bản 4 phút đọc· Cập nhật 2026-11-18

Sau bài này bạn sẽ

  • Giải thích vì sao chuyển tiếp upload và download qua API lãng phí năng lực.
  • Cấp signed URL hoặc SAS token có phạm vi và có hạn.
  • Giới hạn những gì valet key làm được: đối tượng, thao tác, kích thước, thời gian.
  • Kiểm tra những gì tới nơi sau một lượt upload trực tiếp.

Tổng quan

Chìa khoá valet cho nhân viên giữ xe lái xe của bạn, nhưng không mở được cốp hay hộc đồ, và được trả lại khi bạn rời đi. Bạn đâu có đưa họ chìa khoá nhà.

Upload hay download file lớn qua API chiếm worker, bộ nhớ và băng thông mà chẳng được gì — API chỉ chép lại từng byte. Với valet key, API kiểm tra người dùng có được làm việc đó không rồi trả về một signed URL (presigned URL của S3, SAS token của Azure, signed URL của GCS) chỉ cho phép đúng một thao tác trên một đối tượng trong vài phút. Sau đó client nói chuyện thẳng với storage.

Chạy thử

Người tạo nội dung upload video 20 MB trong khi người mua đang xem hàng. So sánh ô Worker API đang bận và Request xem hàng thất bại khi upload đi qua API (A) và khi API chỉ ký URL (B).

Đang tải mô phỏng…

Cấp URL upload có phạm vi

Presigned PUT của S3: một key, một content type, năm phút
@PostMapping("/videos/upload-url")
UploadUrl uploadUrl(@AuthenticationPrincipal User user, @RequestBody @Valid UploadRequest req) {
    if (req.sizeBytes() > 500_000_000) throw new PayloadTooLargeException();
    String key = "uploads/" + user.id() + "/" + UUID.randomUUID() + ".mp4";      // server tự chọn tên
    PutObjectRequest put = PutObjectRequest.builder().bucket("videos").key(key)
        .contentType("video/mp4").contentLength(req.sizeBytes()).build();
    PresignedPutObjectRequest signed = presigner.presignPutObject(b -> b.signatureDuration(Duration.ofMinutes(5)).putObjectRequest(put));
    videos.registerPending(user.id(), key);
    return new UploadUrl(signed.url().toString(), key);
}
  • Phạm vi thật hẹp: một đối tượng (tên do server sinh), một thao tác, bắt buộc content type và độ dài.
  • Thời hạn ngắn: vài phút, không phải vài ngày; ai thấy URL cũng dùng được cho tới khi nó hết hạn.
  • Kiểm tra sau đó: event upload kích hoạt bước quét và xác minh trước khi file được dùng.
  • Download cũng vậy: signed GET URL (hoặc signed URL của CDN) phục vụ file riêng tư mà không cần chuyển tiếp.

Đánh đổi

ĐượcMất
Khả năng scaleTruyền dữ liệu lớn chuyển sang storage vốn sinh ra để làm việc đó; API vẫn nhỏ gọn.Client phải làm hai bước (lấy URL, rồi upload).
Bảo mậtQuyền tối thiểu, có thời hạn, không để thông tin đăng nhập dài hạn ở client.URL bị lộ vẫn dùng được tới khi hết hạn; bước kiểm tra dời ra sau upload.
Kiểm soátStorage ép kích thước, loại file và thời hạn.Tiến độ, retry và upload tiếp tục được phải xử lý ở client.

Lưu ý khi chạy production

  • Cấu hình CORS cho bucket khi upload từ trình duyệt, chỉ cho phép origin của bạn.
  • Dùng multipart / resumable upload cho file lớn và mạng di động.
  • Cho các lượt upload đang chờ bị bỏ dở tự hết hạn bằng luật vòng đời.
  • Kết hợp với claim check khi đối tượng vừa upload tiếp tục đi qua hệ thống messaging.

Đọc thêm

Bài liên quan