1. Architecture
Social Tool Documentation
  • Tổng quan
  • Bussiness | Logic
    • Bussiness | Logic
  • Project
    • ADMIN
      • Tổng quan ADMIN
      • Architecture
        • System architecture
        • Code structure
      • Deployment
        • Local
        • Staging
        • Product
      • Hướng dẫn sử dụng
        • Đăng nhập
        • FAQ
        • Mạng xã hội
          • Tài khoản mạng xã hội
          • Nội dung bài viết & bình luận
          • Quản lý liên kết
          • Thư viện hình ảnh
          • Thu thập dữ liệu
        • Hệ thống
          • Quản lý proxy
        • Chiến dịch
          • Tạo & quản lý chiến dịch
          • Đăng nhập tài khoản
          • Check Proxy
          • Join Group
    • API
      • Tổng quan API
      • Architecture
        • System architecture
        • Database schema
        • Code structure
      • Deployment
        • Local
        • Staging
        • Product
      • API Interface
        • 🔑 Identity & Session
          • List users
          • Create user
          • Update info user
          • Update info user
          • List user departments
          • Delete user
          • List user's AI keys
          • Create AI key
          • Get user's active API key
          • Get supported services
          • Get supported AI models
          • Update AI key
          • Delete AI key
          • Get AI key by ID
          • List departments
          • Create department
          • Update department
          • Create department
          • Update department
          • Update department roles
          • Get department roles
          • Update department status
          • Delete department
          • List user sessions
          • Create user session
          • Delete user session
          • Get user sessions by user ID
          • Delete all user sessions
          • Update user session status
          • List user activity logs
          • Create user activity log
          • Get user activity logs
          • Delete user activity logs
          • User login
          • User registration
          • User logout
          • Logout from all devices
          • Refresh access token
          • Create api key
          • Reset password
          • Get current user
          • Get user roles
          • Create role
          • Update role
          • Update role
          • Update role
          • List user permission groups
          • Get user permission group by ID
          • Delete user permission group
          • Create user permission group
          • Update user permission group
          • Get all user permission groups with permissions
        • 🛰️ Proxy & Connectivity
          • List proxies
          • Create proxy
          • Create many proxies
          • Update proxy
          • Delete proxy
          • Get proxy by ID
          • Import proxies from CSV/Excel
          • Check expired proxies
          • Kiểm tra proxy (qua Campaign)
          • Xóa proxy
          • Cập nhật proxy
          • Proxy Group list
          • Create a Proxy Group
          • Get a Proxy Group by ID
          • Update a Proxy Group
          • Delete a Proxy Group
          • Delete a Proxy Group
          • List proxy providers
          • Create proxy provider
          • Update proxy provider
          • Delete proxy provider
          • Get proxy provider by ID
          • Import proxy packages from CSV
          • List proxy packages
          • Create proxy package
          • Update proxy package
          • Delete proxy package
          • Get proxy package by ID
          • Import proxy packages from CSV
        • 📱 Social Management
          • List socials
          • Create social
          • Update social
          • Delete social
          • Get social by ID
          • List social accounts
          • Create social account
          • Create social account
          • Get account tasks
          • Assign proxies to social account
          • Update social account
          • Delete social account
          • Get social account by ID
          • Join social account
          • Cancel social accounts
          • Cancel social accounts
          • Import social accounts from file
          • Get account usage statistics
          • Push cookies manually for specific accounts (via Campaign)
          • Đổi tên nhiều tài khoản (qua Campaign)
          • Đổi mật khẩu nhiều tài khoản (qua Campaign)
          • Đổi ảnh đại diện (qua Campaign)
          • Social Account Group list
          • Create a Social Account Group
          • Get a Social Account Group by ID
          • Create a Social Account Group
          • Delete a Social Account Group
          • List social pages
          • Create social page
          • Update social page
          • Delete social page
          • Get social page by ID
          • Batch update social page status
          • Batch delete social pages
          • Import social pages from file
          • Search social pages
          • Batch delete social pages
          • Social Page Group list
          • Create a Social Page Group
          • Get a Social Page Group by ID
          • Update a Social Page Group
          • Delete a Social Page Group
          • List social actions
          • Create social action
          • Update social type
          • Delete social action
          • Get social type by ID
          • List social pages
          • Create social content
          • Update social content
          • Delete social content
          • Get social content by ID
          • Batch delete social content
          • Import social accounts from file
          • Create a new social content group
          • Get paginated list of social content groups
          • Get social content group by ID
          • Update social content group
          • Soft delete social content group
          • Batch delete social content groups
          • Delete social content group
          • Get groups by social platform ID
          • Social Image list
          • Create a Social Image
          • Get a Social Image by ID
          • Update a Social Image
          • Delete a Social Image
          • Social Collect Data list
          • Create a Social Collect Data
          • Get a Social Collect Data by ID
        • 📁 Campaign Management
          • List campaigns
          • Create campaign
          • Update campaign
          • Delete campaign
          • Get campaign by ID
          • Create campaign platform
          • List campaign platforms
          • Update campaign platform
          • Delete campaign platform
          • Get campaign platform by ID
          • Create campaign platform
          • Create campaign platform
          • Clone campaign platforms
          • Cancel multiple campaign platforms
          • List campaign joins
          • Create campaign platform
          • List campaign joins
          • Update campaign platform
          • Update campaign platform
          • Update campaign platform
          • Update campaign platform
          • List jobs
          • Update job
          • Delete job
          • Get job by ID
          • List campaign platform tasks
          • Create campaign platform task
          • Update campaign platform task
          • Delete campaign platform task
          • Get campaign platform job task by ID
          • List Report Categories
          • Create Report Categories
          • Create Report Categories
          • Create Report Categories
          • List Report Details
          • Create Report Details
          • Create Report Details
          • Create Report Details
    • TOOL
      • Tổng quan TOOL
      • Architecture
        • Database schema
        • System architecture
        • Code structure
      • Deployment
        • Local
        • Staging
        • Product
      • API Interface
        • 🎯 NATS — Task
          • [NATS RPC] Tạo batch Task mới
          • [NATS RPC] Lấy danh sách tất cả Tasks
          • [NATS RPC] Đếm số Task đang chờ xử lý
          • [NATS RPC] Xóa tất cả Tasks
        • 🍪 NATS — Cookie
          • [NATS RPC] Thêm batch Cookie (Auto Login)
          • [NATS RPC] Lấy danh sách tất cả Cookies
          • [NATS RPC] Xóa tất cả Cookies
        • 🌐 NATS — Proxy
          • [NATS RPC] Gửi batch Proxy để kiểm tra
        • 🔗 NATS — TaskJoin
          • [NATS RPC] Tạo lệnh tham gia Group
          • [NATS RPC] Kiểm tra trạng thái tham gia Group
        • 📤 NATS — Callbacks
          • [NATS PUB] Kết quả thực thi Task
          • [NATS PUB] Kết quả Crawl dữ liệu
          • [NATS PUB] Kết quả Auto Login
          • [NATS PUB] Kết quả kiểm tra Proxy
          • [NATS PUB] Kết quả tham gia Group
          • [NATS PUB] Kết quả kiểm tra trạng thái tham gia
        • 📊 HTTP — Logs & Info
          • Service Root — Thông tin Worker
          • Health Check
          • Đọc file log
          • Log hôm nay
          • Log theo ngày cụ thể
          • Danh sách ngày có log
          • Test kết nối ChatGPT
        • 📋 HTTP — Data Query
          • Danh sách Tasks (phân trang + lọc)
          • Xóa tất cả Tasks
          • Danh sách tất cả Cookies
          • Xóa tất cả Cookies
          • Xóa Cookie theo _id
          • Danh sách Proxies (lọc theo task_id)
          • Xóa tất cả Proxies
          • Proxy Checks đang chờ xử lý
          • Proxy Checks đã hoàn thành
          • Xóa Proxy theo _id
          • Danh sách Task Join (phân trang + lọc)
          • Tạo Task Join (HTTP mode)
          • Xóa tất cả Task Join
  • Schemas
    • AIInfo
    • CommentInfo
    • ReplyInfo
    • ShareInfo
    • CaptchaInfo
    • PageInfo
    • SocialAccountInfo
    • ProxyInfo
    • SocialInfo
    • ActionInfo
    • CreateTaskPayload
    • CreateCookiePayload
    • CreateProxyPayload
    • CreateTaskJoinPayload
    • NatsAcceptedResponse
    • NatsRejectedResponse
    • NatsErrorResponse
    • TaskCompletedPayload
    • CookieUpdatePayload
    • ProxyCheckResultPayload
    • TaskJoinResultPayload
    • TaskJoinCheckResultPayload
    • PagingInfo
    • AppError
  1. Architecture

System architecture

Kiến trúc Hệ thống — Social Tool Worker#

Tài liệu kỹ thuật – Phiên bản 1.0
Mô tả kiến trúc tổng quan, luồng xử lý và khả năng mở rộng của Social Tool Worker

1. Tổng quan#

Social Tool Worker là thành phần thực thi (Automation Worker) trong kiến trúc tổng thể Social Tool. Worker hoạt động như một micro-service độc lập, nhận lệnh từ API Server qua NATS, thực thi hành động trên trình duyệt headless, và trả kết quả.

2. Technology Stack#

Thành phầnCông nghệVai trò
RuntimeBun ≥ 1.2.5JavaScript/TypeScript runtime hiệu suất cao
HTTP FrameworkElysiaJS + SwaggerPhục vụ REST API và health check
BrowserPuppeteer + Stealth PluginĐiều khiển Chrome headless, chống phát hiện bot
CursorGhost CursorMô phỏng di chuyển chuột như người thật
ORMTypegoose + MongooseType-safe MongoDB access
DatabaseMongoDB ≥ 7Lưu trữ task queue, kết quả thực thi
MessagingNATSGiao tiếp bất đồng bộ với API Server
AIOpenAI (GPT-4o-mini)Sinh nội dung comment/reply thông minh
CaptchaOMO Captcha ServiceVượt rào cản captcha tự động
ContainerDocker + SupervisorĐóng gói, auto-restart tiến trình

3. Kiến trúc tổng thể#

3.1. Vị trí trong hệ thống#

Luồng hoạt động:
1.
Admin Dashboard gửi yêu cầu tạo chiến dịch tới API Server qua HTTP.
2.
API Server (Scheduler/Cron) phân rã chiến dịch thành task nhỏ và publish lên NATS.
3.
NATS tự động phân phối task cho Worker đang idle (load balancing).
4.
Worker nhận task, mở trình duyệt headless, nạp cookie + proxy, thực thi hành động trên mạng xã hội.
5.
Worker gửi kết quả (thành công/thất bại) trở lại API Server qua NATS hoặc Webhook.

3.2. Kiến trúc bên trong Worker#

┌───────────────────────────────────────────────────────┐
│                   Social Tool Worker                   │
│                                                       │
│  ┌──────────┐    ┌──────────┐    ┌──────────────┐    │
│  │ NATS Sub │───>│ Services │───>│ Browser Mgr  │    │
│  │ (Events) │    │ (Logic)  │    │ (Puppeteer)  │    │
│  └──────────┘    └──────────┘    └──────────────┘    │
│       │               │                │              │
│       │          ┌────┘                │              │
│       │          │                     ▼              │
│       │     ┌────┴───┐          ┌──────────┐         │
│       │     │  Cron  │          │  Chrome  │         │
│       │     │ Engine │          │ Headless │         │
│       │     └────────┘          └──────────┘         │
│       │                              │                │
│       ▼                              ▼                │
│  ┌──────────┐                ┌──────────────┐        │
│  │ MongoDB  │                │ Social Media │        │
│  │ (Queue)  │                │  Platforms   │        │
│  └──────────┘                └──────────────┘        │
└───────────────────────────────────────────────────────┘
Các thành phần bên trong Worker:
#Thành phầnVai trò
1NATS SubscriberLắng nghe event từ API Server, nhận task mới
2Service LayerXử lý nghiệp vụ: validate task, chuẩn bị payload
3Cron EngineQuét MongoDB, lấy task PENDING, điều phối thực thi
4Browser ManagerQuản lý pool session Puppeteer, giới hạn concurrent
5MongoDBLưu task queue tạm, kết quả xử lý
6NATS Publisher / WebhookGửi kết quả trở lại API Server

4. Hệ thống phân bổ Worker động#

Đây là cơ chế cốt lõi giúp Worker tối ưu tài nguyên. Hệ thống tự động phân chia CRON_TASK_LIMIT worker giữa 4 module dựa trên khối lượng công việc.
Quy tắc phân bổ:
Nếu không có module nào có task pending → chế độ Standby: mỗi module nhận 1 worker.
Nếu có N module active → chia đều CRON_TASK_LIMIT / N worker, phần dư ưu tiên module đầu.
Graceful shutdown: khi tái phân bổ, Worker đợi task đang chạy hoàn thành (tối đa 120s) trước khi dừng.
Debounce: tái phân bổ tối thiểu cách nhau 10 giây để tránh thrashing.

5. Luồng xử lý Task chi tiết#

6. Giao tiếp NATS#

6.1. Các event lắng nghe (Subscribe)#

NATS SubjectModuleMô tả
Task eventsTaskNhận task mới (like, comment, share...)
Cookie eventsCookieNhận yêu cầu login/lấy cookie
Proxy eventsProxyNhận yêu cầu kiểm tra proxy
TaskJoin eventsTaskJoinNhận yêu cầu join group

6.2. Phản hồi kết quả#

Worker gửi kết quả về API Server qua hai kênh:
1.
Webhook HTTP — Gọi trực tiếp endpoint API Server kèm kết quả.
2.
NATS publish — Publish kết quả lên subject tương ứng.
Cơ chế retry: nếu webhook fail, tăng call_webhook_count và thử lại.

7. Khả năng mở rộng (Scalability)#

Scale ngang: Thêm container Worker mới, NATS tự động load balance task.
Scale dọc: Tăng CRON_TASK_LIMIT và BROWSER_LIMIT_PER_PROCESS trong .env.
Tách biệt hoàn toàn: Worker không kết nối trực tiếp tới MySQL của API Server, chỉ giao tiếp qua NATS/Webhook.
Docker Compose: Mỗi Worker chạy trong container riêng, dễ dàng replicate.

8. Biến môi trường quan trọng#

BiếnMô tảGiá trị mặc định
USE_NATSChế độ NATS (true) hay HTTP (false)true
CRON_TASK_LIMITTổng số worker slot10
BROWSER_LIMIT_PER_PROCESSSố browser mỗi process2
NATS_URLURL kết nối NATSnats://shared-nats:4222
NATS_QUEUE_GROUPQueue group cho load balancesocial-tool-group
DB_MONGO_*Cấu hình kết nối MongoDB—
PROXY_API_URLURL dịch vụ Proxy—
KEY_CHATGPTAPI key OpenAI—
OMO_CAPTCHA_KEYAPI key dịch vụ Captcha—
DEBUG_PUPPETEER_HEADLESSBật/tắt headless modetrue
Tài liệu được cập nhật lần cuối: 2026. Mọi thắc mắc vui lòng liên hệ đội ngũ kỹ thuật.
Modified at 2026-03-26 03:07:47
Previous
Database schema
Next
Code structure
Built with