Tổng Quan

Tổng Quan Hệ Thống

Giám sát sức khỏe, luồng dữ liệu và trạng thái vận hành toàn bộ tài khoản Zalo.

Tổng Nodes

0

Đang Online

0

Mất Kết Nối/Lỗi

0

Cụm VPS Máy Chủ (Shard Cluster)

Giám sát tài nguyên CPU, RAM & Worker của từng VPS khởi chạy qua Coolify

Uptime: ...

Lưu lượng Tin nhắn (Real-time)

Cảnh Báo Hệ Thống

Hệ thống đang hoạt động ổn định.

Node Mới:

Nodes đang hoạt động

1/1

Event Monitor

⬇0 │ ⬆0 │ ⚡0
Đang chờ luồng sự kiện...

Trung tâm Cứu hộ Tin nhắn

Dead Letter Queue — Không để mất bất kỳ tin nhắn nào

0
Đang chờ xử lý
0
Node bị lỗi
0
Loại lệnh lỗi
—
Chờ lâu nhất
Thời gian Node Lệnh Chi tiết

n8n Connection

1. Lắng nghe Inbox

Redis Queue: zalo_inbox.

2. Gửi lệnh Outbox (RPC)

Gọi trực tiếp (Bắt buộc kèm Header: x-api-key)

http://localhost:3000/api/zalo/action

Zalo Actions Spec Library

Kho Proxy & Failover

Auto Failover

Tự động xoay IP cùng Subnet khi nhà mạng đổi IP và giám sát kết nối 24/7.

Tổng Proxy
0
Hoạt Động
0
Lỗi / Chết
0
Sắp Hết Hạn
0
Nguồn API
0

Nguồn Đồng Bộ Tự Động (Multi-Provider API)

Chưa cấu hình nguồn API nào. Bấm "+ Nguồn API" để kết nối Proxyshop!
0/0
Gateway (Proxy Entry) IP Outbound Nhà Mạng Node Zalo Hạn Dùng Trạng Thái Thao Tác
Đang tải danh sách Proxy...

Sổ Tay Vận Hành TNG Zalo Enterprise

Đặc tả toàn bộ 100% tính năng, API kết nối, cơ chế bảo mật ngầm và quy trình vận hành chuẩn dành riêng cho Kỹ thuật viên (DevOps/System Admin).

0. Sơ Đồ Kiến Trúc Luồng (Architecture Flow) CORE_ARCH

App Hub / n8n
Gửi lệnh JSON qua Redis hoặc REST
Dragonfly Redis
Inbox / Outbox / DLQ Queues
Manager.js
Điều phối, phân luồng, REST API
Worker Threads
Đa luồng ảo hóa TLS Chrome
Zalo Server
AES Encrypted WebSocket
Giải thích chi tiết từng thành phần
Supabase (PostgreSQL)Lưu trữ vĩnh viễn: Danh sách Nodes, Proxy, Cookie Session, Profile, Nhật ký hoạt động và lịch sử kết nối.
Dragonfly RedisCache tốc độ cao: Hàng đợi tin nhắn (Inbox/Outbox), DLQ, Idempotency Keys, AI Roles, Shard Heartbeat, Cluster Config.
Socket.io (WebSocket)Kênh truyền real-time giữa Frontend UI ↔ Manager: Event Stream, QR Code, Nhật ký Node, Trạng thái online/offline.

Quy Trình Nhập Môn 4 Bước (Onboarding Checklist) QUICK_START

1
🌐
Nạp Kho Proxy

Vào Tab Kho Proxy → Dán danh sách IP:PORT:USER:PASS → Bấm Nạp → Bấm ⚡ Quét kiểm tra sức khỏe.

2
📱
Tạo Zalo Node

Tab Nodes → Nhập SĐT Zalo → Chọn Proxy (Auto / Direct) → Bấm Khởi tạo QR → Mở Zalo trên điện thoại quét mã.

3
🔬
Test Workspace

Bấm nút Workspace trên thẻ Node đã Online → Tab Mini Postman → Chọn Action sendMessage → Bấm Gọi API test thử.

4
🔗
Nối N8N / App Hub

Đọc Mục 7 để nối n8n qua Redis LPUSH zalo_outbox_shard_1 hoặc Mục 10 để cấp x-api-key cho App Hub HLV.

1. Thanh Điều Khiển Toàn Cục (Header) CORE

Export VaultĐóng gói toàn bộ 1000+ Session (Cookie, IMEI, UA, Proxy) → file .json. Gọi GET /api/system/vault/export. Tải hàng ngày phòng cháy VPS.
Restore VaultNạp lại file backup. Gọi POST /api/system/vault/import. Tái tạo toàn bộ Nodes không cần quét QR lại.
Theme Engine4 bảng màu (Blue/Emerald/Purple/Gold) + Dark/Light. Lưu localStorage.
Floating LogsCửa sổ nổi Socket.io real-time. Hiện lỗi Proxy/Cookie/Zalo in màu đỏ tức thì.
Sync ProfileGọi GET /api/account/sync-profile?username=NodeID làm mới Avatar, Tên, Bio từ Zalo Server.
Clear Redis InboxGọi POST /api/system/clear-redis-inbox xóa sạch hàng đợi zalo_inbox khi tắc nghẽn.

2. Dashboard Metrics & Cluster Monitor REALTIME

Thẻ Thống KêTổng Nodes, Online, Lỗi. Nguồn: GET /api/stats/dashboard. CPU%, RAM%, Uptime cập nhật 5s/lần qua Shard Heartbeat.
Biểu Đồ ThroughputChart.js: Inbound (tin nhận) + Outbound (tin gửi). Dữ liệu từ systemMetrics.
Cluster VPS PanelHiển thị tất cả Shard VPS (CPU, RAM, Workers, Accounts). Dữ liệu từ Redis Hash shard_cluster_nodes.
System Warnings50 sự cố gần nhất: Mất kết nối, Proxy die, Cookie hết hạn. Lọc từ systemMetrics.recentErrors.

3. Quản Lý Nodes Fleet & Thao Tác Hàng Loạt FLEET

A. Quy Trình Khởi Tạo Node Mới:
  1. Nhập SĐT Zalo → Chọn Proxy (Auto: bốc ngẫu nhiên 1 IP sạch, thử tối đa 3 lần | Direct: dùng IP VPS).
  2. Bấm Khởi tạo QR → Worker giả lập TLS Chrome Fingerprint → Sinh mã QR dạng hình ảnh Base64.
  3. Mở ứng dụng Zalo trên điện thoại → Quét mã QR → Bấm Xác nhận đăng nhập.
  4. Hệ thống tự bóc tách Profile (Tên, Avatar, UID, IMEI, Gender, Bio, BizPkg) → Lưu Supabase → Node lên ONLINE.
B. Bulk Actions (Thao Tác Hàng Loạt):
Đổi Role AI
Restart Node
Di cư Shard
Xóa Node
C. Thẻ Node hiển thị:

Avatar, Tên Zalo, UID, SĐT, Role AI, Trạng thái (Online/Offline/Error), Proxy đang dùng, Shard ID, Nút Workspace, Nút Logout, Checkbox chọn hàng loạt.

4. Workspace Chẩn Đoán Sâu DEEP_DIAG

Mở: Bấm nút Workspace trên bất kỳ thẻ Node nào.

Sức KhỏeUptime, Cookie, Di cư nóng (Hot-Migration), đổi Shard/Proxy real-time.
IP & FingerprintIP Proxy thực tế, IMEI, Zalo UID, Chrome User-Agent, chống Leak IP VPS.
Mini PostmanGọi trực tiếp 150+ Zalo Actions hoặc CUSTOM_REQUEST. Hiện JSON Response + Latency (ms).
Nhật Ký NodeLịch sử hoạt động (Logs) + Lịch sử kết nối. Lọc theo mức: error/warn/success/auth/connect.

5. Luồng Sự Kiện Real-Time (Event Stream) SOCKET

Hiển thị 8 loại sự kiện Zalo từ tất cả Nodes dạng dòng cuộn real-time:

message
reaction
undo
typing
friend_event
group_event
delivered
seen

Click mở xem JSON thô. Nút ⏸ Tạm dừng đóng băng dữ liệu khi test. Worker gom cụm (Event Batching) 50 event/500ms trước khi đẩy Redis giảm tải RAM.

6. Trạm Cứu Hộ DLQ (Dead Letter Queue) ZERO_LOSS

Kiến trúc Cam kết Không Mất Dữ Liệu. Tin gửi thất bại tự động chuyển về Redis Key zalo_dlq.

Retry All
Vét kho bơm lại
Retry 1
Gửi lại 1 tin
Delete
Xóa chọn lọc
Test DLQ
Bắn tin lỗi test

Bảng DLQ hiện: msg_id, Node, Lệnh gốc (cmd + args), Thời gian kẹt, Lý do lỗi từ Zalo.

7. Tích Hợp n8n & Redis Queues CORE INTEGRATION

Để thiết lập Automation (Tự động hóa), n8n cần giao tiếp với hệ thống thông qua Redis Queues. Không bao giờ giao tiếp trực tiếp với Worker.

Inbound (Nhận tin nhắn Zalo vào n8n)

Tất cả sự kiện Zalo (tin nhắn, group, bạn bè...) đều được Worker đẩy vào hàng đợi chung zalo_inbox. Thiết lập n8n Trigger liên tục rút (Pop) dữ liệu từ hàng đợi này.

Cấu hình Node n8n Redis Trigger:
  • Operation: Pop
  • Key: zalo_inbox
  • Type: List (BRPOP)
  • Timeout: 0 (Lắng nghe liên tục)
Mẫu JSON Dữ liệu n8n nhận được:
{
  "account": "Admin_Nhân_Đức",
  "zalo_username": "t_m7e08gecfz",
  "event": "message",
  "data": {
    "msg": "Khách hàng nhắn tin...",
    "type": "chat.text",
    "uidFrom": "999888777666"
  }
}

Outbound Async (Redis Queue)

Ra lệnh Zalo gửi tin (Không cần đợi kết quả). Đẩy vào hàng đợi zalo_outbox_shard_1.

Cấu hình Node n8n Redis Action:
  • Operation: Push
  • Key: zalo_outbox_shard_1
  • Type: List (LPUSH)
Mẫu JSON Payload n8n cần Push:
{
  "target_acc": "Admin_Nhân_Đức",
  "cmd": "sendMessage",
  "args": [ { "msg": "Xin chào!" }, "999888" ]
}

Universal RPC (Synchronous API)

Gọi bất kỳ lệnh Zalo SDK nào (để đọc data hoặc gửi tin) và nhận kết quả ngay lập tức. Sử dụng HTTP Request Node trong n8n.

Cấu hình Node n8n HTTP Request:
  • Method: POST
  • URL: http://IP:3000/api/zalo/action
  • Header: x-api-key: (Secret Key trong .env)
Mẫu JSON Body (Lấy Profile User):
{
  "account": "Admin_Nhân_Đức",
  "action": "getUserInfo",
  "args": ["15236589138732232"]
}

8. Thư Viện 150+ Zalo Actions Spec SPEC

Toàn bộ Payload mẫu nằm trong public/js/actions-db.js. File này tự động:

Gửi tin nhắn văn bản
Gửi ảnh Album
Gửi Voice ghi âm
Gửi Video preview
Gửi Sticker
Gửi GPS / Danh thiếp
Tạo bình chọn Poll
Khóa mõm nhóm
Đổi Avatar/Cover

Cập nhật: Sửa file JS → F5 tải lại trang. Không cần restart Server.

9. Quản Trị Kho Proxy Dân Cư PROXY

Nạp ProxyDán IP:PORT:USER:PASS hoặc USER:PASS@IP:PORT. Backend tự chuẩn hóa định dạng. Upsert theo batch 500 tránh lỗi Supabase.
⚡ Quét SạchQuét ngầm song song 50 IP/lần tới httpbin.org/ip qua Proxy. IP không phản hồi → đánh dead.
🧹 Dọn DẹpDELETE /api/proxies/dead xóa IP hỏng. DELETE /api/proxies/all xóa toàn bộ kho.
Sửa / Xóa đơn lẻPUT /api/proxies đổi địa chỉ. DELETE /api/proxies xóa 1 IP. POST /api/proxies/check kiểm tra 1 IP.

10. Tích Hợp App Hub HLV (Chi Tiết API Spec) HUB_API

Cho phép Huấn Luyện Viên (HLV) tự quản lý nick Zalo trên hub.thanhnguyen.group mà không cần Admin Core. Tất cả API truy vấn dài hạn đều dùng zalo_username (Zalo Handle ID, VD: t_m7e08gecfz) làm khóa định danh duy nhất.

Biến Môi Trường Cấu Hình App Hub (2 ENV)
APP_HUB_SECRET_KEY=TNG_HUB_SECRET_KEY_2026
APP_HUB_WEBHOOK_URL=https://hub.thanhnguyen.group/api/zalo-webhook

Cả 2 biến đều có giá trị mặc định sẵn trong code. Đổi qua Coolify ENV nếu App Hub chuyển domain.

Luồng Đăng Nhập QR Từ App Hub:
📱 App Hub
POST request-qr
⚙️ Manager
assignAccountToWorker
🔧 Worker
loginQR → QR Base64
📦 qrCacheMap
Polling 500ms × 16
✅ Response
qr_base64 trả về
A. Webhook Push — Core tự động bắn sự kiện tới App Hub
POST ${APP_HUB_WEBHOOK_URL}
Mặc định: https://hub.thanhnguyen.group/api/zalo-webhook
Header: x-api-key: ${APP_HUB_SECRET_KEY} | Timeout: 5000ms
📤 Request Body (JSON)
{
  "zalo_username": "t_m7e08gecfz",
  "event": "DISCONNECTED",
  "message": "Zalo bị ngắt kết nối",
  "shard_id": 1,
  "timestamp": "2026-08-08T14:00:00Z"
}
📋 Danh sách Event Types
CONNECTED — Nick online thành công
DISCONNECTED — Mất kết nối Zalo
ERROR — Sự cố Worker/SDK
BANNED — Bị khóa tài khoản
GET /api/hub/account-status/{zalo_username} — Kiểm tra trạng thái nick
Params: {zalo_username} = Mã Zalo Handle (VD: t_m7e08gecfz)
Header: x-api-key: APP_HUB_SECRET_KEY
Lookup: Supabase → zalo_accounts.zalo_username = {zalo_username}
✅ Response (Nick tồn tại)
{
  "success": true,
  "exists": true,
  "is_online": true,
  "status": "online",
  "display_name": "Nguyễn Văn A",
  "zalo_handle": "@zalohandle",
  "avatar_url": "https://...",
  "agent_role": "cs_bot",
  "last_active": "2026-08-08T...",
  "shard_id": 1,
  "is_business": false,
  "business_package": null
}
❌ Response (Không tìm thấy)
{
  "success": true,
  "exists": false,
  "is_online": false,
  "status": "not_found"
}
POST /api/hub/request-qr — Yêu cầu tạo mã QR đăng nhập
📤 Request Body (JSON)
{
  "zalo_username": "t_m7e08gecfz",
  "agent_role": "cs_bot"
}
• zalo_username (tùy chọn) — Bỏ trống nếu đăng nhập nick mới. Truyền vào nếu tái đăng nhập.
• agent_role (tùy chọn) — Mặc định: "cs_bot"
📥 Response (QR sẵn sàng)
{
  "success": true,
  "session_id": "a1b2c3d4-...",
  "qr_base64": "data:image/png;base64,...",
  "message": "Mã QR đã sẵn sàng..."
}
Cơ chế bên trong:
  1. Core sẽ tự động tạo một session_id (chính là Node ID/UUID ngẫu nhiên).
  2. Nếu truyền zalo_username (nick cũ) → STOP_ACCOUNT ngắt phiên cũ trước.
  3. Gọi assignAccountToWorker khởi chạy Node mới với Node ID ánh xạ.
  4. Vòng lặp polling qrCacheMap: 500ms × 16 lần = 8 giây chờ tối đa
GET /api/hub/check-qr/{session_id} — Polling kiểm tra QR & trạng thái
Params: {session_id} = Lấy từ response của API request-qr
Mục đích: App Hub gọi lặp lại mỗi 2-3s để lấy QR mới nhất hoặc kiểm tra xem HLV đã quét xong chưa.
✅ QR đã sẵn sàng
{
  "success": true,
  "has_qr": true,
  "qr_base64": "data:image/png;..."
}
⏳ Đã quét xong / Thành công
{
  "success": true,
  "has_qr": false,
  "is_online": true,
  "status": "online",
  "zalo_username": "t_m7e08gecfz",
  "phone_number": "+84903762545"
}
Lưu ngay `zalo_username` lại làm Khóa Chính để giao tiếp về sau!

11. Trọn Bộ 50+ REST API Endpoints FULL_API

🔐 Xác Thực & Quản Lý Phiên (Auth) — 3 Endpoints
POST/api/auth/loginĐăng nhập Admin (email + password) → JWT Token
POST/api/auth/refreshLàm mới JWT bằng refresh_token
GET/api/auth/meLấy thông tin Admin đang đăng nhập
📱 Quản Lý Nodes Fleet & Headless Lifecycle — 14 Endpoints
GET/api/accountsDanh sách 1000+ Nodes theo Shard
POST/api/nodes/request-qr⚡ Khởi tạo phiên Zalo headless & cấp QR Code Base64 cho n8n/Bot
GET/api/nodes/check-qr/:session_idPolling kiểm tra trạng thái quét QR & tự động lưu Supabase
POST/api/nodes/login-cookieĐăng nhập Zalo trực tiếp bằng chuỗi hoặc mảng Cookie JSON
POST/api/nodes/:username/restartTái khởi động và reload Node ngay lập tức vào Worker Thread
POST/api/nodes/:username/logoutĐăng xuất tài khoản Zalo và xóa phiên trong Worker
DEL/api/nodes/:usernameXóa vĩnh viễn Node khỏi DB và giải phóng tài nguyên
POST/api/accounts/updateCập nhật Role/Shard/Proxy cho Node
POST/api/zalo/actionUniversal RPC: Gọi mọi lệnh Zalo (Yêu cầu X-API-KEY)
POST/api/accounts/raw-execInternal Mini Postman Handler
GET/api/account/sync-profileĐồng bộ Profile (Tên/Avatar/Bio) từ Zalo
GET/api/accounts/:user/logsNhật ký hoạt động Node (filter level)
GET/api/accounts/:user/connectionsLịch sử kết nối/ngắt kết nối
DEL/api/accounts/:user/logsXóa nhật ký hoạt động
🚑 DLQ Cứu Hộ — 7 Endpoints
GET/api/dlqDanh sách 100 tin kẹt mới nhất
POST/api/dlq/flushRetry All - Vét kho bơm lại toàn bộ
POST/api/dlq/retry-oneRetry 1 tin theo index
POST/api/dlq/retry-selectedRetry nhiều tin chọn lọc
POST/api/dlq/delete-selectedXóa nhiều tin chọn lọc
POST/api/dlq-testBắn tin lỗi cố ý vào DLQ để test
DEL/api/dlqXóa sạch toàn bộ kho DLQ
🌐 Kho Proxy — 8 Endpoints
GET/api/proxies150 Proxy mới nhất
GET/api/proxies/statsThống kê: Total / Active / Dead
POST/api/proxiesNạp Proxy hàng loạt (batch 500)
POST/api/proxies/check-all⚡ Quét ngầm toàn bộ (parallel 50)
POST/api/proxies/checkKiểm tra 1 IP đơn lẻ
PUT/api/proxiesSửa địa chỉ Proxy
DEL/api/proxies/dead🧹 Xóa tất cả IP hỏng
DEL/api/proxies/all💀 Xóa toàn bộ kho Proxy
⚙️ Hệ Thống, Hạ Tầng & Alerting — 16+ Endpoints
GET/api/system/infra-statusKiểm tra ping latency Dragonfly, Supabase, Queue, Circuit Breaker
POST/api/system/infra-testPre-flight test kết nối Dragonfly/Supabase mới trước khi đổi
POST/api/system/infra-reconnectHot-swap tức thì Dragonfly & Supabase mà không gián đoạn Socket
POST/api/system/restore-sessionsNạp lại và khôi phục toàn bộ phiên Zalo vào Workers
POST/api/system/telegram-configCấu hình Telegram Bot Token & Chat ID nhận cảnh báo sự cố
POST/api/system/telegram-testBắn tin nhắn test thử nghiệm bot Telegram
GET/api/healthHealth check: CPU, RAM, Workers, Uptime
GET/api/stats/dashboardDashboard: Metrics + Nodes + Cluster
GET/api/system/rolesDanh sách AI Roles (từ Redis)
POST/api/system/rolesCập nhật AI Roles tùy chỉnh
GET/api/system/shardsDanh sách Shard VPS (từ Redis)
POST/api/system/shardsCập nhật danh sách Shard tùy chỉnh
POST/api/system/clear-redis-inboxXóa sạch hàng đợi zalo_inbox
POST/api/system/cleanup-logsDọn dẹp log cũ (tùy chỉnh số ngày)
GET/api/system/vault/exportXuất backup Vault (tải file JSON)
POST/api/system/vault/importPhục hồi thảm họa từ file backup

12. Mở Rộng Đa VPS & Biến Môi Trường VPS

Bảng Biến Môi Trường Đầy Đủ (8 ENV)
BiếnMặc địnhMô tả
SHARD_ID1ID định danh VPS. Shard 1 = Master, 2+ = Worker
DRAGONFLY_URLredis://dragonfly:6379URL kết nối Redis/Dragonfly Cache
SUPABASE_URL—URL dự án Supabase (PostgreSQL)
SUPABASE_KEY—Service Role Key (quyền full database)
PORT3000Cổng HTTP Server
MAX_WORKERSAuto (CPU cores)Số Worker Threads. Để trống = tự phát hiện CPU
APP_HUB_SECRET_KEYTNG_HUB_SECRET_KEY_2026Khóa xác thực API App Hub HLV
ZALO_API_KEYTNG-SECRET-XYZ-2026Khóa bảo mật X-API-KEY cho n8n gọi RPC
Quy trình thêm VPS Worker mới trên Coolify
  1. Trên Coolify → New Service → Docker/Git. Clone cùng repo tng-zalo-core-main.
  2. Tab Environment Variables → Set SHARD_ID=2, DRAGONFLY_URL=redis://IP_VPS_1:6379, SUPABASE_URL, SUPABASE_KEY.
  3. Set MAX_WORKERS=4 (nếu VPS yếu 1 Core muốn ép 4 luồng).
  4. Deploy. Kiểm tra Dashboard → Panel Cluster sẽ hiện Shard 2 online (Heartbeat 5s/lần).
  5. Vào UI → Chọn Nodes → Bulk Action → Di cư Shard → Chọn Shard 2. Nodes sẽ tự động chuyển qua VPS mới (Hot-Migration).

13. Cơ Chế Chống Khóa Ẩn & Độ Tin Cậy GUARD

Idempotency KeyRedis SET idempotency:{msg_id} NX EX 86400. Bỏ qua lệnh trùng 24h. Chống n8n retry spam.
Human-Like DelaybaseDelay = msg.length × 50ms + Jitter 0.7–1.3x (800ms–10s). Gửi typing trước, đợi readDelay 500ms–2.5s.
SDK TimeoutBọc mọi lệnh Zalo trong Promise.race timeout 12s. Tránh treo Worker vĩnh viễn khi UID sai.
Image MetadataTự đọc header PNG/JPEG/GIF lấy width/height. Tránh Zalo API crash khi truyền ảnh thiếu metadata.
Circuit BreakerNếu Redis Queue lỗi >30 lần liên tiếp → Dập cầu dao 60s bảo vệ hệ thống. Tự reset khi hết cooldown.
Staggered RestoreKhởi động lại các Node với delay ngẫu nhiên 3s–8s giữa mỗi Node. Tránh Zalo phát hiện burst login.
Event BatchingGom cụm tối đa 50 events/500ms → Pipeline LPUSH zalo_inbox. Giảm tải Redis 50× so với gửi lẻ.
Auto CleanupMỗi 6h tự xóa log hoạt động >7 ngày và log kết nối >30 ngày. API: POST /api/system/cleanup-logs.

14. Bảo Trì & 7 Phương Án Zero-Downtime PATCH

A. Update Mềm — Sửa JSON Payload

Sửa file public/js/actions-db.js → F5 tải lại trang → Mini Postman & Thư viện Actions nhận payload mới ngay. Không cần restart Server.

B. Update Nóng — CUSTOM_REQUEST

Khi Zalo đổi API khiến hàm SDK cũ lỗi → Mini Postman chọn CUSTOM_REQUEST → Điền Endpoint + JSON → Backend mã hóa AES bắn thẳng Zalo, bypass SDK.

C. Vá Cứng — Patch-Package

Sửa code trong node_modules/zca-js/ → Chạy npx patch-package zca-js → File .patch sinh ra trong patches/ → Tự áp dụng khi npm install qua hook postinstall.

D. Vá Nóng — Hotfix Live Injection ⚡

Tạo file đúng tên lệnh trong thư mục hotfixes/:

// hotfixes/sendMessage.js
module.exports = { execute: async (api, args) => {
await api.sendMessage(...args);
}};

Worker tự xóa require.cache → nạp code mới real-time. Zero-Downtime, không restart.

E. Hot-Swap Hạ Tầng — Live Reconnect (Dragonfly & Supabase)

Thay đổi URL/Key kết nối Dragonfly Redis hoặc Supabase ngay trên Modal Hạ Tầng. Manager và các Worker Threads chuyển đổi client ngầm mà không làm đứt kết nối Zalo Socket của các phiên đang hoạt động. Tự lưu cấu hình bền vững vào data/runtime_override.json.

F. Chống Tràn RAM — Local Disk Spooling Buffer

Khi Dragonfly gặp sự cố, Worker Threads tự động chuyển tiếp các sự kiện Zalo vào file đĩa cục bộ data/worker_spool_${pid}.log (ngưỡng 2000 sự kiện) thay vì giữ RAM. Tự drain lên Redis khi kết nối hồi phục.

G. Giám Sát Chủ Động — Circuit Breaker & Telegram Alert

Cầu dao tự ngắt bảo vệ hệ thống khi lỗi Redis liên tiếp và tự động gửi tin nhắn cảnh báo đỏ tức thì tới Telegram Bot của đội ngũ kỹ thuật.

15. Từ Điển Mã Lỗi & Xử Lý Sự Cố ERRORS

Bảng tra cứu Mã Lỗi Zalo thường gặp
LỗiÝ nghĩaCách xử lý
-11Mất kết nối mạng / Proxy dieKiểm tra Proxy, bấm ⚡ quét lại kho
-14Sai tham số JSON PayloadKiểm tra cấu trúc args trong actions-db.js
-201Cookie hết hạn / Bị đăng xuấtQuét lại mã QR cho Node bị ảnh hưởng
-13003UID không tồn tại / Bị chặnKiểm tra UID người nhận, đối chiếu Zalo
TimeoutSDK treo >12s không phản hồiUID sai hoặc Zalo quá tải. Tự retry qua DLQ
ECONNRESETProxy bị ngắt giữa chừngĐổi Proxy sạch, khởi động lại Node
QR ExpiredMã QR hết hạn 180sHệ thống tự làm tươi QR mới (auto-retry)

16. Quản Trị Hạ Tầng & Hot-Swap Zero-Downtime INFRA_HUB

Trung tâm điều khiển kết nối hạ tầng giúp Kỹ thuật viên (DevOps) giám sát độ trễ (ping), kiểm tra thử nghiệm (Pre-flight test) và chuyển đổi kết nối Dragonfly Cache hoặc Supabase Database mà không cần khởi động lại container, không gián đoạn các kết nối Zalo WebSocket.

1. Cách Mở Modal Quản Trị Hạ Tầng
  • Nút Hạ Tầng trên thanh Header (cạnh Theme Selector).
  • Thẻ Hạ Tầng Cluster ở Sidebar bên trái (click nút "Hạ Tầng").
  • Bảo Mật Tuyệt Đối: Toàn bộ API và Modal Hạ Tầng được khóa an toàn sau lớp xác thực JWT / Master Key (X-API-KEY), không phơi bày ra màn hình login công cộng để chống tin tặc dò quét IP.
2. Pre-flight Test & Hot-Swap
  • Bấm Kiểm Tra Kết Nối để test thử URL/Key mới trước khi lưu.
  • Bấm Áp Dụng Hot-Swap: Manager cập nhật dynamic client và broadcast UPDATE_REDIS_URL đến tất cả Worker Threads.
  • Ghi nhớ cấu hình tự động vào data/runtime_override.json.
3. Cơ Chế Local Disk Spooling

Khi Dragonfly gián đoạn, Worker Threads tự động chuyển hướng các sự kiện Zalo vào file đĩa cục bộ data/worker_spool_${pid}.log (ngưỡng 2000 sự kiện), chống sập tràn bộ nhớ RAM (OOM). Khi kết nối hồi phục, hệ thống tự động drain toàn bộ tin nhắn lên Redis.

4. Circuit Breaker & Telegram Alert

Cầu dao tự ngắt bảo vệ hệ thống khi lỗi Redis liên tiếp. Đồng thời hệ thống tự động bắn tin nhắn báo động khẩn cấp tới nhóm kỹ thuật qua Telegram Bot Token & Chat ID (cấu hình trực tiếp trong Modal Hạ Tầng).

5. Nạp Lại Toàn Bộ Phiên (Restore Sessions)

Khi cần nạp lại phiên Zalo vào Worker sau khi chuyển đổi Supabase: Bấm nút Nạp Lại Toàn Bộ Phiên Zalo trong Modal Hạ Tầng hoặc gọi POST /api/system/restore-sessions. Manager sẽ quét lại database và nạp tài khoản vào Worker Threads theo thuật toán Staggered Restore (delay 3s-8s).