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ư "156", một phiên bản cụ thể "156.0.8078.47", hoặc một revision có giấy phép "r57" / "156.0.8078.47-r57". 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 có trong Personal và Pro — khóa miễn phí luôn nhận bản mới nhất.

clearcote install --version 156        # 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ó ba 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í. Mở Licenses trong dashboard và nhận khóa theo một trong ba cách: kết nối một tài khoản GitHub đã tạo ít nhất 30 ngày (Connect GitHub and get it free), qua một lần kiểm tra thẻ (thẻ không bao giờ bị trừ tiền; thẻ trả trước bị từ chối), hoặc đăng nhập bằng tài khoản Google Workspace của công ty (tối đa 3 lần nhận cho mỗi tên miền công ty trong mỗi 30 ngày). Mỗi tài khoản GitHub, thẻ hoặc tài khoản Google 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.
• Personal — cùng bản build đó, tối đa 15 trình duyệt cùng lúc, các bản build cũ hơn, ghim phiên bản và kênh preview; không có hỗ trợ qua email.
• 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 151). 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.
• Personal tính từng trình duyệt, tối đa 15 cùng lúc. Mỗi trình duyệt giữ slot riêng của nó, trên một máy hay nhiều máy, và trình duyệt thứ 16 bị từ chối cho đến khi có một trình duyệt đóng lại. Personal cần SDK 0.55.0 trở lên (Profile Manager 0.19.0).
• Pro hỗ trợ tối đa 250 trình duyệt cùng lúc. Với SDK 0.55.0 trở lên, mỗi trình duyệt giữ slot riêng của nó, nên dashboard tính theo trình duyệt chứ không theo máy; SDK cũ hơn vẫn dùng chung một slot cho mỗi 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 thêm các khối 100 hoặc liên hệ với chúng tôi.
• 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 cần Personal hoặc 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 156 r53, mặc định của trình duyệt: tính năng lưu mật khẩu được bật, như trong Chrome: trình duyệt đề nghị lưu mật khẩu sau khi đăng nhập (tùy chọn "Offer to save passwords and passkeys" trong Password Manager sẽ tắt nó). Google lại là công cụ tìm kiếm mặc định, cho cả profile mới lẫn profile hiện có, nên nội dung tìm kiếm gõ vào thanh địa chỉ sẽ đến Google; hãy chọn công cụ khác trong Settings > Search engine. Với Playwright, hãy dùng kèm SDK 0.63.3 trở lên. Danh tính không thay đổi.
• 0.64.1: personaSchema / persona_schema / PersonaSchema chấp nhận 5 và 7 trong mọi SDK.
• 0.64.0, không có khóa giấy phép: SDK tải bản build mở Chromium 151, bản phát hành v0.1.0-pre.25, thay vì 150. version="150" vẫn nhận bản build 150.
• Danh tính được phục vụ từ 2026-10-26 (r52, và cả r51), seed hiện có: persona schema mặc định giờ là 7, một mô hình máy trong đó card đồ họa quyết định loại máy, bộ xử lý, số luồng, bộ nhớ và màn hình của nó, nên một seed sẽ ra một máy khác so với trước. Để giữ danh tính mà seed có trên r45 đến r51, hãy đặt persona_schema=5 / personaSchema: 5. Xem cùng một seed trên các máy khác nhau.
• Bản build có giấy phép 156 r51: danh tính đến từ persona service của Clearcote ở mỗi lần khởi chạy, nên máy cần kết nối HTTPS đi ra tới persona.clearcotelabs.com (và persona-us làm dự phòng), và trình duyệt cần SDK 0.63.0 trở lên (khóa miễn phí 0.63.2), Profile Manager 0.27.0 trở lên. Danh tính không thay đổi với r51. Xem Kiến trúc.
• Bản build có giấy phép 155 r45, seed Windows hiện có: mỗi profile Windows lấy bộ font Office riêng của nó, nên danh sách font thay đổi một lần. persona_schema=4 / personaSchema: 4 giữ nguyên chính xác danh tính của r44.

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.25 (Chromium 151.0.7922.108); bản build có giấy phép hiện tại là 156.0.8078.47-r57. Lộ trình cho biết những gì sắp tới.