Canvas bridge

Render canvas và WebGL trên một GPU thật ở máy từ xa để pixel mà trang đọc lại nhất quán với GPU mà máy render thực sự có — hãy đặt chuỗi GPU trong profile của bạn khớp với GPU đó. Tính năng đang ở giai đoạn thử nghiệm và phải tự bật — khi không có --canvas-bridge-url, Clearcote render hoàn toàn cục bộ, y như trước.

Vì sao cần canvas bridge

Clearcote render canvas/WebGL trên chính GPU mà máy host đang có. Nếu một profile khai báo một GPU khác với máy host, các bài kiểm tra anti-detect / browser-tampering khắt khe — vốn so sánh pixel đã render với phần cứng được khai báo — có thể nhận ra sự không khớp đó: bạn không thể dùng phần mềm để khiến một GPU xuất ra đúng từng pixel của một GPU khác. Canvas bridge loại bỏ sự không khớp này: thay vì render cục bộ và chỉ spoof chuỗi GPU, nó chuyển tiếp các thao tác canvas/WebGL sang một máy từ xa có GPU mà bạn muốn thể hiện, rồi trả về pixel thật của máy đó. Vì chuyển tiếp các thao tác (chứ không phải một thư viện cố định gồm các ảnh ghi sẵn), bridge xử lý được hầu hết canvas được sinh ra, không chỉ các probe đã biết.

Cách hoạt động

Các API readback — getImageData, toDataURL, readPixels và measureText — trả về pixel nguyên gốc của máy bridge; nhiễu farbling cục bộ được bỏ qua trên đường đi qua bridge (pixel từ bridge chính là dữ liệu gốc). Lớp truyền tải là một WebSocket mang một luồng message nhị phân gọn nhẹ. Pixel đến từ GPU mà trình duyệt render đang có, dù đó là GPU nào.

text

  clearcote (your automation host)         bridge host (real GPU)
  +-----------------------------+          +-------------------------+
  | page: getImageData /        |  ops --> | render browser          |
  |       toDataURL / readPixels |         | renders on the real GPU,|
  | CanvasBridgeClient  <-- pixels ---------|  reads back the pixels  |
  +-----------------------------+          +-------------------------+

Bạn cần gì

Một máy render (render host) — bất kỳ máy nào có GPU mà bạn muốn thể hiện (GPU Windows cho persona Windows). GPU của máy này sẽ trở thành danh tính canvas mà các profile của bạn thể hiện, vì vậy hãy chọn phần cứng khớp với persona bạn muốn trình ra (máy NVIDIA để thể hiện NVIDIA, v.v.). Trỏ --backend cdp của server tới một Chrome thông thường mà bạn chạy trên máy đó (khuyến nghị), hoặc dùng --backend local với một binary Clearcote.
Một đường mạng riêng giữa máy automation của bạn và máy bridge. Bridge giao tiếp bằng WebSocket dạng plaintext (ws://) — luôn chạy nó qua mạng riêng hoặc một tunnel có mã hóa (Tailscale, WireGuard, hoặc SSH port forwarding). Tuyệt đối không mở cổng bridge ra internet công cộng.

Thiết lập

1. Khởi động render server trên máy có GPU thật. Đây là một coordinator Python nhỏ, điều khiển một trình duyệt headless và phát lại các thao tác được chuyển tới trên canvas thật của nó, nên pixel trả về chính xác là những gì GPU đó tạo ra. GPU thật của máy render sẽ trở thành danh tính canvas/WebGL. Với --backend cdp, lúc khởi động server sẽ in ra chuỗi renderer của GPU render (render GPU='ANGLE (…)') — hãy ghi lại để dùng ở bước 3. Với --backend local, hãy lấy các chuỗi này từ một Chrome thông thường trên cùng máy.

bash

pip install playwright    # one-time (no browser download needed for CDP)

# a regular Chrome on the GPU host, started with --remote-debugging-port=9222
# --user-data-dir=<a separate folder> (Chrome ignores the port on its default profile);
# its CDP URL is webSocketDebuggerUrl from http://127.0.0.1:9222/json/version
python tools/canvas-bridge-server/server.py \
    --backend cdp \
    --cdp-url ws://127.0.0.1:9222/devtools/browser/... \
    --port 8443

# Or let the server launch a Clearcote binary itself:
# python tools/canvas-bridge-server/server.py \
#     --backend local \
#     --chrome /path/to/clearcote/chrome.exe \
#     --port 8443

2. Tạo tunnel. ws:// không được mã hóa — hãy đặt cả hai máy trong cùng một mạng Tailscale/WireGuard, hoặc forward cổng qua SSH. Mặc định server chỉ bind vào localhost, nên trên Tailscale/WireGuard hãy khởi động nó với --host <that interface's IP>; còn cách dùng SSH bên dưới thì chạy được ngay:

bash

ssh -N -L 8443:localhost:8443 user@bridge-host
# the bridge is now reachable at ws://127.0.0.1:8443

3. Khởi chạy client (Clearcote dùng cho automation của bạn) trỏ tới bridge, kèm các chuỗi của GPU render — renderer đúng y như server đã in ra, còn vendor theo dạng Google Inc. (<first name in the renderer>), ví dụ Google Inc. (Intel). Bridge làm cho pixel khớp với GPU render, còn các chuỗi này làm cho chuỗi được báo cáo cũng khớp theo. Thiếu chúng, tên GPU của persona và pixel đi qua bridge sẽ mâu thuẫn nhau:

bash

--canvas-bridge-url=ws://127.0.0.1:8443 \
--no-sandbox \
--fingerprint=<seed> \
--fingerprint-gpu-vendor='Google Inc. (Intel)' \
--fingerprint-gpu-renderer='ANGLE (Intel, Intel(R) UHD Graphics ... D3D11)'

Flag	Ý nghĩa
--canvas-bridge-url	Endpoint của bridge `ws://host:port`. Bắt buộc để bật bridge.
--canvas-bridge-auth	Thông tin xác thực HTTP Basic `user:secret` (tùy chọn), dành cho mô hình triển khai có đặt lớp xác thực phía trước server. Server tham chiếu không kiểm tra thông tin này, vì vậy hãy dựa vào mạng riêng hoặc tunnel để kiểm soát truy cập.
--no-sandbox	Bắt buộc — client mở socket tới bridge từ renderer process, điều mà sandbox sẽ chặn.
--fingerprint	Seed của persona.
--fingerprint-gpu-vendor / --fingerprint-gpu-renderer	Các chuỗi của GPU render: renderer đúng y như server đã in ra, vendor theo dạng `Google Inc. (<first name in the renderer>)`.
--canvas-bridge-mode	Chính sách theo từng origin: `off`, `all` (mặc định), `allow` hoặc `deny`.
--canvas-bridge-allow / --canvas-bridge-deny	Danh sách eTLD+1 phân tách bằng dấu phẩy, dùng cho `mode=allow` hoặc `mode=deny`.
--canvas-bridge-fallback	Hành vi khi cache miss lúc cache còn trống: `block` (mặc định) chờ bridge; `local` trả về pixel cục bộ thay vì đứng chờ.

Dùng từ SDK

SDK (Node, Python và .NET; phiên bản hiện tại 0.31.1) cung cấp sẵn tùy chọn chính thức canvasBridge / canvas_bridge / CanvasBridge. Khi đặt URL bridge, SDK sẽ sinh ra các switch tương ứng và tự thêm --no-sandbox. Để xem cùng chính sách allow-list trong một script khởi chạy đầy đủ, hãy xem Ví dụ.

javascript

const browser = await clearcote.launch({
  fingerprint: "user-1",
  gpuVendor: "Google Inc. (Intel)",                                // "Google Inc. (<first name in the renderer>)"
  gpuRenderer: "ANGLE (Intel, Intel(R) UHD Graphics ... D3D11)",   // exactly as the server printed it
  canvasBridge: {
    url: "ws://127.0.0.1:8443",
    auth: "user:secret",
    mode: "allow",
    allow: ["example.com"],
    fallback: "local",
  },
});

Kiểm tra xem bridge có hoạt động không

Khi kết nối thành công, log của client in ra canvas-bridge: connected to <host>:<port> (chạy với --enable-logging=stderr --v=1 để thấy dòng này).
Mở một trang có tính hash bề mặt canvas/WebGL — khi bridge đã kết nối, các hash sẽ khớp với GPU của máy bridge, không phải của máy automation. Kiểm tra nhanh: chạy cùng một lệnh canvas.toDataURL() khi có và khi không có bridge; kết quả sẽ khác nhau.
Nếu không kết nối được tới bridge, Clearcote ghi một cảnh báo vào log và quay về render cục bộ — bridge bị cấu hình sai chỉ làm giảm chức năng một cách êm ái, không bao giờ làm hỏng trang.

Lưu ý & giới hạn

Danh tính canvas = máy bridge, không phải seed. Mọi profile dùng chung một máy bridge sẽ có chung hash canvas/WebGL của máy đó, nên có thể bị liên kết với nhau qua hash canvas. Nếu cần nhiều danh tính không thể liên kết, hãy chạy một máy bridge (GPU) cho mỗi nhóm danh tính.
Độ trễ. Một lần readback pixel bị miss cache của bridge sẽ là một round-trip mạng mang tính chặn (timeout 5s, sau đó quay về render cục bộ), trừ khi fallback là local; engine prefetch sau mỗi lần vẽ, nên các lần đọc pixel lặp lại trên một canvas không đổi sẽ không phải chờ. Mỗi lệnh gọi measureText vẫn là một round-trip. Hãy đặt máy bridge trong cùng LAN/datacenter; tránh dùng bridge cho các trang nặng về canvas và nhạy cảm với độ trễ.
Texture WebGL dạng procedural được đưa qua bridge. Các nguồn texture từ ảnh, canvas 2D, video, ImageBitmap và texture 3D sẽ quay về render cục bộ cho canvas đó, nên chúng vẫn đúng nhưng không đi qua bridge.
--no-sandbox là bắt buộc trên client, và dữ liệu truyền đi ở dạng plaintext — luôn dùng tunnel; tuyệt đối không mở cổng bridge ra công cộng.

Đang thử nghiệm. Có trong bản build mở từ v0.1.0-pre.12, và có trong bản build có giấy phép. Tài liệu tham khảo chính thức (kèm bảng xử lý sự cố đầy đủ) có tại hướng dẫn canvas-bridge trên GitHub. Phần lớn các thiết lập không cần đến bridge — xem Các flag fingerprint để biết các cơ chế điều khiển tiêu chuẩn ở cấp engine.