Hướng dẫn Quản trị viên

Tài liệu vận hành hệ thống MSA — Multi Social Analytics dành cho System Administrator, DevOps và Project Admin: dựng môi trường, cấu hình khóa bí mật, quản trị cơ sở dữ liệu, giám sát sức khỏe hệ thống và xử lý sự cố.

Phiên bản 2026.07Đối tượng Admin / DevOpsNền tảng Docker Compose

§Giới thiệu tài liệu

MSA là hệ thống phân tích hiệu suất nội dung đa nền tảng, đóng gói thành 6 service Docker độc lập. Tài liệu này đi theo đúng thứ tự một Admin cần làm: dựng môi trường trước, cấu hình sau, rồi mới đến vận hành hằng ngày và xử lý sự cố.

ℹ️ Quy ước trong tài liệu

Mọi câu lệnh trong tài liệu đều chạy từ thư mục gốc của dự án (nơi chứa docker-compose.yml).

01Kiến trúc & 6 service

Toàn bộ hệ thống chạy trên một mạng Docker nội bộ tên msa_network. Các service gọi nhau bằng tên service (ví dụ postgres, backend-ai), còn bạn truy cập từ máy thật qua cổng host ở bảng dưới.

Service	Container	Image / Nguồn	Cổng host	Vai trò
postgres	`msa_postgres`	`postgres:16-alpine`	`5432`	Cơ sở dữ liệu chính, schema 3NF
redis	`msa_redis`	`redis:7-alpine`	`6380` → 6379	Cache nóng & bộ đếm hạn mức API
dbgate	`msa_dbgate`	`dbgate/dbgate:latest`	`8081` → 3000	Giao diện web quản trị PostgreSQL
backend-ai	`msa_backend_ai`	build `./backend-ai`	`8000`	Python FastAPI — NLP cảm xúc & Chat AI bằng Gemini 2.5 Flash (đã bỏ PhoBERT từ T121, xử lý OOM khi deploy)
backend-core	`msa_backend_core`	build `./backend-core`	`5144`	ASP.NET Core Web API + Background Worker
frontend	`msa_frontend`	build `./frontend`	`3000`	Next.js — giao diện người dùng & Admin Console

Thứ tự phụ thuộc khi khởi động

Docker Compose đã khai báo sẵn depends_on: postgres → redis → backend-ai → backend-core → frontend (dbgate chạy song song).

⚠️ Lưu ý về cổng Redis

Redis map 6380 (host) → 6379 (container) để tránh đụng Redis cài sẵn trên máy. Khi kết nối từ máy thật hãy dùng cổng 6380; khi cấu hình giữa các container vẫn dùng redis:6379.

02Chuẩn bị môi trường

🐳

Docker Desktop

Bắt buộc — chứa cả Docker Engine và Docker Compose v2. Phải đang chạy trước mọi câu lệnh.

🔑

Gemini API Key

Cần cho AI Chat và Executive Insights. Lấy tại Google AI Studio.

📺

Google Cloud Project

Bật YouTube Data API v3, tạo OAuth Client ID cho luồng kết nối YouTube.

📘

Meta App

Facebook App có quyền đọc Page Insights, cấu hình Redirect URI trỏ về backend.

03Khởi chạy hệ thống

Cách 1 — Chạy toàn bộ stack (khuyến nghị)

docker compose up -d --build
docker compose logs -f

Lần chạy đầu tiên sẽ mất vài phút vì phải build 3 image (backend-ai, backend-core, frontend). Các lần sau chỉ cần docker compose up -d.

Cách 2 — Chỉ chạy hạ tầng, tự chạy code ở máy

Phù hợp khi đang phát triển và muốn hot-reload frontend/backend ngoài Docker:

docker compose up -d postgres redis dbgate

Địa chỉ truy cập sau khi khởi chạy

Thành phần	Địa chỉ (local)	Ghi chú
Giao diện chính	`http://localhost:3000`	Landing page → đăng nhập
Backend Web API	`http://localhost:5144`	Base path API: `/api/v1`
AI Core (FastAPI)	`http://localhost:8000/docs`	Swagger UI tự sinh của FastAPI
DBGate	`http://localhost:8081`	Quản trị PostgreSQL bằng trình duyệt

🚨 Phân biệt down và down -v

docker compose down chỉ dừng container, dữ liệu vẫn còn.

docker compose down -v xóa luôn volume — toàn bộ database bị xóa sạch không khôi phục được. Chỉ dùng khi thực sự muốn nạp lại schema từ đầu, và hãy sao lưu trước (xem mục 12).

04Cấu hình & khóa bí mật

Biến	Service	Ý nghĩa
`ConnectionStrings__DefaultConnection`	backend-core	Chuỗi kết nối PostgreSQL
`Redis__ConnectionString`	backend-core	Địa chỉ Redis nội bộ kèm mật khẩu
`AiCore__BaseUrl`	backend-core	Địa chỉ AI Core trong mạng Docker: `http://backend-ai:8000`
`Authentication__Jwt__Key`	backend-core	Khóa ký JWT — tối thiểu 32 ký tự
`GoogleApi__SystemGeminiKey`	backend-core	Khóa Gemini hệ thống dùng cho hạng Free Trial (10 lượt Chat AI đầu). Thiếu khóa này → UI báo "Chưa có API Key hợp lệ để kết nối tới dịch vụ AI"
`FptAi__MarketplaceKey`	backend-core	Khóa FPT AI Marketplace (DeepSeek-V4-Flash) dùng cho hạng Pro — thiếu key thì Pro tự fallback về Gemini hệ thống
`DATABASE_URL`	backend-ai	Chuỗi kết nối PostgreSQL theo cú pháp Python
`GEMINI_API_KEY`	backend-ai	Khóa Google Gemini cho NLP cảm xúc & luồng AI Chat gọi trực tiếp AI Core
`NEXT_PUBLIC_API_URL`	frontend	Base URL API mà trình duyệt gọi tới

🔒 Quy tắc bắt buộc về khóa bí mật

Các giá trị trong docker-compose.yml hiện là placeholder dành cho môi trường phát triển. Tuyệt đối không thay bằng khóa thật rồi commit lên Git.

Khóa thật phải đặt trong file cấu hình cục bộ đã nằm trong .gitignore: appsettings.Development.json cho .NET và .env cho Python/Next.js.

05Quản trị Database qua DBGate

DBGate là giao diện web quản trị PostgreSQL, đã được đóng gói sẵn trong stack.

Mở DBGateTruy cập http://localhost:8081 sau khi container msa_dbgate đã chạy.
Tạo kết nối mớiChọn Add connection → engine PostgreSQL.
Điền thông tin kết nốiHost postgres, port 5432, user msa_user, database msa_database.
Duyệt dữ liệuMở database msa_database → mục Tables để xem và truy vấn.

⚠️ Host là postgres, không phải localhost

DBGate chạy bên trong Docker nên phải gọi database bằng tên service. Chỉ khi bạn dùng công cụ cài trên máy thật (pgAdmin, DBeaver, psql) thì mới điền localhost với cổng 5432.

Về schema và script khởi tạo

Khi container PostgreSQL chạy lần đầu tiên (volume còn trống), Docker tự động thực thi database/init_schema_3nf.sql (tạo toàn bộ bảng 3NF) rồi database/auto_purge_job.sql (stored procedure tự dọn bình luận thô cũ hơn 30 ngày).

06Worker đồng bộ dữ liệu

Backend Core chạy các Background Worker chạy nền định kỳ — đây là lý do dashboard mở ra là có số liệu ngay mà không phải chờ gọi API bên thứ ba.

📊

MetricsSyncWorker

Định kỳ gọi API nền tảng, kéo về bài viết và các chỉ số (views, likes, comments, shares, fan count).

💬

CommentSyncWorker

Mỗi giờ kéo bình luận mới theo con trỏ lũy tiến, đẩy sang AI Core chấm cảm xúc theo mẻ.

📈

TrendingSyncWorker

Cào xu hướng YouTube thật định kỳ (Ngày/Tuần/Tháng), lưu snapshot vào DB cho trang Xu hướng.

Kích hoạt đồng bộ thủ công

Trong buổi demo hoặc khi cần dữ liệu mới ngay: đăng nhập, vào /dashboard/youtube và bấm nút Đồng bộ Worker. Worker sẽ chạy ngay lập tức cho kênh đang chọn.

07Tài khoản & phân quyền

Hệ thống có hai vai trò cốt lõi (User/Admin), tách bạch về menu sidebar, quyền truy cập trang và API endpoint.

Vai trò	Tài khoản demo	Mật khẩu	Thấy được gì
User (KOL)	`user@msa.com`	`User@123`	Phân tích bằng AI (Chat Overview), nhóm Tìm kiếm & Khám phá (Xu hướng thịnh hành, Lắng nghe từ khóa), nhóm Phân tích số liệu (Kênh, Nền tảng, Chiến dịch — Cảm xúc AI nằm lồng trong các trang này), nhóm Phân tích theo Nền tảng (YouTube/Facebook/Instagram/Threads/TikTok), Cài đặt tài khoản
Admin	`admin@msa.com`	`Admin@123`	Tổng quan, Hỗ trợ trực tuyến, Kiểm tra API, Quản lý Người dùng, Trung tâm Telegram, Cài đặt

🚨 Đây là tài khoản demo

Hai tài khoản trên chỉ dùng cho môi trường phát triển và trình diễn. Trước khi đưa hệ thống ra môi trường thật, phải đổi mật khẩu hoặc xóa hẳn hai tài khoản này.

Menu “So sánh hiệu suất” / “Theo dõi đối thủ” — không còn trong sidebar

Hai trang /dashboard/compare/competitors (đối sánh KOL vs đối thủ) và /dashboard/search/competitors (tìm kiếm đối thủ) vẫn hoạt động bình thường về mặt kỹ thuật, nhưng theo yêu cầu của Leader, mục menu tương ứng đã được ẩn khỏi sidebar — chỉ truy cập được khi gõ thẳng URL.

ℹ️ Đã gỡ bỏ công tắc chuyển bố cục V1/V2

Sidebar hiện tại chỉ còn một bố cục menu duy nhất (nhóm theo nghiệp vụ: Tìm kiếm & Khám phá · Phân tích số liệu · Phân tích theo Nền tảng · Cá nhân). Công tắc [ MSA VERSION ] đổi giữa 2 bố cục V1/V2 đã bị gỡ khỏi giao diện, không còn tồn tại trong code.

08Quản lý Người dùng

Truy cập: /dashboard/admin-users — chỉ hiển thị với tài khoản có vai trò Admin.

🔎

Tìm kiếm tức thời

Lọc theo Tên hoặc Email, kết quả cập nhật ngay khi gõ.

🎭

Bộ lọc vai trò

Xem riêng danh sách KOL hoặc Admin.

🏷️

Badge nguồn đăng ký

Phân biệt tài khoản tạo bằng Google OAuth hay tài khoản local.

✅

Trạng thái xác minh

Hiển thị email đã xác minh chưa và 2FA đang bật hay tắt.

09Kiểm tra API & sức khỏe hệ thống

Truy cập: /dashboard/admin-api. Đây là công cụ chẩn đoán đầu tiên nên mở mỗi khi hệ thống có biểu hiện bất thường — giám sát độ trễ PostgreSQL, Redis và AI Core, tô màu xanh/vàng/đỏ theo ngưỡng.

✅ Quy trình chẩn đoán 30 giây

Mở /dashboard/admin-api → bấm Kiểm tra tất cả API → xác định thành phần nào đỏ → chạy docker compose logs -f <tên service> cho đúng service đó.

10Hỗ trợ trực tuyến

Truy cập: /dashboard/admin-chat. Cổng chat phía Admin của luồng hỗ trợ ba bước: người dùng đặt câu hỏi qua widget chat → Gemini 2.5 Flash trả lời trước → chuyển tiếp Admin khi AI không giải quyết được.

11Trung tâm Telegram

Truy cập: /dashboard/telegram-hub. Cho phép liên kết tài khoản Telegram qua bot để nhận thông báo hệ thống.

⚠️ Cần Bot Token

Chức năng này yêu cầu Telegram Bot Token hợp lệ trong cấu hình cục bộ. Nếu chưa cấu hình, trang vẫn mở được nhưng không gửi được thông báo.

12Sao lưu & khôi phục

# Sao lưu
docker exec msa_postgres pg_dump -U msa_user msa_database > backup_msa.sql

# Khôi phục
docker exec -i msa_postgres psql -U msa_user -d msa_database < backup_msa.sql

🚨 Nạp lại schema sạch xóa hết dữ liệu

docker compose down -v rồi docker compose up -d — chỉ dùng khi chấp nhận mất toàn bộ dữ liệu hiện có.

13Xử lý sự cố

Sự cố #1 — Google OAuth hết hạn (`invalid_grant`)

🚨 Nguyên nhân số một làm demo "trắng dữ liệu"

Khi OAuth Consent Screen của Google còn ở chế độ Testing, Google tự động hủy hiệu lực Refresh Token sau đúng 7 ngày. Xử lý: hủy kết nối cũ tại /dashboard/connections rồi kết nối lại.

Sự cố #2 — Fanpage Facebook không có dữ liệu

Meta App còn ở Development mode nên giới hạn quyền đọc Page Insights một số Fanpage — giới hạn chính sách, không phải lỗi code. Hồ sơ cá nhân Facebook vĩnh viễn không có dữ liệu (Meta khóa API này từ 2018).

Sự cố #3 — Trang hiển thị rỗng nhưng không lỗi

Frontend tuân theo chuẩn Zero-Crash: khi API lỗi hoặc trả về mảng rỗng, giao diện hiển thị trạng thái rỗng có ý nghĩa thay vì màn hình trắng.

14Quy tắc bảo mật khi vận hành

🔐

Token mã hóa AES-256-GCM

Token mạng xã hội được mã hóa trước khi ghi vào database, không bao giờ trả về trình duyệt.

🧂

Mật khẩu BCrypt

Băm có salt. Không bao giờ lưu plaintext, kể cả trong log.

⏳

JWT sống 15 phút

Token phiên hết hạn nhanh để giảm thiệt hại nếu bị đánh cắp.

📱

2FA — OTP 6 số

Người dùng tự bật trong Cài đặt tài khoản qua ứng dụng Authenticator.

15Checklist trước buổi demo

Dựng hạ tầngdocker compose up -d rồi docker compose ps — xác nhận cả 6 container đều Up.
Kiểm tra khóa GeminiXác nhận GEMINI_API_KEY đã là khóa thật, không còn placeholder.
Re-auth Google/YouTubeViệc quan trọng nhất — xem lại sự cố #1 ở trên.
Thử đăng nhập cả hai vai tròĐăng nhập user@msa.com và admin@msa.com.
Chạy đồng bộ thậtMở /dashboard/youtube, bấm Đồng bộ Worker.
Ping toàn bộ APIMở /dashboard/admin-api, bấm Kiểm tra tất cả API — mọi thành phần phải xanh.

Tài liệu tiếp theo

📗 Hướng dẫn Người dùng →

Thuyết trình

🎤 Slide giới thiệu →