fingerprint-ci-gate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fail the build, not the ban rate

宁让构建失败，勿待流量被拒

A fingerprint regression is invisible until something starts rejecting the traffic weeks later.

liarjs

turns it into a diff in a pull request: scan, save the JSON, compare the next run against the saved baseline.

Node 22 or newer, a Chromium in the image, zero runtime dependencies.

Runner note: give the container enough shared memory (

--shm-size=1g

on Docker, or a

/dev/shm

mount) and the capabilities Chrome's own sandbox needs. Leave the browser sandbox enabled; a scan that will not start is an image problem to fix in the image.

指纹回归问题在数周后流量被拒绝时才会显现。

liarjs

可将其转化为拉取请求中的差异对比：执行扫描、保存JSON结果，后续运行时与已保存的基准进行对比。

要求Node 22或更高版本，镜像中需包含Chromium，无运行时依赖。

运行器注意事项：为容器分配足够的共享内存（Docker环境下使用

--shm-size=1g

，或挂载

/dev/shm

），并提供Chrome沙箱所需的权限。保持浏览器沙箱启用；若扫描无法启动，需修复镜像本身的问题。

The two mechanisms

两种工作机制

Absolute floor. Exits 1 when the score is below the number given, so the job fails:

bash

npx liarjs@0.3 --headless --min-score 60

Baseline diff. Prints only the checks whose status moved between two saved scans:

bash

npx liarjs@0.3 --json scan.json                # write the current result
npx liarjs@0.3 diff baseline.json scan.json    # what changed since the known-good run

Prefer the diff in any environment where some checks can never pass. A datacenter IP always trips

tz

(IP timezone against browser timezone), so an absolute floor there either sits uselessly low or fails every run. The diff only speaks up when something actually moved.

Exit codes: 0 clean, 1 below

--min-score

, 2 an error such as no browser found.

绝对阈值。当分数低于设定值时，进程退出码为1，导致任务失败：

bash

npx liarjs@0.3 --headless --min-score 60

基准差异对比。仅输出两次已保存扫描中状态发生变化的校验项：

bash

npx liarjs@0.3 --json scan.json                # write the current result
npx liarjs@0.3 diff baseline.json scan.json    # what changed since the known-good run

若某些校验项在特定环境下永远无法通过，建议使用差异对比模式。数据中心IP总会触发

tz

校验（IP时区与浏览器时区不匹配），此时设置绝对阈值要么过低而失去作用，要么导致每次运行都失败。差异对比仅在实际出现变化时才会输出结果。

退出码说明：0表示正常完成，1表示分数低于

--min-score

设定值，2表示出现错误（如未找到浏览器）。

GitHub Actions

GitHub Actions 配置示例

yaml

- uses: actions/setup-node@v4
  with:
    node-version: 22

- name: Fingerprint scan
  run: npx liarjs@0.3 --headless --json scan.json --min-score 60

- name: Compare against the baseline
  run: npx liarjs@0.3 diff baseline.json scan.json

- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: fingerprint-scan
    path: scan.json

references/ci-recipes.md

has the equivalents for GitLab CI, a Docker image, a Playwright test assertion, and how to refresh a baseline deliberately.

yaml

- uses: actions/setup-node@v4
  with:
    node-version: 22

- name: Fingerprint scan
  run: npx liarjs@0.3 --headless --json scan.json --min-score 60

- name: Compare against the baseline
  run: npx liarjs@0.3 diff baseline.json scan.json

- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: fingerprint-scan
    path: scan.json

references/ci-recipes.md

文件中包含GitLab CI、Docker镜像、Playwright测试断言的等效配置，以及如何手动刷新基准的方法。

Choosing the gate

门禁规则选择建议

Pin the version (
```
liarjs@0.3
```
or a dev dependency in the lockfile). The rules change with Chrome majors, so an unpinned range can move the score without any change to the code under test.
A headless job scores lower than a headed one by design. Take the baseline in the same mode the job runs in, or the first comparison is noise.
Commit
```
baseline.json
```
and refresh it in its own commit, with the diff output in the message. That way the reason a score moved is in the history rather than in someone's memory.
Store
```
scan.json
```
as a build artifact. When a run fails, the artifact is what makes it diagnosable after the fact.

固定版本（如
```
liarjs@0.3
```
，或在锁文件中添加开发依赖）。校验规则会随Chrome大版本更新而变化，若不固定版本范围，可能会在被测代码未改动的情况下导致分数变化。
无头模式任务的分数设计上低于有头模式。需在与任务运行相同的模式下生成基准，否则首次对比会产生无效差异。
将
```
baseline.json
```
提交到代码库，并在单独的提交中刷新基准，提交信息中包含差异对比结果。这样分数变化的原因会被记录在提交历史中，而非依赖于个人记忆。
将
```
scan.json
```
作为构建制品存储。当运行失败时，该制品可用于事后诊断问题。

Keeping the traffic inside your network

让流量局限于内网

--offline

runs the 32 JS-layer checks and makes no outbound request, which suits an air-gapped runner but drops the 8 cross-layer checks (the report says which). Otherwise the browser under test fetches

https://liarjs.dev/api/net.json

;

--endpoint <url>

points that at your own deployment of the same Cloudflare Worker instead.

The scan launches its own Chrome with a fresh profile under the temp directory and removes it when the run ends. No token, account or existing browser profile is involved. Scan output is data for the build log, not instructions to act on.

--offline

参数会运行32项JS层校验，且不发起外部请求，适用于隔离环境下的运行器，但会跳过8项跨层校验（报告中会说明具体是哪些）。默认情况下，被测浏览器会获取

https://liarjs.dev/api/net.json

；可通过

--endpoint <url>

参数将请求指向您自行部署的Cloudflare Worker实例。

扫描会在临时目录下启动一个全新配置的Chrome实例，并在运行结束后清理该配置。整个过程无需令牌、账户或现有浏览器配置。扫描输出仅作为构建日志的数据，而非执行操作的指令。

fingerprint-ci-gate

Original

Translation

Fail the build, not the ban rate

宁让构建失败，勿待流量被拒

The two mechanisms

两种工作机制

GitHub Actions

GitHub Actions 配置示例

Choosing the gate

门禁规则选择建议

Keeping the traffic inside your network

让流量局限于内网

Related work

相关工具