Một nền tảng riêng cho đối tác
APIGA có website, mã nguồn, database, tài khoản và cấu hình riêng. Không dùng chung ví hoặc phiên đăng nhập của website hiện hữu.
Website & HTTPS
Domain và HTTPS đã hoạt động. Đã có khung quản trị backend DEV, database riêng và API điểm thử nghiệm. Chưa kết nối nguồn game/video. Mở quản trị DEV →
API → phiên xem → video
Server đối tác dùng API key. APIGA xác thực, cấp mã đăng nhập ngắn hạn và phiên xem; người xem được cấp vé video theo quyền.
Đối tác, mỗi bên một API key/một agent, người xem, đăng nhập qua tích hợp API, cấp vé và trang xem theo mẫu đã khảo sát. Điểm, ví, tỷ giá và quyết toán là phần mở rộng cần chốt riêng. Hồ sơ này không xác nhận các phần mềm đề xuất đã được cài đặt.
Đầu nguồn đã xử lý video; APIGA nhận phát lại theo API được cấp. Không có quyền quản trị đầu nguồn: mọi chức năng phải được kiểm chứng qua hợp đồng API, không dựa vào giả định có thể sửa backend của họ.
Một đối tác · một API key · một agent
Nhiều đối tác sử dụng các bộ kết nối riêng trên cùng nền tảng APIGA. Mỗi đối tác được cấp đúng một API key đang hoạt động và một tài khoản agent duy nhất; các player thuộc phạm vi agent tương ứng.
Khóa và định danh
API key xác thực server đối tác qua HTTPS. Partner ID / Agent ID là định danh, không phải bí mật thay thế key. Server suy ra agent từ key đã xác thực; không cho bên gọi đổi agent tùy ý trong request.
Cách ly dữ liệu đối tác
Player được định danh bởi cặp đối tác + mã player bên đối tác. Hai bên có thể dùng cùng username mà không bị gộp tài khoản. Dữ liệu, quyền xem và lịch sử luôn được kiểm theo đúng đối tác.
Luồng player mở giao diện xem
- Server đối tác gọi API APIGA bằng API key và mã player. Endpoint và schema sẽ chốt khi thiết kế.
- APIGA kiểm key, agent và trạng thái player; cấp mã mở trang dùng một lần, thời hạn ngắn.
- Server đối tác đưa URL mở trang cho player. URL chỉ mang mã tạm, không chứa API key dài hạn.
- Player mở trang APIGA; mã được đổi sang phiên riêng của người xem rồi loại khỏi URL. Không dùng tài khoản mẫu để đăng nhập chung cho mọi player.
- Trang xem lấy thông tin đấu trường và vé video theo quyền của phiên; giao diện tham khảo website đã khảo sát.
Yêu cầu hiện tại dùng một API key cho mỗi đối tác, không bắt đối tác dùng thêm bộ OAuth client_id/client_secret. Cách truyền key bằng header, quyền thao tác, chu kỳ thay key và thu hồi sẽ được đặc tả sau; đổi key không tạo agent thứ hai. API key chỉ giữ trên server đối tác, lưu phía APIGA bằng cơ chế xác minh phù hợp và không ghi vào log.
Không đặt quota thương mại/ngày/tháng hoặc hạn mức RPS theo gói đối tác trong phác thảo này. Năng lực xử lý vật lý vẫn hữu hạn: concurrency, timeout, hàng đợi có giới hạn và backpressure là biện pháp bảo vệ kỹ thuật cần chốt, không phải cam kết xử lý vô hạn. Khi quá tải phải trả trạng thái rõ ràng và giữ nguyên nguyên tắc chống trùng.
Tham khảo giao diện sau đăng nhập
Đã đăng nhập và quan sát trực tiếp lobby cùng trang đấu trường trên website mẫu theo quyền được cung cấp. Đây là khảo sát làm rõ yêu cầu; chưa sao chép giao diện, chưa kết nối backend hoặc triển khai chức năng trên APIGA.
Lobby
Banner giới thiệu, danh sách đấu trường, trạng thái trận và nút vào xem. Thanh điều hướng gồm vé, báo cáo, tin nhắn, tài khoản và thông tin số dư.
Trang đấu trường
Khung video lớn, mã và trạng thái trận, hai phía Meron/Wala, bảng lịch sử kết quả, thống kê và chế độ xem đôi. Giao diện hiện có thêm khối odds, nhập điểm và thao tác đặt vé.
Lúc khảo sát, trang đấu trường báo “No broadcast right now”; chưa chứng minh video đang phát hoặc chất lượng luồng. Không tạo player, đặt vé, cấp điểm hay thực hiện giao dịch. Tài khoản và thông tin đăng nhập mẫu không được đưa vào hồ sơ công khai.
Cần xác nhận trước khi dựng giao diện: mở thẳng đấu trường hay qua lobby; giữ những thành phần nào của mẫu; có bật điểm/vé/báo cáo hay chỉ hiển thị video và kết quả. Câu “chỉ xem, chưa thay đổi gì” được hiểu là giới hạn công việc hiện tại ở khảo sát và sửa hồ sơ, không tự chốt hoặc triển khai nghiệp vụ.
Tách API, dữ liệu và đường truyền video
Khởi đầu bằng backend chia module rõ ràng. API không giữ trạng thái quan trọng trong RAM; worker và tầng truyền video có thể mở rộng độc lập.
Luồng điều khiển / API
Không cần chia nhiều microservice từ đầu. Tách module đối tác, phiên xem, video, kết nối nguồn, yêu cầu/outbox, quản trị và audit trong cùng backend; tách tiến trình API và worker khi vận hành.
Cài đúng thành phần, đúng giai đoạn
Đây là bộ công nghệ khuyến nghị để chốt thiết kế. Phiên bản phải còn được hỗ trợ và được kiểm tra tương thích khi triển khai; không nâng runtime dùng chung của website khác một cách tự động.
| Yêu cầu | Phần mềm / dịch vụ | Nơi chạy & thời điểm |
|---|---|---|
| Web, HTTPS, reverse proxy | Nginx + Certbot; Cloudflare DNS | Đã có cho trang tĩnh. API/video sẽ có cấu hình riêng; không cài Nginx thứ hai tranh cổng. |
| Backend API đối tác | Node.js LTS được hỗ trợ + TypeScript + Fastify; OpenAPI | Giai đoạn 1, runtime riêng cho APIGA. JSON Schema kiểm dữ liệu; đặc tả API cho đối tác. |
| Database giao dịch | PostgreSQL + driver pg + công cụ migration (đề xuất node-pg-migrate) | Giai đoạn 1, DB/user riêng, private network hoặc loopback; có migration và rollback được kiểm thử. |
| Quản lý kết nối DB | PgBouncer | Trước khi chạy nhiều API/worker. Tổng pool phải nằm trong ngân sách kết nối DB; kiểm tính tương thích transaction pooling. |
| Cache & phối hợp tải | Redis | Khi cần cache hoặc trạng thái tạm dùng chung nhiều API. Không áp quota request đối tác; cơ chế bảo vệ quá tải sẽ chốt riêng. Không giữ duy nhất số dư, idempotency hoặc kết quả quan trọng ở Redis. |
| Ghi trước, gửi sau | PostgreSQL outbox + worker ứng dụng | Giai đoạn 1. Đây là logic phải xây, không phải cài một phần mềm là có sẵn chống trùng. |
| Hàng đợi tải cao | RabbitMQ; quorum queues khi cần HA | Giai đoạn 2 hoặc sớm hơn nếu tải yêu cầu. Bật publisher confirms, manual ack, retry có giới hạn và hàng đợi lỗi. |
| Phát lại video | Relay riêng theo giao thức nguồn + Nginx; player tương thích | Chọn sau khi xác minh FLV/HLS/WebRTC và quyền phát lại. Không mặc định cần FFmpeg, không tái mã hóa nếu không cần. |
| Tự khởi động lại | systemd; Docker/Compose là lựa chọn đóng gói sau | Giai đoạn 1: restart có backoff, tự chạy sau reboot, graceful shutdown, giới hạn CPU/RAM/file descriptor. |
| Quan sát & cảnh báo | Prometheus + Grafana + Alertmanager; node_exporter, postgres_exporter; Pino + journald | Trước khi có đối tác production. Dashboard nội bộ; log có request ID và che dữ liệu nhạy cảm. |
| Backup & phục hồi theo thời điểm | pgBackRest + WAL archiving + kho object storage ngoài máy | Khi PostgreSQL được đưa vào dùng. Chốt retention, mã hóa và kiểm thử restore; timer backup được giám sát. |
| Cân bằng tải nhiều máy | Managed load balancer có health check; HAProxy nếu tự quản | Giai đoạn 2. Một HAProxy đơn lẻ vẫn là điểm lỗi; cần gateway dự phòng hoặc dịch vụ quản lý. |
| Database failover | Ưu tiên PostgreSQL managed HA; hoặc Patroni + etcd + fencing | Giai đoạn 2. Nếu tự quản: quorum điều phối trên 3 node độc lập; không dựng failover tự động thiếu chống split-brain. |
| Kiểm thử tải & API | k6 + test runner ứng dụng + HTTP client | Từ giai đoạn 1, chạy máy phát tải riêng. Tải nguồn thật chỉ khi được phép. |
Lưu bền vững, kiểm soát xử lý trùng.
Xác thực và nhận dạng yêu cầu
Kiểm tra API key, scope, trạng thái đối tác, ánh xạ agent và schema. Dùng request ID và idempotency key theo đối tác/loại thao tác. Key bí mật không xuất hiện trong frontend hoặc URL.
Ghi nhận nguyên tử trong PostgreSQL
Ràng buộc UNIQUE cho khóa chống trùng. Lưu hash nội dung, trạng thái và outbox trong cùng transaction. Cùng key/cùng nội dung trả trạng thái hoặc kết quả cũ; khác nội dung từ chối.
Chỉ xác nhận sau khi đã commit
Tác vụ nền trả 202 và mã tra cứu khi yêu cầu đã được lưu bền vững. Không thông báo hoàn thành nghiệp vụ chỉ vì đã đưa vào hàng đợi.
Worker gửi và ghi kết quả
Claim công việc bằng lease/khóa phù hợp, giới hạn số tác vụ đang chạy. Không giữ transaction DB trong lúc đợi mạng. Khi dùng RabbitMQ, ack sau khi đã lưu kết quả; consumer có inbox/khóa nghiệp vụ chống giao lại.
Retry có điều kiện, đối soát khi chưa rõ
Backoff tăng dần và jitter, số lần tối đa, dead-letter và thao tác phát lại có kiểm soát. Không tự retry lỗi quyền hoặc dữ liệu không hợp lệ.
Đầu nguồn có thể đã xử lý nhưng phản hồi bị mất. Trạng thái phải là “chưa xác định”, tra cứu theo mã giao dịch trước khi gửi lại. Nếu nguồn không có idempotency/tra cứu, không thể bảo đảm exactly-once cho tác động ở cả hai hệ thống.
received → queued → processing → succeeded / failed / unknown
Outbox publisher có thể gửi trùng nếu chết sau khi publish nhưng trước khi đánh dấu đã gửi. Vì vậy outbox, hàng đợi và consumer phải phối hợp; không thành phần nào tự bảo đảm toàn bộ chuỗi.
Dữ liệu có chủ sở hữu rõ ràng
Các nhóm dữ liệu dự kiến
Đối tác, agent một-một và key đã băm; người xem và ánh xạ ID đối tác; phiên đăng nhập; yêu cầu chống trùng; outbox/inbox; quyền xem và vé; trạng thái kết nối nguồn; sự kiện kết quả có phiên bản; audit. Tên bảng và schema chưa chốt.
Ràng buộc vận hành
Định danh theo tenant; query luôn có phạm vi đối tác. API và worker dùng quyền DB tối thiểu. Secret nằm ngoài public. Session cookie Secure/HttpOnly, thời hạn và thu hồi rõ ràng; mã đăng nhập dùng một lần.
- Transaction ngắn, index theo truy vấn thật, phân trang cursor; đặt timeout truy vấn và theo dõi slow query.
- Primary xử lý ghi và đọc cần nhất quán ngay. Replica chỉ đọc báo cáo/dữ liệu chấp nhận trễ; không quyết định số dư hoặc quyền vừa thu hồi từ replica trễ.
- Không dùng Redis lock làm lớp bảo vệ duy nhất. Unique constraints và cập nhật nguyên tử là nền tảng.
- Tiền/điểm nếu bổ sung: số nguyên theo đơn vị nhỏ nhất, bút toán bất biến và giao dịch bù, không sửa lịch sử. Quỹ đối tác và ví người chơi cập nhật trong một transaction; không cho key thường tạo điểm.
Phần mở rộng: điểm, tỷ giá và kết quả
Chưa thuộc mặc định bản xem đầu tiên. VNDK dự kiến 1 điểm API = 1,000 VND; USD còn chọn 1 điểm = 1 USD hoặc 0.1 USD. Tách nguồn vào, cấu hình và xử lý server; chưa tự cho phép đổi chéo. Kết quả lưu nguồn/mã trận/phiên bản/trạng thái xác nhận; đính chính dùng quyết toán bù. Không có hai hệ thống cùng có thẩm quyền tính số dư.
Giới hạn đúng chỗ, mở rộng đúng nút thắt
| Nút thắt | Biện pháp thiết kế | Chỉ số cần theo dõi |
|---|---|---|
| Đối tác gửi dồn | Không áp quota request. Điều phối công bằng giữa đối tác, giới hạn công việc đang xử lý và backlog để bảo vệ hệ thống; quá tải tạm thời trả trạng thái rõ ràng. | RPS, độ trễ, phản hồi quá tải, concurrency mỗi đối tác. |
| API chờ nguồn chậm | Timeout, circuit breaker, pool kết nối; concurrency upstream có giới hạn. | p95/p99, lỗi nguồn, số request đang chờ. |
| Database quá nhiều kết nối | PgBouncer và pool có ngân sách; transaction ngắn; index; báo cáo chạy nền. | Pool wait, lock wait, query time, IOPS. |
| Hàng đợi tăng liên tục | Backpressure, giới hạn backlog, ưu tiên và phân nhóm worker; quá tải từ chối có kiểm soát. | Tuổi message cũ nhất, tốc độ vào/ra, retry. |
| Ví đối tác bị tranh khóa | Cập nhật nguyên tử; đo hot row trước khi chia hạn mức/quỹ. Không song song hóa sai tính nhất quán. | Transaction chờ khóa và deadlock. |
| Video đầy băng thông | Tầng relay riêng; chỉ gom kênh tương thích và xác thực từng viewer. Xử lý backpressure, ngắt viewer chậm, dọn source khi hết viewer. | Viewer, Mbps, egress, stall, frame/time tiến triển. |
2 Mbps × 1.000 người xem ≈ 2 Gbps đầu ra, chưa gồm overhead. API nhẹ không có nghĩa video nhẹ. Phải đo bitrate thực và băng thông NIC/nhà cung cấp trước khi chọn máy.
Cloudflare phục vụ website/API và tầng video là hai quyết định riêng. Gói website không mặc định bao gồm quyền phân phối video tùy ý qua proxy; phải xác nhận dịch vụ phù hợp trước khi chọn đường phát.
Restart, failover và backup là ba lớp khác nhau
| Sự cố | Cách phục hồi | Điều kiện / giới hạn |
|---|---|---|
| API hoặc worker chết | systemd restart có backoff; readiness kiểm phụ thuộc, liveness kiểm tiến trình. | Graceful shutdown, drain request; tránh vòng lặp restart vô hạn. |
| Chết giữa một công việc | Lease hết hạn hoặc message được giao lại; consumer đối chiếu idempotency/inbox. | Không chỉ lưu tiến độ trong RAM. |
| Mất máy API | Load balancer loại node lỗi, chuyển sang node khác. | Ít nhất hai máy độc lập; hai process trên một VPS không đủ. |
| Mất Redis | Dựng lại cache; cơ chế bảo vệ tải chạy chế độ an toàn, hạn chế cấp phiên mới nếu không xác minh được. | Dữ liệu có thẩm quyền còn trong PostgreSQL. |
| Mất broker | Outbox giữ sự kiện chưa xác nhận; quorum queue/managed broker chịu lỗi node. | Quorum RabbitMQ đề xuất 3 node độc lập, cần đa số còn hoạt động. |
| Mất PostgreSQL primary | Failover sang standby qua cơ chế điều phối. | Fencing primary cũ, tránh split-brain. Async có thể mất giao dịch cuối; sync tăng độ trễ và có thể chặn ghi. |
| Xóa nhầm / dữ liệu hỏng | pgBackRest + WAL, phục hồi theo thời điểm vào môi trường cách ly. | Replica không thay backup; kiểm restore định kỳ, lưu ngoài máy. |
| Mất nguồn video | Hiển thị trạng thái, dừng retry dồn; khôi phục phiên khi nguồn hồi phục. | Muốn phát liên tục cần nguồn dự phòng thực sự; nhân đôi API không tạo thêm nguồn. |
Cần chốt: RPO là mức dữ liệu tối đa chấp nhận mất; RTO là thời gian phục hồi mục tiêu. Hai chỉ số này quyết định loại replication, backup, ngân sách và mức tự động hóa. Chưa có cam kết RPO/RTO trong bản phác thảo này.
Làm nền tảng trước, mở rộng bằng số liệu
Chốt đầu vào và hợp đồng nguồn
- Đọc tài liệu API nguồn: đăng nhập, tài khoản, vé xem, thời hạn, rate limit, lỗi, idempotency và tra cứu.
- Chốt số đối tác, RPS thường/đỉnh, viewer đồng thời, bitrate, RPO/RTO và ngân sách.
- Chốt phạm vi bản đầu; xác nhận chính sách phân phối video và kế hoạch backup ngoài máy.
Nền tảng riêng & bản xem đầu tiên
- Repository, runtime/service/user riêng; PostgreSQL + migration, API + outbox/worker; key và session riêng.
- Xây ánh xạ một đối tác/một key/một agent, đăng nhập player qua mã mở trang, cấp vé và giao diện theo mẫu đã chốt; kiểm tenant và chống trùng ngay từ đầu.
- Backup ngoài máy, log/metrics, health check và restart; giới hạn CPU/RAM/IO để bảo vệ website hiện hữu.
- Thêm PgBouncer trước khi tăng process, Redis khi cần cache và phối hợp trạng thái tạm. Chưa cần broker riêng nếu outbox worker đủ tải.
Production có đối tác & dự phòng
- Ít nhất hai máy API, load balancer có dự phòng; DB primary/standby hoặc managed HA.
- RabbitMQ khi cần, publisher confirms/ack và outbox/inbox; có thể dùng dịch vụ broker quản lý.
- Tách relay video khỏi máy API/database theo tải; theo dõi băng thông, viewer và giới hạn nguồn.
- Dashboard/cảnh báo, runbook, diễn tập mất node và failover; webhook có chữ ký và retry nếu được chọn.
Mở rộng theo nút thắt đã đo
- Tăng API theo CPU/latency, worker theo tuổi hàng đợi, relay theo egress; không scale vượt giới hạn nguồn.
- Replica cho báo cáo, partition dữ liệu lịch sử khi thật sự cần; kiểm lại index và query trước khi sharding.
- Cân nhắc nhiều vùng và nguồn video dự phòng sau khi có yêu cầu cụ thể; không thêm độ phức tạp chỉ để có nhiều thành phần.
Chứng minh bằng bài kiểm thử
Tính đúng
Gửi đồng thời cùng idempotency key; cùng idempotency key khác payload; worker chết sau commit/trước ack; nguồn nhận nhưng timeout; đối tác truy cập chéo; key bị thu hồi; vé hết hạn hoặc dùng lại. Không lộ credential trong log.
Khả năng chịu tải
k6 đo RPS, p95/p99 và tỷ lệ lỗi theo endpoint; spike, stress và soak. Dùng nguồn giả lập trước, có sự đồng ý khi tải nguồn thật. Kiểm một đối tác gửi dồn không làm đói đối tác khác.
Chất lượng video
Time và decoded frames thực sự tiến triển; đo thời gian khởi phát, stall, reconnect và cleanup. HTTP 200 chưa chứng minh video đang phát. Kiểm số viewer và egress riêng với RPS API.
Khôi phục thực tế
Kill API/worker, mất Redis/broker, reboot node và failover DB trong môi trường kiểm thử. Restore backup vào nơi cách ly, đối chiếu dữ liệu; đo RPO/RTO, cảnh báo tới người trực.
Không công bố “chịu được X người xem” hoặc “không mất dữ liệu” trước khi đo. Chốt ngưỡng nghiệm thu sau khi có yêu cầu tải và giới hạn đầu nguồn.
Những quyết định còn mở
- Giao thức video, quyền gom luồng, giới hạn phiên và cơ chế cấp/thu hồi vé nguồn.
- Danh sách API đầu tiên, endpoint tra cứu và hỗ trợ idempotency tại đầu nguồn.
- Số viewer đồng thời, bitrate, RPS, ngân sách, mục tiêu RPO/RTO.
- Nơi chạy từng thành phần, dịch vụ managed hay tự quản, nơi lưu backup ngoài máy.
- Phương thức đăng nhập đối tác → người xem, vòng đời key/token và chính sách xử lý quá tải, không áp quota request.
- Phạm vi điểm/ví/kết quả/tỷ giá nếu bổ sung; chưa coi là chức năng bản đầu.
Chỉ trang trình bày này được xuất bản theo yêu cầu. Không cài backend, database, broker hoặc cụm dự phòng từ hồ sơ. Cập nhật bản thảo khi có quyết định mới; lịch thực hiện và cấu hình máy sẽ chốt sau khảo sát.
Tài liệu chính thức
Cơ sở tham khảo cho các thành phần đề xuất; thông số và phiên bản cần đối chiếu lại ở thời điểm triển khai.