[Open Source] #139 - Immich Drop Uploader: Hệ thống trung chuyển ảnh/video cho Immich với kiến trúc Chunked Proxy, WebSockets và cơ chế chống trùng lặp SHA-1
Việc thu thập ảnh và video từ nhiều người (bạn bè, khách hàng) trong một sự kiện thường gặp rào cản lớn: Nếu dùng Google Photos/Dropbox, bạn phải chia sẻ link có rủi ro bảo mật hoặc bắt họ tạo tài khoản. Immich Drop Uploader giải quyết bài toán này bằng cách cung cấp một giao diện "Kéo & Thả" đơn giản, cho phép người dùng ẩn danh tải lên trực tiếp vào server Immich của bạn thông qua các đường link mời (invite links) có kiểm soát.
Dưới góc độ kỹ thuật, dự án này là một bài học mẫu mực về việc xây dựng một API Proxy hiệu năng cao bằng FastAPI, kết hợp với kỹ thuật Chunked Upload để xử lý các tệp tin media dung lượng lớn.
Github: https://github.com/simon987/immich-drop-uploader
🛠️ 1. Nền tảng công nghệ: FastAPI và Sức mạnh của Asynchronous Python
Dự án chọn một ngăn xếp công nghệ tập trung vào tốc độ xử lý I/O và tính gọn nhẹ:
- Backend Core (FastAPI & Python 3.11): Tận dụng cơ chế
async/awaitđể xử lý hàng loạt luồng tải lên song song mà không gây nghẽn mạch. FastAPI cũng đóng vai trò là một lớp bảo mật, che giấu hoàn toàn API Key của server Immich gốc. - State Management (SQLite): Sử dụng SQLite (
state.db) để lưu trữ dấu vân tay kỹ thuật số (SHA-1 hash) của các tệp tin. Điều này cho phép hệ thống kiểm tra trùng lặp cực nhanh ngay tại lớp trung chuyển trước khi gửi dữ liệu đi xa hơn. - Real-time Communication (WebSockets): Thay vì sử dụng cơ chế Polling (hỏi - đáp liên tục), hệ thống sử dụng WebSockets để đẩy trực tiếp trạng thái và tiến độ (%) tải lên từ server về trình duyệt người dùng.
- Frontend (Vanilla JS & Tailwind): Loại bỏ sự cồng kềnh của các framework như React/Vue để đạt tốc độ tải trang tức thì, hỗ trợ hoàn hảo chế độ Dark Mode và giao diện Responsive cho thiết bị di động.
🏗️ 2. Trụ cột kiến trúc: Kiến trúc Proxy và Xử lý tệp tin phân đoạn
Kiến trúc của Immich Drop Uploader được thiết kế theo tư duy "Cổng bảo vệ" (Gateway):
- Chunked Upload Strategy: Để vượt qua giới hạn dung lượng tải lên của các Proxy ngược (như Cloudflare hay Nginx vốn thường giới hạn 100MB), hệ thống tự động chia nhỏ tệp tin thành các mảnh (chunks) nhỏ ở phía Client và lắp ghép lại tại Server.
- Encapsulated Invites: Hệ thống tạo ra các Token mời độc lập. Mỗi Token có thể đi kèm với: mật khẩu truy cập riêng, giới hạn số lần tải, và ngày hết hạn. Điều này đảm bảo quyền truy cập chỉ được cấp tạm thời và đúng mục đích.
- Two-tier Deduplication:
- Lớp 1 (Local): Kiểm tra SHA-1 hash trong SQLite nội bộ.
- Lớp 2 (Remote): Truy vấn Immich API để xác nhận tệp tin đã tồn tại trong thư viện chính chưa.
🔄 3. Workflow: Hành trình của một tệp tin từ Guest đến Immich Library (Sequence Diagram)
Sơ đồ mô tả quy trình xử lý dữ liệu qua lớp trung gian bảo mật:
⚡ 4. Các kỹ thuật "Pro-level" trong mã nguồn
- Atomic Session Management: Dự án sử dụng hệ thống quản lý phiên (Session) dựa trên Token trong URL. Khi một "link dùng một lần" (one-time link) hoàn tất tác vụ tải lên cuối cùng, backend sẽ tự động vô hiệu hóa Token ngay lập tức để ngăn chặn việc tái sử dụng.
- Streaming Proxying: Thay vì tải toàn bộ file 1GB vào RAM rồi mới gửi sang Immich, FastAPI có thể được cấu hình để "stream" dữ liệu nhận được trực tiếp sang Immich API, giúp tối ưu hóa bộ nhớ cho các server cấu hình thấp.
- Automatic Album Provisioning: Một kỹ thuật tinh tế là khả năng tự động tạo Album. Nếu người quản trị chỉ định một tên Album mới trong Link mời, hệ thống sẽ tự động gọi API khởi tạo Album trên Immich nếu nó chưa tồn tại.
- Mobile UI Optimization: Frontend sử dụng các CSS biến môi trường (
safe-area-inset-bottom) để đảm bảo các nút bấm tải lên không bị che bởi thanh điều hướng trên iPhone/Android.
⚖️ 5. So sánh chiến lược
| Tiêu chí | Immich Drop Uploader | Immich Share Link (Gốc) | Nextcloud Drop |
|---|---|---|---|
| Quyền tải lên | Người dùng ẩn danh | Thường yêu cầu quyền User | Ẩn danh |
| Bảo mật API Key | Tuyệt đối (Server-side) | N/A | N/A |
| Xử lý tệp lớn | Chunked (Rất ổn định) | Cơ bản | Tùy cấu hình PHP |
| Chống trùng lặp | Có (SHA-1 Cache) | Có (Immich logic) | Thường không có |
| Tùy biến Album | Tự động hoàn toàn | Thủ công | Thủ công |
✅ Kết luận: Tại sao Immich Drop Uploader là một công cụ phải có?
Dự án này là một ví dụ điển hình về việc giải quyết một "điểm đau" (pain point) cụ thể trong trải nghiệm người dùng bằng một giải pháp kỹ thuật tinh gọn. Bằng cách tách biệt luồng xác thực người dùng ẩn danh khỏi server Immich chính, nó mang lại sự an toàn và tiện lợi tối đa cho các quản trị viên lưu trữ ảnh cá nhân.
Đối với các kỹ sư Backend, nghiên cứu dự án này giúp bạn hiểu sâu về:
- Kỹ thuật xây dựng API Proxy an toàn.
- Cách triển khai Chunked Upload và quản lý trạng thái tệp tin.
- Tư duy sử dụng WebSockets để tăng trải nghiệm người dùng trong các tác vụ thời gian dài.
All rights reserved
