Production Engineering: vận hành Cube
Triển khai thành nhiều node, cấu hình biến môi trường, bảo mật, giám sát, xử lý sự cố và phát hành an toàn.
Mục lục chương
Kiến trúc triển khai
Cụm gồm ba nhóm node với chức năng riêng: tiếp nhận truy vấn, lưu cache và build nền.
Handbook mô tả một cụm High Availability chạy trên Kubernetes hoặc Cube Cloud. Handbook gọi các node API là router nodes; theo tài liệu Cube, đó là các API instance, còn router là thành phần của Cube Store. API instance tiếp nhận request từ client, kiểm tra RLS, biên dịch SQL và quản lý cache kết quả. Cube Store gồm một router node điều phối và các worker lưu trữ, xử lý pre-aggregation. Refresh worker chạy nền, build và refresh pre-aggregations theo lịch.
Biến môi trường và secrets
Trên production, hành vi của Cube chủ yếu do một số biến môi trường CUBEJS_ quyết định.
Biến cấu hình của Cube dùng tiền tố CUBEJS_ (từ v0.28, nhóm biến Redis cũng chuyển sang tiền tố này); riêng Cube Store dùng tiền tố CUBESTORE_. Chọn từng biến để xem giá trị khuyến nghị trên production và tác dụng tương ứng. Hai biến bắt buộc phải cấu hình đúng: CUBEJS_DEV_MODE phải là false, CUBEJS_API_SECRET phải là chuỗi bí mật riêng của production.
Biến cần hiểu kỹ nhất là CUBEJS_ROLLUP_ONLY, tức rollup-only mode. Khi bật chế độ này, mọi truy vấn chỉ được trả lời từ pre-aggregations; truy vấn nào chưa có bảng rollup phù hợp sẽ không được gửi xuống data warehouse nguồn.
Đọc sâuMột file .env mẫu cho API instance
CUBEJS_DB_TYPE=postgres CUBEJS_DB_PASS=<DB_PASSWORD> CUBEJS_API_SECRET=<API_SECRET> CUBEJS_DEV_MODE=false CUBEJS_ROLLUP_ONLY=true
Trên node refresh worker, thêm CUBEJS_REFRESH_WORKER=true. Biến này thay cho CUBEJS_SCHEDULED_REFRESH_TIMER cũ. Secrets nên được cung cấp từ secret manager của hạ tầng và không được commit vào Git.
Xác thực và bảo mật
Ba lớp bảo vệ: secret ký JWT đủ mạnh, TLS, và giới hạn nguồn được phép gọi API.
Cube dùng CUBEJS_API_SECRET để kiểm tra chữ ký JWT trong mỗi request. Nếu secret yếu, bất kỳ ai cũng có thể tự ký token và mạo danh tenant khác. Hai lớp còn lại là TLS cho mọi API và giới hạn nguồn truy cập: CORS chỉ chấp nhận các domain trong whitelist, SQL API chỉ mở cho dải IP nội bộ.
Logs, metrics và giám sát
Log dạng JSON, bốn chỉ số chính và cảnh báo tự động khi latency vượt ngưỡng.
Handbook đề xuất xuất log dạng JSON để Fluentd hoặc Logstash thu thập, đồng thời kết nối endpoint Prometheus /metrics với Grafana hoặc Datadog. Chọn từng chỉ số để xem ý nghĩa.
Xử lý sự cố hiệu năng
Xác định truy vấn chậm, tìm nguyên nhân không trúng pre-aggregation, sau đó kiểm tra queue.
Quy trình gồm ba bước dưới đây. Phần lớn truy vấn chậm là do pre-aggregation miss: truy vấn bị chuyển xuống data warehouse thay vì đọc từ Cube Store. Lý do miss thường là granularity, thiếu dimension, hoặc khoảng thời gian nằm ngoài refresh_range. Nếu nguyên nhân không phải miss, cần kiểm tra queue length.
Lỗi thường gặp trên production
Bốn lỗi thường gặp và cách xử lý nhanh cho từng lỗi.
Chọn lỗi để xem hiện tượng, nguyên nhân gốc và bước xử lý. Hai cách sửa phổ biến nhất là bọc điều kiện bằng FILTER_GROUP và cấu hình export bucket khi build rollup. Chương 06 trình bày cú pháp sửa cụ thể.
CI/CD và phát hành
Data model là code, nên mỗi thay đổi cần đi qua PR, kiểm tra tự động, môi trường thử nghiệm và rolling update.
Quy trình Git-first trong handbook có bốn bước, kết thúc bằng rolling update trên Kubernetes. Chọn từng bước để xem nội dung kiểm tra.
Checklist sẵn sàng production
Sáu hạng mục cần hoàn tất trước khi đưa Cube vào phục vụ người dùng thực tế.
Đánh dấu các hạng mục đã hoàn tất. Trạng thái được lưu trong trình duyệt này. Các ngưỡng (cache hit > 80%, lỗi 5xx > 1%, P95 > 2 giây) là gợi ý của handbook, cần điều chỉnh theo hệ thống thực tế.