PyPI khắc phục sự cố lỗi lưu trữ tệp: Hai tuần đầy biến động và bài học cho hạ tầng

Trong khoảng hai tuần của tháng 8/2026, người dùng PyPI đã phải đối mặt với các lỗi 502 và 503 không liên tục khi tải tệp từ files.pythonhosted.org, gây gián đoạn quá trình cài đặt gói tin. Nguyên nhân xuất phát từ hai vấn đề riêng biệt: một lỗi cấu hình trong quá trình triển khai canary của Fastly và một loạt các lỗi tiềm ẩn trong chính cấu hình của PyPI. Sự cố này đã được khắc phục hoàn toàn từ ngày 28/8, nhưng để lại nhiều bài học quý giá về quản lý hạ tầng CDN và khả năng phục hồi.

Bối cảnh hệ thống lưu trữ tệp của PyPI

Khi người dùng chạy pip install, yêu cầu sẽ được gửi đến files.pythonhosted.org - một dịch vụ CDN của Fastly đặt trước ba nguồn dữ liệu (backends). Quy trình hoạt động như sau:

• Amazon S3: Là bản sao dữ liệu chính, bền vững, được ghi đầu tiên khi tải tệp lên.
• Backblaze B2: Được đồng bộ tự động từ S3 nhờ thỏa thuận miễn phí băng thông giữa Fastly và Backblaze, giúp giảm chi phí phục vụ tệp.
• Conveyor: Xử lý các yêu cầu không phải là tệp gói, như URL có thể dự đoán và các chuyển hướng cũ.

Trên luồng đọc (khi người dùng cài đặt), Fastly sẽ ưu tiên thử B2 trước, nếu B2 không phản hồi hoặc trả lỗi, hệ thống sẽ chuyển sang S3 làm phương án dự phòng. Các tệp sau khi được lưu vào bộ nhớ đệm sẽ không bao giờ thay đổi và có thời gian sống lên đến 11,5 năm.

Diễn biến sự cố

• Ngày 15/8: Fastly xác nhận vấn đề bắt đầu tại một nút cache ở khu vực Seattle.
• Ngày 17/8: Hai báo cáo đầu tiên về lỗi 502 liên tục được mở.
• Ngày 18/8: Một báo cáo chi tiết ghi nhận 88 lỗi 502 trong 6 giờ, ảnh hưởng đến 32 gói không liên quan. Đáng chú ý, các yêu cầu range nhỏ (như đọc metadata PEP 658) cũng bị ảnh hưởng.
• Ngày 19/8: Vấn đề được cô lập tại một nút cache cụ thể (cache-pae2080020) với 100% yêu cầu bị lỗi 502 trong hơn 19 giờ. Fastly đã gỡ bỏ định tuyến gây ảnh hưởng.
• Ngày 20/8: Fastly quan sát thấy sự phục hồi tại điểm ảnh hưởng.
• Ngày 21-24/8: Các bản vá liên tục được áp dụng để xử lý các lỗi phát sinh như yêu cầu range không hợp lệ từ các trình tải xuống song song.
• Ngày 28/8: Fastly vá lỗi cấu hình canary và loại PyPI khỏi chương trình thử nghiệm. Các sửa đổi cuối cùng hoàn tất, dịch vụ trở lại bình thường.

Nguyên nhân sâu xa

Lỗi từ quá trình triển khai canary của Fastly: PyPI đã tham gia chương trình canary của Fastly nhiều năm, giúp họ kiểm thử các thay đổi trước khi phát hành rộng rãi. Tuy nhiên, một lần rollback một phần đã khiến cấu hình cache tại một điểm POP ở Seattle bị khôi phục trong khi cấu hình định tuyến phía trước thì không, dẫn đến lỗi 502. Fastly đã cam kết gỡ toàn bộ lưu lượng PSF khỏi chương trình canary cho đến khi có các kiểm soát và thông báo rõ ràng hơn.

Lỗi từ cấu hình của chính PyPI: Đội ngũ kỹ thuật phát hiện ba lỗi quan trọng trong cấu hình Fastly của mình:

• Lỗi dự phòng không hoạt động: Khi B2 không phản hồi do timeout hoặc lỗi kết nối, Fastly tự tạo mã lỗi 503 và bỏ qua hoàn toàn cơ chế chuyển sang S3. Cần có bản vá để xử lý trường hợp B2 không phản hồi hoàn toàn.

• Lỗi xử lý range request: Tính năng segmented caching không hỗ trợ đầy đủ cú pháp range của HTTP, gây lỗi 501 cho các yêu cầu đọc cuối tệp (suffix range) - một kỹ thuật mà nhiều trình cài đặt sử dụng để đọc metadata mà không cần tải toàn bộ tệp.

• Lỗi thứ tự khởi tạo URL: Việc kiểm tra miễn trừ segmented caching chạy trước khi chuẩn hóa URL khiến các yêu cầu .metadata có kèm query string không được nhận diện đúng, dẫn đến lỗi 501 bị lưu vào cache và phục vụ cho mọi yêu cầu tiếp theo.

Bài học và khuyến nghị

Theo dữ liệu từ Datadog, mức lỗi 5xx nền tảng trước sự cố đã ở mức hàng nghìn đến hàng chục nghìn mỗi ngày, khiến việc phát hiện sự gia tăng bất thường trở nên khó khăn. Sau khi các bản vá được áp dụng, con số này giảm xuống còn hàng chục đến hàng trăm - thấp hơn 2-3 bậc so với trước đó, cho thấy nhiều lỗi tưởng chừng là "tiếng ồn" thực chất là do các lỗi này gây ra.

PyPI đang tuyển thêm kỹ sư hạ tầng để tăng cường khả năng phát hiện sớm và phòng ngừa sự cố. Đồng thời, khuyến nghị quan trọng dành cho cộng đồng là kích hoạt tính năng cache các gói phụ thuộc trong các hệ thống CI/CD (như GitHub Actions) để giảm tải cho hạ tầng PyPI và giảm rủi ro gián đoạn cho các quy trình tự động của chính họ.

Nếu bạn gặp sự cố tương tự trong tương lai, hãy báo cáo tại pypi/support kèm theo càng nhiều chi tiết càng tốt (đặc biệt là header x-served-by và timestamp) để đội ngũ kỹ thuật có thể xử lý nhanh chóng.

Biểu đồ lỗi 5xx theo ngày

Sự cố lần này là minh chứng rõ ràng cho thấy ngay cả những hạ tầng được quản lý tốt nhất cũng có thể gặp sự cố từ các yếu tố bên ngoài (như lỗi từ nhà cung cấp CDN) và các lỗi tiềm ẩn lâu ngày. Việc theo dõi sát sao, phản hồi nhanh từ cộng đồng và quá trình điều tra kỹ lưỡng đã giúp PyPI vượt qua thử thách này một cách thành công.

Sơ đồ kiến trúc lưu trữ tệp của Fastly