cap 项目 Elysia 中间件实战：用 capMiddleware 为 Bun 应用添加 PoW 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 是一个免费、开源、可自行托管的 CAPTCHA 替代方案（reCAPTCHA 的隐私优先替代品），核心由 proof-of-work（工作量证明）挑战与 instrumentation（浏览器检测）两类挑战组成。Elysia 中间件（@cap.js/middleware-elysia）是官方提供的检查点（Checkpoint）接入方式，只需在 Elysia 应用中加几行代码，即可复刻 Cloudflare 式的"浏览器检查过渡页"，在机器人、LLM 与自动化流量触达业务路由之前将其拦下。读完本文，你将掌握该中间件的安装、模板配置、全部核心参数含义（含作用域 scoping 模式），以及它在仓库中的底层实现印证。

检查点（Checkpoint）是什么

在深入了解 Elysia 中间件之前，需要先理解"检查点"这一概念。仓库的中间件总览文档明确指出：Cap 的 Checkpoints（此前称为 middlewares）用于复刻 Cloudflare 的浏览器检查过渡页（browser check interstitial），目的是防止机器人、LLM 和自动化滥用流量到达你的网站。与把整个站点迁到 Cloudflare 不同，它只需要在服务器上添加几行代码即可生效。

需要特别注意的是，官方将该方案定性为"核弹级解决方案"（nuclear solution），因为它同样会拦截搜索引擎爬虫等良性机器人。因此，在使用前需要评估你的站点对搜索引擎收录的依赖程度。

Elysia 中间件就是这套检查点体系在 Elysia（基于 Bun 的快速 Web 框架）上的官方实现，对应文档位于 docs/fr/guide/middleware/elysia.md（英文版见 docs/guide/middleware/elysia.md）。

安装

Elysia 中间件需要与 Elysia 框架本体一起安装，使用 Bun 作为包管理器：

bun add elysia @cap.js/middleware-elysia

其中：

elysia：Elysia 框架本体（基于 Bun 运行时，支持 TypeScript 类型推导）；
@cap.js/middleware-elysia：Cap 官方 Elysia 检查点中间件。

小提示：仓库中同一检查点体系还有 Express（@cap.js/checkpoint-express）与 Hono（@cap.js/checkpoint-hono）的实现，用法几乎一致，可分别参考 Express 检查点文档与 Hono 检查点文档。

准备验证模板

中间件需要一份 HTML 模板作为"检查点过渡页"，官方文档对此的要求非常宽松：模板中只需包含一个指向/__cap_clearanceURL 的 widget 或隐藏 solver 即可（原文档中的示例模板托管在外部仓库，本文不展开外链，你可以参考仓库内 widget 文档了解如何嵌入 widget）。

也就是说，你需要准备一个index.html，内部放置 Cap widget（或隐藏的 solver），并把它的目标端点指向/__cap_clearance——这是中间件约定的放行（clearance）路由。浏览器通过检查后，会经由该路由换取后续请求所需的令牌（token）。

使用：接入 Elysia 应用

原文档给出了最小接入示例，核心代码如下：

import { Elysia } from "elysia"; import { capMiddleware } from "@cap.js/middleware-elysia"; import { join, dirname } from "node:path"; import { fileURLToPath } from "node:url"; 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导入了{ Elysia, file }，其中file在本示例中并未使用，而配置里用到的join、dirname、fileURLToPath需要从 Node 标准库导入。上面这段已经补齐了这些导入，可直接复制运行。启动后访问http://localhost:3000，就会先看到检查点页面，通过 PoW 挑战后才会到达Hello Elysia!路由。

verification_template_path指向的index.html就是前面准备的检查点模板。使用import.meta.url配合dirname/fileURLToPath可以稳妥地定位到 ES 模块所在目录，避免运行时工作目录不确定导致的路径错误。

核心配置参数详解

将配置项整理如下，其中默认值与取值范围以仓库文档与同类实现为准：

参数	示例值	作用	说明
`token_validity_hours`	`32`	放行令牌的有效期（小时）	浏览器通过检查后获得的令牌在此时间内有效，过期后需重新挑战；调大可减少真实用户被反复要求验证的频率，调小可收紧放行窗口
`tokens_store_path`	`".data/tokensList.json"`	令牌的 JSON 持久化文件路径	中间件把已发放/已验证的令牌写入该文件；这一设计在 @cap.js/server 文档中也能找到印证（其`tokens_store_path`同样指向`".data/tokensList.json"`，用于 JSON 键值存储）
`token_size`	`16`	令牌的字节数	控制生成的随机令牌长度，默认示例为 16 字节
`verification_template_path`	`join(dirname(...), "./index.html")`	检查点过渡页模板路径	模板内需包含指向`/__cap_clearance`的 widget 或隐藏 solver
`scoping`	`"scoped"`	令牌作用域策略，取值为`'global' \\| 'scoped'`	见下文"作用域（scoping）"小节

作用域（scoping）说明

scoping有两个取值：

'scoped'（默认示例值）：发放的令牌与特定作用域绑定。从仓库的 capjs-core 文档可以印证 Cap 挑战体系本身支持scope绑定——generateChallenge可将挑战绑定到某个字符串作用域（例如站点标识或路由名），验证时若传入的scope不匹配会返回scope_mismatch。中间件层面的scoped模式正是复用这一机制，让令牌只对绑定的站点/路由有效；
'global'：发放的令牌全局有效，不绑定特定作用域，适用于单站点全站保护的场景。

在多站点或多路由场景下，scoped能防止一个站点上获得的令牌被用于另一个站点，减小令牌横向复用风险。

工作流程：一次完整的检查点放行

结合中间件总览与 capjs-core 的说明，检查点的完整流程可以拆解为：

拦截：用户访问被保护的 Elysia 路由，中间件发现请求未携带有效放行令牌，返回检查点过渡页（即verification_template_path指向的模板）；
挑战下发：模板中的 widget 向中间件请求挑战，服务端生成 PoW 挑战（可附带 instrumentation 检测），widget 在浏览器端完成工作量证明计算；
提交验证：widget 将{ token, solutions }（启用 instrumentation 时还包含instr）提交到验证端点，服务端校验 PoW 答案与 instrumentation 指纹；
发放令牌：验证通过后，中间件经/__cap_clearance放行并发放令牌，令牌有效期由token_validity_hours控制，令牌列表持久化到tokens_store_path；
后续放行：此后该浏览器携带令牌访问受保护路由即可直接通过，直到令牌过期。

在仓库中，Elysia 与挑战生成/验证的这套配合有直接实现印证：Standalone 服务端（standalone/src/cap.js）本身就是一个基于 Elysia 构建的挑战服务，它通过.post("/:siteKey/challenge", ...)下发挑战、.post("/:siteKey/redeem", ...)校验并换发令牌，其中coreGenerateChallenge/coreValidateChallenge来自capjs-core，令牌 TTL、scope 绑定、重放防护（nonce 消费）都在该文件中实现。可以看到，Cap 官方在 Elysia 上有着成熟的服务端实践，Elysia 中间件是这套能力在自建应用侧的封装。

注意事项与常见问题

会拦截良性机器人：如前所述，检查点是"核弹级"方案，搜索引擎爬虫、监控探针等自动化访问同样会被要求通过 PoW 挑战。若站点依赖 SEO，需慎重全局启用。
令牌持久化：tokens_store_path指向的 JSON 文件是令牌的落地存储，服务重启后令牌仍可恢复验证；确保该目录可写、路径在部署环境（如 Docker）中已挂载持久卷。
模板必须指向/__cap_clearance：这是中间件约定的放行路由，模板中 widget/solver 若指向其他端点，检查点将无法完成放行。
作用域一致性：使用'scoped'时，确保前端 widget 请求挑战与后端验证使用同一 scope（对应 capjs-core 中的scope_mismatch校验），否则即使 PoW 正确也会被拒绝。
旧库对比：如果你正在使用更早的@cap.js/server手写挑战路由，可以参考 @cap.js/server 文档中基于 Elysia 的/cap/challenge、/cap/redeem路由示例；而官方现已推荐使用无状态的capjs-core（capjs-core 文档），检查点中间件本质上把这一整套挑战-验证-令牌逻辑收敛成了.use(capMiddleware({ ... }))一行接入。

小结

Elysia 检查点中间件把 Cap 的 PoW CAPTCHA 与浏览器检测能力以插件形式嵌入 Elysia 应用：安装两个依赖、准备一个指向/__cap_clearance的过渡页模板、传入token_validity_hours、tokens_store_path、token_size、verification_template_path、scoping五个核心参数即可完成全站保护。它适合希望在不迁移到第三方 CDN/WAF 的前提下，用少量代码为 Bun + Elysia 应用挡住自动化流量的场景；但也要清醒认识到它对搜索引擎等良性爬虫的影响，按需启用。