[Open Source] #151 - Flame: Hệ thống Startpage tự lưu trữ với kiến trúc Config-Driven, kiến trúc tích hợp Docker/Kubernetes API và hệ thống Theme linh hoạt

Trong hệ sinh thái Homelab, việc ghi nhớ hàng chục địa chỉ IP và Port của các dịch vụ (Plex, Pi-hole, Home Assistant) là một thử thách. Flame ra đời như một giải pháp "Trang chủ thông minh" (Startpage), cho phép người dùng quản trị ứng dụng và dấu trang một cách tập trung. Điểm vượt trội của Flame không chỉ nằm ở giao diện tinh tế mà còn ở khả năng tự động phát hiện các ứng dụng đang chạy trong hạ tầng Docker hoặc Kubernetes để đưa lên màn hình chính mà không cần khai báo thủ công.

Dưới góc độ kỹ thuật, Flame là một minh chứng xuất sắc về việc ứng dụng Node.js/React, kiến trúc Stateless phối hợp với các tiến trình Background Jobs để đồng bộ dữ liệu thời tiết và hạ tầng.

Github: https://github.com/pawelmalak/flame

🛠️ 1. Nền tảng công nghệ: Gọn nhẹ và Bền bỉ

Flame chọn một ngăn xếp công nghệ tối ưu cho việc tự lưu trữ (self-hosting), giảm thiểu tối đa tài nguyên tiêu thụ:

• Backend Core (Node.js & Express): Đảm nhiệm vai trò điều phối API và phục vụ tài nguyên tĩnh. Sử dụng Sequelize ORM để quản trị cơ sở dữ liệu SQLite, giúp hệ thống hoạt động ổn định mà không cần cài đặt server Database cồng kềnh.
• Database Evolution (Umzug): Sử dụng Umzug để quản lý các bản vá (Migrations) tự động. Kỹ thuật này đảm bảo cấu trúc dữ liệu luôn nhất quán khi người dùng nâng cấp phiên bản Docker mới.
• Frontend (React & TypeScript): Xây dựng giao diện Single Page Application (SPA) mượt mà với tính an toàn kiểu dữ liệu cao. Sử dụng Redux-Thunk để quản lý các luồng dữ liệu phức tạp từ cấu hình hệ thống đến thông tin thời tiết.
• Real-time Layer (WebSockets): Sử dụng giao thức ws để đẩy trực tiếp các cập nhật trạng thái thời tiết từ server về trình duyệt mà không cần người dùng tải lại trang (Refresh).

🏗️ 2. Trụ cột kiến trúc: Config-Driven và Local-first Security

Kiến trúc của Flame được thiết kế quanh triết lý "Mọi thứ đều nằm trong tầm kiểm soát của GUI":

• Config-Driven Design: Thay vì sửa file .yaml hay .json thủ công, toàn bộ trải nghiệm từ màu sắc, bố cục đến danh sách ứng dụng đều được cấu hình qua giao diện web và lưu trữ bền vững vào SQLite.
• Infrastructure Autodiscovery: Đây là "vũ khí bí mật" của Flame.
  • Docker Integration: Gọi trực tiếp vào Docker Socket (/var/run/docker.sock) để đọc các Labels của container (vd: flame.name, flame.url), tự động đưa container thành một ứng dụng trên Dashboard.
  • Kubernetes Integration: Tương tác với K8s API để quét các tài nguyên Ingress, biến hạ tầng đám mây thành các lối tắt truy cập tức thì.
• Tiered Visibility: Mỗi ứng dụng hoặc bookmark hỗ trợ thuộc tính isPublic. Flame tích hợp JWT Middleware để phân cấp người xem: khách truy cập chỉ thấy mục công khai, trong khi quản trị viên sau khi đăng nhập mới có quyền xem các dịch vụ nhạy cảm và thay đổi cài đặt.

🔄 3. Workflow: Từ Khởi tạo đến Đồng bộ hóa dữ liệu (Sequence Diagram)

Sơ đồ mô tả quy trình khởi chạy và cập nhật thông tin thời tiết theo thời gian thực:

⚡ 4. Các kỹ thuật "Pro-level" trong mã nguồn

1. Dynamic Theming via CSS Variables: Flame không sử dụng các file CSS cứng cho từng theme. Thay vào đó, nó định nghĩa một bộ CSS Variables (--color-primary, --color-background) trên document.body. Khi người dùng thay đổi theme trên giao diện, Redux sẽ cập nhật giá trị các biến này, tạo hiệu ứng thay đổi giao diện tức thì ("On-the-fly").
2. Search Parsing Engine: Tích hợp bộ máy phân tích cú pháp tìm kiếm thông minh. Nó có thể phân biệt giữa một URL, một địa chỉ IP nội bộ, hoặc một từ khóa đi kèm tiền tố (/g, /yt, /d) để định tuyến người dùng đến đúng công cụ tìm kiếm mong muốn.
3. Docker Socket Orchestration: Sử dụng thư viện axios để giao tiếp với file socket UNIX của Docker. Đây là kỹ thuật chuyên sâu cho phép ứng dụng bên trong container "nói chuyện" và lấy thông tin từ máy chủ vật lý bên dưới.
4. Drag & Drop Persistence: Sử dụng react-beautiful-dnd để xử lý việc sắp xếp. Tọa độ và thứ tự mới của các thành phần được gửi về backend ngay sau khi người dùng nhả chuột, đảm bảo bố cục luôn được lưu lại chính xác.

⚖️ 5. So sánh chiến lược

✅ Kết luận: Tại sao Flame là mảnh ghép hoàn hảo cho Homelab?

Flame không chỉ đơn thuần là một danh sách các đường dẫn; nó là một hệ thống quản trị hạ tầng tầng cao (High-level Orchestration Dashboard). Việc kết hợp giữa khả năng tự động phát hiện ứng dụng và hệ thống cấu hình hướng GUI đã biến Flame thành trang chủ lý tưởng cho cả người dùng phổ thông lẫn các kỹ sư DevOps vận hành server gia đình.

Đối với các lập trình viên Backend, nghiên cứu Flame mang lại giá trị về:

• Kỹ thuật tương tác với Docker/Kubernetes API từ ứng dụng.
• Cách xây dựng hệ thống Dynamic Theming hiệu quả với CSS Variables.
• Tư duy thiết kế Stateless Container giúp dữ liệu bền vững.