企业官网建设流程全解析

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

本篇技术指南讲解如何为基于 Bun 的 Elysia 应用接入官方中间件@cap.js/middleware-elysia，用几行代码在路由前加装 Cap Checkpoint 浏览器验证关卡，让所有请求先通过自托管、开源的工作量证明（proof-of-work）CAPTCHA 验证。读完本文你将掌握完整安装步骤、全部中间件配置参数、验证模板（widget / hidden solver）的接入要求，并通过阅读仓库中验证服务端源码，理解 token 签发、挑战生成与兑换的底层机制。

Checkpoint 是什么

Cap 的 Checkpoint（此前称为 middleware）旨在复刻 Cloudflare 的浏览器检查中间页：在请求真正到达你的网站之前，先对访客执行一次浏览器能力与工作量证明验证，从而拦截机器人、自动化脚本和大规模滥用流量。相比把整个站点迁移到 Cloudflare，这种方式只需在你的服务器代码里增加几行配置，即可为指定的 Elysia 路由加上一道验证关卡。

需要说明的是，这是一种"核弹级"方案——它会同时影响良性爬虫（如搜索引擎爬虫），部署前请评估你的流量构成。关于 Checkpoint 的整体设计思路，可参考 checkpoints 总览。

安装

在 Elysia 项目中使用 Bun 安装依赖：

bun add elysia @cap.js/middleware-elysia

安装完成后，你还需要准备一份验证模板（HTML 文件）。模板只需包含一个指向/__cap_clearanceURL 的 widget 或隐藏 solver（hidden solver），用于在浏览器侧完成挑战求解并将结果回传到该路径。整个验证流程与模板无关，模板本身可以非常精简。

最小可用示例

以下代码创建一个 Elysia 实例，挂载capMiddleware后对外提供根路由：

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

将verification_template_path指向你准备好的验证模板后，这段代码即可直接运行。listen(3000)启动服务后，所有经过中间件的路由都会先执行浏览器验证。

配置参数详解

capMiddleware接受以下选项：

关于verification_template_path，示例中通过import.meta.url动态获取当前模块目录，再join出模板路径，这样可以避免硬编码绝对路径带来的部署迁移问题。

scoping 的作用

scoping控制 token 的适用范围：

• 'global'：一次验证通过后，放行 token 全局生效，所有受保护路由共享同一份验证结果，适合整站统一的验证入口；
• 'scoped'：token 仅对特定作用域（如某个站点 key 或路由范围）生效，隔离性更强，适合多租户或分区保护场景。

从服务端源码可以印证"作用域"这一概念贯穿挑战全流程：在 standalone/src/cap.js 中，生成挑战时会把scope设为站点 key（scope: params.siteKey），兑换验证时也会携带scope进行匹配；若不匹配，服务端返回"Challenge token does not match site key"（见 cap.js）。也就是说，scoped token 在服务端是与具体站点 key 绑定的，无法跨作用域复用。

验证流程背后的服务端机制

虽然中间件本身"开箱即用"，理解其背后的服务端流程有助于调优与排障。Cap 的验证服务（capServer，同样基于 Elysia 构建，见 standalone/src/cap.js）核心包含两个阶段：

1. 挑战生成（challenge）

客户端向POST /:siteKey/challenge发起请求，服务端会依次执行：

1. 校验站点 key 是否存在（不存在返回 404，见 cap.js）；
2. 检查客户端 IP 是否命中封禁规则（返回 403，见 cap.js）；
3. 可选的非浏览器 UA 拦截与必需请求头校验（见 cap.js）；
4. 根据配置的协议（hashwx/rsw/sha256-pow）调用capjs-core的generateChallenge生成挑战（见 cap.js）。

挑战本身带有 15 分钟 TTL（CHALLENGE_TTL_MS = 15 * 60 * 1000，见 cap.js），过期后客户端需要重新获取挑战。

2. 挑战兑换与 token 签发（redeem）

浏览器求解完成后，向POST /:siteKey/redeem提交 token 与 solutions（见 cap.js），服务端调用capjs-core的validateChallenge进行校验：

• 校验失败会根据原因返回 400/403/429 等状态码并计入失败指标，常见原因包括missing_token、expired、scope_mismatch、already_redeemed、invalid_solution以及各类 instrumentation 拦截（见 cap.js）；
• 校验成功后签发 redeem token（randomBytes(8).toString("hex")组成的siteKey:redeemId:redeemSecret结构，见 cap.js），默认 TTL 为 2 小时（TOKEN_TTL_MS = 2 * 60 * 60 * 1000，见 cap.js）。

这个 2 小时的默认 token TTL 与中间件配置里的token_validity_hours概念对应——前者是服务端默认值，后者是你在中间件里可以显式控制的放行时长，二者共同决定了用户"一次验证、多次放行"的体验窗口。

验证模板的接入要求

verification_template_path指向的 HTML 是浏览器侧验证的入口，接入要求只有一个关键点：模板中必须包含一个指向/__cap_clearanceURL 的 widget 或隐藏 solver。widget 负责展示挑战交互界面，hidden solver 则在后台静默完成证明求解。两者任选其一即可，模板的其他内容（品牌信息、样式、跳转逻辑）完全由你自定义。

与其他框架中间件的对照

Cap 还提供了其他框架的等价 Checkpoint 中间件，配置结构保持一致，便于横向迁移：

• Express：@cap.js/checkpoint-express，使用capCheckpoint，需要额外安装cookie-parser（见 Express 指南）；
• Hono：@cap.js/checkpoint-hono，使用capCheckpoint，同样支持token_validity_hours、tokens_store_path、token_size、verification_template_path等参数（见 Hono 指南）。

如果你在 Elysia 之外还有 Express 或 Hono 服务，可以参照对应文档用相同思路接入，统一由同一套自托管验证后端提供服务。

小结

通过@cap.js/middleware-elysia，你只需三步即可完成 Elysia 路由的 Checkpoint 保护：

1. bun add elysia @cap.js/middleware-elysia安装依赖；
2. 准备一份包含指向/__cap_clearance的 widget 或 hidden solver 的验证模板；
3. 在 Elysia 实例上.use(capMiddleware({ ... }))并按需配置token_validity_hours、tokens_store_path、token_size、verification_template_path与scoping。

中间件把浏览器侧挑战与自托管验证服务串联起来：挑战生成、结果校验、token 签发与作用域绑定均在服务端完成（源码见 standalone/src/cap.js）。这套流程让开发者在不迁移站点、不依赖第三方云服务的前提下，用自托管开源方案获得与 Cloudflare 浏览器检查类似的机器人拦截能力。

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