从 Fortress（BSD 版本）迁移

如果你把 Fortress 采用 BSD 许可的某个版本（v149、v150 或 v151）作为 CDP 端点运行，只需改变浏览器的启动方式，就能把这套方案迁到 Clearcote。连接端点的代码保持不变。

Fortress 于 2026 年 9 月 30 日随 v3（Chromium 153）改用自己的源码可用（source-available）许可证，更早的版本仍保留 BSD-3 许可。本指南面向正在使用这些 BSD 版本、并且更愿意迁到 Clearcote 而不是升级到 v3 的团队。许可证、价格和支持平台的并列对比，参见Clearcote 与 Fortress 对比。

需要改动的地方

原来启动 Fortress 的方式	现在启动 Clearcote 的方式
Python：`tilion-fortress` 中的 `Fortress()`，然后读取 `f.cdp_url`	`clearcote` 中的 `serve()`，然后读取 `srv.cdp_url`
Node：`Fortress.launch()`，然后读取 `f.cdpUrl`	`clearcote` 中的 `await serve()`，然后读取 `srv.cdpUrl`
Docker：`tilion/fortress:149`、`:150` 或 `:151`，端口 9222	`teamflatearth/clearcote`，端口 9222
`tilion` 启动器，或带 `--remote-debugging-port=9222` 参数的二进制文件	`clearcote serve --port 9222`

连接调用之后的所有代码，也就是你的 Playwright、Puppeteer、browser-use、Crawl4AI 或 Stagehand 代码，都保持原样。有一点需要先检查：自 2026 年 9 月 30 日起，tilion/fortress:latest 镜像标签已指向 v3，所以拉取 :latest 的方案用的已经不是 BSD 版本了。在完成切换之前，请把标签固定为 :149、:150 或 :151。

Python 和 Node：serve()

serve() 会用 SDK 的启动设置（身份画像、代理、默认值）启动 Clearcote，在回环地址上开放一个 CDP 端点，并返回一个带有该端点 URL 的句柄。如果其他代码还在使用旧地址，请传入 port=9222；不传时，serve() 会自动选择一个空闲端口。

# 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() 会停止浏览器、等待其退出，并删除 serve() 创建的临时 profile；在 Python 中，with 代码块会替你调用它。对于 browser-use、Crawl4AI 或 Stagehand，把它们的 CDP 设置设为 srv.cdp_url（Node：srv.cdpUrl）即可。.NET SDK 中对应的调用是 ServeAsync。更多内容参见Puppeteer 及其他 CDP 客户端。

Docker

换掉镜像，保留端口。客户端连接的仍是原来的地址。

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 让端点只在本机可用：CDP 端口意味着对浏览器的完全控制，所以只应将其发布到你信任的网络。设置 CC_FINGERPRINT 可以选择或复用某个身份：不设置时，sdk-0.39.0 及之后的镜像会为每个容器分配各自的随机种子，更早的镜像则让所有容器共用同一个。镜像完全通过环境变量（平台、语言、时区、代理）配置，完整列表见部署。

在命令行中：clearcote serve

如果你之前是自己启动二进制文件或 tilion 启动器，再让客户端连接 9222 端口，那么 clearcote serve（包含在 Python 和 Node 包中）就是对应的常驻替代方案。不带参数的连接会获得一个共享的默认浏览器，所以现有客户端无需改动即可使用；连接也可以在 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

有哪些不同

身份来自种子。在 BSD 版本中，Fortress 的启动器会套用一个前后一致的默认 Windows 身份画像，你可以用 --uxr-* 开关（--uxr-timezone、--uxr-languages、--uxr-screen-width、--uxr-canvas-seed 等）或 TILION_TZ / TILION_LANG 逐项修改它。Clearcote 则从一个 fingerprint 种子（seed）派生整个身份画像，包括按站点区分的 canvas 和 WebGL 噪声，因此同一个种子每次都给出同一个身份，换一个新种子则得到一个毫不相关的身份。请给每个账号分配各自的种子，而不是把 --uxr-* 的值逐个搬过来；用 platform 设置平台，用 timezone 和 accept_language（Node：acceptLanguage）设置时区和语言，或者让 geoip 根据代理自动匹配它们。参见推荐设置。
在被服务的 profile 中打开页面。像示例中那样使用 browser.contexts[0]。使用 Puppeteer 时，连接时传入 defaultViewport: null，让窗口保持身份画像给定的尺寸。
把代理交给 Clearcote，而不是客户端。给 serve() 传入 proxy，或给 clearcote serve 传入 --proxy，并开启 geoip，让时区、语言和 WebRTC 地址与出口一致。带用户名和密码的代理需要最新构建；在开源版构建上，请使用按 IP 授权的代理。参见代理与 geoip。
Fortress 自己的启动开关和环境变量在这里不起作用。Clearcote 的选项见启动选项和指纹参数。
拟人化输入是 launch() 的选项。它在 Playwright 一侧运行，因此不适用于通过 CDP 接入的客户端。
支持的平台与 BSD 版本相同：Windows x64 和 Linux x64，Docker 镜像为 x64。

你会得到哪个 Clearcote 构建

没有许可证密钥时，SDK 和镜像运行的是开源版构建：BSD-3 许可，每个补丁都公开且可复现，基于 Chromium 150，无需账号。有密钥时，它们运行最新构建（Chromium 154），其中另含私有补丁：凭 GitHub 可免费使用，同一时间运行一个浏览器；需要更多时选择 Pro。用 clearcote login 保存密钥，或设置 CLEARCOTE_LICENSE_KEY；参见安装。

检查切换结果

端点运行起来后，直接问它是什么：

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 会打印它解析出的构建标签，以及带有确切浏览器版本的 Launch test ok。安装手册列出了每个构建应报告的版本，以及检查失败时该怎么做。