企业官网建设流程全解析

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

本篇指南讲解如何通过官方中间件@cap.js/checkpoint-hono为基于 Hono 框架的 Web 应用添加 Cap Checkpoint，用自托管、开源的工作量证明（proof-of-work）CAPTCHA 与浏览器检查保护路由。读完本文你将掌握：中间件的安装与一行式接入、全部配置参数（令牌有效期、令牌存储路径、令牌大小、验证模板路径）的语义与调优建议、验证过渡页模板（指向/__cap_clearance）的组织方式，以及 Checkpoint 方案在实际生产中的适用边界与注意事项。

什么是 Cap Checkpoint

Cap 的 Checkpoint（此前称为中间件）复刻了 Cloudflare 的浏览器检查过渡页：当访客请求到达受保护路由时，中间件先拦截请求并返回一个验证页面，只有通过工作量证明质询（并完成浏览器环境检查）的客户端才会获得放行令牌，后续请求携带该令牌继续访问业务路由。这样可以在机器人、LLM 和自动化滥用到达你的网站之前就将其拦截，详见 关于 Checkpoint。

它的设置和使用都很简单——只需在服务器上添加几行代码，无需把整个网站迁移到 Cloudflare。但需要注意，这属于一种“核弹级”方案，因为它也会影响搜索引擎爬虫等善意的机器人。如果你的站点依赖 SEO 自然流量，请在启用前评估对爬虫抓取的影响。

Cap Checkpoint 的浏览器检查过渡页流程：访客先经过验证页，通过后获得放行令牌。

安装依赖

在 Hono 项目中安装 Hono 框架本体与 Cap 的 Hono 官方中间件包：

bun add hono @cap.js/checkpoint-hono

安装后即可在任意 Hono 应用中引入capCheckpoint中间件。

用法：三行接入 Checkpoint

以下是一个最小可运行的 Hono 应用示例（取自 Hono Checkpoint 官方文档）：

import { Hono } from "hono"; import { serveStatic } from "hono/bun"; import { capCheckpoint } from "@cap.js/checkpoint-hono"; import { join, dirname } from "path"; import { fileURLToPath } from "url"; const app = new Hono(); app.use( "*", capCheckpoint({ token_validity_hours: 32, // 令牌有效时长 tokens_store_path: ".data/tokensList.json", token_size: 16, // 令牌大小（字节） verification_template_path: join(dirname(fileURLToPath(import.meta.url)), "./index.html"), }), ); app.get("/", (c) => c.text("Hello Hono!")); export default app;

就这么简单！现在就可以用这个中间件保护你的路由了。app.use("*", capCheckpoint({ ... }))会把所有路由置于 Checkpoint 之后，任何未持有有效放行令牌的请求都会先被引导至验证过渡页。

提示：示例中的import { serveStatic } from "hono/bun"用于在 Bun 运行时托管静态资源（如验证模板所需的 widget 脚本），可按需保留。join(dirname(fileURLToPath(import.meta.url)), "./index.html")的作用是解析出当前模块所在目录并拼出验证模板的绝对路径，在 ESM 环境下替代__dirname。

配置参数详解

capCheckpoint接收一个配置对象，官方示例展示了四个核心参数，均存在合理的默认调优空间：

从配置项形态看，Checkpoint 系列中间件沿用了需要持久化令牌存储（文件系统令牌列表）的实现方式——这与新一代无状态服务端库capjs-core（基于签名 JWT、可运行于边缘环境）形成对照，后者已在 @cap.js/server 迁移说明 中被声明为推荐替代方案。如果后续需要无状态化，可留意该迁移路径。

验证模板与/__cap_clearanceURL

verification_template_path指向的模板文件是整个 Checkpoint 的门面。根据 Elysia Checkpoint 文档 的说明，模板中只需包含一个指向/__cap_clearanceURL 的验证组件或隐藏求解器即可：

• 模板里嵌入 Cap widget（<cap-widget>元素），并将它的 API 端点指向中间件暴露的质询端点；
• 也可以嵌入一个隐藏求解器（hidden solver），自动在后台完成工作量证明求解，用户无感知地通过验证；
• 中间件会在/__cap_clearance等内置路由上处理质询的签发（challenge）与兑换（redeem）逻辑，完成兑换后即为访客种下有效放行令牌。

在 Hono 场景下，你可以将index.html与业务静态资源放在同一目录，通过serveStatic提供，同时把该 HTML 路径传给verification_template_path。Cap widget 前端资源位于仓库 widget 模块（构建产物如 cap.min.js、cap-floating.min.js），可参考 widget 文档 与 floating 隐藏式 CAPTCHA 文档 了解 widget 的完整 API（如data-cap-api-endpoint、data-cap-floating等属性）。

底层原理：质询 → 兑换 → 校验

Checkpoint 中间件背后的服务端能力与 Cap 服务端库一致，其核心流程分三步：

1. 签发质询：客户端请求过渡页后，服务端生成一组工作量证明质询（challenge），返回给验证组件；
2. 兑换质询：客户端在浏览器中完成哈希求解（相关实现在 hashwx 中，WASM 求解器位于 wasm/src/browser），把解答（solutions）连同质询令牌提交回服务端/__cap_clearance兑换端点；校验通过后签发放行令牌；
3. 校验令牌：后续每个请求都会携带该令牌，中间件对照令牌存储（tokens_store_path指定的 JSON 文件）校验其存在性与有效期（token_validity_hours），通过后放行到业务路由。

这一“创建质询 → 兑换 → 校验令牌”的调用链在 @cap.js/server 服务端库文档 中有完整方法级说明（createChallenge、redeemChallenge、validateToken），Checkpoint 中间件不过是把这三步封装进了框架的请求/响应周期，并托管了过渡页渲染。理解这条链路后，你就能按需调整验证粒度（如仅保护登录、注册等敏感路由，而不是全局"*"拦截）。

其他框架对照：Express 与 Elysia

Cap 为多种 Node/Bun Web 框架提供了同构的 Checkpoint 中间件，参数模型完全一致，便于横向迁移：

• Express：@cap.js/checkpoint-express，需额外安装cookie-parser（因为令牌通过 Cookie 传递），示例见 Express Checkpoint 文档；
• Elysia：@cap.js/middleware-elysia（capMiddleware），配置对象中还额外暴露了scoping: "scoped"选项（取值为'global' | 'scoped'），用于控制令牌作用域，见 Elysia Checkpoint 文档。

如果你是 Hono 用户，直接使用@cap.js/checkpoint-hono即可获得与上述框架一致的能力，无需关心底层框架适配细节。

适用场景与注意事项

• 适合：Web 站点/API 的通用反自动化防护，拦截 LLM 抓取、爬虫与批量滥用流量，尤其适合希望自托管、不想把流量托管给 Cloudflare 等第三方服务的场景；
• 注意：Checkpoint 是“核弹级”方案，会一并拦截搜索引擎爬虫等善意机器人，可能影响 SEO；建议结合业务实际，仅对高价值或易受攻击的路由启用，或配合放行白名单策略；
• 依赖：中间件依赖文件系统令牌存储，多实例/无状态部署场景请提前规划令牌存储的共享或迁移到无状态方案（参见 capjs-core 迁移说明）。

现在，用三行代码为你的 Hono 应用加上 Checkpoint，即可获得自托管、开源、隐私优先（无需第三方服务、不采集用户数据）的工作量证明 CAPTCHA 防护。

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