Giữ Clearcote luôn được cập nhật

Khi không có khóa giấy phép, mỗi phiên bản SDK được ghim với một bản build mở đã xác minh SHA-256, và việc cập nhật chỉ là nâng phiên bản package như bình thường. Khi có khóa, SDK tải bản build có giấy phép hiện hành ở mỗi lần khởi chạy — không cần nâng phiên bản.

Những bản build hiện có

Các Chromium major mà chúng tôi đang phát hành hoặc đang phát triển, và thời điểm mỗi gói nhận được chúng:

Người dùng SDK (khuyến nghị)

Nâng phiên bản package như khi bạn cập nhật bất kỳ dependency nào:

npm i clearcote@latest          # Node
pip install -U clearcote        # Python
dotnet add package Clearcote    # .NET (adds or updates to the newest version)

Ở lần launch() tiếp theo, SDK nhận thấy bản build cần dùng chưa có trong cache, tải nó về — bản build mở từ GitHub Releases, bản build có giấy phép từ clearcotelabs.com — và xác minh SHA-256 trước khi dùng. Không có gì chạy khi chưa được xác minh. Mỗi bản build được cache riêng trong thư mục cache của người dùng — %LOCALAPPDATA%\clearcote\Cache trên Windows, ~/.cache/clearcote trên Linux (đặt CLEARCOTE_CACHE để đổi vị trí) — nên mỗi bản chỉ cần tải một lần. Các bản build cũ được giữ lại cho đến khi bạn chạy clearcote clear-cache.

Nhiều chương trình, một cache

Các chương trình dùng chung cache sẽ lần lượt cài đặt một bản build (SDK 0.41.0+, áp dụng như nhau cho Python, Node và .NET): chương trình đầu tiên tải bản build về, các chương trình khác chờ rồi dùng nó, và một bản build mà chương trình khác đang chạy sẽ không bao giờ bị thay thế ngay dưới chân nó. Một chương trình đang chờ sẽ bỏ cuộc sau 30 phút, kèm thông báo nêu tên tiến trình đang giữ việc cài đặt (lock là file .install-lock trong thư mục cache của bản build đó; thông báo sẽ cho biết khi nào có thể xóa nó một cách an toàn). Lock bị bỏ lại bởi một chương trình bị crash sẽ được tự động tiếp quản.

Một bản build trong cache có file bị hỏng hoặc bị xóa (bị antivirus cách ly, thư mục bị xóa) sẽ được sửa ở lần khởi chạy tiếp theo bằng một lần tải. Nếu các file của nó vẫn đang được sử dụng, lần khởi chạy sẽ dừng ngay và yêu cầu bạn đóng mọi chương trình đang dùng trình duyệt đó, rồi thử lại. Cơ chế lock cần mọi tiến trình dùng chung cache chạy SDK 0.41.0 trở lên; các bản phát hành cũ hơn không chờ lock.

Windows: một số môi trường không thể khởi động bản build đã tải về ngay tại chỗ, chẳng hạn một chương trình chạy bên trong một ứng dụng đóng gói (MSIX), nơi Windows chuyển hướng các thao tác ghi vào %LOCALAPPDATA% (lần khởi chạy thất bại với spawn UNKNOWN hoặc "the side-by-side configuration is incorrect"). Khi đó SDK tạo một bản sao của bản build trong ~/.clearcote/recovered, và mọi lần khởi chạy sau đó từ Python, Node hoặc .NET đều dùng bản sao này, nên không còn gì bị bỏ lại trong thư mục tạm và các lần khởi chạy lặp lại chỉ mất vài giây (Python và Node từ 0.40.1, .NET từ 0.41.0). clearcote clear-cache cũng xóa các bản sao đó; .NET SDK không có command line, nên ở đó hãy gọi WinLaunch.ClearRecovered().

Cập nhật bản build mở mà không cần nâng cấp SDK

Khi không có khóa, hãy bật auto-update để dùng bản build mở mới nhất trên GitHub thay vì bản mà SDK ghim. Bản này được xác minh với SHA256SUMS.txt của bản phát hành đó (và với khóa ký nếu đã cài gpg); nếu không kết nối được tới GitHub, SDK quay về bản build đã ghim. Từ shell, clearcote update làm điều tương tự. Khi có khóa, tùy chọn này không thay đổi gì — bạn vốn đã nhận bản build có giấy phép hiện hành.

import { launch } from "clearcote";
await launch({ autoUpdate: true });   // or set env CLEARCOTE_AUTO_UPDATE=1

Bản thân trình duyệt không bao giờ tự gửi dữ liệu về (phone home) hay tự cập nhật. Khi không có khóa, trình duyệt chỉ thay đổi khi bạn nâng phiên bản SDK hoặc bật autoUpdate. Khi có khóa, SDK nhận từng bản build có giấy phép mới ở lần khởi chạy tiếp theo; Pro có thể giữ nguyên một bản build bằng version.

Chọn bản build

Truyền version (hoặc đặt CLEARCOTE_BROWSER_VERSION): "latest", một major như "154", một phiên bản cụ thể "154.0.8037.57", hoặc một revision có giấy phép "r36" / "154.0.8037.57-r36". Phiên bản hoặc major được đối chiếu với catalog đã công bố, còn revision được đối chiếu với licence server, trước khi tải bất cứ thứ gì. releaseChannel: "preview" (release_channel trong Python, hoặc CLEARCOTE_RELEASE_CHANNEL=preview) sẽ lấy bản build preview nếu có. Trên bản build có giấy phép, các bản build cũ, việc ghim phiên bản và kênh preview là tính năng của Pro — khóa miễn phí luôn nhận bản mới nhất.

clearcote install --version 154        # fetch + verify a build ahead of time
clearcote install --channel preview     # the newest preview build (Pro)
clearcote info                          # what's installed and cached, and your key
clearcote clear-cache                   # delete cached builds

Người dùng binary trực tiếp / Docker

• Binary trực tiếp (chỉ áp dụng cho bản build mở — bản build có giấy phép chạy qua SDK, clearcote serve hoặc Docker image): tải file nén mới từ trang Releases, xác minh checksum + chữ ký (xem Xác minh), rồi trỏ executable_path / executablePath (hoặc CLEARCOTE_BINARY) tới file chrome mới.
• Docker: chạy docker pull teamflatearth/clearcote để lấy image mới nhất, rồi tạo lại container. Khóa miễn phí cần image được build từ SDK 0.30.0 trở lên. Khi có khóa, hãy mount -v clearcote-cache:/opt/xdg-cache để bản build có giấy phép chỉ tải một lần thay vì tải lại vào mỗi container mới. Xem Triển khai.

Bản build có giấy phép — luôn mới nhất, và luôn có trước

Bản build có giấy phép bám theo Chromium mới nhất và các patch mới nhất, nên bạn nhận được cập nhật mà không phải tự build lại. Đặt CLEARCOTE_LICENSE_KEY, truyền licenseKey, hoặc chạy clearcote login (Python/Node; dùng npx clearcote login nếu cài npm cục bộ) — lệnh này kiểm tra khóa và lưu vào ~/.clearcote/license.key, file mà mọi SDK, kể cả .NET, đều đọc. Có hai cách để nhận khóa:

• Miễn phí với GitHub — mỗi lần một trình duyệt, không mất phí. Đăng nhập bằng tài khoản GitHub đã tạo ít nhất 30 ngày, mở Licenses trong dashboard, nhấn Connect GitHub and get it free, rồi Claim my free key (mỗi tài khoản GitHub một khóa). Khóa có hiệu lực 30 ngày; hãy gia hạn miễn phí ngay trên trang đó trước khi hết hạn.
• Pro — cùng bản build đó, tối đa 250 trình duyệt chạy đồng thời, có các bản build cũ, ghim phiên bản và kênh preview, cùng hỗ trợ qua email từ chủ dự án.

Các major mới đến với bản build có giấy phép trước. Khi một Chromium major mới được build, nó có ngay trên Miễn phí với GitHub và Pro; bản build mở nhận major đó sau — mục tiêu là khoảng 2 tháng sau khi phát hành (hiện bản build mở đang ở Chromium 150). Bản build mở luôn hoàn toàn mở và có thể tái tạo; bản build có giấy phép nhận major mới nhất sớm hơn.

Cách tính số trình duyệt có giấy phép

Mỗi trình duyệt khởi chạy bằng khóa sẽ lấy một slot từ licence server và trả lại khi đóng. Dashboard của bạn hiển thị số slot đang dùng, và clearcote info in ra cùng con số đó.

• Miễn phí với GitHub tính mọi trình duyệt. Chỉ có một slot, nên trình duyệt thứ hai — trong cùng chương trình, ở chương trình khác hay trên máy khác — sẽ bị từ chối với lỗi The free tier runs one browser at a time, and one is already running cho đến khi trình duyệt đầu tiên đóng. Trình duyệt bị crash mà không kịp đóng sẽ giải phóng slot trong vòng 6 phút.
• Pro tính theo máy và hỗ trợ tối đa 250 trình duyệt cùng lúc. Mọi trình duyệt trên cùng một máy dùng chung slot của máy đó. Các gói đăng ký bắt đầu trước ngày 26 tháng 9 năm 2026 vẫn giữ điều khoản không giới hạn trước đây; nếu bạn cần hơn 250, hãy liên hệ và chúng tôi sẽ nâng giới hạn.
• Khóa miễn phí cần SDK 0.30.0 trở lên (Python, Node và .NET), vì để tính mọi trình duyệt, SDK phải báo cáo từng lần khởi chạy và giữ giấy phép luôn được cập nhật trong khi trình duyệt đó chạy. SDK cũ hơn sẽ nhận SDK_UPGRADE_REQUIRED kèm lệnh nâng cấp, và SDK cũ nào vẫn đến được engine thì cũng bị từ chối ở đó. Khóa Pro vẫn hoạt động với SDK cũ như trước.
• Trình duyệt miễn phí sẽ dừng khi mất slot. Việc kiểm tra diễn ra liên tục, không chỉ lúc khởi động: nếu khóa bị thu hồi, slot bị check-in ở nơi khác, hoặc giấy phép vượt giới hạn, trình duyệt miễn phí đang mở sẽ tắt trong khoảng 2 đến 3 phút. Các lần rớt mạng ngắn (lỡ một hai heartbeat) sẽ được bỏ qua; mất kết nối lâu hơn khoảng 2 đến 3 phút cũng sẽ dừng trình duyệt miễn phí theo cách tương tự.
• Gói miễn phí luôn chạy bản build mới nhất. Yêu cầu một bản build có giấy phép cũ hơn hoặc kênh preview sẽ trả về FREE_LATEST_ONLY; ghim bản build là tính năng của Pro.
• Lượt tải với khóa miễn phí: tối đa 10 bản build khác nhau trong mỗi 24 giờ. Cùng một bản build chỉ tính một lần, dù bạn khởi chạy bao nhiêu lần.

pip install -U clearcote          # Python 0.30.0+
npm i clearcote@latest            # Node 0.30.0+
dotnet add package Clearcote      # .NET 0.30.0+

Những gì thay đổi khi bạn nâng cấp

Phần lớn các bản phát hành SDK không thay đổi gì mà bạn phải xử lý. Những bản dưới đây thay đổi cách một cấu hình hiện có hoạt động; mọi bản phát hành đều được liệt kê trong mục Releases trên dashboard của bạn.

• Bản build có giấy phép 154 r36, seed hiện có: giờ đây seed lấy card đồ họa từ nhiều mẫu card thật của chính hãng card đồ họa trên máy, thay vì một mẫu duy nhất cho mỗi hãng, nên phần lớn các seed sẽ báo một card khác so với trên r35. Trên máy có card NVIDIA, một seed từng khai báo phần cứng cấp thấp (4 đến 6 luồng xử lý, 4 đến 8 GB bộ nhớ, màn hình nhỏ) giờ sẽ khai báo phần cứng tầm trung trở lên, và trên máy đó không seed nào khai báo màn hình cảm ứng. Để giữ các danh tính mà seed của bạn có trước r36, hãy đặt persona_schema=2 / personaSchema: 2. Xem cùng một seed trên các máy khác nhau.
• Bản build có giấy phép 154 r36, cookie bên thứ ba: giờ đây trình duyệt cho phép chúng theo mặc định, như Chrome, kể cả khi một SDK cũ hơn hoặc launcher của riêng bạn không truyền tùy chọn cookie nào. --block-third-party-cookies sẽ chặn chúng.
• 0.42.0, host Linux: WebGL của persona Linux giờ được render qua Mesa trên EGL ở chế độ headed cũng như headless (host cần có libegl1), nên chuỗi renderer, danh sách extension và các giới hạn WebGL của một persona Linux chạy headed sẽ thay đổi một lần, sang dạng mà các lần khởi chạy headless vốn đã hiển thị và phần lớn máy Linux thật báo cáo. Một lần khởi chạy headed dưới Xvfb không có trình quản lý cửa sổ sẽ mở ra với cửa sổ vừa với màn hình. Các lần khởi chạy headless giữ một màn hình thực tế kể cả khi persona không có hiệu lực, và serve() cũng giữ màn hình đó khi bạn chỉ truyền --window-position. Xem Playwright & Puppeteer.
• Bản build có giấy phép 154 r34 trở lên, disableGpuFingerprint: giờ nó chỉ thay đổi những gì GPU báo cáo. Việc readback pixel WebGL vẫn giữ nhiễu theo từng site của seed, nên readPixels và các kết quả xuất của một canvas WebGL khớp với nhau. Trước đây, nó chỉ tắt riêng nhiễu của readPixels. Xem Các flag fingerprint.
• 0.41.1, nhập liệu giống người: với humanize, cuộn trang di chuyển theo từng nấc con lăn chuột trọn vẹn, như một con lăn thật: 100 px mỗi nấc trên một danh tính Windows, 120 trên Linux và 40 trên macOS. Khoảng cách được yêu cầu sẽ được làm tròn tới nấc gần nhất (tối thiểu một nấc), nên mouse.wheel(0, 800) cuộn 800 px trên Windows và 840 trên Linux. Khi gõ phím, giờ đây đôi khi phím tiếp theo được nhấn xuống trước khi phím trước được nhả ra ở các cặp phím gõ nhanh. Trong .NET, một humanizer được seed bằng một số giờ đây di chuyển với cùng danh tính vận động (motor identity) như trong Python và Node; trước đây, mọi seed dạng số khác 0 đều dùng chung một danh tính. Xem Nhập liệu giống người.
• 0.41.0 trên bản build có giấy phép từ r32: persona đến trình duyệt qua biến môi trường của nó thay vì qua dòng lệnh, nên một công cụ từng đọc seed từ danh sách tiến trình sẽ không còn tìm thấy nó (persona_env=False giữ cách cũ). Các context mà một lần khởi chạy local tạo ra không còn giả lập color scheme sáng, nên một persona tối sẽ báo là tối ở mọi nơi (truyền color_scheme để cố định một chế độ). Một lần khởi chạy Linux headless có persona sẽ nhận một màn hình đúng kích thước mà persona khai báo. Xem Tùy chọn khởi chạy.
• 0.41.0, .NET trên Linux: các lần khởi chạy giờ dùng bộ font đi kèm trình duyệt, như Python và Node vẫn luôn làm, thay vì font của host. Vì vậy, một persona Windows ở đó đo ra kết quả khác trước, giờ giống như hai SDK còn lại. Xem font của riêng bạn trên Linux.
• 0.41.0, persona Linux trên máy tính Windows: SDK cảnh báo một lần cho mỗi tiến trình. Windows chạy GPU qua Direct3D, vốn giới hạn các limit của WebGL và WebGPU, và persona có thể hạ một limit xuống nhưng không bao giờ nâng nó vượt quá mức của driver, nên một persona Linux ở đó sẽ báo những limit mà không máy Linux nào có. Hãy khai báo Windows trên Windows, hoặc chạy persona Linux trên Linux hay trong Docker. quiet hoặc CLEARCOTE_NO_WARN sẽ tắt cảnh báo này.
• Image Docker sdk-0.41.0: Chrome có thể chạy với sandbox của nó, nếu bạn khởi động container với seccomp profile của image; nếu không có profile, container chạy như trước. Font cho các hệ chữ viết được tích hợp sẵn. Xem Triển khai.
• 0.40.0: trên macOS, launch() chạy image Docker của Clearcote (cần Docker Desktop; docker=False sẽ tắt nó). Xem macOS.

Sau khi nâng cấp, hãy xác minh lại

Một bản build mới có thể làm thay đổi một tín hiệu. Hãy chạy lại các bài kiểm tra fingerprint (ví dụ CreepJS) và, nếu bạn dùng profile được import, hãy xác nhận profile đó vẫn tải lên nhất quán — xem Xác minh. Bản build mở hiện tại là v0.1.0-pre.23 (Chromium 150.0.7871.114); bản build có giấy phép hiện tại là 154.0.8037.57-r36. Lộ trình cho biết những gì sắp tới.