🚀 Cài Đặt & Khởi Động

Dành cho: Kỹ thuật viên, DevOps — người chịu trách nhiệm cài đặt hệ thống lần đầu và triển khai lên server.

Tổng Quan

Sau khi hoàn thành hướng dẫn này, bạn sẽ có:

✅ Hệ thống GBS Crawler chạy được trên máy tính
✅ Trình duyệt Playwright đã cài đặt
✅ Cảnh báo Telegram đã kết nối
✅ Ít nhất 1 khách hàng đã đăng nhập thành công

Thời gian ước tính: ~15 phút

Bước 1: Kiểm Tra Yêu Cầu Hệ Thống

Thành phần	Phiên bản tối thiểu	Kiểm tra
Python	3.11+	`python3 --version`
uv (trình quản lý package)	Mới nhất	`uv --version`
Hệ điều hành	macOS hoặc Linux	—

Cài đặt Python (nếu chưa có)

bash

# macOS (dùng Homebrew)
brew install python@3.12

# Ubuntu/Debian
sudo apt update && sudo apt install python3.12

Cài đặt uv (nếu chưa có)

uv là trình quản lý package Python siêu nhanh (thay thế pip + venv):

bash

curl -LsSf https://astral.sh/uv/install.sh | sh

Sau khi cài, kiểm tra:

bash

uv --version
# Kết quả mẫu: uv 0.7.x

Bước 2: Clone Dự Án & Cài Đặt Dependencies

bash

# Clone dự án từ repository
git clone <url-repo> gbs-crawler
cd gbs-crawler

# Cài đặt tất cả package phụ thuộc
uv sync

Lệnh uv sync sẽ:

Tạo virtual environment (.venv/) tự động
Cài tất cả package từ pyproject.toml (Playwright, Pandas, APScheduler, Rich, Click...)
Cài GBS Crawler dưới dạng package CLI (lệnh gbs)

Bước 3: Cài Đặt Trình Duyệt Playwright

GBS Crawler sử dụng Playwright để điều khiển trình duyệt Chromium tự động:

bash

uv run playwright install chromium

💡 Tại sao chỉ cài Chromium? Chromium tương thích tốt nhất với các sàn TMĐT Việt Nam (Shopee, TikTok, Lazada). Firefox/WebKit có thể gặp vấn đề fingerprinting.

Bước 4: Cấu Hình Telegram Bot (Cảnh Báo Lỗi)

Hệ thống gửi cảnh báo qua Telegram khi crawl thất bại. Bạn cần tạo file .env:

4.1 Tạo Telegram Bot

Mở Telegram, tìm @BotFather
Gửi lệnh /newbot, đặt tên và username cho bot
Copy Bot Token (dạng: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)

4.2 Lấy Chat ID

Thêm bot vào nhóm Telegram của đội ngũ
Gửi 1 tin nhắn bất kỳ trong nhóm
Truy cập: https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
Tìm trường "chat": {"id": -1001234567890} — đây là Chat ID

4.3 Tạo file .env

Tạo file .env tại thư mục gốc dự án:

bash

cp .env.example .env   # Nếu có file mẫu

Hoặc tạo mới:

env

# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
TELEGRAM_CHAT_ID="-1001234567890"

⚠️ Bảo mật: File .env chứa thông tin nhạy cảm. Không commit lên Git (đã có trong .gitignore).

Bước 5: Cấu Hình Khách Hàng

5.1 File `config/customers.csv`

Hệ thống cung cấp file mẫu customers.example.csv. Bạn cần copy ra file mới:

bash

cp config/customers.example.csv config/customers.csv

File này chứa thông tin tài khoản của từng khách hàng trên từng sàn:

csv

customer_id,customer_name,marketplace,seller_url,username,password,extra_params,notes,profile_name
vita_dairy,Vita Dairy,shopee,https://banhang.shopee.vn,,,,,Vita Dairy
vita_dairy,Vita Dairy,tiktok,https://seller-vn.tiktok.com,,,,,Vita Dairy
vita_dairy,Vita Dairy,lazada,https://sellercenter.lazada.vn,,,,,Vita Dairy

⚠️ Bảo mật: File config/customers.csv đã được thêm vào .gitignore để không bị push lên GitHub, nhằm bảo vệ thông tin đăng nhập của khách. Mọi cấu hình thực tế phải ghi vào customers.csv, không ghi vào file .example.csv.

Giải thích các cột:

Cột	Bắt buộc	Mô tả
`customer_id`	✅	ID ngắn, viết_thường, không dấu (VD: `vita_dairy`)
`customer_name`	✅	Tên hiển thị (VD: `Vita Dairy`)
`marketplace`	✅	Tên sàn: `shopee`, `tiktok`, `lazada`
`seller_url`	✅	URL trang Seller Center
`username`	❌	Tên đăng nhập (nếu cần lưu — khuyến nghị để trống vì dùng Cookie)
`password`	❌	Mật khẩu (khuyến nghị để trống vì lý do bảo mật)
`extra_params`	❌	Tham số bổ sung (dạng `key1=val1,key2=val2`)
`notes`	❌	Ghi chú tự do
`profile_name`	✅	Tên thư mục profile trong `profiles/` — tất cả sàn của 1 KH nên dùng cùng tên

5.2 File `config/crawl_jobs.csv`

Tương tự, copy file mẫu:

bash

cp config/crawl_jobs.example.csv config/crawl_jobs.csv

File này định nghĩa những báo cáo nào cần tải cho từng khách hàng:

csv

customer_id,marketplace,report_type,frequency,priority,enabled,date_range_type,notes

vita_dairy,shopee,income,monthly,high,true,last_month,Thu nhập sàn - nút Xuất
vita_dairy,shopee,wallet,monthly,high,true,last_month,Số dư ví ShopeePay
vita_dairy,shopee,ads_onsite,daily,medium,true,yesterday,Paid ads CPC

Giải thích các cột:

Cột	Giá trị	Mô tả
`report_type`	`income`, `statement`, `wallet`, `ads_onsite`, `affiliate_bill`...	Loại báo cáo cần tải
`frequency`	`daily` hoặc `monthly`	Tần suất tải
`priority`	`high`, `medium`, `low`	Mức độ ưu tiên (chạy `high` trước)
`enabled`	`true` hoặc `false`	Bật/tắt — đặt `false` để tạm dừng mà không xóa
`date_range_type`	`yesterday`, `last_month`, `last_week`	Khoảng thời gian báo cáo

Bước 6: Đăng Nhập Lần Đầu

Với mỗi khách hàng + sàn, bạn cần đăng nhập 1 lần để hệ thống lưu Cookie:

bash

# Ví dụ: Đăng nhập Shopee cho Vita Dairy
gbs login -c vita_dairy -m shopee

Trình duyệt sẽ mở lên → Đăng nhập bình thường → Đóng trình duyệt khi xong.

Bước 7: Chạy Thử

Test nhanh (dry-run)

bash

gbs crawl --dry-run

Lệnh này chỉ liệt kê các job sẽ chạy mà không tải thật — dùng để kiểm tra cấu hình.

Chạy thật

bash

gbs crawl

Kiểm tra kết quả

bash

# Xem trạng thái
gbs status

# Tìm file báo cáo
ls -la data/

Bước 8: Triển Khai Lên Server (Production)

Để hệ thống chạy liên tục trên server:

Dùng tmux (Đơn giản)

bash

# Tạo session mới
tmux new -s gbs

# Bật scheduler
gbs schedule

# Tách khỏi session (nhấn Ctrl+B rồi D)
# Để quay lại: tmux attach -t gbs

Dùng systemd (Chuyên nghiệp hơn)

Tạo file service:

bash

sudo nano /etc/systemd/system/gbs-crawler.service

ini

[Unit]
Description=GBS Crawler Scheduler
After=network.target

[Service]
User=your-username
WorkingDirectory=/path/to/gbs-crawler
ExecStart=/path/to/gbs-crawler/.venv/bin/python main.py schedule
Restart=always
RestartSec=60

[Install]
WantedBy=multi-user.target

bash

sudo systemctl enable gbs-crawler
sudo systemctl start gbs-crawler
sudo systemctl status gbs-crawler

✅ Checklist Cài Đặt

[ ] Python 3.11+ đã cài
[ ] uv đã cài
[ ] uv sync chạy thành công
[ ] uv run playwright install chromium thành công
[ ] File .env đã tạo với Telegram token
[ ] File customers.csv đã thêm khách hàng
[ ] File crawl_jobs.csv đã thêm danh sách báo cáo
[ ] gbs login thành công cho ít nhất 1 KH
[ ] gbs crawl --dry-run hiện danh sách job đúng
[ ] gbs crawl tải được file về data/

📌 Xem tiếp: Hướng dẫn sử dụng hằng ngày | Tham chiếu lệnh CLI

🚀 Cài Đặt & Khởi Động ​

Tổng Quan ​

Bước 1: Kiểm Tra Yêu Cầu Hệ Thống ​

Cài đặt Python (nếu chưa có) ​

Cài đặt uv (nếu chưa có) ​

Bước 2: Clone Dự Án & Cài Đặt Dependencies ​

Bước 3: Cài Đặt Trình Duyệt Playwright ​

Bước 4: Cấu Hình Telegram Bot (Cảnh Báo Lỗi) ​

4.1 Tạo Telegram Bot ​

4.2 Lấy Chat ID ​

4.3 Tạo file .env ​

Bước 5: Cấu Hình Khách Hàng ​

5.1 File config/customers.csv ​

5.2 File config/crawl_jobs.csv ​

Bước 6: Đăng Nhập Lần Đầu ​

Bước 7: Chạy Thử ​

Test nhanh (dry-run) ​

Chạy thật ​

Kiểm tra kết quả ​

Bước 8: Triển Khai Lên Server (Production) ​

Dùng tmux (Đơn giản) ​

Dùng systemd (Chuyên nghiệp hơn) ​

✅ Checklist Cài Đặt ​

🚀 Cài Đặt & Khởi Động

Tổng Quan

Bước 1: Kiểm Tra Yêu Cầu Hệ Thống

Cài đặt Python (nếu chưa có)

Cài đặt uv (nếu chưa có)

Bước 2: Clone Dự Án & Cài Đặt Dependencies

Bước 3: Cài Đặt Trình Duyệt Playwright

Bước 4: Cấu Hình Telegram Bot (Cảnh Báo Lỗi)

4.1 Tạo Telegram Bot

4.2 Lấy Chat ID

4.3 Tạo file .env

Bước 5: Cấu Hình Khách Hàng

5.1 File `config/customers.csv`

5.2 File `config/crawl_jobs.csv`

Bước 6: Đăng Nhập Lần Đầu

Bước 7: Chạy Thử

Test nhanh (dry-run)

Chạy thật

Kiểm tra kết quả

Bước 8: Triển Khai Lên Server (Production)

Dùng tmux (Đơn giản)

Dùng systemd (Chuyên nghiệp hơn)

✅ Checklist Cài Đặt