为 Express 添加 Cap Checkpoint：使用 @cap.js/checkpoint-express 以自托管工作量证明 CAPTCHA 保护路由

• 网络安全
• 应用安全
• 后端

本文是一份面向 Node.js / Bun 开发者的实战指南，讲解如何通过官方中间件@cap.js/checkpoint-express为 Express 应用接入 Cap Checkpoint——一种复刻 Cloudflare 浏览器检查过渡页的自托管、开源防护方案。文中会覆盖安装命令、完整的中间件接入代码、全部配置选项的语义解析，以及质询令牌如何在后端完成校验的完整链路。读完本文，你将能够在一个 Express 应用中独立部署并验证这套工作量证明（Proof-of-Work）CAPTCHA 与浏览器环境检查机制。

Cap Checkpoint：一种“核弹级”的入口防护方案

在接入 Express 之前，先理解 Checkpoint 在整个 Cap 体系中的定位。根据 Cap 官方文档 docs/zh/guide/middleware/index.md 的说明，Cap Checkpoint（此前称为中间件）用于复刻 Cloudflare 的浏览器检查过渡页，在机器人、LLM 与自动化滥用到达你的网站之前就将其拦截。

它有几个鲜明的特点：

• 部署成本低：只需在服务器上添加几行代码，无需把整个网站迁移到 Cloudflare；
• 拦截能力强：它属于“核弹级”方案，因为除了恶意机器人之外，它也会影响搜索引擎爬虫等善意的机器人，接入前需要评估你的业务对爬虫流量的依赖；
• 防护类型：工作量证明（Proof-of-Work）CAPTCHA + 浏览器环境检查（instrumentation），后者可显著提高机器人的作弊门槛。

Cap 生态为多种服务端框架提供了同构的官方中间件包，Express 对应的是@cap.js/checkpoint-express，此外还有 Hono（@cap.js/checkpoint-hono，见 docs/zh/guide/middleware/hono.md）与 Elysia（@cap.js/middleware-elysia，见 docs/zh/guide/middleware/elysia.md）。它们共享同一套参数设计，本文对配置选项的讲解同样适用于其他框架。

安装依赖

在项目目录下运行：

bun add express cookie-parser @cap.js/checkpoint-express

这条命令会安装三个包：

说明：文档给出的包管理器是Bun（仓库整体也基于 Bun 生态构建，例如 core/package.json 与 standalone/package.json 均使用 Bun 管理）。如果你使用 npm / pnpm，请自行替换为对应的npm i/pnpm i命令。

快速开始：为 Express 应用接入 Checkpoint

以下是从官方文档 docs/zh/guide/middleware/express.md 继承的完整示例。它演示了如何用中间件保护全部路由，只有通过质询的客户端才能继续访问受保护内容：

import express from "express"; import cookieParser from "cookie-parser"; import path from "path"; import { dirname } from "path"; import { fileURLToPath } from "url"; import { capCheckpoint } from "@cap.js/checkpoint-express"; const app = express(); const __dirname = dirname(fileURLToPath(import.meta.url)); app.use(express.json()); app.use(cookieParser()); app.use( capCheckpoint({ /* token_validity_hours: 32, tokens_store_path: ".data/tokensList.json", token_size: 16, verification_template_path: join(__dirname, "./index.html"), */ }), ); app.get("/", (req, res) => { res.sendFile(path.join(__dirname, "success.html")); }); app.listen(3000, () => { console.log(`Server running on http://localhost:3000`); });

代码要点：

• cookieParser()必须在capCheckpoint(...)之前注册，因为质询通过后的令牌状态依赖 Cookie 传递；
• capCheckpoint({...})以全局中间件形式挂载，因此会拦截其之后注册的全部路由——示例中/路由返回的success.html只有通过质询的客户端才能看到；
• 示例中的配置对象全部处于注释状态，此时使用默认配置即可直接运行。

就是这么简单。运行后打开http://localhost:3000，未通过质询的访问会被引导到浏览器检查过渡页，完成工作量证明与浏览器环境检查后，才会看到你的真实页面。

配置选项详解

示例注释中展示的四个选项是这套中间件的核心参数，其语义可由官方文档与仓库内其他框架文档（docs/zh/guide/middleware/hono.md、docs/zh/guide/middleware/elysia.md）交叉印证：

完整启用全部自定义配置的写法如下：

import { join } from "path"; app.use( capCheckpoint({ token_validity_hours: 32, // 令牌有效时长（小时） tokens_store_path: ".data/tokensList.json", // 令牌列表存储文件 token_size: 16, // 令牌大小（字节） verification_template_path: join(__dirname, "./index.html"), // 质询过渡页模板 }), );

验证模板与/__cap_clearance

verification_template_path指向的 HTML 模板是 Checkpoint 的核心 UI。从 docs/zh/guide/middleware/elysia.md 的说明可以确认：模板中只需包含一个指向/__cap_clearanceURL 的验证组件（<cap-widget>）或隐藏求解器，Checkpoint 中间件会在该 URL 上完成质询的签发、校验与放行逻辑。

也就是说，你不需要在模板里手写任何质询协议逻辑，只需要：

1. 引入 Cap 验证组件（Widget）的脚本；
2. 在模板中放置一个<cap-widget>元素（或隐藏求解器）；
3. 让验证组件指向/__cap_clearance，中间件会自动接管后续流程。

验证组件（Widget）的完整用法可参考 docs/zh/guide/widget.md。

令牌如何被校验：从质询通过到放行

要真正理解这套中间件的安全性，需要知道质询通过之后发生了什么。Cap 生态的校验链路在服务端源码中有清晰的实现，以 standalone/src/siteverify.js 为例（@cap.js/checkpoint-express与 Cap Standalone 后端共享相同的令牌校验语义），可以归纳出以下关键环节：

1. 令牌格式。站点验证时，response（客户端提交的令牌）必须能被:分隔成三段（见 standalone/src/siteverify.js），第一段是站点密钥。格式不合法会直接返回400。

2. 站点密钥与秘密密钥校验。服务端根据站点密钥查找对应的secretHash（哈希存储，不保存明文），通过 standalone/src/secret-hash.js 中的verifySecret校验提交的secret，不匹配返回403。

3. 令牌的一次性消费与过期。服务端使用GETDEL语义（standalone/src/siteverify.js）读取并删除令牌：令牌必须存在（否则404）、必须未过期（否则403），并且每个令牌只能被成功验证一次，防止重放攻击。

4. 成功响应。全部校验通过后返回{ "success": true }。

因此，无论使用哪个接入方式（Checkpoint 中间件或直接对接 Standalone），你的后端都永远不要信任客户端传来的未经验证的令牌——必须先经过上述校验流程，才能认为该请求来自已通过质询的真实浏览器。

与 Cap Standalone 后端配合：完整的生产部署形态

@cap.js/checkpoint-express解决的是“入口拦截”这一层，而质询本身的签发、令牌的最终校验则依赖一个 Cap 服务端。官方推荐的部署方式是Cap Standalone，详见 docs/zh/guide/standalone/index.md：

• 它运行在 Bun 上，空闲内存占用约 50 MB，内置 instrumentation（浏览器环境检测）质询，并提供兼容 reCAPTCHA 的siteverifyAPI 与一个管理站点密钥的 Web 控制台；
• 推荐用 Docker Compose 一键启动（镜像tiago2/cap:latest，搭配 Valkey/Redis 存储），随后在控制台创建站点密钥，记下站点密钥（site key）与秘密密钥（secret key）；
• 客户端验证组件通过data-cap-api-endpoint="https://<instance_url>/<site_key>/"指向你的实例（docs/zh/guide/standalone/index.md）；
• 用户完成 CAPTCHA 后，后端向<instance_url>/<site_key>/siteverify发送POST { "secret": ..., "response": ... }验证令牌（docs/zh/guide/standalone/index.md）。

在生产环境中，将 Checkpoint 的验证模板指向你的 Standalone 实例即可形成完整闭环：Express 入口拦截 → 质询过渡页 → Cap Standalone 签发与校验 → 放行受保护路由。部署时还需注意：

• Standalone 实例必须能从公网访问，验证组件才能与它通信；
• 如果部署在反向代理后面，请按 docs/zh/guide/standalone/options.md 中的说明配置速率限制与客户端 IP 识别（X-Forwarded-For/X-Real-IP等头）；
• /siteverify端点默认不做速率限制，因为它面向服务器间调用（docs/zh/guide/standalone/options.md）。

注意事项与适用前提

• 环境要求：官方文档以 Bun 为包管理器与运行环境；仓库整体基于 Bun 构建，建议在 Bun 运行时下使用，以获得与文档一致的行为。
• 影响搜索引擎爬虫：如前文所述，Checkpoint 会拦截所有未通过质询的客户端，包括善意爬虫。如果 SEO 对你的业务至关重要，需要谨慎评估或只在敏感路由上启用。
• 默认配置即可运行：不传任何配置时，中间件使用内置默认值（令牌有效期 32 小时、令牌大小 16 字节、默认存储路径），适合快速验证；正式上线前再显式配置verification_template_path与持久化路径。

小结

接入 Cap Checkpoint 到 Express 只需要三步：安装@cap.js/checkpoint-express、在cookieParser之后挂载capCheckpoint中间件、准备一个指向/__cap_clearance的验证模板。再结合 Cap Standalone 完成质询签发与siteverify校验，你就在完全自托管、开源的条件下，为自己的 Express 应用建立了一道复刻 Cloudflare 风格的浏览器检查防线——不依赖任何第三方闭源验证码服务。

• 网络安全
• 应用安全
• 后端