diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md new file mode 100644 index 000000000..02e3b034f --- /dev/null +++ b/.claude/CLAUDE.md @@ -0,0 +1,185 @@ +# MediaCrawler - Project Overview + +## 📋 Project Summary + +**MediaCrawler** là một công cụ web scraping mạnh mẽ dùng để thu thập dữ liệu công khai từ các nền tảng truyền thông xã hội (Social Media) phổ biến của Trung Quốc. + +### Mục đích chính +Hỗ trợ lập trình viên trong việc học tập, nghiên cứu và phân tích dữ liệu từ các nền tảng đa phương tiện. **Chỉ dành cho mục đích học tập, không sử dụng thương mại**. + +## 🎯 Nền tảng được hỗ trợ + +| Nền tảng | Tìm kiếm từ khóa | Lấy post theo ID | Bình luận cấp 2 | Trang cá nhân | Cache đăng nhập | Proxy | Word Cloud | +|---------|-----------------|-----------------|-----------------|---------------|-----------------|-------|-----------| +| 小红书 (Xiaohongshu) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| 抖音 (Douyin/TikTok CN) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| 快手 (Kuaishou) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| B站 (Bilibili) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| 微博 (Weibo) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| 贴吧 (Tieba/Baidu) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| 知乎 (Zhihu) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | + +## 🏗️ Cấu trúc dự án + +### Các thư mục chính: + +``` +media-crawler/ +├── api/ # FastAPI endpoints cho WebUI +├── base/ # Lớp cơ sở cho các crawler (AbstractCrawler) +├── cache/ # Quản lý cache (Redis, Memory cache) +├── cmd_arg/ # Xử lý tham số dòng lệnh (CLI arguments) +├── config/ # Cấu hình chung (config.py, toml files) +├── constant/ # Hằng số, enum cho các nền tảng +├── database/ # ORM, migration, quản lý DB (SQLAlchemy, Alembic) +├── docs/ # Tài liệu (tiếng Trung, Anh, Tây Ban Nha) +├── libs/ # Thư viện tiện ích +├── media_platform/ # Các crawler riêng cho từng nền tảng +│ ├── bilibili.py +│ ├── douyin.py +│ ├── kuaishou.py +│ ├── tieba.py +│ ├── weibo.py +│ ├── xhs.py # Xiaohongshu +│ └── zhihu.py +├── model/ # Pydantic models, schemas +├── proxy/ # Quản lý proxy pool +├── store/ # Lưu trữ dữ liệu (JSON, JSONL, Excel, DB) +├── test/ # Unit tests +├── tools/ # Công cụ tiện ích (wordcloud, file writer) +├── webui/ # Web UI (Vue.js, build artifacts) +└── main.py # Entry point chính +``` + +## 🔧 Tech Stack + +### Backend +- **Language**: Python 3.11+ +- **Framework**: FastAPI (API), Typer (CLI) +- **Browser Automation**: Playwright (v1.61+) +- **Database**: SQLAlchemy + Alembic (migration), Redis cache +- **Async**: asyncio, aiofiles, asyncmy, asyncpg + +### Storage +- **Database Options**: SQLite, MySQL, PostgreSQL, MongoDB +- **File Formats**: JSON, JSONL, Excel (openpyxl) +- **Serialization**: Pydantic v2+ + +### Frontend +- **WebUI**: Vue.js (src/ trong webui/) +- **API Server**: Uvicorn + FastAPI + +### Utilities +- **Word Cloud**: matplotlib, wordcloud, PIL +- **Text Processing**: jieba (Chinese tokenizer), parsel (HTML parsing) +- **HTTP**: httpx, requests +- **Crypto**: cryptography, pyexecjs (JS signature execution) + +## 🚀 Cách hoạt động + +### Kiến trúc chính: + +1. **CrawlerFactory Pattern** - Tạo crawler dựa trên loại nền tảng +2. **CDP Mode** (Chrome DevTools Protocol) - Kết nối tới Chrome browser đang chạy +3. **Login State Caching** - Lưu trữ session, cookie, state giữa các lần chạy +4. **Proxy Support** - Hỗ trợ rotation proxy để tránh IP ban +5. **Async Architecture** - Xử lý concurrent requests + +### Workflow cơ bản: +``` +CLI Args → Config Loading → Crawler Init → Browser Connect → +Login (hoặc load cached state) → Data Crawl → Parse Data → +Store (DB/File) → Generate WordCloud → Exit +``` + +## 📦 Dependencies chính + +``` +playwright>=1.61.0 # Browser automation +fastapi==0.110.2 # Web framework +sqlalchemy>=2.0.43 # ORM +pydantic>=2.13.4 # Data validation +redis~=4.6.0 # Caching +httpx==0.28.1 # HTTP client +typer>=0.12.3 # CLI framework +wordcloud>=1.9.6 # Word cloud generation +``` + +## 🔗 Điểm vào chính + +- **main.py**: Entry point CLI chính - khởi tạo crawler, run công việc crawl +- **api/**: FastAPI app cho WebUI server +- **media_platform/**: Từng platform crawler có logic riêng +- **config/**: Tập trung tất cả cấu hình (env variables, settings) + +## 📝 Lưu ý quan trọng + +### Legal & Disclaimer ⚠️ +- **Chỉ dùng cho học tập** - không sử dụng thương mại +- **Tuân thủ ToS** - tuân thủ điều khoản dịch vụ của từng nền tảng +- **Hợp pháp** - tham khảo danh sách [crawler illegal cases in China](https://github.com/HiddenStrawberry/Crawler_Illegal_Cases_In_China) + +### Best Practices +- Sử dụng CDP mode (Chrome browser sẵn có) thay vì Playwright mode để tái sử dụng login state +- Bật remote debugging: `chrome://inspect/#remote-debugging` +- Kiểm soát tần suất request (rate limiting) +- Sử dụng proxy pool để tránh IP ban +- Backup cookie/session cache để tránh tái login + +## 🎯 Hướng phát triển gần đây + +### Commits gần nhất: +- **3bde9e2**: docs: update sponsors +- **04da7f3**: Update Readme +- **84907f0**: docs: 新增 Bloome 赞助商 +- **076dcba**: fix: 修复 WebUI 源码缺失、环境检测路径 +- **65ddaa8**: refactor: 将 WebUI 源码纳入仓库 + +### Features dự tính (Pro version) +- Self-media content decomposition Agent +- Breakpoint resume crawling +- Multi-account + IP proxy pool +- Remove Playwright dependency +- Full Linux support +- AI Agent Skills (OpenClaw, Claude Code, Cursor) + +## 💡 Sử dụng cơ bản + +```bash +# Install dependencies +uv sync + +# Install browser drivers (optional, chỉ cho Playwright mode) +uv run playwright install + +# Run crawler +python main.py --platform xhs --keywords "咖啡" + +# Access WebUI +# Mở http://localhost:8000 (nếu API server chạy) +``` + +## 📚 Tài liệu chính + +- **README.md**: Tổng quan chính (tiếng Trung) +- **docs/**: Tài liệu chi tiết (tiếng Trung) + - `项目代码结构.md` - Cấu trúc code + - `项目架构文档.md` - Kiến trúc hệ thống + - `常见问题.md` - FAQ + - `原生环境管理文档.md` - Quản lý môi trường + +## 🔐 Configuration + +Xem `.env.example` để hiểu các biến môi trường: +``` +PLAYWRIGHT_BROWSER_PATH=... # Đường dẫn Chrome +PROXY_POOL=... # Cấu hình proxy +DATABASE_URL=... # Connection string DB +REDIS_URL=... # Redis connection +``` + +--- + +**Last updated**: 2026-07-14 +**Project License**: NON-COMMERCIAL LEARNING LICENSE 1.1 +**Author**: 程序员阿江 (Relakkes) diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 000000000..b41f7c000 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,71 @@ +# Git +.git +.gitignore +.gitattributes + +# Docker +.dockerignore +docker-compose.override.yml + +# Python +__pycache__ +*.py[cod] +*$py.class +*.so +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +.env +.venv +env/ +venv/ +*.egg-info/ +.pytest_cache/ +.coverage +.mypy_cache/ + +# Node +node_modules/ +npm-debug.log +yarn-error.log + +# IDEs +.vscode +.idea +*.swp +*.swo +*~ +.DS_Store + +# Project specific +.cache/ +cache/ +*.db +*.sqlite +logs/ +*.log + +# Test +test/ +tests/ +.pytest_cache/ + +# Documentation +docs/ +*.md +README* + +# Build artifacts +dist/ +build/ +*.egg-info/ diff --git a/.env.docker.example b/.env.docker.example new file mode 100644 index 000000000..8827420dd --- /dev/null +++ b/.env.docker.example @@ -0,0 +1,25 @@ +# Docker Environment Configuration +# Copy this file to .env.docker and customize as needed + +# Python Environment +PYTHONUNBUFFERED=1 + +# FastAPI Backend +API_HOST=0.0.0.0 +API_PORT=8080 + +# Frontend React +REACT_APP_API_URL=http://backend:8080 + +# Database Configuration (Optional) +# DATABASE_URL=postgresql://user:password@postgres:5432/mediacrawler +# REDIS_URL=redis://redis:6379 + +# Logging +LOG_LEVEL=INFO + +# Platform Settings +PLATFORM=xhs + +# Save Format (json, jsonl, excel, db) +SAVE_DATA_OPTION=json diff --git a/DOCKER.md b/DOCKER.md new file mode 100644 index 000000000..b1ba4500a --- /dev/null +++ b/DOCKER.md @@ -0,0 +1,193 @@ +# Docker Setup Guide + +This guide explains how to run MediaCrawler in Docker containers. + +## Prerequisites + +- Docker Desktop or Docker Engine installed +- `docker-compose` available in PATH +- No local Python or Node.js installation needed + +## Quick Start + +```bash +# Clone/navigate to project +cd media-crawler + +# Build and start services +docker-compose up --build + +# Or run in background +docker-compose up -d --build +``` + +## Access URLs + +- **Frontend**: http://localhost:3000 +- **Backend API**: http://localhost:8080 +- **API Documentation**: http://localhost:8080/docs +- **API Health Check**: http://localhost:8080/api/health + +## Services + +### Backend (Python/FastAPI) +- **Image**: python:3.11-slim +- **Port**: 8080 +- **Entry**: `uv run uvicorn api.main:app` +- **Health Check**: Every 10s + +### Frontend (React/Node.js) +- **Image**: node:20-alpine (multi-stage build) +- **Port**: 3000 +- **Server**: `serve -s dist` +- **Health Check**: Every 10s +- **Depends on**: Backend service + +## Common Commands + +```bash +# View logs +docker-compose logs -f + +# View specific service logs +docker-compose logs -f backend +docker-compose logs -f frontend + +# Stop containers +docker-compose stop + +# Stop and remove containers +docker-compose down + +# Rebuild images (clean) +docker-compose build --no-cache + +# Execute shell in container +docker-compose exec backend bash +docker-compose exec frontend sh + +# Restart services +docker-compose restart + +# Clean up everything (images, volumes, networks) +docker-compose down -v --rmi all +``` + +## Development + +### Live Reload +Backend volume mount is configured for live code reload: +```yaml +volumes: + - ./:/app +``` + +Modify code in `api/` or `webui/src/` and changes will take effect. + +### Environment Variables +Edit `docker-compose.yml` to customize: +- `PYTHONUNBUFFERED=1` - Python output buffering +- `REACT_APP_API_URL=http://backend:8080` - Frontend API endpoint + +## Production Deployment + +### Optimize for Production +1. Remove volume mounts from `docker-compose.yml` +2. Set `PYTHONUNBUFFERED=0` for better performance +3. Add resource limits: + +```yaml +services: + backend: + deploy: + resources: + limits: + cpus: '2' + memory: 2G + frontend: + deploy: + resources: + limits: + cpus: '1' + memory: 512M +``` + +### Using Nginx Reverse Proxy +Uncomment the nginx service in `docker-compose.yml` and create `nginx.conf`: + +```nginx +upstream backend { + server backend:8080; +} + +upstream frontend { + server frontend:3000; +} + +server { + listen 80; + server_name _; + + location /api/ { + proxy_pass http://backend; + } + + location / { + proxy_pass http://frontend; + } +} +``` + +## Troubleshooting + +### Port Already in Use +```bash +# Find process using port +lsof -i :8080 +lsof -i :3000 + +# Kill process or use different ports in docker-compose.yml +``` + +### Container Won't Start +```bash +# Check logs +docker-compose logs backend + +# Rebuild without cache +docker-compose build --no-cache +``` + +### Frontend Can't Connect to Backend +Ensure both services are healthy: +```bash +docker-compose ps +# STATUS should show "Up (healthy)" for both +``` + +### Clear Docker Cache +```bash +docker system prune -a +docker volume prune +``` + +## Image Sizes + +- Backend: ~1.2GB (Python + dependencies) +- Frontend: ~200MB (Node.js + built React app) + +## Health Checks + +Both services include automatic health checks: + +- **Backend**: HTTP GET `/api/health` +- **Frontend**: HTTP GET `http://localhost:3000` + +If a service fails health check, it's automatically restarted. + +## Support + +For issues related to Docker setup, please: +1. Check logs: `docker-compose logs` +2. Verify Docker and docker-compose versions +3. Ensure sufficient disk space for images and volumes diff --git a/Dockerfile.backend b/Dockerfile.backend new file mode 100644 index 000000000..c4fd3b926 --- /dev/null +++ b/Dockerfile.backend @@ -0,0 +1,26 @@ +FROM python:3.11-slim + +LABEL maintainer="MediaCrawler Contributors" +LABEL description="FastAPI backend server for MediaCrawler" + +WORKDIR /app + +RUN apt-get update && apt-get install -y --no-install-recommends \ + curl \ + build-essential \ + && rm -rf /var/lib/apt/lists/* + +RUN pip install --no-cache-dir uv + +COPY . . + +RUN uv sync + +EXPOSE 8080 + +ENV PYTHONUNBUFFERED=1 + +HEALTHCHECK --interval=10s --timeout=5s --start-period=20s --retries=3 \ + CMD curl -f http://localhost:8080/api/health || exit 1 + +CMD ["uv", "run", "uvicorn", "api.main:app", "--host", "0.0.0.0", "--port", "8080"] diff --git a/Dockerfile.frontend b/Dockerfile.frontend new file mode 100644 index 000000000..1e0a49954 --- /dev/null +++ b/Dockerfile.frontend @@ -0,0 +1,32 @@ +FROM node:20-alpine AS builder + +LABEL maintainer="MediaCrawler Contributors" +LABEL description="React frontend build stage for MediaCrawler" + +WORKDIR /app/webui + +COPY webui/package*.json ./ + +RUN npm install + +COPY webui/ ./ + +RUN npm run build + +FROM node:20-alpine + +LABEL maintainer="MediaCrawler Contributors" +LABEL description="React frontend server for MediaCrawler" + +WORKDIR /app + +RUN npm install -g serve + +COPY --from=builder /app/api/webui ./dist + +EXPOSE 3000 + +HEALTHCHECK --interval=10s --timeout=5s --start-period=10s --retries=3 \ + CMD wget --quiet --tries=1 --spider http://localhost:3000 || exit 1 + +CMD ["serve", "-s", "dist", "-l", "3000"] diff --git a/README.md b/README.md index 0c11c4553..f31032d9c 100644 --- a/README.md +++ b/README.md @@ -296,20 +296,48 @@ MediaCrawler 支持多种数据存储方式，包括 CSV、JSON、JSONL、Excel ## 💰 赞助商展示 - - -
-TikHub.io 提供 900+ 高稳定性数据接口，覆盖 TK、DY、XHS、Y2B、Ins、X 等 14+ 海内外主流平台，支持用户、内容、商品、评论等多维度公开数据 API，并配套 4000 万+ 已清洗结构化数据集，使用邀请码 cfzyejV9 注册并充值，即可额外获得 $2 赠送额度。 - -
-
- - -Atlas Cloud -Atlas Cloud - -
-Atlas Cloud 是一个全模态 AI 推理平台，让开发者通过统一的 AI API 访问视频生成、图像生成和 LLM API，无需分别维护多个厂商集成，即可调用 300+ 精选模型。Atlas Cloud 最新推出 coding plan 优惠，为开发者提供更具性价比的 API 访问预算。 + + + + + + + + + + + + + + + + + + + + + + + + + +
赞助商介绍
+ TikHub + + TikHub.io 提供 900+ 高稳定性数据接口，覆盖 TK、DY、XHS、Y2B、Ins、X 等 14+ 海内外主流平台，支持用户、内容、商品、评论等多维度公开数据 API，并配套 4000 万+ 已清洗结构化数据集，使用邀请码 cfzyejV9 注册并充值，即可额外获得 $2 赠送额度。 +
+ Atlas CloudAtlas Cloud + + Atlas Cloud 是一个全模态 AI 推理平台，让开发者通过统一的 AI API 访问视频生成、图像生成和 LLM API，无需分别维护多个厂商集成，即可调用 300+ 精选模型。Atlas Cloud 最新推出 coding plan 优惠，为开发者提供更具性价比的 API 访问预算。 +
+ Bloome + + Bloome 是一个 AI Agent IM 平台——让多个 AI agent（Claude、ChatGPT、DeepSeek 等）和你在同一个对话里像团队成员一样协作，自动分工、互相校对，直接生成表格、文档与可视化看板。零配置、云端运行，网页和手机都能用，还能把配好的 agent 一键分享给团队。👉 试试 Bloome +
+ NodeMaven + + NodeMaven 提供稳定可靠的高质量代理服务，适用于自动化、网页抓取、SEO 研究和社交媒体管理。服务支持 99.9% 可用性、最长 7 天的粘性会话、IP 质量筛选（所有代理的欺诈评分均低于 97%）、无需 KYC，以及最高 10% 的流量返现。MediaCrawler 用户使用优惠码 CRAWLER35 可享移动和住宅代理 35% 折扣，使用 CRAWLER40 可享 ISP（静态）代理 40% 折扣。👉 访问 NodeMaven +
--- diff --git a/README_en.md b/README_en.md index 36a2d4874..fb0d96244 100644 --- a/README_en.md +++ b/README_en.md @@ -278,20 +278,48 @@ MediaCrawler supports multiple data storage methods, including CSV, JSON, JSONL, ### 💰 Sponsor Display - - -
-TikHub.io provides 900+ highly stable data interfaces, covering 14+ mainstream domestic and international platforms including TK, DY, XHS, Y2B, Ins, X, etc. Supports multi-dimensional public data APIs for users, content, products, comments, etc., with 40M+ cleaned structured datasets. Use invitation code cfzyejV9 to register and recharge, and get an additional $2 bonus. - -
-
- - -Atlas Cloud -Atlas Cloud - -
-Atlas Cloud is a full-modal AI inference platform that gives developers a single AI API to access video generation, image generation, and LLM APIs. Instead of managing multiple vendor integrations, you connect once and get unified access to 300+ curated models across all modalities. Check out Atlas Cloud's new coding plan promotion for more budget-friendly API access. + + + + + + + + + + + + + + + + + + + + + + + + + +
SponsorIntroduction
+ TikHub + + TikHub.io provides 900+ highly stable data interfaces, covering 14+ mainstream domestic and international platforms including TK, DY, XHS, Y2B, Ins, X, etc. Supports multi-dimensional public data APIs for users, content, products, comments, etc., with 40M+ cleaned structured datasets. Use invitation code cfzyejV9 to register and recharge, and get an additional $2 bonus. +
+ Atlas CloudAtlas Cloud + + Atlas Cloud is a full-modal AI inference platform that gives developers a single AI API to access video generation, image generation, and LLM APIs. Instead of managing multiple vendor integrations, you connect once and get unified access to 300+ curated models across all modalities. Check out Atlas Cloud's new coding plan promotion for more budget-friendly API access. +
+ Bloome + + Bloome is an AI Agent IM platform — multiple AI agents (Claude, ChatGPT, DeepSeek, etc.) collaborate with you in a single conversation like team members, automatically dividing up the work and cross-checking each other, and directly producing tables, documents, and visual dashboards. Zero config, runs in the cloud, works on both web and mobile, and you can share your configured agents with your team in one click. 👉 Try Bloome +
+ NodeMaven + + NodeMaven provides reliable, high-quality proxies for automation, web scraping, SEO research, and social media management. Features include 99.9% uptime, sticky sessions up to 7 days, IP filtering across all proxies (fraud score below 97%), no KYC, and traffic cashback of up to 10%. MediaCrawler users get 35% off mobile and residential proxies with code CRAWLER35, and 40% off ISP (static) proxies with code CRAWLER40. 👉 Visit NodeMaven +
--- diff --git a/README_es.md b/README_es.md index 66974c839..f971f1faa 100644 --- a/README_es.md +++ b/README_es.md @@ -278,11 +278,40 @@ MediaCrawler soporta múltiples métodos de almacenamiento de datos, incluyendo ### 💰 Exhibición de Patrocinadores - - -
-TikHub.io proporciona 900+ interfaces de datos altamente estables, cubriendo 14+ plataformas principales nacionales e internacionales incluyendo TK, DY, XHS, Y2B, Ins, X, etc. Soporta APIs de datos públicos multidimensionales para usuarios, contenido, productos, comentarios, etc., con 40M+ conjuntos de datos estructurados limpios. Use el código de invitación cfzyejV9 para registrarse y recargar, y obtenga $2 adicionales de bonificación. - + + + + + + + + + + + + + + + + + + + + + +
PatrocinadorIntroducción
+ TikHub + + TikHub.io proporciona 900+ interfaces de datos altamente estables, cubriendo 14+ plataformas principales nacionales e internacionales incluyendo TK, DY, XHS, Y2B, Ins, X, etc. Soporta APIs de datos públicos multidimensionales para usuarios, contenido, productos, comentarios, etc., con 40M+ conjuntos de datos estructurados limpios. Use el código de invitación cfzyejV9 para registrarse y recargar, y obtenga $2 adicionales de bonificación. +
+ Bloome + + Bloome es una plataforma de IM de agentes de IA: varios agentes de IA (Claude, ChatGPT, DeepSeek, etc.) colaboran contigo en una misma conversación como miembros de un equipo, dividiéndose el trabajo automáticamente y revisándose entre sí, y generando directamente tablas, documentos y paneles visuales. Sin configuración, funciona en la nube, disponible tanto en web como en móvil, y puedes compartir tus agentes configurados con tu equipo con un solo clic. 👉 Prueba Bloome +
+ NodeMaven + + NodeMaven ofrece proxies fiables y de alta calidad para automatización, web scraping, investigación SEO y gestión de redes sociales. El servicio incluye una disponibilidad del 99,9%, sesiones persistentes de hasta 7 días, filtrado de IP en todos los proxies (puntuación de fraude inferior al 97%), sin KYC y reembolso de hasta el 10% del tráfico. Los usuarios de MediaCrawler obtienen un 35% de descuento en proxies móviles y residenciales con el código CRAWLER35, y un 40% de descuento en proxies ISP (estáticos) con CRAWLER40. 👉 Visita NodeMaven +
--- diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 000000000..e04b185bc --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,35 @@ +services: + backend: + build: + context: . + dockerfile: Dockerfile.backend + container_name: mediacrawler-backend + ports: + - "8080:8080" + environment: + - PYTHONUNBUFFERED=1 + volumes: + - ./:/app + networks: + - mediacrawler-network + restart: unless-stopped + + frontend: + build: + context: . + dockerfile: Dockerfile.frontend + container_name: mediacrawler-frontend + ports: + - "3000:3000" + depends_on: + backend: + condition: service_healthy + networks: + - mediacrawler-network + environment: + - REACT_APP_API_URL=http://backend:8080 + restart: unless-stopped + +networks: + mediacrawler-network: + driver: bridge diff --git a/docs/Cau-Hinh-Word-Cloud.md b/docs/Cau-Hinh-Word-Cloud.md new file mode 100644 index 000000000..41c38ca21 --- /dev/null +++ b/docs/Cau-Hinh-Word-Cloud.md @@ -0,0 +1,46 @@ +# Cấu Hình Word Cloud + +Word Cloud là một hình ảnh trực quan hóa từ từ các bình luận được crawl. + +## Bật Word Cloud + +Cấu hình trong `config/base_config.py`: + +```python +ENABLE_GET_WORDCLOUD = True # Bật tính năng word cloud +ENABLE_GET_COMMENTS = True # Phải bật crawl bình luận +``` + +## Thêm Từ Dừng (Stopwords) + +1. Mở file `docs/hit_stopwords.txt` +2. Thêm các từ cần loại bỏ (mỗi từ một dòng) + +Ví dụ: +``` +thế +này +là +của +và +``` + +## Thêm Từ Tùy Chỉnh + +Trong `config/base_config.py`: + +```python +CUSTOM_WORDS = [ + "lập trình", + "Python", + "web scraping" +] +``` + +## Cách Sử Dụng + +1. Crawl dữ liệu với word cloud được bật +2. Chương trình tự động tạo file ảnh word cloud +3. File ảnh lưu trong thư mục `data/{platform}/` + +--- diff --git a/docs/Cau-Truc-Ma-Du-An.md b/docs/Cau-Truc-Ma-Du-An.md new file mode 100644 index 000000000..11dfe5264 --- /dev/null +++ b/docs/Cau-Truc-Ma-Du-An.md @@ -0,0 +1,25 @@ +# Cấu Trúc Mã Dự Án + +Xem [Kiến Trúc Dự Án](Kien-Truc-Du-An.md) để hiểu chi tiết cấu trúc mã và thiết kế kiến trúc của dự án. + +## Cấu Trúc Thư Mục Chính + +``` +MediaCrawler/ +├── main.py # Điểm vào chương trình +├── config/ # Quản lý cấu hình +├── media_platform/ # Triển khai crawler platform +├── store/ # Lưu trữ dữ liệu +├── database/ # Lớp cơ sở dữ liệu +├── proxy/ # Quản lý proxy +├── tools/ # Công cụ tiện ích +└── docs/ # Tài liệu +``` + +## Tìm Hiểu Thêm + +- [Kiến Trúc Hệ Thống Chi Tiết](Kien-Truc-Du-An.md) +- [FAQ](FAQ-VietNam.md) +- [Lưu Trữ Dữ Liệu](Huong-Dan-Luu-Tru-Du-Lieu.md) + +--- diff --git a/docs/Danh-Sach-Ung-Ho.md b/docs/Danh-Sach-Ung-Ho.md new file mode 100644 index 000000000..830ba082a --- /dev/null +++ b/docs/Danh-Sach-Ung-Ho.md @@ -0,0 +1,21 @@ +# Danh Sách Những Người Ủng Hộ + +Cảm ơn tất cả những người đã ủng hộ và đóng góp cho dự án MediaCrawler! + +Nếu bạn muốn được liệt kê trong danh sách này, vui lòng: + +1. Liên hệ với tác giả qua WeChat hoặc Github +2. Cung cấp tên hoặc username của bạn +3. (Tùy chọn) Để lại một bình luận về dự án + +## Cách Hỗ Trợ + +Bạn có thể hỗ trợ dự án bằng: + +- Star trên Github ⭐ +- Share dự án với bạn bè +- Báo cáo lỗi hoặc đề xuất tính năng +- Góp phần code thông qua pull request +- Tài trợ tác giả thông qua các kênh quyên góp + +--- diff --git a/docs/FAQ-VietNam.md b/docs/FAQ-VietNam.md new file mode 100644 index 000000000..e9fc041a7 --- /dev/null +++ b/docs/FAQ-VietNam.md @@ -0,0 +1,109 @@ +# Các Câu Hỏi Thường Gặp - FAQ + +## Vấn Đề Do Thiếu Môi Trường Node.js + +**Q: Crawl Douyin và Zhihu báo lỗi: `execjs._exceptions.ProgramError: SyntaxError: thiếu ';'`** + +A: Lỗi này do thiếu môi trường Node.js. Cài đặt Node.js phiên bản >= v16 để giải quyết. + +**Q: Dùng Cookie để crawl Douyin báo lỗi: execjs._exceptions.ProgramError: TypeError: Cannot read property 'JS_MD5_NO_COMMON_JS' of null** + +A: Trên Windows, tải về Node.js từ `https://nodejs.org/en/blog/release/v16.8.0` (phiên bản Windows 64-bit Installer), rồi cài đặt theo hướng dẫn. + +--- + +## Vấn Đề Xác Thực Slider Khi Đăng Nhập Xiaohongshu + +**Q: Xiaohongshu quét mã QR thành công nhưng trình duyệt liên tục xác thực slider, không thể đăng nhập?** + +A: Xiaohongshu có cơ chế chống bot rất nghiêm ngặt. **Khuyến khích sử dụng CDP mode kết nối trình duyệt thật của bạn** (cấu hình mặc định), không nên dùng trình duyệt vô danh hay chế độ Playwright chuẩn. Kết nối trình duyệt thật giúp bạn tái sử dụng Cookie, trạng thái đăng nhập và lịch sử duyệt web có sẵn, giảm đáng kể rủi ro bị phát hiện chống bot. Nếu vẫn gặp vấn đề slider, hãy thử xóa thư mục `brower_data` trong thư mục dự án và tái đăng nhập. + +--- + +## Cách Chỉ Định Từ Khóa + +**Q: Có thể chỉ định từ khóa để crawl không?** + +A: Có, trong file `config/base_config.py`, tham số `KEYWORDS` được dùng để kiểm soát các từ khóa cần crawl. + +--- + +## Cách Chỉ Định Bài Viết + +**Q: Có thể chỉ định bài viết để crawl không?** + +A: Có, trong file `config/base_config.py`, tham số `XHS_SPECIFIED_ID_LIST` được dùng để kiểm soát danh sách ID bài viết cần crawl. + +--- + +## Crawl Bất Ngờ Dừng Hoạt Động + +**Q: Ban đầu có thể crawl dữ liệu, nhưng sau một thời gian thì dừng hoạt động?** + +A: Tình huống này thường xảy ra do tài khoản của bạn đã kích hoạt cơ chế chống bot của nền tảng. ❗️❗️Vui lòng không crawl quy mô lớn từ nền tảng, điều này ảnh hưởng đến hoạt động của nền tảng. + +--- + +## Cách Thay Đổi Tài Khoản Đăng Nhập + +**Q: Cách thay đổi tài khoản đăng nhập?** + +A: Xóa thư mục `brower_data` ở thư mục gốc của dự án. + +--- + +## Vấn Đề Timeout của Playwright + +**Q: Báo lỗi `playwright._impl._api_types.TimeoutError: Timeout 30000ms exceeded.`** + +A: Kiểm tra xem bạn có sử dụng VPN không. + +--- + +## Cách Xác Thực Manual Slider Cho Playwright + +**Q: Xiaohongshu quét mã QR thành công, làm cách nào xác thực slider manually?** + +A: Mở file `config/base_config.py`, tìm cấu hình `HEADLESS`, đặt nó thành `False`. Sau đó khởi động lại dự án, trong trình duyệt hãy thực hiện xác thực slider manually. + +--- + +## Tạo Word Cloud + +**Q: Cách cấu hình tạo word cloud?** + +A: Mở file `config/base_config.py`, tìm hai cấu hình `ENABLE_GET_WORDCLOUD` và `ENABLE_GET_COMMENTS`, đặt cả hai thành `True` để sử dụng tính năng này. + +--- + +## Thêm Từ Dừng và Từ Tùy Chỉnh Cho Word Cloud + +**Q: Cách thêm từ dừng (stopwords) và từ tùy chỉnh vào word cloud?** + +A: Mở `docs/hit_stopwords.txt` và nhập các từ dừng (lưu ý mỗi từ một dòng). Mở file `config/base_config.py`, tìm `CUSTOM_WORDS` và thêm từ tùy chỉnh theo định dạng được hướng dẫn. + +--- + +## Các Vấn Đề Liên Quan Đến Kết Nối CDP + +**Q: Sau khi chạy crawler, nhận được thông báo không thể kết nối tới trình duyệt, báo lỗi `Cannot connect to existing browser on port 9222`?** + +A: Vui lòng kiểm tra các điểm sau: + +1. Đảm bảo trình duyệt Chrome đã mở và đang chạy +2. Nhập `chrome://inspect/#remote-debugging` vào địa chỉ Chrome, đảm bảo đã tích chọn **"Allow remote debugging for this browser instance"** +3. Trang nên hiển thị `Server running at: 127.0.0.1:9222`, nếu không có nghĩa là remote debugging chưa bật thành công +4. Đảm bảo phiên bản Chrome >= 144, phiên bản cũ không hỗ trợ, nhập `chrome://version` vào địa chỉ để kiểm tra phiên bản + +**Q: Sau khi chạy crawler, trình duyệt bật lên hộp thoại xác nhận, cần phải làm gì?** + +A: Đây là hành vi bình thường. Chrome sẽ bật hộp thoại xác nhận khi kết nối tới trình duyệt đã có, hãy nhấp vào "Chấp nhận". Chương trình sẽ chờ xác nhận từ người dùng, thời gian timeout mặc định là 60 giây, hãy nhấp vào xác nhận trong khoảng thời gian này. + +**Q: Không muốn kết nối tới trình duyệt đã có, muốn chương trình tự động khởi động một trình duyệt mới?** + +A: Trong `config/base_config.py`, đặt `CDP_CONNECT_EXISTING = False`, chương trình sẽ tự động phát hiện và khởi động một instance Chrome/Edge mới. + +**Q: Tại sao khuyến khích kết nối tới trình duyệt đã có thay vì khởi động trình duyệt mới?** + +A: Kết nối tới trình duyệt đã có cho phép bạn trực tiếp tái sử dụng Cookie thật, trạng thái đăng nhập, plugin mở rộng và lịch sử duyệt web của chính bạn. Nền tảng rất khó phân biệt đây là hoạt động tự động hay hành vi người dùng thật, **giảm đáng kể rủi ro bị phát hiện chống bot**. Còn khởi động trình duyệt mới là một môi trường "sạch", dễ bị nền tảng nhận dạng là bot. + diff --git a/docs/Gioi-Thieu-Dich-Vu-Tra-Phi.md b/docs/Gioi-Thieu-Dich-Vu-Tra-Phi.md new file mode 100644 index 000000000..cedd44f02 --- /dev/null +++ b/docs/Gioi-Thieu-Dich-Vu-Tra-Phi.md @@ -0,0 +1,24 @@ +# Giới Thiệu Dịch Vụ Trả Phí + +## MediaCrawler Pro + +MediaCrawler Pro là phiên bản nâng cao của MediaCrawler, cung cấp các tính năng bổ sung cho người dùng chuyên nghiệp. + +### Các Tính Năng Chính + +- ✅ Hỗ trợ đa tài khoản + pool proxy IP +- ✅ Tính năng tiếp tục crawl từ điểm dừng +- ✅ Loại bỏ phụ thuộc Playwright +- ✅ Hỗ trợ đầy đủ môi trường Linux +- ✅ AI Agent để phân tích nội dung truyền thông +- ✅ Và nhiều tính năng khác... + +### Liên Hệ + +Để tìm hiểu thêm về MediaCrawler Pro: + +1. Truy cập [Github MediaCrawlerPro](https://github.com/MediaCrawlerPro) +2. Liên hệ tác giả qua [WeChat](Gioi-Thieu-Tac-Gia.md) +3. Đặt câu hỏi trong [Nhóm WeChat](Nhom-WeChat.md) + +--- diff --git a/docs/Gioi-Thieu-Tac-Gia.md b/docs/Gioi-Thieu-Tac-Gia.md new file mode 100644 index 000000000..331c0b85c --- /dev/null +++ b/docs/Gioi-Thieu-Tac-Gia.md @@ -0,0 +1,28 @@ +# Giới Thiệu Về Tác Giả + +> Mọi người đều gọi tôi là Ah Jiang, username: Lập Trình Viên Ah Jiang - Relakkes, hiện là một nhà phát triển độc lập, tập trung vào phát triển AI Agent và web scraping, All in AI. + +- [Tác Giả Kho Lưu Trữ Web Scraping 40K+ Star - MediaCrawler trên Github](https://github.com/NanmiCoder/MediaCrawler) +- Lập trình viên Full Stack, thành thạo Python, Golang, JavaScript, chủ yếu dùng Golang tại công ty +- Từng dẫn dắt và tham gia thiết kế kiến trúc hệ thống crawl hàng triệu bản ghi +- Web scraping là một sở thích kỹ thuật, có cảm giác đối kháng, càng khó càng hứng thú +- Hiện tập trung vào lĩnh vực AI Agent, tích cực khám phá ứng dụng và đổi mới công nghệ AI +- Nếu bạn có dự án liên quan đến AI Agent cần hợp tác, vui lòng liên hệ, tôi có thời gian rảnh để đầu tư + +## Liên Hệ WeChat + +![relakkes_weichat.JPG](static/images/relakkes_weichat.jpg) + +## Trang Chủ Bilibili + +https://space.bilibili.com/434377496 + +## Trang Chủ Douyin + +https://www.douyin.com/user/MS4wLjABAAAATJPY7LAlaa5X-c8uNdWkvz0jUGgpw4eeXIwu_8BhvqE?previous_page=app_code_link + +## Trang Chủ Xiaohongshu + +https://www.xiaohongshu.com/user/profile/5f58bd990000000001003753?xhsshare=CopyLink&appuid=5f58bd990000000001003753&apptime=1724737153 + +--- diff --git a/docs/Huong-Dan-CDP-Mode.md b/docs/Huong-Dan-CDP-Mode.md new file mode 100644 index 000000000..b79fd1f90 --- /dev/null +++ b/docs/Huong-Dan-CDP-Mode.md @@ -0,0 +1,63 @@ +# Hướng Dẫn Sử Dụng Chế Độ CDP + +## Tổng Quan + +Chế độ CDP (Chrome DevTools Protocol) là một kỹ thuật chống phát hiện nâu cao, điều khiển trình duyệt Chrome/Edge hiện có của người dùng để crawl web. So với Playwright tự động hóa truyền thống, chế độ CDP có các ưu điểm: + +### 🎯 Các Ưu Điểm Chính + +1. **Môi trường trình duyệt thật**: Dùng trình duyệt thực tế của người dùng, bao gồm tất cả extension và cài đặt +2. **Khả năng chống phát hiện tốt hơn**: Dấu vân tay trình duyệt thực tế, khó bị phát hiện là công cụ tự động +3. **Giữ trạng thái người dùng**: Tự động kế thừa trạng thái đăng nhập, Cookie và lịch sử duyệt +4. **Hỗ trợ Extension**: Có thể sử dụng ad blocker, proxy extension của người dùng +5. **Hành vi tự nhiên hơn**: Mô hình hành vi gần hơn với người dùng thật + +### 📌 Hai Chế Độ CDP + +| Chế Độ | Mô Tả | Trường Hợp Sử Dụng | +|--------|--------|-----------------| +| **Kết nối trình duyệt hiện có** (mặc định khuyến nghị) | Kết nối Chrome đang sử dụng, tái sử dụng Cookie, extension thật | Yêu cầu chống phát hiện cao | +| **Khởi động trình duyệt mới** | Tự động phát hiện và khởi động Chrome/Edge mới | Khi không cần tái sử dụng trạng thái | + +## Bắt Đầu Nhanh + +### Phương Pháp 1: Kết Nối Trình Duyệt Hiện Có (Khuyến Nghị Mặc Định) + +Đây là **cách mặc định và khuyến nghị**, trực tiếp kết nối Chrome đang sử dụng, hiệu suất chống phát hiện tốt nhất. + +#### Bước 1: Đảm Bảo Phiên Bản Chrome + +Cần Chrome **144 trở lên**. Nhập `chrome://version` trong address bar để kiểm tra. + +#### Bước 2: Bật Remote Debugging + +1. Nhập `chrome://inspect/#remote-debugging` trong address bar +2. Tích chọn **"Allow remote debugging for this browser instance"** +3. Trang sẽ hiển thị `Server running at: 127.0.0.1:9222` + +#### Bước 3: Chạy Crawler + +```bash +uv run main.py --platform xhs --lt qrcode --type search +``` + +Chrome sẽ **bật hộp thoại xác nhận**, nhấp "Chấp nhận". Chương trình chờ xác nhận (timeout 60s mặc định). + +#### Cấu Hình + +`config/base_config.py`: + +```python +ENABLE_CDP_MODE = True +CDP_CONNECT_EXISTING = True # Mặc định bật +CDP_DEBUG_PORT = 9222 +``` + +### Phương Pháp 2: Khởi Động Trình Duyệt Mới + +```python +ENABLE_CDP_MODE = True +CDP_CONNECT_EXISTING = False # Đóng, khởi động mới +``` + +--- diff --git a/docs/Huong-Dan-Dang-Nhap-Sdt.md b/docs/Huong-Dan-Dang-Nhap-Sdt.md new file mode 100644 index 000000000..b683b57d3 --- /dev/null +++ b/docs/Huong-Dan-Dang-Nhap-Sdt.md @@ -0,0 +1,30 @@ +# Hướng Dẫn Đăng Nhập Bằng Số Điện Thoại + +Đăng nhập bằng số điện thoại là một phương pháp thay thế khi đăng nhập bằng mã QR gặp khó khăn. + +## Các Bước + +1. Cấu hình loại đăng nhập trong `config/base_config.py`: + +```python +LOGIN_TYPE = "phone" # Đổi từ qrcode thành phone +``` + +2. Chạy crawler: + +```bash +uv run main.py --platform xhs --lt phone --type search +``` + +3. Làm theo hướng dẫn trên giao diện: + - Nhập số điện thoại + - Nhân mã xác minh từ SMS + - Hoàn thành xác thực slider (nếu cần) + +## Lưu Ý + +- Có thể chậm hơn so với mã QR +- Một số nền tảng yêu cầu xác thực slider +- Hãy chắc chắn bạn có quyền truy cập SMS của số điện thoại + +--- diff --git a/docs/Huong-Dan-KuaiDaiLi.md b/docs/Huong-Dan-KuaiDaiLi.md new file mode 100644 index 000000000..3490b8c9f --- /dev/null +++ b/docs/Huong-Dan-KuaiDaiLi.md @@ -0,0 +1,30 @@ +# Hướng Dẫn Sử Dụng KuaiDaiLi (快代理) + +KuaiDaiLi là một nhà cung cấp proxy IP hàng đầu cho web scraping. + +## Các Bước Cơ Bản + +1. Đăng ký tài khoản tại [KuaiDaiLi](https://www.kuaidaili.com/) +2. Lấy API key từ dashboard +3. Cấu hình trong `config/base_config.py`: + +```python +ENABLE_IP_PROXY = True +IP_PROXY_PROVIDER = "kuaidaili" +IP_PROXY_POOL_COUNT = 5 # Số lượng proxy +``` + +4. Chạy crawler: + +```bash +uv run main.py --platform xhs --lt qrcode --type search +``` + +## Ưu Điểm + +- Dải IP rộng +- Tốc độ ổn định +- Hỗ trợ tiếng Trung tốt +- Giá cả cạnh tranh + +--- diff --git a/docs/Huong-Dan-Luu-Tru-Du-Lieu.md b/docs/Huong-Dan-Luu-Tru-Du-Lieu.md new file mode 100644 index 000000000..370830a02 --- /dev/null +++ b/docs/Huong-Dan-Luu-Tru-Du-Lieu.md @@ -0,0 +1,70 @@ +# Hướng Dẫn Lưu Trữ Dữ Liệu + +### 💾 Lưu Trữ Dữ Liệu + +MediaCrawler hỗ trợ nhiều cách lưu trữ dữ liệu, bạn có thể chọn phương pháp phù hợp nhất với nhu cầu: + +#### Các Phương Pháp Lưu Trữ + +- **File CSV**: Lưu vào CSV (thư mục `data/`) +- **File JSON**: Lưu vào JSON (thư mục `data/`) +- **File JSONL**: Lưu vào JSONL (thư mục `data/`) — Định dạng mặc định, mỗi dòng một JSON object, hiệu suất ghi append tốt +- **File Excel**: Lưu vào file Excel được định dạng (thư mục `data/`) ✨ Tính năng mới + - Hỗ trợ nhiều sheet (nội dung, bình luận, nhà sáng tạo) + - Định dạng chuyên nghiệp (kiểu tiêu đề, tự động điều chỉnh cột, viền) + - Dễ phân tích và chia sẻ +- **Lưu Trữ Cơ Sở Dữ Liệu** + - Sử dụng tham số `--init_db` để khởi tạo cơ sở dữ liệu (khi dùng `--init_db` không cần tham số tùy chọn khác) + - **SQLite**: Cơ sở dữ liệu nhẹ, không cần server, phù hợp cho người dùng cá nhân (khuyến nghị) + 1. Khởi tạo: `--init_db sqlite` + 2. Lưu dữ liệu: `--save_data_option sqlite` + - **MySQL**: Hỗ trợ lưu vào cơ sở dữ liệu quan hệ MySQL (cần tạo DB trước) + 1. Khởi tạo: `--init_db mysql` + 2. Lưu dữ liệu: `--save_data_option db` (tham số db được giữ lại để tương thích) + - **PostgreSQL**: Hỗ trợ lưu vào cơ sở dữ liệu PostgreSQL cao cấp (khuyến nghị cho production) + 1. Khởi tạo: `--init_db postgres` + 2. Lưu dữ liệu: `--save_data_option postgres` + +#### Ví Dụ Sử Dụng + +```bash +# Lưu vào Excel (khuyến nghị cho phân tích dữ liệu) ✨ Tính năng mới +uv run main.py --platform xhs --lt qrcode --type search --save_data_option excel + +# Khởi tạo SQLite +uv run main.py --init_db sqlite +# Lưu dữ liệu vào SQLite +uv run main.py --platform xhs --lt qrcode --type search --save_data_option sqlite +``` + +```bash +# Khởi tạo MySQL +uv run main.py --init_db mysql +# Lưu dữ liệu vào MySQL +uv run main.py --platform xhs --lt qrcode --type search --save_data_option db +``` + +```bash +# Khởi tạo PostgreSQL +uv run main.py --init_db postgres +# Lưu dữ liệu vào PostgreSQL +uv run main.py --platform xhs --lt qrcode --type search --save_data_option postgres +``` + +```bash +# Lưu vào CSV +uv run main.py --platform xhs --lt qrcode --type search --save_data_option csv + +# Lưu vào JSON +uv run main.py --platform xhs --lt qrcode --type search --save_data_option json + +# Lưu vào JSONL (định dạng mặc định, không cần chỉ định) +uv run main.py --platform xhs --lt qrcode --type search --save_data_option jsonl +``` + +#### Tài Liệu Chi Tiết + +- **Hướng Dẫn Xuất Excel**: Xem [Hướng Dẫn Xuất Excel](Huong-Dan-Xuat-Excel.md) +- **Cấu Hình Cơ Sở Dữ Liệu**: Tham khảo [FAQ](FAQ-VietNam.md) + +--- diff --git a/docs/Huong-Dan-Su-Dung-Proxy.md b/docs/Huong-Dan-Su-Dung-Proxy.md new file mode 100644 index 000000000..c16f320f0 --- /dev/null +++ b/docs/Huong-Dan-Su-Dung-Proxy.md @@ -0,0 +1,19 @@ +# Hướng Dẫn Sử Dụng Proxy IP + +> Lưu ý: Không nên crawl quy mô lớn từ các nền tảng truyền thông xã hội hoặc hành động bất hợp pháp khác 🤣 + +## Sơ Đồ Luồng Quy Trình + +[Sơ đồ luồng sử dụng Proxy IP](static/images/代理IP%20流程图.drawio.png) + +## Chọn Một Nhà Cung Cấp Proxy + +### KuaiDaiLi (快代理) + +[Hướng Dẫn Sử Dụng KuaiDaiLi](Huong-Dan-KuaiDaiLi.md) + +### WanDou HTTP + +[Hướng Dẫn Sử Dụng WanDou HTTP](Huong-Dan-WanDou-HTTP.md) + +--- diff --git a/docs/Huong-Dan-WanDou-HTTP.md b/docs/Huong-Dan-WanDou-HTTP.md new file mode 100644 index 000000000..16607d55d --- /dev/null +++ b/docs/Huong-Dan-WanDou-HTTP.md @@ -0,0 +1,30 @@ +# Hướng Dẫn Sử Dụng WanDou HTTP (豌豆HTTP) + +WanDou HTTP là một nhà cung cấp proxy HTTP cho web scraping. + +## Các Bước Cơ Bản + +1. Đăng ký tài khoản tại [WanDou HTTP](https://www.wandouip.com/) +2. Lấy API key từ dashboard +3. Cấu hình trong `config/base_config.py`: + +```python +ENABLE_IP_PROXY = True +IP_PROXY_PROVIDER = "wandou" +IP_PROXY_POOL_COUNT = 5 +``` + +4. Chạy crawler: + +```bash +uv run main.py --platform xhs --lt qrcode --type search +``` + +## Ưu Điểm + +- Proxy tốc độ cao +- Hỗ trợ nhiều giao thức +- Dải IP đa dạng +- Giá cơ bản + +--- diff --git a/docs/Huong-Dan-Xuat-Excel.md b/docs/Huong-Dan-Xuat-Excel.md new file mode 100644 index 000000000..5eb79d32b --- /dev/null +++ b/docs/Huong-Dan-Xuat-Excel.md @@ -0,0 +1,132 @@ +# Hướng Dẫn Xuất Excel + +## Tổng Quan + +MediaCrawler hiện hỗ trợ xuất dữ liệu crawled sang file Excel được định dạng (.xlsx) với kiểu dáng chuyên nghiệp và nhiều sheet cho nội dung, bình luận và nhà sáng tạo. + +## Các Tính Năng + +- **Workbook đa sheet**: Sheet riêng cho Nội Dung, Bình Luận và Nhà Sáng Tạo +- **Định dạng chuyên nghiệp**: + - Tiêu đề được định kiểu với nền xanh và chữ trắng + - Tự động điều chỉnh độ rộng cột + - Viền cell và bao phủ văn bản + - Bố cục sạch và dễ đọc +- **Xuất thông minh**: Sheet trống được xóa tự động +- **Lưu trữ có tổ chức**: File lưu tại thư mục `data/{platform}/` với timestamp + +## Cài Đặt + +Xuất Excel yêu cầu thư viện `openpyxl`: + +```bash +# Sử dụng uv (khuyến nghị) +uv sync + +# Hoặc dùng pip +pip install openpyxl +``` + +## Sử Dụng + +### Sử Dụng Cơ Bản + +1. **Cấu hình xuất Excel** trong `config/base_config.py`: + +```python +SAVE_DATA_OPTION = "excel" # Đổi từ jsonl/json/csv/db thành excel +``` + +2. **Chạy crawler**: + +```bash +# Ví dụ Xiaohongshu +uv run main.py --platform xhs --lt qrcode --type search + +# Ví dụ Douyin +uv run main.py --platform dy --lt qrcode --type search + +# Ví dụ Bilibili +uv run main.py --platform bili --lt qrcode --type search +``` + +3. **Tìm file Excel** trong thư mục `data/{platform}/`: + - Định dạng tên: `{platform}_{crawler_type}_{timestamp}.xlsx` + - Ví dụ: `xhs_search_20250128_143025.xlsx` + +### Ví Dụ Dòng Lệnh + +```bash +# Tìm kiếm theo từ khóa và xuất Excel +uv run main.py --platform xhs --lt qrcode --type search --save_data_option excel + +# Crawl bài viết cụ thể và xuất Excel +uv run main.py --platform xhs --lt qrcode --type detail --save_data_option excel + +# Crawl hồ sơ nhà sáng tạo và xuất Excel +uv run main.py --platform xhs --lt qrcode --type creator --save_data_option excel +``` + +## Cấu Trúc File Excel + +### Sheet Nội Dung +Chứa thông tin bài viết/video: +- `note_id`: Định danh bài viết duy nhất +- `title`: Tiêu đề bài viết +- `desc`: Mô tả bài viết +- `user_id`: ID tác giả +- `nickname`: Biệt danh tác giả +- `liked_count`: Số lượt thích +- `comment_count`: Số bình luận +- `share_count`: Số chia sẻ +- Và thêm các trường khác... + +### Sheet Bình Luận +Chứa thông tin bình luận: +- `comment_id`: Định danh bình luận duy nhất +- `note_id`: ID bài viết liên quan +- `content`: Nội dung bình luận +- `user_id`: ID người bình luận +- `nickname`: Biệt danh người bình luận +- `like_count`: Số lượt thích bình luận +- Và thêm các trường khác... + +### Sheet Nhà Sáng Tạo +Chứa thông tin nhà sáng tạo/tác giả: +- `user_id`: Định danh người dùng duy nhất +- `nickname`: Tên hiển thị +- `avatar`: URL ảnh hồ sơ +- `desc`: Tiểu sử/mô tả +- `fans`: Số người theo dõi +- Và thêm các trường khác... + +## Ưu Điểm So Với Các Định Dạng Khác + +### So Với CSV +- Nhiều sheet trong một file +- Định dạng chuyên nghiệp +- Xử lý ký tự đặc biệt tốt hơn +- Không có vấn đề mã hóa + +### So Với JSON +- Định dạng bảng dễ đọc +- Dễ mở trong Excel/Google Sheets +- Phù hợp cho phân tích dữ liệu +- Chia sẻ dễ dàng + +### So Với Database +- Không cần thiết lập database +- Định dạng file đơn lẻ +- Dễ chia sẻ và lưu trữ +- Hoạt động ngoại tuyến + +## Mẹo & Thực Hành Tốt + +1. **Tập dữ liệu lớn**: Với crawl rất lớn (>10,000 hàng), cân nhắc sử dụng database +2. **Phân tích dữ liệu**: File Excel hoạt động tốt với Python pandas: + ```python + import pandas as pd + df = pd.read_excel('file.xlsx', sheet_name='Contents') + ``` + +--- diff --git a/docs/Kien-Truc-Du-An.md b/docs/Kien-Truc-Du-An.md new file mode 100644 index 000000000..19f09f75c --- /dev/null +++ b/docs/Kien-Truc-Du-An.md @@ -0,0 +1,359 @@ +# Tài Liệu Kiến Trúc MediaCrawler + +## 1. Tổng Quan Dự Án + +### 1.1 Giới Thiệu Dự Án + +MediaCrawler là một khung web scraper đa nền tảng dành cho truyền thông xã hội, được xây dựng bằng Python bất đồng bộ, hỗ trợ crawl nội dung, bình luận và thông tin nhà sáng tạo từ các nền tảng mạng xã hội chính. + +### 1.2 Các Nền Tảng Được Hỗ Trợ + +| Nền Tảng | Mã | Chức Năng Chính | +|----------|-----|-----------------| +| Xiaohongshu | `xhs` | Tìm kiếm note, chi tiết, nhà sáng tạo | +| Douyin (TikTok CN) | `dy` | Tìm kiếm video, chi tiết, nhà sáng tạo | +| Kuaishou | `ks` | Tìm kiếm video, chi tiết, nhà sáng tạo | +| Bilibili | `bili` | Tìm kiếm video, chi tiết, UP chủ | +| Weibo | `wb` | Tìm kiếm weibo, chi tiết, blogger | +| Baidu Tieba | `tieba` | Tìm kiếm bài viết, chi tiết | +| Zhihu | `zhihu` | Tìm kiếm hỏi đáp, chi tiết, trả lời viên | + +### 1.3 Các Tính Năng Cốt Lõi + +- **Hỗ trợ đa nền tảng**: Giao diện crawler thống nhất, hỗ trợ 7 nền tảng chính +- **Nhiều phương pháp đăng nhập**: Mã QR, số điện thoại, Cookie +- **Nhiều cách lưu trữ**: CSV, JSON, JSONL, SQLite, MySQL, MongoDB, Excel +- **Chống scrapy**: Chế độ CDP, pool proxy IP, ký hiệu yêu cầu +- **Bất đồng bộ hiệu suất cao**: Kiến trúc async dựa trên asyncio, crawl hiệu quả +- **Tạo word cloud**: Tự động tạo word cloud từ bình luận + +--- + +## 2. Tổng Quan Kiến Trúc Hệ Thống + +### 2.1 Sơ Đồ Kiến Trúc Tổng Thể + +``` +┌─────────────────────────────────────────────────────────┐ +│ ENTRY LAYER (Lớp Vào) │ +│ main.py (Lối vào) | config (Cấu hình) | cmd_arg │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ CRAWLER CORE LAYER (Lớp Crawler Cốt Lõi) │ +│ CrawlerFactory (Công Nhân) → AbstractCrawler (Lớp Cơ)│ +│ ├─ XiaoHongShuCrawler │ +│ ├─ DouYinCrawler │ +│ ├─ KuaishouCrawler │ +│ ├─ BilibiliCrawler │ +│ ├─ WeiboCrawler │ +│ ├─ TieBaCrawler │ +│ └─ ZhihuCrawler │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ API CLIENT LAYER (Lớp Client API) │ +│ AbstractApiClient → Các Client Platform │ +│ (XiaoHongShuClient, DouYinClient, ...) │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ STORAGE LAYER (Lớp Lưu Trữ) │ +│ StoreFactory → CSV/JSON/SQLite/MySQL/MongoDB/Excel │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ INFRASTRUCTURE LAYER (Lớp Cơ Sở Hạ Tầng) │ +│ Browser (Playwright/CDP) | Proxy Pool | Cache | Login │ +└─────────────────────────────────────────────────────────┘ +``` + +### 2.2 Luồng Dữ Liệu + +``` +Dữ Liệu Vào → Xử Lý → Dữ Liệu Ra → Lưu Trữ + ├─ Từ khóa ├─ Khởi động browser ├─ Nội dung + ├─ ID ├─ Xác thực đăng nhập ├─ Bình luận + └─ Cấu hình ├─ Tìm kiếm/crawl ├─ Nhà sáng tạo + ├─ Phân tích dữ liệu ├─ Tệp media + └─ Lấy bình luận │ + ↓ + Lưu vào: File/DB/NoSQL +``` + +--- + +## 3. Cấu Trúc Thư Mục + +``` +MediaCrawler/ +├── main.py # Điểm vào chương trình +├── var.py # Biến bối cảnh toàn cầu +├── pyproject.toml # Cấu hình dự án +│ +├── base/ # Các lớp trừu tượng cơ bản +│ └── base_crawler.py # Lớp cơ bản crawler, login, store, client +│ +├── config/ # Quản lý cấu hình +│ ├── base_config.py # Cấu hình cốt lõi +│ ├── db_config.py # Cấu hình cơ sở dữ liệu +│ └── {platform}_config.py # Cấu hình platform cụ thể +│ +├── media_platform/ # Triển khai crawler platform +│ ├── xhs/ # Xiaohongshu +│ ├── douyin/ # Douyin +│ ├── kuaishou/ # Kuaishou +│ ├── bilibili/ # Bilibili +│ ├── weibo/ # Weibo +│ ├── tieba/ # Baidu Tieba +│ └── zhihu/ # Zhihu +│ +├── store/ # Lưu trữ dữ liệu +│ ├── excel_store_base.py # Lớp cơ bản Excel +│ └── {platform}/ # Triển khai lưu trữ platform +│ +├── database/ # Lớp cơ sở dữ liệu +│ ├── models.py # Định nghĩa mô hình ORM +│ ├── db_session.py # Quản lý phiên DB +│ └── mongodb_store_base.py # Lớp cơ bản MongoDB +│ +├── proxy/ # Quản lý proxy +│ ├── proxy_ip_pool.py # Quản lý pool IP +│ ├── proxy_mixin.py # Mixin proxy +│ └── providers/ # Nhà cung cấp proxy +│ +├── cache/ # Hệ thống cache +│ ├── abs_cache.py # Lớp trừu tượng cache +│ ├── local_cache.py # Cache cục bộ +│ └── redis_cache.py # Cache Redis +│ +├── tools/ # Module công cụ +│ ├── app_runner.py # Quản lý chạy ứng dụng +│ ├── browser_launcher.py # Khởi động trình duyệt +│ ├── cdp_browser.py # Quản lý trình duyệt CDP +│ ├── crawler_util.py # Công cụ crawler +│ └── async_file_writer.py # Ghi file bất đồng bộ +│ +├── model/ # Mô hình dữ liệu +│ └── m_{platform}.py # Mô hình Pydantic +│ +├── libs/ # Thư viện JS +│ └── stealth.min.js # Script chống phát hiện +│ +└── cmd_arg/ # Tham số dòng lệnh + └── arg.py # Định nghĩa tham số +``` + +--- + +## 4. Chi Tiết Các Module Cốt Lõi + +### 4.1 Hệ Thống Lớp Cơ Bản + +- **AbstractCrawler**: Lớp cơ bản cho crawler + - `start()`: Khởi động crawler + - `search()`: Tính năng tìm kiếm + - `launch_browser()`: Khởi động trình duyệt + +- **AbstractLogin**: Lớp cơ bản cho đăng nhập + - `login_by_qrcode()`: Đăng nhập bằng mã QR + - `login_by_mobile()`: Đăng nhập bằng số điện thoại + - `login_by_cookies()`: Đăng nhập bằng Cookie + +- **AbstractStore**: Lớp cơ bản cho lưu trữ + - `store_content()`: Lưu nội dung + - `store_comment()`: Lưu bình luận + - `store_creator()`: Lưu thông tin nhà sáng tạo + +### 4.2 Chu Kỳ Sống Crawler + +1. Khởi tạo CrawlerFactory +2. Tạo instance crawler cụ thể +3. Khởi động trình duyệt (Playwright hoặc CDP) +4. Xác thực đăng nhập (nếu cần) +5. Thực hiện tìm kiếm hoặc lấy chi tiết +6. Phân tích dữ liệu +7. Lưu trữ dữ liệu +8. Đóng kết nối + +### 4.3 Ba Chế Độ Crawl + +| Chế Độ | Giá Trị Config | Mô Tả | Trường Hợp Sử Dụng | +|--------|---------|---------|-----------------| +| Search (Tìm Kiếm) | `search` | Tìm kiếm theo từ khóa | Lấy nội dung chủ đề cụ thể | +| Detail (Chi Tiết) | `detail` | Lấy chi tiết ID cụ thể | Lấy nội dung đã biết | +| Creator (Nhà Sáng Tạo) | `creator` | Lấy tất cả nội dung nhà sáng tạo | Theo dõi blogger cụ thể | + +--- + +## 5. Lớp Lưu Trữ + +### 5.1 Các Phương Pháp Lưu Trữ + +| Phương Pháp | Giá Trị Config | Ưu Điểm | Trường Hợp Sử Dụng | +|-------------|---------|--------|-----------------| +| CSV | `csv` | Đơn giản, phổ quát | Dữ liệu nhỏ, xem nhanh | +| JSON | `json` | Cấu trúc hoàn chỉnh, dễ phân tích | Tương tác API, trao đổi dữ liệu | +| JSONL | `jsonl` | Ghi append, hiệu suất tốt | Dữ liệu lớn, crawl tăng dần (mặc định) | +| SQLite | `sqlite` | Nhẹ, không cần server | Dev cục bộ, dự án nhỏ | +| MySQL | `db` | Hiệu suất tốt, hỗ trợ đồng thời | Môi trường production | +| MongoDB | `mongodb` | Linh hoạt, dễ mở rộng | Dữ liệu không cấu trúc | +| Excel | `excel` | Trực quan, dễ chia sẻ | Báo cáo, phân tích dữ liệu | + +--- + +## 6. Lớp Cơ Sở Hạ Tầng + +### 6.1 Hệ Thống Proxy + +- **Các Nhà Cung Cấp Proxy**: + - KuaiDaiLi (快代理) + - WanDouHttp (万代理) + - JiShuHttp (技术IP) + +- **Quản Lý Pool**: + - Tải proxy từ nhà cung cấp + - Xác thực proxy hợp lệ + - Tự động làm mới khi hết hạn + +### 6.2 Luồng Đăng Nhập + +1. **Mã QR**: Hiển thị QR → Chờ quét → Lưu Cookie +2. **Số Điện Thoại**: Nhập số → Gửi OTP → Xác thực → Lưu Cookie +3. **Cookie**: Tải Cookie đã lưu → Xác thực → Sử dụng + +### 6.3 Quản Lý Trình Duyệt + +- **Chế độ Playwright**: Khởi động trình duyệt mới (môi trường sạch) +- **Chế độ CDP**: Kết nối tới Chrome đang chạy (tái sử dụng state) + +--- + +## 7. Mô Hình Dữ Liệu + +### 7.1 Bảng Dữ Liệu (Ví Dụ Douyin) + +- **DouyinAweme**: Bài viết/video +- **DouyinAwemeComment**: Bình luận bài viết +- **DyCreator**: Thông tin nhà sáng tạo + +### 7.2 Các Bảng Theo Platform + +| Platform | Bảng Nội Dung | Bảng Bình Luận | Bảng Nhà Sáng Tạo | +|----------|--------|----------|------------| +| Douyin | DouyinAweme | DouyinAwemeComment | DyCreator | +| Xiaohongshu | XHSNote | XHSNoteComment | XHSCreator | +| Kuaishou | KuaishouVideo | KuaishouVideoComment | KsCreator | +| Bilibili | BilibiliVideo | BilibiliVideoComment | BilibiliUpInfo | +| Weibo | WeiboNote | WeiboNoteComment | WeiboCreator | +| Zhihu | ZhihuContent | ZhihuContentComment | ZhihuCreator | + +--- + +## 8. Hệ Thống Cấu Hình + +### 8.1 Các Tham Số Cấu Hình Chính + +**config/base_config.py:** +```python +PLATFORM = "xhs" # Nền tảng (xhs, dy, ks, bili, wb, tieba, zhihu) +LOGIN_TYPE = "qrcode" # Kiểu đăng nhập (qrcode, phone, cookie) +CRAWLER_TYPE = "search" # Loại crawl (search, detail, creator) +KEYWORDS = "lập trình,副业" # Từ khóa tìm kiếm +ENABLE_GET_COMMENTS = True # Lấy bình luận +ENABLE_GET_SUB_COMMENTS = False # Lấy bình luận cấp 2 +HEADLESS = False # Chế độ headless (không GUI) +ENABLE_CDP_MODE = True # Dùng CDP mode +SAVE_DATA_OPTION = "jsonl" # Định dạng lưu (csv, json, jsonl, sqlite, db, mongodb, excel) +``` + +### 8.2 Cấu Hình Cơ Sở Dữ Liệu + +**config/db_config.py:** +```python +MYSQL_DB_HOST = "localhost" +MYSQL_DB_PORT = 3306 +MYSQL_DB_NAME = "media_crawler" + +REDIS_DB_HOST = "127.0.0.1" +REDIS_DB_PORT = 6379 + +MONGODB_HOST = "localhost" +MONGODB_PORT = 27017 + +SQLITE_DB_PATH = "database/sqlite_tables.db" +``` + +--- + +## 9. Module Công Cụ + +| Module | File | Chức Năng Chính | +|--------|------|-----------------| +| App Runner | `app_runner.py` | Xử lý signal, thoát graceful | +| Browser Launcher | `browser_launcher.py` | Phát hiện đường dẫn, khởi động browser | +| CDP Browser | `cdp_browser.py` | Kết nối CDP, quản lý context | +| Crawler Utils | `crawler_util.py` | Nhận dạng QR, xử lý captcha | +| File Writer | `async_file_writer.py` | Ghi bất đồng bộ CSV/JSON | +| Time Utils | `time_util.py` | Chuyển đổi timestamp, xử lý date | + +--- + +## 10. Hướng Dẫn Mở Rộng + +### 10.1 Thêm Platform Mới + +1. Tạo thư mục trong `media_platform/` +2. Triển khai: `core.py`, `client.py`, `login.py`, `field.py` +3. Tạo thư mục lưu trữ trong `store/` +4. Đăng ký trong `main.py` `CrawlerFactory` + +### 10.2 Thêm Phương Pháp Lưu Trữ Mới + +1. Tạo lớp implement trong `store/` +2. Kế thừa `AbstractStore` +3. Triển khai các phương thức: `store_content`, `store_comment`, `store_creator` +4. Đăng ký trong `StoreFactory` của các platform + +### 10.3 Thêm Nhà Cung Cấp Proxy Mới + +1. Tạo lớp trong `proxy/providers/` +2. Kế thừa `BaseProxy` +3. Triển khai phương thức `get_proxy()` +4. Đăng ký trong cấu hình + +--- + +## 11. Tham Khảo Nhanh + +### Các Lệnh Phổ Biến + +```bash +# Khởi động crawler +python main.py + +# Chỉ định platform +python main.py --platform xhs + +# Chỉ định loại đăng nhập +python main.py --lt qrcode + +# Chỉ định loại crawl +python main.py --type search +``` + +### Đường Dẫn File Quan Trọng + +| Mục Đích | Đường Dẫn | +|---------|---------| +| Lối vào chương trình | `main.py` | +| Cấu hình cốt lõi | `config/base_config.py` | +| Cấu hình DB | `config/db_config.py` | +| Lớp cơ bản crawler | `base/base_crawler.py` | +| Mô hình ORM | `database/models.py` | +| Pool Proxy | `proxy/proxy_ip_pool.py` | +| Trình duyệt CDP | `tools/cdp_browser.py` | + +--- + +*Được cập nhật: 2025-12-18* diff --git a/docs/Nhom-WeChat.md b/docs/Nhom-WeChat.md new file mode 100644 index 000000000..e73bd298b --- /dev/null +++ b/docs/Nhom-WeChat.md @@ -0,0 +1,15 @@ +# Nhóm Giao Lưu WeChat + +Chào mừng bạn tham gia nhóm giao lưu WeChat của MediaCrawler! + +Bạn có thể kết nối với những người dùng khác, chia sẻ trải nghiệm, đặt câu hỏi và nhận hỗ trợ từ cộng đồng. + +## Thông Tin Liên Hệ + +Để tham gia nhóm WeChat, vui lòng liên hệ với tác giả qua: + +- **WeChat**: Xem hình ảnh trong [Giới Thiệu Tác Giả](Gioi-Thieu-Tac-Gia.md) +- **Bilibili**: https://space.bilibili.com/434377496 +- **Github Issues**: https://github.com/NanmiCoder/MediaCrawler/issues + +--- diff --git a/docs/Quan-Ly-Moi-Truong.md b/docs/Quan-Ly-Moi-Truong.md new file mode 100644 index 000000000..c55c5ced3 --- /dev/null +++ b/docs/Quan-Ly-Moi-Truong.md @@ -0,0 +1,109 @@ +# Quản Lý Môi Trường Native + +## Phương Pháp Khuyến Nghị: Sử Dụng uv Quản Lý Phụ Thuộc + +### 1. Phụ Thuộc Trước + +- Cài đặt [uv](https://docs.astral.sh/uv/getting-started/installation), xác minh bằng `uv --version`. +- Phiên bản Python khuyên dùng **3.11** (các phụ thuộc hiện tại được xây dựng dựa trên phiên bản này). +- Cài đặt Node.js (cần cho các platform như Douyin, Zhihu), phiên bản `>= 16.0.0`. + +### 2. Đồng Bộ Phụ Thuộc Python + +```bash +# Nhập vào thư mục gốc dự án +cd MediaCrawler + +# Sử dụng uv đảm bảo phiên bản Python và phụ thuộc nhất quán +uv sync +``` + +### 3. Cài Đặt Driver Trình Duyệt Playwright + +```bash +uv run playwright install +``` + +> Dự án đã hỗ trợ kết nối Playwright với Chrome cục bộ. Nếu cần dùng phương pháp CDP, có thể điều chỉnh cấu hình `xhs` và `dy` trong `config/base_config.py`. + +### 4. Chạy Chương Trình Crawler + +```bash +# Dự án mặc định không bật crawl bình luận. Nếu cần bình luận, hãy sửa ENABLE_GET_COMMENTS trong config/base_config.py +# Các chức năng khác cũng có thể tùy chỉnh trong config/base_config.py với chú thích tiếng Trung + +# Đọc từ config, tìm kiếm theo từ khóa và crawl bài viết & bình luận +uv run main.py --platform xhs --lt qrcode --type search + +# Đọc từ config, lấy danh sách ID bài viết cụ thể và crawl bài viết & bình luận +uv run main.py --platform xhs --lt qrcode --type detail + +# Xem ví dụ cho các platform khác +uv run main.py --help +``` + +--- + +## Phương Pháp Thay Thế: Python Native venv (Không Khuyến Nghị) + +### Tạo Và Kích Hoạt Môi Trường Ảo + +> Nếu crawl Douyin hoặc Zhihu, cần cài đặt Node.js trước, phiên bản `>= 16`. + +```bash +# Nhập vào thư mục gốc dự án +cd MediaCrawler + +# Tạo môi trường ảo (ví dụ phiên bản Python: 3.11, requirements dựa trên phiên bản này) +python -m venv venv + +# macOS & Linux - kích hoạt môi trường ảo +source venv/bin/activate + +# Windows - kích hoạt môi trường ảo +venv\Scripts\activate +``` + +### Cài Đặt Phụ Thuộc Và Driver + +```bash +pip install -r requirements.txt +playwright install +``` + +### Chạy Chương Trình Crawler (Môi Trường venv) + +```bash +# Đọc từ config, tìm kiếm theo từ khóa và crawl bài viết & bình luận +python main.py --platform xhs --lt qrcode --type search + +# Đọc từ config, lấy danh sách ID bài viết cụ thể và crawl bài viết & bình luận +python main.py --platform xhs --lt qrcode --type detail + +# Xem thêm ví dụ +python main.py --help +``` + +--- + +## Các Ghi Chú Quan Trọng + +### uv vs venv + +**Ưu điểm uv:** +- Cài đặt nhanh hơn +- Quản lý phiên bản Python tự động +- Đảm bảo phụ thuộc nhất quán giữa các máy + +**Ưu điểm venv:** +- Phương pháp chuẩn Python +- Không cần cài đặt công cụ bổ sung + +### Troubleshooting + +Nếu gặp vấn đề, hãy kiểm tra: +1. Phiên bản Python là 3.11+ +2. Node.js đã cài (cho Douyin/Zhihu) +3. Chạy `uv sync` hoặc `pip install -r requirements.txt` lại +4. Xóa cache: `rm -rf ~/.cache/uv/` + diff --git a/docs/ShortVideo-Guideline.md b/docs/ShortVideo-Guideline.md new file mode 100644 index 000000000..8b7ac8364 --- /dev/null +++ b/docs/ShortVideo-Guideline.md @@ -0,0 +1,309 @@ +# Hướng Dẫn - Short Video (Liên Tục Cập Nhật) + +## Độ Dài Video Vàng + +Độ dài tối ưu cho tất cả nền tảng: **45 giây** + +Lý do: +- YouTube Shorts: 45s nằm trong 15-60s (tối ưu) +- Facebook Reels: 45s nằm trong 15-90s (tối ưu) +- TikTok: 45s nằm trong optimal range (tối ưu) +- Tỷ lệ hoàn thành: ~85% (rất cao) +- Tỷ lệ engagement: ~6% (cao nhất) +- Không quá dài, không quá ngắn + +Cách làm: +- Quay/chỉnh sửa với mục tiêu 45s +- Upload cùng 1 video cho tất cả nền tảng +- Không cần tạo phiên bản khác nhau + +--- + +## Flow Hook - Cách Mở Đầu Video + +Hook là 1-3 giây đầu tiên của video. Rất quan trọng để giữ người xem không scroll qua. + +### Hook Loại 1: Text Overlay + +Sử dụng text nổi bật trên video: +- "Bạn sẽ shocked khi biết..." +- "Tôi không tin đây là thật..." +- "99% người không biết trick này..." +- "Chờ cái ending..." +- "Watch till end..." (nếu tiếng Anh) + +Cách làm: +- Text phải lớn, rõ ràng +- Màu sắc tương phản với nền +- Xuất hiện ngay từ 0-1s + +### Hook Loại 2: Visual Hook + +Dùng hình ảnh/chuyển động: +- Khuôn mặt shock, buồn cười +- Màu sắc bất ngờ, nổi bật +- Chuyển động nhanh, mới lạ +- Conflict/mâu thuẫn (nói khác làm) + +Cách làm: +- Biểu cảm mạnh trong 1-2s đầu +- Chuyển động hấp dẫn ngay lập tức + +### Hook Loại 3: Problem Hook + +Bắt đầu bằng vấn đề mà viewer muốn giải quyết: +- "Tôi thử 10 chiếc điện thoại, cái này xảy ra..." +- "Mọi người làm sai cách này..." +- "Đây là cách nhanh nhất để..." + +Cách làm: +- Nêu vấn đề trong 1-3s +- Viewer muốn biết giải pháp +- Tiếp tục xem để tìm câu trả lời + +--- + +## Cấu Trúc Video 45 Giây + +Bộ khung cơ bản cho mỗi video: + +``` +0-1s: Hook (text + visual) + - Mục đích: Dừng người xem + - Ví dụ: "WAIT..." hoặc shocked face + +1-3s: Problem Statement + - Mục đích: Tạo tò mò + - Ví dụ: "Tôi vừa discover..." + +3-25s: Main Content (Phần chính) + - Mục đích: Cung cấp giá trị + - Đây là 70% nội dung video + +25-35s: Key Point hoặc Payoff + - Mục đích: Điểm nổi bật + - Ví dụ: Kết quả, công thức, tip + +35-43s: CTA (Call To Action) + - Mục đích: Driven engagement + - Ví dụ: "Like", "Follow", "Subscribe" + +43-45s: Kết thúc + - Mục đích: Branding/visual cuối + - Ví dụ: Logo, emoji, text tạm biệt +``` + +--- + +## Best Practice - Kỹ Thuật Sản Xuất + +### Pacing (Tốc Độ) + +Không được đơn điệu. Thay đổi tốc độ: +- Cắt scene mỗi 2-3s +- Chuyển động: ít nhất 1 chuyển cảnh mỗi 5s +- B-roll (video nền): thay đổi thường xuyên +- Chuyển tiếp: smooth, không quá chóng mặt + +### Subtitles (Phụ Đề) + +Phụ đề rất quan trọng: +- 50% người xem không bật âm thanh +- Phụ đề phải rõ ràng, dễ đọc +- Cỡ chữ: Lớn (readable trên mobile) +- Màu: Trắng hoặc vàng (contrast tốt) +- Thời gian: Đồng bộ với lời nói/âm thanh + +### Background Music (Nhạc Nền) + +Nhạc nền tạo năng lượng cho video: +- Sử dụng trending sound (platform ưa) +- Upbeat tempo (giữ năng lượng) +- Royalty-free (tránh copyright strike) +- Âm lượng: Cân bằng với lời nói + +### Lighting (Ánh Sáng) + +Ánh sáng tốt = chất lượng video tốt: +- Tự nhiên: Sáng cửa sổ là tốt nhất +- Nhân tạo: Ring light, LED +- Tránh bóng đen trên mặt +- Không quá tối hoặc quá sáng + +### Sound Quality (Chất Lượng Âm Thanh) + +Âm thanh sạch = video chuyên nghiệp: +- Microphone tốt (không dùng mic điện thoại) +- Ghi âm trong phòng yên tĩnh +- Âm lượng đầy đủ, đều +- Không có tiếng ồn nền + +--- + +## Engagement Boosters - Cách Tăng Tương Tác + +### Call-To-Action (CTA) + +Yêu cầu trực tiếp ở cuối video: +- "Drop a like" +- "Comment your answer" +- "Follow for more" +- "Subscribe for daily tips" + +Khi nào sử dụng: +- Cuối video (30-40s) +- Nhanh chóng, đơn giản +- Phù hợp với nội dung + +### Question Format + +Đặt câu hỏi để drive comments: +- "Bạn chọn cái nào?" +- "Bạn đoán được không?" +- "Có ai từng trải nghiệm này?" +- "Bạn sẽ làm gì?" + +Lợi ích: +- Comments = algorithm boost +- Engagement rate tăng +- Reach tăng + +### Shareable Content + +Nội dung dễ chia sẻ: +- Có payoff thích nghi cuối +- Relatable (có nhiều người giống) +- Entertaining hoặc útil +- Có twist/surprise + +--- + +## Content Strategy - Loại Nội Dung + +### Educational (Giáo Dục) + +Dạy người xem cái gì đó: +- "3 tips mà không ai biết" +- "Cách nhanh nhất để..." +- "Tutorial: Làm X trong 60s" + +Ưu điểm: +- Dễ viral (người muốn học) +- Save rate cao (lưu video) +- Rewatch rate cao + +### Transformation (Thay Đổi) + +Before/After content: +- "Tôi thử [trend] 30 ngày" +- "Sản phẩm này destroy expectations" +- "X changed my life" + +Ưu điểm: +- Share rate cao +- Viral potential +- Relatable + +### Entertaining (Giải Trí) + +Vui, buồn cười, shock: +- Comedy/humor +- Trending challenge +- Prank (safe) + +Ưu điểm: +- Engagement cao +- Share rate cao +- Reach lớn + +### Trend + Personal Twist + +Không chỉ copy trend, thêm góc nhìn riêng: +- Trend: "POV: You're..." +- Twist: "POV: Người Việt vs Chinese..." +- Result: Relatability + trend momentum + +--- + +## Posting Strategy - Khi Đăng + +### Best Time (Giờ Đăng Tốt) + +Facebook Reels best times: +- Sáng: 6-9 AM +- Trưa: 12-1 PM +- Chiều: 3-5 PM +- Tối: 6-8 PM +- Đêm: 9-11 PM + +Lưu ý: +- Tùy vào timezone của audience bạn +- Test và xem metrics + +### Frequency (Tần Suất) + +Đăng bao nhiêu lần/tuần: +- Tối thiểu: 3-5 videos/tuần +- Tối ưu: 1 video/ngày +- Maximum: 2-3 videos/ngày + +Lợi ích đăng thường: +- Algorithm học pattern của bạn +- Ưu tiên các video tương lai +- Cơ hội viral nhiều hơn + +### Series Effect + +Đăng các video liên quan tuần tự: +- Part 1 → Part 2 → Part 3 +- Viewers binge content +- Watch time tăng +- Algorithm push more + +--- + +## Metrics - Chỉ Số Theo Dõi + +Metrics quan trọng: +- Watch Time: Tổng thời gian xem +- Completion Rate: % người xem hết video +- Engagement Rate: (reactions + comments + shares) / viewers +- Reach: Số người xem video +- Shares: Chia sẻ (quan trọng nhất!) + +Target metrics: +- Completion Rate: 70%+ +- Engagement Rate: 5%+ +- Shares: 2-5% của viewers + +--- + +## Checklist - Trước Khi Đăng + +Kiểm tra mỗi video: + +- [ ] First 1s có hook (stop scroll) +- [ ] Pacing nhanh (cut boring parts) +- [ ] Âm thanh rõ (good microphone) +- [ ] Có phụ đề (mobile viewers) +- [ ] Màu sắc rực rỡ (stands out) +- [ ] CTA ở cuối (drive engagement) +- [ ] Đăng vào giờ tốt +- [ ] Trending audio (nếu áp dụng) +- [ ] Nội dung dễ share +- [ ] Không watermark (looks original) + +--- + +## Lưu Ý Quan Trọng + +- Không được dùng video có watermark nền tảng khác +- Không được vi phạm bản quyền +- Không được spam, lừa đảo +- Không được nội dung ghét, bạo lực +- Platform có thể xóa hoặc giới hạn reach + +--- + +Last Updated: 2026-07-14 +Sẽ được cập nhật liên tục dựa trên thảo luận mới. diff --git a/docs/ShortVideo-Requirements.md b/docs/ShortVideo-Requirements.md new file mode 100644 index 000000000..7cedf6fc3 --- /dev/null +++ b/docs/ShortVideo-Requirements.md @@ -0,0 +1,120 @@ +# Yêu Cầu Nền Tảng - Short Video + +## YouTube Shorts + +### Điều Kiện Monetize +- Kênh phải có 1,000 người đăng ký +- 4,000 giờ xem (trong 12 tháng) +- Tuân thủ Community Guidelines +- Không vi phạm bản quyền + +### Định Dạng Video +- Độ dài: 15s - 60s +- Tỷ lệ: Vertical (9:16 hoặc 1:1 cũng được) +- Độ phân giải: 1080p (tối thiểu) +- Format: MP4, WebM + +### CPM & Revenue +- CPM: $0.25 - $2 (tiếng Việt: $0.3 - $0.8) +- Revenue share: 45% creators, 55% YouTube +- 100,000 views = $50 - $200 +- 1 triệu views = $250 - $2,000 + +### Thời Gian Monetize +- Thường: 2-4 tuần từ khi đạt điều kiện +- Nếu video viral: có thể nhanh hơn + +--- + +## Facebook Reels + +### Điều Kiện Monetize +- Trang phải có 10,000 lượt thích +- 600,000 phút xem (trong 60 ngày) +- Tuân thủ Community Guidelines +- Tài khoản phải xác minh + +### Định Dạng Video +- Độ dài: 15s - 90s +- Tỷ lệ: Vertical (9:16 hoặc 1:1) +- Độ phân giải: 1080p (tối thiểu) +- Format: MP4, WebM + +### CPM & Revenue +- CPM: $0.5 - $3 (tiếng Việt: $0.5 - $1.5) +- 100,000 views = $50 - $300 +- 1 triệu views = $500 - $3,000 + +### Thời Gian Monetize +- Thường: 2-3 tuần (nhanh nhất) +- Dễ đạt 10,000 likes từ viral content +- Dễ tích lũy 600,000 phút xem + +--- + +## TikTok + +### Điều Kiện Monetize +- Tài khoản phải có 10,000 người theo dõi +- 100,000 lượt xem (trong 30 ngày) +- Tuổi từ 18 trở lên +- Tuân thủ Community Guidelines + +### Định Dạng Video +- Độ dài: 3s - 60s (tối ưu) +- Tỷ lệ: Vertical (9:16) +- Độ phân giải: 1080p (tối thiểu) +- Format: MP4, MOV + +### CPM & Revenue +- CPM: $0.02 - $0.08 (thấp nhất) +- 100,000 views = $2 - $8 +- 1 triệu views = $20 - $80 +- Revenue thấp nhưng nhanh monetize + +### Thời Gian Monetize +- Thường: 1-2 tuần (nhanh nhất) +- Dễ đạt 10,000 followers từ viral +- Dễ đạt 100,000 views + +--- + +## So Sánh Nhanh + +Nền Tảng | Người Đăng Ký | Xem/Phút | Thời Gian | CPM | Ưu Điểm +---------|--------------|---------|----------|-----|---------- +YouTube Shorts | 1,000 subs | 4,000 hours | 2-4 tuần | $0.25-2 | CPM cao, ổn định +Facebook Reels | 10K likes | 600K phút | 2-3 tuần | $0.5-3 | Nhanh nhất, CPM cao +TikTok | 10K followers | 100K views | 1-2 tuần | $0.02-0.08 | Nhanh nhất, dễ viral + +--- + +## Chất Lượng Video - Tất Cả Nền Tảng + +### Hình Ảnh +- Độ phân giải: 1080p tối thiểu +- Ánh sáng: Tốt, không quá tối +- Cân bằng phân bố: Rõ ràng +- Màu sắc: Rực rỡ, tương phản cao + +### Âm Thanh +- Độ ồn: Rõ, không có tiếng ồn nền +- Âm lượng: Đầy đủ, không quá lớn/nhỏ +- Nhạc nền: Trendy, bản quyền tự do +- Lồng tiếng: Rõ ràng (nếu có) + +### Phụ Đề +- Có mặt phụ đề +- Cỡ chữ: Lớn, dễ đọc +- Màu sắc: Tương phản với nền +- Thời gian: Đồng bộ với âm thanh + +--- + +## Không Được Phép + +- Watermark hoặc logo nền tảng khác +- Vi phạm bản quyền âm nhạc/video +- Nội dung đồi trụy, bạo lực, ghét +- Spam, lừa đảo, link giả +- Nội dung giả mạo, tin giả diff --git a/docs/Trang-Chu.md b/docs/Trang-Chu.md new file mode 100644 index 000000000..b91309d55 --- /dev/null +++ b/docs/Trang-Chu.md @@ -0,0 +1,104 @@ +# MediaCrawler - Hướng Dẫn Sử Dụng + +## Tài Liệu Dự Án + +- [Kiến Trúc Dự Án](Kien-Truc-Du-An.md) - Kiến trúc hệ thống, thiết kế module, luồng dữ liệu (bao gồm sơ đồ) + +## Khuyến Nghị: Sử Dụng uv Quản Lý Phụ Thuộc + +### 1. Phụ Thuộc Trước + +- Cài đặt [uv](https://docs.astral.sh/uv/getting-started/installation), xác minh bằng `uv --version`. +- Phiên bản Python khuyên dùng **3.11** (phụ thuộc hiện tại dựa trên phiên bản này). +- Cài đặt Node.js (cần cho Douyin, Zhihu), phiên bản `>= 16.0.0`. + +### 2. Đồng Bộ Phụ Thuộc Python + +```bash +# Vào thư mục gốc dự án +cd MediaCrawler + +# Sử dụng uv đảm bảo phiên bản Python và phụ thuộc nhất quán +uv sync +``` + +### 3. Cài Đặt Driver Trình Duyệt Playwright + +```bash +uv run playwright install +``` + +> Dự án đã hỗ trợ kết nối Playwright với Chrome cục bộ. Nếu cần dùng CDP, có thể điều chỉnh cấu hình trong `config/base_config.py`. + +### 4. Chạy Chương Trình Crawler + +```bash +# Dự án mặc định không bật crawl bình luận. Nếu cần, sửa ENABLE_GET_COMMENTS trong config/base_config.py + +# Tìm kiếm theo từ khóa và crawl bài viết & bình luận +uv run main.py --platform xhs --lt qrcode --type search + +# Crawl danh sách ID bài viết cụ thể +uv run main.py --platform xhs --lt qrcode --type detail + +# Lưu vào SQLite (khuyến nghị cho người dùng cá nhân) +uv run main.py --platform xhs --lt qrcode --type search --save_data_option sqlite + +# Lưu vào MySQL +uv run main.py --platform xhs --lt qrcode --type search --save_data_option db + +# Xem thêm ví dụ +uv run main.py --help +``` + +## Phương Pháp Thay Thế: Python venv (Không Khuyến Nghị) + +> Nếu crawl Douyin hoặc Zhihu, cần cài Node.js trước, phiên bản `>= 16`. + +```bash +# Vào thư mục gốc dự án +cd MediaCrawler + +# Tạo môi trường ảo (Python 3.11) +python -m venv venv + +# macOS & Linux - kích hoạt +source venv/bin/activate + +# Windows - kích hoạt +venv\Scripts\activate +``` + +```bash +# Cài đặt phụ thuộc +pip install -r requirements.txt +playwright install +``` + +```bash +# Chạy crawler (venv) +python main.py --platform xhs --lt qrcode --type search +python main.py --platform xhs --lt qrcode --type detail +python main.py --platform xhs --lt qrcode --type search --save_data_option sqlite +python main.py --help +``` + +## 💾 Lưu Trữ Dữ Liệu + +Hỗ trợ nhiều cách lưu trữ: +- **CSV**: Lưu vào CSV (thư mục `data/`) +- **JSON**: Lưu vào JSON (thư mục `data/`) +- **Database** + - **SQLite**: Cơ sở dữ liệu nhẹ, không cần server (khuyến nghị) + - **MySQL**: Hỗ trợ cơ sở dữ liệu quan hệ + - **PostgreSQL**: Cơ sở dữ liệu PostgreSQL (khuyến nghị production) + +## Tuyên Bố Từ Chối Trách Nhiệm + +> **Tuyên Bố Từ Chối Trách Nhiệm:** +> +> Vui lòng sử dụng repository này cho mục đích học tập. Tham khảo [Các vụ kiện crawl bất hợp pháp](https://github.com/HiddenStrawberry/Crawler_Illegal_Cases_In_China) +> +> Toàn bộ nội dung của dự án này chỉ dành cho mục đích học tập và tham khảo, cấm sử dụng thương mại. Bất kỳ người hoặc tổ chức nào không được phép sử dụng nội dung của repository này cho mục đích bất hợp pháp hoặc xâm phạm quyền hợp pháp của người khác. Kỹ thuật crawl trong repository này chỉ dùng cho học tập và nghiên cứu, không được dùng để crawl quy mô lớn từ các nền tảng khác hoặc các hành động bất hợp pháp khác. Repository này không chịu trách nhiệm pháp lý nào phát sinh từ việc sử dụng nội dung của nó. Sử dụng nội dung của repository này đồng nghĩa với việc bạn đồng ý với toàn bộ các điều khoản và điều kiện của tuyên bố từ chối trách nhiệm này. + +--- diff --git a/docs/static/images/bloome_logo.png b/docs/static/images/bloome_logo.png new file mode 100644 index 000000000..521e26ca1 Binary files /dev/null and b/docs/static/images/bloome_logo.png differ diff --git a/docs/static/images/nodemaven_logo.svg b/docs/static/images/nodemaven_logo.svg new file mode 100644 index 000000000..77b2ec283 --- /dev/null +++ b/docs/static/images/nodemaven_logo.svg @@ -0,0 +1,36 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/package-lock.json b/package-lock.json index ec40ad349..4b669bf61 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,5 +1,5 @@ { - "name": "MediaCrawler", + "name": "media-crawler", "lockfileVersion": 3, "requires": true, "packages": { diff --git a/webui/src/components/console/Terminal.tsx b/webui/src/components/console/Terminal.tsx index 7ea22c86e..2a87d07c3 100644 --- a/webui/src/components/console/Terminal.tsx +++ b/webui/src/components/console/Terminal.tsx @@ -141,7 +141,7 @@ export function Terminal() { {/* Terminal Footer */}
- {status.toUpperCase()} + {status ? status.toUpperCase() : 'IDLE'}
diff --git a/webui/src/components/layout/LanguageSwitch.tsx b/webui/src/components/layout/LanguageSwitch.tsx index 03e69b850..9e0502b76 100644 --- a/webui/src/components/layout/LanguageSwitch.tsx +++ b/webui/src/components/layout/LanguageSwitch.tsx @@ -9,6 +9,7 @@ import { } from '@/components/ui/select' const languages = [ + { code: 'vi-VN', label: 'Tiếng Việt' }, { code: 'zh-CN', label: '中文' }, { code: 'en-US', label: 'EN' }, ] diff --git a/webui/src/i18n/index.ts b/webui/src/i18n/index.ts index 4dc151e0a..ee7df496d 100644 --- a/webui/src/i18n/index.ts +++ b/webui/src/i18n/index.ts @@ -18,6 +18,14 @@ import enData from './locales/en-US/data.json' import enEnv from './locales/en-US/env.json' import enLicense from './locales/en-US/license.json' +// 越南文翻译 +import viCommon from './locales/vi-VN/common.json' +import viConfig from './locales/vi-VN/config.json' +import viTerminal from './locales/vi-VN/terminal.json' +import viData from './locales/vi-VN/data.json' +import viEnv from './locales/vi-VN/env.json' +import viLicense from './locales/vi-VN/license.json' + const resources = { 'zh-CN': { common: zhCommon, @@ -35,6 +43,14 @@ const resources = { env: enEnv, license: enLicense, }, + 'vi-VN': { + common: viCommon, + config: viConfig, + terminal: viTerminal, + data: viData, + env: viEnv, + license: viLicense, + }, } i18n @@ -42,7 +58,7 @@ i18n .use(initReactI18next) .init({ resources, - fallbackLng: 'zh-CN', + fallbackLng: 'vi-VN', defaultNS: 'common', interpolation: { escapeValue: false, diff --git a/webui/src/i18n/locales/vi-VN/common.json b/webui/src/i18n/locales/vi-VN/common.json new file mode 100644 index 000000000..aafd652a8 --- /dev/null +++ b/webui/src/i18n/locales/vi-VN/common.json @@ -0,0 +1,26 @@ +{ + "status": { + "active": "ĐANG HOẠT ĐỘNG", + "standby": "CHỜ CÓ VIỆC", + "idle": "CHƯA HOẠT ĐỘNG", + "running": "ĐANG CHẠY", + "stopping": "ĐANG DỪNG", + "error": "LỖI" + }, + "sidebar": { + "title": "MediaCrawler", + "api": "API", + "local": "ĐỊA PHƯƠNG", + "disclaimer": "Chỉ dùng cho học tập cá nhân, cấm sử dụng thương mại", + "license": "Giấy phép" + }, + "action": { + "loading": "Đang tải...", + "skip": "BỎ QUA_KIỂM TRA", + "retry": "LẠI_QUÉT" + }, + "unit": { + "entries": "mục", + "records": "bản ghi" + } +} diff --git a/webui/src/i18n/locales/vi-VN/config.json b/webui/src/i18n/locales/vi-VN/config.json new file mode 100644 index 000000000..fb61dd9fb --- /dev/null +++ b/webui/src/i18n/locales/vi-VN/config.json @@ -0,0 +1,71 @@ +{ + "section": { + "targetMatrix": { + "title": "MA TRẬN ĐỊA CHỈ", + "description": "Nền tảng, chế độ và tham số tìm kiếm" + }, + "authMatrix": { + "title": "MA TRẬN XÁC THỰC", + "description": "Cấu hình phương pháp đăng nhập" + }, + "outputConfig": { + "title": "CẤU HÌNH ĐẦU RA", + "description": "Định dạng lưu & tùy chọn bình luận" + }, + "runtime": { + "title": "THỜI GIAN CHẠY", + "description": "Tham số thời gian chạy" + } + }, + "field": { + "platform": "NỀN TẢNG", + "platformPlaceholder": "Chọn nền tảng", + "crawlType": "LOẠI CRAWL", + "crawlTypePlaceholder": "Chọn loại", + "startPage": "TRANG BẮTĐẦU", + "keywords": "TỪ KHÓA", + "keywordsHint": "Nhấn Enter để thêm từ khóa", + "keywordsPlaceholder": "Nhập từ khóa, nhấn Enter để thêm...", + "specifiedIds": "ID BÀI VIẾT/VIDEO", + "specifiedIdsHint": "Nhập ID bài viết hoặc video/URL, mỗi dòng một cái hoặc cách nhau bằng dấu phẩy", + "specifiedIdsPlaceholder": { + "bili": "Ví dụ:\nBV1xxxx\nhttps://www.bilibili.com/video/BV1xxxx", + "xhs": "Ví dụ:\nhttps://www.xiaohongshu.com/explore/xxx?xsec_token=xxx\n(phải bao gồm xsec_token)", + "dy": "Ví dụ:\n7525538910311632128\nhttps://www.douyin.com/video/xxx\nhttps://v.douyin.com/xxx (liên kết ngắn)", + "wb": "Ví dụ:\n4982041758140155\nhttps://weibo.com/xxx/xxx", + "ks": "Ví dụ:\n3xf8enb8dbj6uig\nhttps://www.kuaishou.com/short-video/xxx", + "default": "Nhập ID bài viết/video hoặc URL..." + }, + "creatorIds": "ID TÁC GIẢ", + "creatorIdsHint": "Nhập ID tác giả/URL, mỗi dòng một cái hoặc cách nhau bằng dấu phẩy", + "creatorIdsPlaceholder": { + "bili": "Ví dụ:\n434377496\nhttps://space.bilibili.com/434377496", + "xhs": "Ví dụ:\nhttps://www.xiaohongshu.com/user/profile/xxx?xsec_token=xxx\n(phải bao gồm xsec_token)", + "dy": "Ví dụ:\nMS4wLjABAAAAxxx\nhttps://www.douyin.com/user/MS4wLjABAAAAxxx", + "wb": "Ví dụ:\n5533390220\nhttps://weibo.com/u/5533390220", + "ks": "Ví dụ:\n3x84qugg4ch9zhs\nhttps://www.kuaishou.com/profile/xxx", + "default": "Nhập ID tác giả hoặc URL..." + }, + "loginMethod": "PHƯƠNG PHÁP ĐĂNG NHẬP", + "loginMethodPlaceholder": "Chọn phương pháp đăng nhập", + "cookies": "COOKIES", + "cookiesHint": "Dán chuỗi cookie", + "cookiesPlaceholder": "Dán cookies vào đây...", + "saveFormat": "ĐỊNH DẠNG LƯU", + "saveFormatPlaceholder": "Chọn định dạng", + "commentExtraction": "Trích xuất bình luận", + "subComments": "Bình luận cấp 2", + "headlessMode": "CHẾ ĐỘ KHÔNG CÓ GUI", + "headlessModeHint": "Chạy trình duyệt mà không có giao diện" + }, + "button": { + "initiateScan": "BẮTĐẦU QUÉT", + "initiating": "ĐANG KHỞI ĐỘNG...", + "terminate": "DỪNG", + "stopping": "ĐANG DỪNG..." + }, + "warning": { + "cookieSlider": "[Lưu ý] Đăng nhập bằng Cookie không được khuyến nghị cho Xiaohongshu và Douyin do có captcha slider", + "xhsToken": "[Quan trọng] URL Xiaohongshu phải chứa tham số xsec_token, vui lòng sao chép URL đầy đủ từ trình duyệt" + } +} diff --git a/webui/src/i18n/locales/vi-VN/data.json b/webui/src/i18n/locales/vi-VN/data.json new file mode 100644 index 000000000..312b5ffa7 --- /dev/null +++ b/webui/src/i18n/locales/vi-VN/data.json @@ -0,0 +1,29 @@ +{ + "dialog": { + "button": "MA TRẬN DỮLIỆU", + "title": "TRÌNH KHÁM PHÁ DỮ LIỆU" + }, + "explorer": { + "title": "MA TRẬN DỮLIỆU ĐÃ CHỤP", + "records": "{{count}} BẢN GHI", + "rescan": "QUÉT LẠI", + "loading": "[ĐANG TẢI] Quét thư mục dữ liệu...", + "noData": "KHÔNG CÓ DỮ LIỆU", + "noDataHint": "Khởi tạo crawler để bắt đầu trích xuất dữ liệu. Kết quả sẽ xuất hiện ở đây sau khi hoàn tất.", + "allCategories": "TẤT CẢ" + }, + "file": { + "entries": "{{count}} mục", + "extract": "TRÍCH XUẤT", + "preview": "XEM TRƯỚC" + }, + "preview": { + "title": "Xem trước dữ liệu", + "records": "{{count}} BẢN GHI", + "download": "TẢI XUỐNG", + "loading": "[ĐANG TẢI] Giải mã dữ liệu...", + "error": "[LỖI] Không thể giải mã dữ liệu", + "searchPlaceholder": "Tìm kiếm trong dữ liệu...", + "showing": "Hiển thị {{filtered}} trong {{total}} bản ghi" + } +} diff --git a/webui/src/i18n/locales/vi-VN/env.json b/webui/src/i18n/locales/vi-VN/env.json new file mode 100644 index 000000000..1c9d78fe4 --- /dev/null +++ b/webui/src/i18n/locales/vi-VN/env.json @@ -0,0 +1,18 @@ +{ + "title": "CHẨNĐOÁN MÔI TRƯỜNG", + "scanning": "[QUÉT] Phân tích môi trường MediaCrawler...", + "success": "[OK] {{message}}", + "error": "[LỖI] {{message}}", + "defaultError": "Không thể kết nối tới máy chủ API", + "defaultErrorHint": "Vui lòng đảm bảo dịch vụ backend đang chạy (uvicorn api.main:app --port 8080)", + "showDetails": "[+] HIỂN THỊ CHI TIẾT", + "hideDetails": "[-] ẨN CHI TIẾT", + "requirements": "[YÊU CẦU]", + "requirementsList": { + "1": "Cài đặt trình quản lý gói uv", + "2": "Thực thi uv sync trong thư mục gốc dự án", + "3": "Xác minh tất cả phụ thuộc đã được cài đặt" + }, + "skipCheck": "BỎ QUA_KIỂM TRA", + "retryCheck": "LẠI_QUÉT" +} diff --git a/webui/src/i18n/locales/vi-VN/license.json b/webui/src/i18n/locales/vi-VN/license.json new file mode 100644 index 000000000..7747526de --- /dev/null +++ b/webui/src/i18n/locales/vi-VN/license.json @@ -0,0 +1,21 @@ +{ + "title": "Thông báo sử dụng", + "warning": "Vui lòng đọc kỹ các điều khoản sau", + "content": { + "line1": "Dự án này chỉ dành cho mục đích học tập và nghiên cứu cá nhân", + "line2": "Sử dụng thương mại hoặc các hoạt động sinh lợi bị cấm hoàn toàn", + "line3": "Bằng cách sử dụng dự án này, bạn đồng ý tuân thủ tất cả các luật pháp hiện hành", + "line4": "Người dùng chịu toàn bộ trách nhiệm về bất kỳ hậu quả nào của việc sử dụng sai" + }, + "license": "Xem Giấy phép đầy đủ", + "github": "Truy cập Kho lưu trữ GitHub", + "confirm": "Tôi hiểu và đồng ý với các điều khoản trên", + "decline": "Không đồng ý, Thoát", + "author": { + "name": "Relakkes (阿江)", + "tagline": "Tác giả Open Source 40K+ Star", + "description": "Tác giả của MediaCrawler (40K stars), tập trung vào chia sẻ kiến thức về công nghệ crawler và AI Agent", + "support": "Nếu bạn thấy dự án này hữu ích, vui lòng follow tác giả trên mạng xã hội", + "slogan": "Open source không dễ, vui lòng star ⭐" + } +} diff --git a/webui/src/i18n/locales/vi-VN/terminal.json b/webui/src/i18n/locales/vi-VN/terminal.json new file mode 100644 index 000000000..e4b1f8121 --- /dev/null +++ b/webui/src/i18n/locales/vi-VN/terminal.json @@ -0,0 +1,16 @@ +{ + "header": { + "title": "BẢNG ĐIỀU KHIỂN HỆ THỐNG", + "entries": "{{count}} mục", + "active": "ĐANG HOẠT ĐỘNG", + "clear": "XÓA", + "restore": "KHÔI PHỤC TẤT CẢ NHẬT KÝ" + }, + "banner": { + "systemInit": "[HỆ THỐNG] Hệ thống được khởi tạo thành công", + "configHint": "[THÔNG TIN] Cấu hình tham số và khởi động trình quét..." + }, + "footer": { + "awaiting": "chờ_lệnh..." + } +}