Chuyển từ Fortress (bản phát hành BSD)

Nếu bạn đang chạy một trong các bản phát hành theo giấy phép BSD của Fortress (v149, v150 hoặc v151) làm endpoint CDP, bạn có thể chuyển thiết lập đó sang Clearcote chỉ bằng cách thay đổi cách khởi động trình duyệt. Code kết nối tới endpoint vẫn giữ nguyên.

Ngày 30/9/2026, Fortress chuyển sang giấy phép source-available của riêng mình với v3 (Chromium 153), còn các bản phát hành trước đó vẫn giữ giấy phép BSD-3. Hướng dẫn này dành cho các team đang dùng một trong những bản phát hành BSD đó và muốn chuyển sang Clearcote thay vì lên v3. Để xem giấy phép, giá và nền tảng của hai bên đặt cạnh nhau, xem Clearcote vs Fortress.

Những gì thay đổi

Bạn đang khởi động Fortress bằng	Khởi động Clearcote bằng
Python: `Fortress()` từ `tilion-fortress`, rồi `f.cdp_url`	`serve()` từ `clearcote`, rồi `srv.cdp_url`
Node: `Fortress.launch()`, rồi `f.cdpUrl`	`await serve()` từ `clearcote`, rồi `srv.cdpUrl`
Docker: `tilion/fortress:149`, `:150` hoặc `:151` trên cổng 9222	`teamflatearth/clearcote` trên cổng 9222
Launcher `tilion`, hoặc binary với `--remote-debugging-port=9222`	`clearcote serve --port 9222`

Mọi thứ sau lời gọi kết nối, tức code Playwright, Puppeteer, browser-use, Crawl4AI hay Stagehand của bạn, vẫn giữ nguyên. Có một điều cần kiểm tra trước: tag image tilion/fortress:latest đã trỏ tới v3 từ ngày 30/9/2026, nên thiết lập nào pull :latest sẽ không còn ở bản phát hành BSD nữa. Hãy ghim :149, :150 hoặc :151 cho đến khi bạn chuyển xong.

Python và Node: serve()

serve() khởi động Clearcote với các thiết lập khởi chạy của SDK (persona, proxy, giá trị mặc định) cùng một endpoint CDP trên loopback, và trả về một handle chứa URL của endpoint. Truyền port=9222 nếu code khác đang chờ địa chỉ cũ; nếu không, serve() sẽ tự chọn một cổng trống.

# pip install -U clearcote
from clearcote import serve
from playwright.sync_api import sync_playwright

with serve(fingerprint="acct-1", port=9222) as srv:        # was: with Fortress() as f:
    with sync_playwright() as p:
        browser = p.chromium.connect_over_cdp(srv.cdp_url)  # was: f.cdp_url
        page = browser.contexts[0].new_page()               # the served profile
        page.goto("https://example.com")
        print(page.title())
        browser.close()                                     # disconnect before the with blocks end

close() dừng trình duyệt, chờ nó thoát hẳn và xóa profile tạm mà serve() đã tạo; trong Python, khối with tự gọi hàm này cho bạn. Với browser-use, Crawl4AI hay Stagehand, hãy đặt srv.cdp_url (Node: srv.cdpUrl) vào thiết lập CDP của chúng. SDK .NET có lệnh gọi tương tự là ServeAsync. Xem thêm tại Puppeteer và các client CDP khác.

Docker

Đổi image và giữ nguyên cổng. Client kết nối tới đúng địa chỉ như trước.

bash

# was: docker run --rm -p 9222:9222 tilion/fortress:151
docker run -d --rm -p 127.0.0.1:9222:9222 -e CC_FINGERPRINT=acct-1 teamflatearth/clearcote

# the latest build: pass your key from the environment and keep the download in a volume
docker run -d --rm -p 127.0.0.1:9222:9222 -e CC_FINGERPRINT=acct-1 \
  -e CLEARCOTE_LICENSE_KEY -v clearcote-cache:/opt/xdg-cache teamflatearth/clearcote

python

browser = p.chromium.connect_over_cdp("http://localhost:9222")   # unchanged
page = browser.contexts[0].new_page()                            # the container's own profile

-p 127.0.0.1:9222:9222 giữ endpoint chỉ trên máy này: có cổng CDP là có toàn quyền điều khiển trình duyệt, nên chỉ mở cổng này ra những mạng bạn tin cậy. Đặt CC_FINGERPRINT để chọn hoặc dùng lại một danh tính: nếu không đặt, image từ sdk-0.39.0 trở đi cho mỗi container một seed ngẫu nhiên riêng, còn image cũ hơn cho mọi container dùng chung một seed. Image được cấu hình hoàn toàn bằng biến môi trường (nền tảng, ngôn ngữ, múi giờ, proxy), liệt kê trong Triển khai.

Từ shell: clearcote serve

Nếu bạn tự khởi động binary hoặc launcher tilion và trỏ các client vào cổng 9222, thì clearcote serve (có trong package Python và Node) là phương án thay thế chạy thường trực. Một kết nối không kèm tham số sẽ nhận một trình duyệt mặc định dùng chung, nên các client hiện có vẫn chạy mà không cần sửa; một kết nối cũng có thể yêu cầu danh tính riêng ngay trong URL.

bash

# was: tilion --headless=new --remote-debugging-port=9222 --user-data-dir=/tmp/p
clearcote serve --port 9222

#   connect_over_cdp("http://127.0.0.1:9222")                     # the shared default browser
#   connect_over_cdp("http://127.0.0.1:9222?fingerprint=acct-1")  # a browser of its own for acct-1

Những điểm hoạt động khác

Danh tính đến từ seed. Trong các bản phát hành BSD, launcher của Fortress áp dụng một persona Windows mặc định nhất quán, và bạn chỉnh riêng từng thành phần bằng các switch --uxr-* (--uxr-timezone, --uxr-languages, --uxr-screen-width, --uxr-canvas-seed, v.v.) hoặc TILION_TZ / TILION_LANG. Clearcote suy ra toàn bộ persona, kể cả nhiễu canvas và WebGL theo từng trang, từ một seed fingerprint duy nhất, nên cùng một seed luôn cho cùng một danh tính, còn một seed mới cho một danh tính không liên quan. Hãy cho mỗi tài khoản một seed riêng thay vì chuyển từng giá trị --uxr-* sang; đặt nền tảng bằng platform, còn múi giờ và ngôn ngữ bằng timezone và accept_language (Node: acceptLanguage), hoặc để geoip tự khớp chúng với proxy. Xem Cấu hình khuyến nghị.
Mở trang trong profile được serve. Dùng browser.contexts[0] như trong các ví dụ. Với Puppeteer, hãy kết nối với defaultViewport: null để cửa sổ giữ đúng kích thước mà persona đã đặt.
Giao proxy cho Clearcote, không phải cho client. Truyền proxy cho serve(), hoặc --proxy cho clearcote serve, và bật geoip để múi giờ, ngôn ngữ và địa chỉ WebRTC khớp với IP đầu ra. Proxy có username và password cần bản build mới nhất; với bản build mở, hãy dùng proxy xác thực theo IP. Xem Proxy & geoip.
Các switch và biến môi trường riêng của Fortress không có tác dụng ở đây. Các tùy chọn của Clearcote nằm trong Tùy chọn khởi chạy và Flag fingerprint.
Nhập liệu giống người là một tùy chọn của launch(). Nó chạy ở phía Playwright, nên không áp dụng cho client kết nối qua CDP.
Cùng nền tảng với các bản phát hành BSD: Windows x64 và Linux x64, còn Docker image là x64.

Bạn nhận được bản build Clearcote nào

Khi không có khóa giấy phép, SDK và image chạy bản build mở: BSD-3, mọi patch đều công khai và tái tạo được, trên Chromium 150, không cần tài khoản. Khi có khóa, chúng chạy bản build mới nhất (Chromium 154), có thêm các patch không công khai: miễn phí với GitHub cho mỗi lúc một trình duyệt, và Pro nếu cần nhiều hơn. Lưu khóa bằng clearcote login hoặc đặt CLEARCOTE_LICENSE_KEY; xem Cài đặt.

Kiểm tra sau khi chuyển

Khi endpoint đang chạy, hãy hỏi xem nó là gì:

bash

curl -s http://127.0.0.1:9222/json/version   # the browser behind the endpoint
clearcote info                                # SDK, licence, cached build and a launch test

clearcote info in ra tag build mà nó xác định được và Launch test ok kèm phiên bản trình duyệt chính xác. Quy trình cài đặt liệt kê phiên bản mà mỗi bản build cần báo về, và việc cần làm khi một bước kiểm tra thất bại.