ChatAI Node Server – Tài liệu

1. Tổng quan

Server chỉ xây cầu và chuyển tiếp: nhận request, đưa job vào queue, broadcast/notify qua WebSocket. Không lưu trữ tin nhắn – client tự lo lưu trữ và dọn dẹp. Mỗi request từ client (HTTP hoặc WebSocket) đều kích hoạt xử lý queue.

2. Multi-server (Sub servers)

Cho phép thêm các server Node khác làm sub, điều phối và phân chia tầng theo server sub.

2.1 Bật / tắt multi-server

• Trong Node Admin (/nodeadmin/) → tab Multi-server.
• Bật checkbox Bật multi-server: server hiện tại trở thành server điều phối (orchestrator).
• Khi tắt: server hoạt động đơn lẻ, không gửi job tới sub.

2.2 Server điều phối và server sub

• Server điều phối: server nào bật multi-server (và có danh sách sub) sẽ là server điều phối. Mỗi khi xử lý job (broadcast, notify_user, persist_broadcast, p2p_signal), sau khi xử lý local, nó gửi cùng job tới từng sub qua POST {sub.url}/api/sub/receive.
• Server sub: các server được thêm vào danh sách sub. Sub phải chạy cùng phiên bản và cấu hình cùng X-Sub-Secret (xem 2.4). Sub nhận job qua POST /api/sub/receive, thêm vào queue local và xử lý (broadcast/notify trong phạm vi sub đó).

2.3 Thêm / xóa server sub

• Trong Node Admin → Multi-server: nhập URL (vd: http://localhost:3101), Tên, Tầng (số, mặc định 0). Bấm Thêm sub.
• Tầng (tier): dùng để phân tầng sub (vd: tầng 0 = ưu tiên cao, tầng 1 = bổ sung). Hiện tại mọi job đều được gửi tới tất cả sub; tầng có thể dùng sau cho định tuyến theo phòng hoặc nhóm.
• Xóa sub: bấm Xóa trên từng dòng trong bảng danh sách sub.

2.4 Bảo mật: X-Sub-Secret

Để sub chấp nhận job từ server điều phối, mọi server (điều phối và sub) phải cấu hình cùng một secret.

• Trên server điều phối: khi gửi POST tới {sub}/api/sub/receive, gửi header X-Sub-Secret: <secret>.
• Trên server sub: endpoint POST /api/sub/receive chỉ chấp nhận request có header X-Sub-Secret khớp với cấu hình.
• Cấu hình: trong servernode/src/config.js, mục multiServer.subSecret. Hoặc biến môi trường SUB_SECRET / CHATAI_SUB_SECRET. Đổi giá trị mặc định khi triển khai thật.

2.5 Luồng job khi multi-server bật

1. Client gửi tin (vd: POST /api/chat/send) tới server điều phối.
2. Điều phối thêm job vào queue local, xử lý (broadcast trong phòng trên chính nó).
3. Điều phối gửi POST tới từng sub: { "type": "broadcast", "payload": { ... } } kèm X-Sub-Secret.
4. Mỗi sub nhận request, kiểm tra secret, thêm job vào queue local và xử lý (broadcast trên sub đó).

3. API liên quan multi-server

4. Lưu trữ danh sách sub

Danh sách sub và trạng thái bật/tắt được lưu trong file servernode/data/sub-servers.json (tự tạo thư mục nếu chưa có). Server khởi động lại vẫn giữ cấu hình.

5. Node Admin – Đăng nhập và phân quyền

Giao diện quản trị tại /nodeadmin/. Hỗ trợ hai phương thức đăng nhập:

5.1 Đăng nhập User (userId + mật khẩu)

• Chọn tab User, nhập userId và mật khẩu (nếu user đã đặt).
• User phải tồn tại trong hệ thống (tạo qua tab User bởi admin).
• Nếu user có token viewer được cấp: đăng nhập thành công sẽ hiển thị toàn bộ giao diện admin theo quyền (Token, Device, User, v.v.).
• Nếu không có token: chỉ hiển thị tab Tài khoản – quản lý thiết bị và token API của mình.

5.2 Đăng nhập Admin (token)

• Chọn tab Admin, dán token quản trị (X-Admin-Token).
• Token được cấp bởi super admin hoặc admin có quyền.

5.3 Phân quyền (admin/member)

Cách cấp token: Super admin tạo token mới → chọn role admin (nhập User được quản lý) hoặc viewer (nhập UserId).

6. Token API của user

User tạo token để tích hợp vào App (mobile, web, bot). Token dùng header X-User-Token khi gọi API.

6.1 API User (cần X-User-Token – session hoặc token API)

6.2 API Admin (cần X-Admin-Token)

6.3 Xác thực X-User-Token

API chấp nhận hai loại:

• Session token: trả về khi đăng nhập POST /api/auth/login (userId + password). Hết hạn sau 24h.
• Token API: tạo trong Node Admin (tab API Token hoặc Tài khoản). Không hết hạn, dùng cho tích hợp App.

7. Device API

Device hoạt động độc lập, được cấp token qua user hoặc admin. Xác thực bằng X-User-Token hoặc userId trong body/query.

7.1 API User (X-User-Token hoặc userId)

7.2 API Admin (X-Admin-Token)

7.3 WebSocket với device token

const ws = new WebSocket('wss://example.com/ws');
ws.onopen = () => {
  ws.send(JSON.stringify({ type: 'auth_device', token: 'YOUR_DEVICE_TOKEN' }));
};
ws.onmessage = (ev) => {
  const m = JSON.parse(ev.data);
  if (m.type === 'auth_ok') {
    ws.send(JSON.stringify({ type: 'subscribe', roomId: 'device_group:' + groupId }));
  }
};

8. Auth API

9. Bảo mật (Security)

Server tích hợp các lớp bảo mật cho môi trường production:

• Rate limit: Giới hạn request theo IP (mặc định 200 req/phút) – chống DDoS.
• Auth rate limit: Giới hạn thử đăng nhập (mặc định 15 lần/15 phút) – chống brute-force.
• Chống inject/XSS: Kiểm tra body JSON, từ chối nội dung chứa script, SQL-like, eval, v.v.
• Token format: Validate format token (độ dài, ký tự) trước khi xử lý – chống token giả mạo.
• Security headers: X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, Referrer-Policy.
• Cảnh báo: Lưu log cảnh báo (rate limit, inject, token) – xem qua GET /api/admin/security/warnings (cần X-Admin-Token).

9.1 Cấu hình (biến môi trường)

10. Tài liệu khác

• DEVICE_API.md – Chi tiết Device API.
• MULTI_SERVER.md – Chi tiết Multi-server.
• LUU_TRU_MEMORY_FILE_BACKUP.md – Lưu trữ và backup.
• README server: servernode/README.md – API HTTP, WebSocket, queue, session, dashboard.