Bức tranh tổng thể
MediaCrawler làm được gì?
Đây là bộ thu thập thông tin công khai từ các nền tảng nội dung Trung Quốc, thống nhất sau một CLI và một WebUI. Mỗi nền tảng có client riêng, nhưng chia sẻ lớp đăng nhập, proxy, cache, lưu trữ và mô hình chạy.
Tìm theo từ khóa
Nhập một hoặc nhiều từ khóa, chọn trang bắt đầu và giới hạn số nội dung cần lấy.
Lấy theo ID/URL
Nhắm đúng bài, video, câu trả lời hoặc chủ đề; nhiều nền tảng nhận cả URL lẫn ID thuần.
Trang tác giả
Thu thập hồ sơ creator và nội dung từ danh sách creator ID hoặc URL cấu hình sẵn.
Bình luận 2 cấp
Bật/tắt bình luận cấp 1, cấp 2 và đặt giới hạn trên từng nội dung.
Ảnh, video, word cloud
Có cờ tải media; word cloud dùng nội dung bình luận, từ dừng, từ ghép tùy chỉnh và font tiếng Trung.
Nhiều cách lưu
Tệp văn bản, Excel nhiều sheet, SQLite, MySQL, PostgreSQL và MongoDB.
Repo tránh phải tự đảo ngược toàn bộ thuật toán mã hóa: nó giữ phiên trình duyệt đã đăng nhập và thực thi biểu thức JavaScript trong browser context để lấy tham số chữ ký.
Phù hợp để
Nghiên cứu nội dungKhảo sát chủ đề, tác giả, mức độ tương tác trên một mẫu nhỏ.
Học kỹ thuật crawlerĐọc cách tách platform, client, login, store, proxy và cache.
Tạo dữ liệu phân tíchXuất Excel/JSONL hoặc lưu CSDL để xử lý tiếp bằng pandas/BI.
Ma trận phạm vi
7 nền tảng, 3 chế độ chạy
Ba chế độ dùng chung là search, detail và creator. Tuy nhiên định dạng ID/URL có khác nhau, nhất là Xiaohongshu và Zhihu.
xhsXiaohongshu
Ghi chú, tác giả, bình luận
URL chi tiết và tác giả cần xsec_token/xsec_source.dyDouyin
Video, tác giả, bình luận
Nhận URL video, URL modal, link rút gọn hoặc ID thuần.ksKuaishou
Video, tác giả, bình luận
Nhận URL video/profile hoặc ID thuần.biliBilibili
Video, creator, bình luận
Nhận URL video, BV number; có tùy chọn độ phân giải BILI_QN.wbBài đăng, tác giả, bình luận
Có chế độ lấy toàn văn, nhưng tăng nguy cơ bị giới hạn.tiebaBaidu Tieba
Chủ đề, người dùng, phản hồi
Nhận thread ID hoặc URL /p/; creator nhận portrait ID hoặc URL.zhihuZhihu
Câu trả lời, bài viết, video
Detail nhận URL answer, zhuanlan hoặc zvideo.| Chế độ | Đầu vào | Kết quả chính | Dùng khi |
|---|---|---|---|
search | --keywords | Danh sách nội dung và bình luận tùy chọn | Khảo sát một chủ đề |
detail | --specified_id | Chi tiết đúng ID/URL được chỉ định | Đã biết nội dung cần lấy |
creator | --creator_id hoặc config nền tảng | Hồ sơ và nội dung của tác giả | Theo dõi một creator cụ thể |
Ghi chú đầu vào theo nền tảng +
Xiaohongshu: URL note/creator cần giữ xsec_token, creator còn cần xsec_source. Có cờ XHS_INTERNATIONAL cho rednote.com.
Douyin: hỗ trợ URL video, URL có modal_id, link v.douyin.com và video ID.
Bilibili: dùng URL video hoặc BV number; creator dùng URL space hoặc UID.
Tieba: detail nhận số thread hoặc URL /p/<id>; creator nhận URL hoặc portrait ID.
Zhihu: detail nhận URL answer, bài Zhuanlan và ZVideo. Danh sách creator trong zhihu_config.py.
Quickstart an toàn
Cài đặt và chạy lần đầu
Đường đi được README hiện tại khuyến nghị là uv + Node.js + Chrome thật qua CDP. Driver Playwright chỉ cần khi bạn tắt CDP và quay về chế độ trình duyệt tiêu chuẩn.
Chuẩn bị môi trường
Cài uv, Node.js 16+ và Chrome mới. Với chế độ kết nối Chrome đang mở, tài liệu repo yêu cầu Chrome 144+.
Lấy mã nguồn và đồng bộ
git clone https://github.com/NanmiCoder/MediaCrawler.git
cd MediaCrawler
uv syncBật remote debugging
Mở chrome://inspect/#remote-debugging, bật “Allow remote debugging for this browser instance”, kiểm tra máy chủ tại 127.0.0.1:9222.
Chạy mẫu và xác nhận Chrome
uv run main.py --platform xhs --lt qrcode --type searchKhi Chrome hiện hộp thoại, chọn chấp nhận trong thời gian chờ mặc định 60 giây.
Đặt ENABLE_CDP_MODE = False, sau đó chạy uv run playwright install. Giữ HEADLESS = False khi cần xử lý slider/xác minh thủ công.
Chạy uv run main.py --help để xem tham số đúng với commit đang dùng. CLI mới có nhiều tùy chọn hơn một số đoạn README cũ.
Bộ tạo lệnh
Ghép lệnh chạy đúng nhu cầu
Chọn các tùy chọn bên dưới. Lệnh được tạo theo parser Typer trong cmd_arg/arg.py, không phải ví dụ rút gọn.
uv run main.py --platform xhs --lt qrcode --type search --keywords "trí tuệ nhân tạo,AI ứng dụng" --get_comment yes --get_sub_comment no --save_data_option jsonlToàn bộ tham số CLI
| Tham số | Giá trị | Tác dụng |
|---|---|---|
--platform | xhs | dy | ks | bili | wb | tieba | zhihu | Chọn nền tảng |
--lt | qrcode | phone | cookie | Kiểu đăng nhập |
--type | search | detail | creator | Chế độ thu thập |
--keywords | chuỗi,phân,cách,bởi,dấu,phẩy | Từ khóa cho search |
--specified_id | URL hoặc ID, có thể nhiều giá trị | Đối tượng cho detail |
--creator_id | URL hoặc ID, có thể nhiều giá trị | Đối tượng cho creator |
--start | số nguyên >= 1 | Trang bắt đầu |
--crawler_max_notes_count | số nguyên | Số bài/video tối đa |
--get_comment | yes/no, true/false, 1/0 | Lấy bình luận cấp 1 |
--get_sub_comment | yes/no, true/false, 1/0 | Lấy bình luận cấp 2 |
--max_comments_count_singlenotes | số nguyên | Giới hạn bình luận mỗi bài |
--max_concurrency_num | số nguyên | Số crawler chạy đồng thời |
--headless | yes/no | Ẩn hoặc hiện trình duyệt |
--save_data_option | csv | db | json | jsonl | sqlite | mongodb | excel | postgres | Định dạng lưu |
--save_data_path | đường dẫn | Thư mục đầu ra tùy chỉnh |
--init_db | sqlite | mysql | postgres | Khởi tạo bảng dữ liệu |
--cookies | chuỗi cookie | Cookie khi dùng --lt cookie |
--enable_ip_proxy | yes/no | Bật proxy IP |
--ip_proxy_pool_count | số nguyên | Số IP trong pool |
--ip_proxy_provider_name | kuaidaili | wandouhttp | static | Nguồn proxy |
--static_proxy_url | http://user:pass@host:port | Proxy tĩnh |
uv run main.py --platform dy --lt qrcode --type detail \
--specified_id "https://v.douyin.com/xxxx/,7280854932641664319" \
--get_comment yes --get_sub_comment yes --save_data_option exceluv run main.py --init_db sqlite
uv run main.py --platform bili --lt qrcode --type creator \
--creator_id "434377496,20813884" --save_data_option sqliteĐiều khiển sâu
Cấu hình đầy đủ trong repo
CLI ghi đè các lựa chọn thường dùng. Những tính năng sâu hơn nằm trong config/base_config.py, config/db_config.py và file riêng từng nền tảng.
| Biến | Mặc định | Ý nghĩa |
|---|---|---|
PLATFORM / KEYWORDS | xhs / chuỗi từ khóa | Nền tảng và danh sách từ khóa tìm kiếm |
LOGIN_TYPE / COOKIES | qrcode / rỗng | QR, điện thoại hoặc cookie |
CRAWLER_TYPE | search | search, detail hoặc creator |
ENABLE_CDP_MODE | True | Điều khiển Chrome/Edge thật qua CDP |
CDP_CONNECT_EXISTING | True | Kết nối trình duyệt người dùng đang mở |
HEADLESS / CDP_HEADLESS | False | Hiện trình duyệt để dễ xử lý xác minh |
SAVE_LOGIN_STATE | True | Lưu trạng thái đăng nhập cho lần sau |
SAVE_DATA_OPTION | jsonl | Đầu ra mặc định, ghi nối từng dòng |
CRAWLER_MAX_NOTES_COUNT | 15 | Giới hạn số nội dung mỗi lần chạy |
MAX_CONCURRENCY_NUM | 1 | Mức song song thận trọng |
ENABLE_GET_COMMENTS | True | Thu thập bình luận cấp 1 |
CRAWLER_MAX_COMMENTS_COUNT_SINGLENOTES | 10 | Giới hạn bình luận mỗi nội dung |
ENABLE_GET_SUB_COMMENTS | False | Bình luận cấp 2, tắt mặc định |
ENABLE_GET_MEIDAS | False | Tải ảnh/video, tên biến giữ nguyên theo repo |
ENABLE_GET_WORDCLOUD | False | Sinh thống kê từ và ảnh word cloud |
CRAWLER_MAX_SLEEP_SEC | 2 | Khoảng nghỉ tối đa giữa các lượt |
DISABLE_SSL_VERIFY | False | Chỉ bật với proxy MITM tự ký, có rủi ro bảo mật |
Tải ảnh và video
Đặt ENABLE_GET_MEIDAS = True. Cân nhắc dung lượng, bản quyền và tần suất tải trước khi bật.
Bình luận nhiều cấp
Bật ENABLE_GET_COMMENTS, sau đó mới bật ENABLE_GET_SUB_COMMENTS. Đặt giới hạn mỗi bài để giảm tải.
Đám mây từ khóa
Dùng JSON/JSONL, bật comment và word cloud; tùy biến CUSTOM_WORDS, stopwords và font.
Tốc độ và đồng thời
MAX_CONCURRENCY_NUM và CRAWLER_MAX_SLEEP_SEC ảnh hưởng trực tiếp đến tải và nguy cơ bị giới hạn.
Cấu hình riêng đáng chú ý +
Bilibili: BILI_QN chọn chất lượng video; có khoảng ngày, giới hạn bài/ngày, creator mode và giới hạn dynamics.
Xiaohongshu: SORT_TYPE, danh sách note/creator URL có token, XHS_INTERNATIONAL cho RedNote.
Weibo: WEIBO_SEARCH_TYPE và ENABLE_WEIBO_FULL_TEXT; lấy toàn văn làm tăng thêm request.
Tieba: hỗ trợ danh sách thread ID, tên bar và URL creator.
Douyin: PUBLISH_TIME_TYPE lọc thời gian đăng.
Từ kết quả đến phân tích
Lưu dữ liệu và vận hành WebUI
CLI hiện liệt kê 8 lựa chọn lưu. Tài liệu repo ưu tiên JSONL cho ghi nối, SQLite cho cá nhân và Excel khi cần chia sẻ với người không dùng code.
| Đầu ra | Giá trị CLI | Phù hợp | Khởi tạo |
|---|---|---|---|
| JSONL | jsonl | Mặc định, ghi nối nhanh, hợp dữ liệu lớn vừa | Không |
| JSON | json | Dễ đọc, dùng được cho word cloud | Không |
| CSV | csv | Nhẹ, mở nhanh bằng bảng tính | Không |
| Excel | excel | Nhiều sheet Contents/Comments/Creators, có định dạng | Không |
| SQLite | sqlite | Gọn, có khử trùng lặp, hợp cá nhân | --init_db sqlite |
| MySQL | db | CSDL quan hệ, tên db giữ để tương thích cũ | --init_db mysql |
| PostgreSQL | postgres | CSDL quan hệ cho quy mô lớn hơn | --init_db postgres |
| MongoDB | mongodb | Document database, có trong CLI hiện tại | Cấu hình trong db_config.py |
Excel được tổ chức thành nhiều sheet
Workbook có thể chứa Contents, Comments và Creators; sheet rỗng tự bị bỏ. Header xanh, tự điều chỉnh độ rộng, có border và wrap text. Tệp nằm trong data/{platform}/ với timestamp.
WebUI: dùng crawler không cần nhớ lệnh
Chế độ phát triển
# Terminal 1
uv run uvicorn api.main:app --port 8080 --reload
# Terminal 2
cd webui
npm install
npm run devMở http://localhost:5173. Frontend proxy /api về cổng 8080.
Chạy bản đã build
cd webui
npm install
npm run build
cd ..
uv run uvicorn api.main:app --port 8080 --reloadMở http://localhost:8080. API phục vụ luôn tài nguyên tĩnh.
API schema của WebUI hiện hỗ trợ CSV, MySQL, JSON, JSONL, SQLite, MongoDB và Excel. PostgreSQL có trong CLI nhưng chưa được liệt kê trong schema WebUI ở commit được kiểm tra.
Trình duyệt và mạng
CDP, proxy, login state
Đây là nhóm tính năng quyết định độ ổn định. Cấu hình mặc định ưu tiên minh bạch: browser có giao diện, concurrency thấp, lưu phiên và kết nối Chrome đang dùng.
Kết nối Chrome đang mở
ENABLE_CDP_MODE = True và CDP_CONNECT_EXISTING = True. Tận dụng cookie, extension, lịch sử và fingerprint thật.
Tự mở browser mới
Đặt CDP_CONNECT_EXISTING = False. Repo tự dò Chrome/Edge; dùng CUSTOM_BROWSER_PATH nếu dò thất bại.
QR, cookie, điện thoại
QR dễ bắt đầu; cookie phù hợp phiên có sẵn; phone cần Android, SMS Forwarder, webhook, Redis và dịch vụ như ngrok nên repo không khuyến nghị.
Lưu và đổi tài khoản
SAVE_LOGIN_STATE = True giúp tái sử dụng phiên. Muốn đổi account, xóa thư mục dữ liệu browser của platform rồi đăng nhập lại.
Bật proxy IP
uv run main.py --platform xhs --lt qrcode --type search \
--enable_ip_proxy yes \
--ip_proxy_provider_name static \
--static_proxy_url "http://user:password@host:port"Repo còn tích hợp provider kuaidaili và wandouhttp. Với proxy động, cấu hình khóa của nhà cung cấp theo tài liệu tương ứng. Không dùng proxy để mở rộng crawl trái phép; proxy không thay thế rate limit.
Chỉ đặt DISABLE_SSL_VERIFY = True khi làm việc với proxy doanh nghiệp, Burp Suite hoặc mitmproxy dùng chứng chỉ tự ký. Tắt xác minh SSL khiến lưu lượng có nguy cơ bị tấn công trung gian.
Đọc repo như một hệ thống
Kiến trúc, xử lý lỗi và giới hạn
MediaCrawler tách phần dùng chung khỏi adapter từng nền tảng. Đây cũng là giá trị học tập quan trọng nhất của repo: thêm platform hoặc store mới mà không phải viết lại toàn bộ luồng.
Xử lý lỗi thường gặp
Không kết nối được cổng 9222
Kiểm tra Chrome đang mở, bật remote debugging trong chrome://inspect/#remote-debugging, xác nhận máy chủ hiển thị ở 127.0.0.1:9222 và Chrome đủ mới.
Xiaohongshu bị slider lặp lại
Ưu tiên CDP với browser thật, giữ headless tắt. Nếu vẫn lỗi, xóa dữ liệu browser đã cache và đăng nhập lại.
Douyin/Zhihu báo lỗi JavaScript
Kiểm tra Node.js đã cài và phiên bản từ 16 trở lên. Hai platform này cần runtime JS để thực thi phần ký.
Chạy đầu tiên được, sau đó mất dữ liệu
Có thể tài khoản đã chạm cơ chế kiểm soát rủi ro. Giảm số lượng, concurrency, tăng thời gian nghỉ và dừng việc crawl diện rộng.
Word cloud không được tạo
Dùng JSON/JSONL, bật cả comment và word cloud, kiểm tra đường dẫn stopwords và file font.
Chỉ học tập và nghiên cứu phi thương mại
Theo README và giấy phép của repo: không dùng cho mục đích thương mại, bất hợp pháp, xâm phạm quyền lợi, crawl quy mô lớn hoặc gây ảnh hưởng vận hành nền tảng. Người dùng tự chịu trách nhiệm tuân thủ pháp luật, điều khoản dịch vụ, robots.txt, quyền riêng tư và sở hữu trí tuệ.
Checklist trước khi nhấn chạy
- ✓Mục tiêu hợp pháp, phi thương mại, mẫu dữ liệu vừa đủ
- ✓Đã chọn đúng platform, mode và định dạng ID/URL
- ✓Chrome remote debugging sẵn sàng hoặc Playwright driver đã cài
- ✓Giới hạn số bài, bình luận, concurrency và khoảng nghỉ hợp lý
- ✓Đầu ra và CSDL đã khởi tạo đúng nhu cầu
- ✓Không ghi cookie/khóa proxy nhạy cảm vào Git