使用 Cap Checkpoint 中间件为 Elysia 应用接入自托管工作量证明 CAPTCHA-平芜编程栈

网络安全
应用安全
后端

【免费下载链接】cap

Free, open-source and self-hosted CAPTCHA alternative to reCAPTCHA. Privacy-first and powered by proof-of-work and instrumentation challenges.

项目地址：https://gitcode.com/gh_mirrors/cap13/cap

点击查看免费下载

Cap 的 Checkpoint（官方中间件）能够在你的 Elysia 应用前复刻 Cloudflare 式的"浏览器检查"过渡页：在机器人、LLM 与自动化滥用真正到达你的路由之前，先通过自托管、开源的工作量证明（Proof-of-Work）CAPTCHA 完成验证。读完本文你将掌握@cap.js/middleware-elysia的安装方式、完整配置参数含义，以及如何用几行代码把整个 Elysia 应用保护起来，并了解中间件背后的验证流程与仓库实现细节。

Checkpoint 是什么

Checkpoint 此前被称为"中间件"，是 Cap 提供的服务端保护方案。它像 Cloudflare 一样在访问者与你的业务路由之间插入一个浏览器检查过渡页，访问者必须先通过验证，才能继续访问后面的内容。与 Cap Standalone（自托管后端 + 控制台）不同，Checkpoint 直接嵌入你的应用进程，只需在服务器上加几行代码，无需把整个网站迁移到任何第三方 CDN。

需要注意，这是一种"核弹级"方案：它会拦截所有未经验证的访问，因此也会影响搜索引擎爬虫等善意的机器人。如果你希望精确控制放行对象，应优先考虑独立的验证组件方案；如果你只想挡住绝大多数自动化流量，Checkpoint 是最快的方式。

安装

Elysia 生态基于 Bun 运行，中间件同样推荐使用bun安装依赖：

bun add elysia @cap.js/middleware-elysia

其中elysia是你的 Web 框架本体，@cap.js/middleware-elysia是 Cap 官方的 Elysia 中间件包。

安装完成后，你的应用需要一个验证组件（widget）或隐藏求解器，并且必须指向/__cap_clearanceURL——这是中间件内置的验证交接端点。你可以把仓库 docs/public/checkpoints_screenshot.webp 对应的过渡页流程作为参考来设计自己的验证模板。

基本用法

将中间件挂载到 Elysia 实例上即可保护全部路由：

import { Elysia, file } from "elysia"; import { capMiddleware } from "@cap.js/middleware-elysia"; new Elysia() .use( capMiddleware({ token_validity_hours: 32, // 令牌有效时长 tokens_store_path: ".data/tokensList.json", token_size: 16, // 令牌大小（字节） verification_template_path: join(dirname(fileURLToPath(import.meta.url)), "./index.html"), scoping: "scoped", // 'global' | 'scoped' }), ) .get("/", () => "Hello Elysia!") .listen(3000);

原文档示例中Elysia的导入里包含file，但示例代码并未使用它——你可以按需引入，实际只需要Elysia和capMiddleware即可。

启动后访问http://localhost:3000，未持有有效令牌的请求会先看到验证过渡页，通过工作量证明验证后获得令牌，后续请求即可正常进入GET /返回 "Hello Elysia!"。

配置参数详解

capMiddleware接受一个配置对象，各参数含义如下：

参数	默认语义	说明
`token_validity_hours`	32	验证通过后签发的令牌有效时长（小时）。令牌过期后访问者需要重新验证。
`tokens_store_path`	`.data/tokensList.json`	已签发令牌的持久化存储文件路径。中间件将令牌列表写入该 JSON 文件，服务重启后令牌仍然有效。
`token_size`	16	令牌的字节长度。数值越大令牌越难被暴力枚举，同时存储占用也越大。
`verification_template_path`	无	验证过渡页 HTML 模板的绝对路径。模板中只需包含一个指向`/__cap_clearance`的验证组件或隐藏求解器。
`scoping`	`"scoped"`	令牌作用域策略，可选`'global'`或`'scoped'`。`'scoped'`下令牌与特定请求上下文（如站点/域名）绑定，更安全；`'global'`下令牌在全局范围通用。

其中scoping是 Cap 体系中反复出现的安全概念：仓库在 standalone/test/scoped-keys.test.js 中同样测试了 scoped 站点密钥的隔离行为，说明"作用域隔离"是贯穿 Cap 各组件的一致设计。生产环境建议保持'scoped'，避免令牌被跨站点复用。

verification_template_path使用join(dirname(fileURLToPath(import.meta.url)), "./index.html")计算，这样无论从哪个目录启动服务，都能正确解析到与入口文件同级的index.html——注意这是 ESM 场景下替代__dirname的标准写法。

中间件的验证流程

从仓库实现看，Cap 的挑战验证遵循"挑战—兑换—令牌"三段式流程，中间件的/__cap_clearance端点与 Cap 后端共享同一套设计：

访问者请求被中间件拦截，未持有有效令牌则返回verification_template_path指定的过渡页；
页面中的验证组件向/__cap_clearance发起挑战请求，服务端生成工作量证明挑战；
客户端在浏览器中完成工作量证明求解，提交解决方案（solutions）；
服务端校验解决方案，成功后签发令牌，并写入tokens_store_path指定的存储文件；
之后携带该令牌的请求被中间件放行，直到令牌超过token_validity_hours过期。

这一流程与 standalone/src/cap.js 中POST /:siteKey/challenge（生成挑战）与POST /:siteKey/redeem（兑换令牌，含防重放 nonce 消费、过期与作用域校验）的职责划分一致：挑战只负责"给出问题"，兑换才负责"校验答案并签发令牌"。中间件把这两个环节封装在/__cap_clearance一个端点内，并对业务路由透明。

从代码结构看，仓库的 standalone/src/server.js 本身就是用 Elysia 构建的管理控制台（new Elysia({ prefix: "/server", ... })，并通过onBeforeHandle实现认证与作用域守卫），这从侧面验证了 Elysia 生态下编写、测试和部署这类中间件/服务是 Cap 项目实际采用的工程路径。

与其他框架中间件对比

Cap 提供了一组同构的框架中间件，配置模式几乎一致，迁移成本极低：

Express：使用@cap.js/checkpoint-express，配合cookie-parser解析令牌，见 Express Checkpoint；
Hono：使用@cap.js/checkpoint-hono，通过app.use("*", capCheckpoint({...}))全局挂载，见 Hono Checkpoint；
Elysia：即本文的@cap.js/middleware-elysia，通过.use(capMiddleware({...}))挂载。

三者共享token_validity_hours、tokens_store_path、token_size、verification_template_path等核心参数，唯一的差异是 Express 需要显式引入cookie-parser。如果你在 Bun 生态中同时使用 Elysia 与 Hono，选择哪个中间件取决于你的路由框架，验证逻辑本身保持一致。