FoxProfile

Quản lý nhiều profile trình duyệt chống phát hiện, miễn phí và mã nguồn mở

Mỗi profile có fingerprint thiết bị, cookie và proxy riêng · Hai engine: Camoufox (Firefox) và Chrome · Giao diện tiếng Anh và tiếng Việt · REST API và MCP cho tự động hóa

English · Tiếng Việt

Bắt đầu nhanh · Tính năng · REST API · MCP · Đóng góp

![FoxProfile](docs/images/main.png) FoxProfile quản lý các profile trình duyệt chống phát hiện: mỗi profile là một danh tính riêng với fingerprint thiết bị, cookie, proxy, timezone và locale của nó. Trình duyệt mặc định là [Camoufox](https://github.com/daijro/camoufox), một bản Firefox được chỉnh sửa ở tầng mã nguồn để giả lập fingerprint; ngoài ra có engine Chrome dựa trên [fingerprint-chromium](https://github.com/adryfish/fingerprint-chromium). FoxProfile là lựa chọn tự host, chạy trên máy bạn hoặc VPS, thay cho các antidetect browser trả phí như GoLogin, GPM hay MoreLogin. ## Ủng hộ FoxProfile miễn phí, mã nguồn mở, được làm vào thời gian rảnh và sẽ luôn như vậy. Nếu nó tiết kiệm cho bạn thời gian hay chi phí, bạn có thể mời mình một ly cà phê; cà phê sẽ thành bug fix, cập nhật theo bản mới của Camoufox và Chrome, và trả lời issue nhanh hơn.

## Mục lục - [Ủng hộ](#ủng-hộ) - [Tính năng](#tính-năng) - [Yêu cầu](#yêu-cầu) - [Bắt đầu nhanh](#bắt-đầu-nhanh) - [Timezone, locale và Kiểm tra IP](#timezone-locale-và-kiểm-tra-ip) - [Chế độ server và web panel](#chế-độ-server-và-web-panel) - [MCP: cho AI điều khiển trình duyệt](#mcp-cho-ai-điều-khiển-trình-duyệt) - [Engine Chrome](#engine-chrome) - [Cookie và fingerprint](#cookie-và-fingerprint) - [Cấu hình](#cấu-hình) - [REST API](#rest-api) - [Phát triển](#phát-triển) - [Đóng góp](#đóng-góp) - [Lưu ý sử dụng](#lưu-ý-sử-dụng) - [Giấy phép](#giấy-phép) - [Ghi công](#ghi-công) ## Tính năng - **Fingerprint cố định cho từng profile.** Lần mở đầu tiên sinh ra một thiết bị (màn hình, GPU, số nhân CPU, font, nhiễu canvas/audio) và lưu lại; các lần sau mở lại đúng thiết bị đó. Có thể chủ động tạo fingerprint mới. - **Hai engine.** Camoufox (Firefox, mặc định) hoặc Chrome (fingerprint-chromium), chọn khi tạo profile. Bản Chrome được tự tải về khi cần. - **Giữ phiên làm việc.** Lịch sử, cookie và đăng nhập nằm trong thư mục của profile; các tab đang mở được mở lại ở lần khởi động sau. - **Mỗi profile một proxy riêng**, hỗ trợ HTTP/HTTPS/SOCKS4/SOCKS5 có hoặc không có mật khẩu, kể cả dạng `host:port:user:pass`, có nút kiểm tra proxy. - **Timezone và locale** tự khớp theo IP hoặc đặt cố định cho từng profile. Nút **Kiểm tra IP** đối chiếu IP ra với Cloudflare, ipinfo, ip-api và cảnh báo khi lệch quốc gia/timezone hoặc IP bị gắn datacenter. - **Xuất/nhập cookie** dạng JSON Cookie-Editor / EditThisCookie (GoLogin, GPM, Multilogin, extension Cookie-Editor) và `cookies.txt` Netscape (yt-dlp, curl, wget). - **Xuất/nhập cả profile** ra file ZIP để chuyển sang máy khác, có hoặc không kèm dữ liệu trình duyệt. Fingerprint luôn đi kèm. - **Bảng profile dễ quét**: mỗi dòng cho thấy engine, thiết bị đang giả lập, proxy (đã ẩn mật khẩu), timezone/locale và trạng thái. Trạng thái phân biệt bằng cả hình lẫn màu: dấu tím viền kép kèm giờ mở là đang chạy, viền xám là đang mở, dấu đỏ gạch ngang là mở lỗi. - **Lọc và tìm kiếm**: lọc theo đang chạy, có/không proxy, engine Chrome (kèm số đếm); tìm theo tên hoặc proxy. - **Thao tác hàng loạt**: chọn nhiều profile để mở, dừng hoặc xóa cùng lúc. - **MCP server**: Claude, Cursor... tự mở profile, lướt web, click, gõ, chụp màn hình. - **Chế độ server + web panel**: chạy trên VPS, quản lý và xem màn hình từ xa qua trình duyệt, có token bảo vệ. - **REST API** để điều khiển bằng script, có trang tài liệu Swagger. - Giao diện **tiếng Anh** (mặc định) và tiếng Việt, đổi ngay trong app. Font đóng gói sẵn, không cần mạng. ## Yêu cầu - Python 3.10 trở lên - Windows, macOS hoặc Linux (CI chạy test trên cả ba) - Vài trăm MB dung lượng trống cho Camoufox và cơ sở dữ liệu GeoIP, thêm ~140-190 MB nếu dùng engine Chrome ## Bắt đầu nhanh ```bash git clone https://github.com/chienbm98/foxprofile.git cd foxprofile python -m venv .venv .venv\Scripts\activate # Windows source .venv/bin/activate # Linux/macOS pip install -r requirements.txt python -m camoufox fetch ``` `camoufox fetch` tải bản trình duyệt Camoufox (vài trăm MB) từ GitHub của dự án Camoufox. Lần mở profile đầu tiên sẽ tải thêm cơ sở dữ liệu GeoIP (~50 MB). Chạy ứng dụng: ```bash python -m src.main ``` Trên Windows có thể bấm đúp `run_foxprofile.bat`. Ứng dụng mở cửa sổ quản lý và đồng thời chạy API tại `http://127.0.0.1:8000`; tài liệu API ở `http://127.0.0.1:8000/docs`. Đặt `FOXPROFILE_LANG=vi` để dùng giao diện tiếng Việt. ## Timezone, locale và Kiểm tra IP Mặc định, mỗi lần mở profile, cả hai engine đều tra IP đi ra (qua proxy của profile) và đặt timezone, locale, toạ độ theo IP đó; Camoufox còn báo IP này qua WebRTC. Có ba điều nên biết: - **Locale tự động được chọn một lần cho mỗi quốc gia rồi giữ cố định.** Lần mở đầu tiên từ một quốc gia sẽ chọn theo tỷ lệ người nói từng ngôn ngữ ở đó (IP Pháp cho `fr-FR` khoảng 60% số lần, còn lại là `en-FR`, `es-FR`…), và profile giữ locale đó ở mọi lần mở sau, cho đến khi proxy chuyển sang quốc gia khác. Muốn một locale cụ thể thì đặt tay. "Fingerprint mới" cũng xoá locale đang giữ. - **Các cơ sở dữ liệu GeoIP không phải lúc nào cũng thống nhất.** Cùng một IP có thể được Cloudflare xếp vào nước này, Google vào nước khác; Camoufox cũng có thể chọn một timezone cùng giờ nhưng khác tên (ví dụ IP Việt Nam ra `Asia/Bangkok` thay vì `Asia/Ho_Chi_Minh`). - **IP datacenter dễ bị bắt captcha** bất kể cấu hình trình duyệt. Với các trang dùng Cloudflare, proxy residential hoặc 4G quan trọng hơn mọi tinh chỉnh khác. ![Hộp thoại tạo profile](docs/images/profile-dialog.png) Trong hộp thoại tạo/sửa profile có hai ô **Timezone** (tên IANA, ví dụ `Asia/Ho_Chi_Minh`) và **Locale** (dạng `vi-VN`); để trống là tự động theo IP. Nút **Kiểm tra IP** lấy IP đi ra qua proxy, đối chiếu với Cloudflare, ipinfo và ip-api, rồi cảnh báo khi lệch quốc gia hoặc timezone, khi IP bị gắn datacenter và khi proxy ra Internet bằng IPv4 và IPv6 khác nhau. Khi kiểm tra theo profile (API hoặc MCP `check_profile_ip`), kết quả còn hiện locale mà profile đang giữ. ## Chế độ server và web panel Không cần cửa sổ desktop: chỉ chạy API và web panel, trình duyệt chạy headless. Phù hợp để chạy trên VPS. ```bash python -m src.server # http://127.0.0.1:8000 python -m src.server --host 0.0.0.0 # mở ra mạng: BẮT BUỘC đặt token ``` Mở `http://<địa-chỉ>:8000/` để vào **web panel**: cùng bảng profile, bộ lọc và thao tác hàng loạt như app desktop; tạo, sửa, mở/dừng profile, xuất/nhập cookie và **xem màn hình từ xa**. Bạn có thể bấm thẳng lên ảnh màn hình và gõ phím để tự đăng nhập hay giải captcha, kể cả khi trình duyệt đang chạy headless trên server. | Web panel | Xem màn hình từ xa | | --- | --- | | ![Web panel](docs/images/panel.png) | ![Xem màn hình từ xa](docs/images/panel-viewer.png) | **Bảo mật:** khi nghe ngoài `127.0.0.1`, server **từ chối khởi động** nếu chưa đặt `FOXPROFILE_API_TOKEN` (tối thiểu 24 ký tự). Web panel, REST API và MCP đều dùng chung token này. ```bash # Tạo token ngẫu nhiên python -c "import secrets; print(secrets.token_urlsafe(32))" ``` Khi đưa lên VPS, nên đặt server sau reverse proxy có HTTPS (Caddy, Nginx) để token không bị gửi đi dưới dạng chữ thường. Trên Linux không có màn hình, đặt `FOXPROFILE_HEADLESS=virtual` (cần cài `xvfb`) để trình duyệt chạy trên màn hình ảo, khó bị phát hiện hơn chế độ headless thường. Hướng dẫn triển khai đầy đủ (Ubuntu, systemd, nginx, HTTPS): [docs/DEPLOY.md](docs/DEPLOY.md). ## MCP: cho AI điều khiển trình duyệt FoxProfile có sẵn MCP server, để Claude Code, Claude Desktop, Cursor, VS Code... tự quản lý profile và thao tác trên trang: mở URL, đọc trang, click, gõ, chụp màn hình. **Cách nhanh nhất:** bấm **Kết nối AI (MCP)** ở thanh bên trái của app desktop hoặc web panel. Hộp thoại sinh sẵn cấu hình cho từng ứng dụng AI, đúng địa chỉ và token của bạn, chỉ cần bấm Sao chép rồi dán. ![Kết nối AI (MCP)](docs/images/mcp-guide.png) MCP được phục vụ qua HTTP tại `/mcp`, ngay trên cổng của FoxProfile, nên dùng được cả khi FoxProfile chạy trên VPS: ```bash # Claude Code claude mcp add --transport http foxprofile http://127.0.0.1:8000/mcp # Server có token: claude mcp add --transport http foxprofile https://vps.cua-ban.com/mcp --header "Authorization: Bearer " ``` ```jsonc // Cursor: ~/.cursor/mcp.json { "mcpServers": { "foxprofile": { "url": "http://127.0.0.1:8000/mcp" } } } ``` Claude Desktop chỉ chạy được server MCP cục bộ: dùng `foxprofile_mcp.py` (cùng máy) hoặc cầu nối `npx mcp-remote` (máy khác). Hộp thoại "Kết nối AI" sinh sẵn cả hai. Sau đó chỉ cần nhắn AI, ví dụ: *"Mở profile tiktok-us-02, vào tiktok.com và chụp màn hình cho tôi"*. | Nhóm | Tool | | --- | --- | | Profile | `list_profiles`, `get_profile`, `create_profile`, `update_profile`, `launch_profile`, `stop_profile`, `running_profiles` | | Cookie & fingerprint | `export_cookies`, `import_cookies`, `get_fingerprint`, `reset_fingerprint`, `check_proxy`, `check_profile_ip` | | Trang | `browser_navigate`, `browser_back`, `browser_snapshot`, `browser_get_text`, `browser_click`, `browser_click_at`, `browser_type`, `browser_press`, `browser_wait_for`, `browser_screenshot`, `browser_evaluate` | | Tab | `browser_tabs`, `browser_tab_new`, `browser_tab_select`, `browser_tab_close` | MCP **không** có tool xóa profile, để AI không thể vô tình xóa cookie của tài khoản. Trang chỉ mở được `http`, `https` và `about:blank`; `file://` và `about:config` bị chặn. ## Engine Chrome Ngoài Camoufox (Firefox), profile có thể chạy trên engine **Chrome**: một bản Chromium đã vá fingerprint ở tầng C++ ([fingerprint-chromium](https://github.com/adryfish/fingerprint-chromium), giấy phép BSD-3). Chọn ở ô **Engine** khi tạo profile; không đổi được sau khi tạo. Bản trình duyệt (~140-190 MB tuỳ hệ điều hành, tải từ GitHub của fingerprint-chromium và kiểm tra SHA-256) được tự tải ở nền ngay khi tạo profile Chrome đầu tiên, hoặc lúc mở profile nếu chưa có; tiến độ hiện trong log. Muốn tải trước bằng tay: `python -m chrome_engine fetch`. Nên chọn đúng hệ điều hành của máy đang chạy FoxProfile: persona khác hệ điều hành sẽ lộ font của máy, và persona Linux trên Windows/macOS bị từ chối vì WebGL lộ GPU thật. Hỗ trợ Windows x64, macOS Apple Silicon và Linux x64 (hiện ít kiểm thử trên máy thật hơn). Chi tiết và kết quả kiểm thử: [chrome_engine/README.md](chrome_engine/README.md). Giới hạn đã biết: - **Font lấy từ máy.** Persona khác hệ điều hành sẽ hiện font của máy, vì vậy persona nên dùng đúng hệ điều hành của máy. Trên máy macOS, persona Windows còn có scrollbar overlay 0px. - **Cửa sổ hiện trên màn hình báo kích thước màn hình thật.** fingerprint-chromium 148 bỏ qua các switch giả kích thước màn hình, nên các profile trên cùng một máy có chung kích thước màn hình; trình duyệt chạy ẩn (headless) báo 1920x1080. - **Không có Widevine.** Bản build dựa trên ungoogled-chromium nên video có DRM (các dịch vụ streaming) không phát được, và trang web kiểm tra được điều này. - **Chậm hơn Chrome hiện hành vài phiên bản.** FoxProfile ghim fingerprint-chromium 148 vì bản 150 bị crash khi trang vẽ emoji lên canvas. - **WebRTC khi có proxy không gửi UDP**, giống chính sách của extension WebRTC Leak Prevent: không lộ địa chỉ nào, nhưng cuộc gọi WebRTC chỉ chạy được qua TURN server dùng TCP. ## Cookie và fingerprint ![Cookie & fingerprint](docs/images/cookies.png) Bấm nút cookie trên dòng profile để mở hộp thoại **Cookie & fingerprint**. **Trình duyệt của profile phải đang tắt**, vì FoxProfile mở profile ở chế độ headless để đọc và ghi cookie. - Cookie phiên (session) khi nhập vào sẽ được đặt hạn 1 năm. Nếu không, trình duyệt sẽ xóa chúng ngay khi đóng. - "Tạo fingerprint mới" xóa fingerprint đã lưu; lần mở sau profile sẽ là một thiết bị khác. Đổi hệ điều hành của profile cũng tự sinh fingerprint mới. ## Cấu hình Mọi cấu hình đều không bắt buộc. Muốn đổi thì sao chép `.env.example` thành `.env`. | Biến | Mặc định | Ý nghĩa | | --- | --- | --- | | `FOXPROFILE_LANG` | `en` | Ngôn ngữ giao diện: `en` hoặc `vi` | | `FOXPROFILE_PROFILES_FILE` | `profiles.json` | File lưu danh sách profile | | `FOXPROFILE_DATA_DIR` | `camoufox_data` | Thư mục dữ liệu, mỗi profile một thư mục con | | `FOXPROFILE_LOG_DIR` | `logs` | Thư mục log | | `FOXPROFILE_LOG_LEVEL` | `INFO` | Mức log | | `FOXPROFILE_PROXY_TIMEOUT` | `10` | Thời gian chờ khi kiểm tra proxy (giây) | | `FOXPROFILE_LAUNCH_TIMEOUT` | `90` | Thời gian API chờ trình duyệt mở xong (giây) | | `FOXPROFILE_HEADLESS` | `false` (`true` ở chế độ server) | Chạy trình duyệt ẩn: `true`, `false` hoặc `virtual` (Linux + Xvfb) | | `FOXPROFILE_RESTORE_TABS` | `true` | Mở lại các tab của lần chạy trước | | `FOXPROFILE_API_TOKEN` | *(trống)* | Token cho API, web panel và MCP. Bắt buộc khi API nghe ngoài `127.0.0.1` | | `FOXPROFILE_API_HOST` | `127.0.0.1` | Địa chỉ API | | `FOXPROFILE_API_PORT` | `8000` | Cổng API | ### Định dạng proxy `host:port`, `http://host:port`, `https://...`, `socks4://...`, `socks5://...`, có thể kèm `user:pass@`. Dạng `host:port:user:pass` mà nhà cung cấp proxy hay đưa cũng dùng được. Để trống nghĩa là kết nối trực tiếp. ### Dữ liệu được lưu ở đâu ```text profiles.json danh sách profile (tên, engine, proxy, hệ điều hành, timezone, locale) camoufox_data// dữ liệu trình duyệt: cookie, lịch sử, localStorage camoufox_data//fingerprint.json fingerprint thiết bị (engine Camoufox) camoufox_data//chrome_persona.json fingerprint thiết bị (engine Chrome) camoufox_data//tabs.json các tab sẽ được mở lại logs/foxprofile_YYYYMMDD.log log theo ngày ``` > [!WARNING] > `camoufox_data/` chứa cookie đăng nhập của mọi tài khoản. Không commit, không chia sẻ thư mục này. ## REST API Tiền tố: `/api/v1`. Xem đầy đủ tại `/docs` khi ứng dụng đang chạy. | Method | Đường dẫn | Mô tả | | --- | --- | --- | | `GET` | `/health` | Kiểm tra API | | `GET` / `POST` | `/profiles` | Liệt kê / tạo profile | | `GET` / `PATCH` / `DELETE` | `/profiles/{name}` | Xem / sửa / xóa profile (không đổi được `engine`) | | `GET` | `/profiles/{name}/data-dir` | Đường dẫn thư mục dữ liệu của profile | | `POST` | `/profiles/{name}/export` | Xuất profile ra ZIP | | `POST` | `/profiles/import` | Nhập profile từ ZIP | | `GET` | `/profiles/{name}/cookies?format=json\|netscape` | Xuất cookie | | `POST` | `/profiles/{name}/cookies` | Nhập cookie (`{"content": ""}`) | | `GET` / `DELETE` | `/profiles/{name}/fingerprint` | Xem / tạo fingerprint mới | | `GET` | `/profiles/{name}/ip-check` | Kiểm tra IP ra của profile: quốc gia, timezone theo Cloudflare/ipinfo/ip-api, cảnh báo lệch | | `GET` | `/browser` | Danh sách profile đang chạy | | `GET` | `/browser/{name}/status` | Profile có đang chạy không | | `POST` | `/browser/{name}/launch` | Mở trình duyệt, chờ đến khi mở xong hoặc lỗi (409 nếu đang chạy hoặc đang bận) | | `POST` | `/browser/{name}/stop` | Đóng trình duyệt | | `POST` | `/proxy/check` | Kiểm tra proxy | | `POST` | `/proxy/geo-check` | Như `ip-check` cho tổ hợp `{proxy, timezone, locale}` chưa lưu | | `POST` | `/browser/{name}/page/navigate` · `back` | Mở URL trong tab đang chọn, quay lại trang trước | | `GET` | `/browser/{name}/page/snapshot` · `text` | Cây accessibility của trang (để chọn selector), chữ trên trang | | `POST` | `/browser/{name}/page/click` · `type` · `press` · `wait` | Click, gõ, bấm phím, chờ phần tử (selector Playwright) | | `POST` | `/browser/{name}/page/click-at` · `keyboard` | Click theo tọa độ, gõ vào ô đang chọn | | `GET` | `/browser/{name}/page/screenshot` | Ảnh PNG của tab (`?format=json` để nhận base64) | | `POST` | `/browser/{name}/page/evaluate` | Chạy JavaScript | | `GET` / `POST` | `/browser/{name}/page/tabs` | Liệt kê / mở tab mới | | `POST` / `DELETE` | `/browser/{name}/page/tabs/{index}/select` · `/page/tabs/{index}` | Chọn / đóng tab | | `GET` | `/mcp/setup?base_url=...` | Cấu hình MCP cho từng ứng dụng AI (dùng bởi hộp thoại Kết nối AI) | Khi có `FOXPROFILE_API_TOKEN`, mọi request (trừ `/health` và `/info`) phải gửi header `Authorization: Bearer `. Ví dụ: ```bash # Tạo profile macOS có proxy. "engine": "chrome" để dùng engine Chrome (mặc định "camoufox"). curl -X POST http://127.0.0.1:8000/api/v1/profiles \ -H "Content-Type: application/json" \ -d '{"name": "tiktok-us-02", "os_type": "macos", "proxy": "socks5://user:pass@203.0.113.10:1080"}' # Mở trình duyệt. Trả 200 khi đã mở, 502 kèm lý do nếu lỗi. # Thêm ?wait=false để trả về ngay (202). curl -X POST http://127.0.0.1:8000/api/v1/browser/tiktok-us-02/launch # Xuất cookie dạng cookies.txt curl "http://127.0.0.1:8000/api/v1/profiles/tiktok-us-02/cookies?format=netscape" -o cookies.txt ``` ## Phát triển ```bash pip install -r requirements-dev.txt ruff check src tests chrome_engine ruff format --check src tests chrome_engine pytest # test cần trình duyệt thật sẽ tự bỏ qua nếu chưa tải ``` Cấu trúc thư mục, quy ước code và quy trình gửi PR nằm trong [CONTRIBUTING.md](CONTRIBUTING.md). Thay đổi giao diện theo [DESIGN.md](DESIGN.md) và sửa cả app desktop lẫn web panel. Lịch sử thay đổi: [CHANGELOG.md](CHANGELOG.md). ## Đóng góp Mọi đóng góp đều được chào đón: báo lỗi, đề xuất tính năng, sửa tài liệu, dịch thuật hay viết code. - Báo lỗi hoặc đề xuất: mở [issue](https://github.com/chienbm98/foxprofile/issues/new/choose) theo mẫu. - Gửi code: đọc [CONTRIBUTING.md](CONTRIBUTING.md) trước khi mở Pull Request. - Lỗ hổng bảo mật: **không** mở issue công khai, xem [SECURITY.md](SECURITY.md). - Mọi người tham gia cần tuân theo [Quy tắc ứng xử](CODE_OF_CONDUCT.md). Nếu FoxProfile có ích với bạn, hãy cho dự án một ⭐ trên GitHub. ## Lưu ý sử dụng Antidetect browser là công cụ hợp pháp, thường dùng để bảo vệ quyền riêng tư, kiểm thử web, hoặc để agency quản lý tài khoản của nhiều khách hàng. Tuy vậy, dùng nhiều tài khoản trên cùng một nền tảng có thể vi phạm điều khoản của Facebook, TikTok, Google, Shopee... Bạn tự chịu trách nhiệm về cách mình sử dụng. ## Giấy phép Phát hành theo [giấy phép MIT](LICENSE). Copyright (c) 2026 chienbm98. ## Ghi công - Trình duyệt [Camoufox](https://github.com/daijro/camoufox) của daijro. - [fingerprint-chromium](https://github.com/adryfish/fingerprint-chromium) của adryfish cho engine Chrome (BSD-3). - Font [Be Vietnam Pro](https://github.com/bettergui/BeVietnamPro) và [JetBrains Mono](https://github.com/JetBrains/JetBrainsMono), giấy phép SIL Open Font License (`src/assets/fonts/`).