Cap 社区库生态全景:用你熟悉的语言与框架集成自托管 CAPTCHA(Widget / Hooks / Server / Client 全分类指南)

原创2026-09-27 18:43:431,749 阅读
文章标签:网络安全应用安全后端

Cap 社区库生态全景:用你熟悉的语言与框架集成自托管 CAPTCHA(Widget / Hooks / Server / Client 全分类指南)

导读

本文围绕 Cap 官方社区文档中收录的“社区维护库”清单展开:Cap 是一套免费、开源、可自托管的 CAPTCHA 方案(以 proof-of-work 与 instrumentation 挑战为核心),官方默认提供浏览器 Widget 与 standalone 服务器,但如果你希望绕开 standalone、改用自己熟悉的后端语言或前端框架,社区维护的库就是你的入口。读完本文,你将掌握社区生态的四大分类(Widget、Hooks、Server、Client)各自解决什么问题、哪些库可用、以及为什么这些库常常滞后于官方新特性,并能在官方体系与社区方案之间做出正确的技术选型。

一、先看清官方体系:社区库对标的是什么

要理解社区库的价值,先要弄清 Cap 的官方架构。官方体系由三部分协作完成(详见 官方 standalone 指南 与 工作原理说明):

  1. 前端 Widget:官方浏览器组件,通过 data-cap-api-endpoint 属性指向你的实例地址。源码在 widget/src/src/cap.js,其中直接读取 data-cap-api-endpoint 属性来定位 API。
  2. 后端服务器:推荐以 Docker 运行 Cap Standalone(基于 Bun,空闲内存约 50 MB),负责生成挑战、下发 token、校验解答。若不想用 Docker,官方还提供无状态核心库 capjs-core(见 core/README.md),提供 generateChallenge / validateChallenge 两个纯函数:挑战 token 是 HS256 签名的 JWT,instrumentation 元数据用 AES-256-GCM 加密内嵌在 JWT 中,全程无文件系统、无内存 token 列表。
  3. 服务端验证接口:用户完成挑战后,你的后端要向实例的 /siteverify 端点发请求换取校验结果,实现位于 standalone/src/siteverify.js,成功时返回 { "success": true }。

社区库大体上就是在“前端 Widget”与“后端服务器”这两个位置上提供替代实现:要么把官方 Widget 封装进某框架,要么用另一种语言重写/代理服务器端能力。因此,理解官方这套 Widget + 服务器 + /siteverify 三段式协议,是评估任何社区库的基础。

二、阅读清单前必须知道的几个事实

原文档在列出清单前特别声明了两条重要前提,这是选型时的“第一原则”:

  1. 特性滞后风险:社区库经常不支持较新的特性,例如 seeded challenge(带种子的挑战) 和 instrumentation challenge(插桩挑战)。所谓 seeded challenge,是指客户端基于一个种子 token 自行生成并求解多个挑战;instrumentation challenge 则是在沙箱 iframe 中解压并执行一段防御脚本。这两者都是官方近期能力的核心(见 工作原理说明 的第 3~6 步),而社区库若没有同步跟进,就只能退回更基础的 proof-of-work 流程。
  2. 服务器类库的安全责任:社区维护的服务器实现不受官方支持、未经过官方持续安全审计,官方无法保证其质量、安全性与兼容性;这类库还可能不支持 storage hooks 或 seeded challenge 等新特性。

也就是说,社区库适合“快速上手、语言契合”的场景,但如果你依赖最新的防御特性(尤其是 instrumentation),应优先验证目标库的维护状态,或考虑官方 standalone。

三、Widget 类库:把官方组件装进你的前端框架

官方 Widget 本身不依赖任何框架,默认“哪里都能跑”,因此社区 Widget 包装器“通常并非必需”,它们存在的意义是改善开发体验(类型提示、组件化、与框架生态对齐)。原文档收录的 Widget 类库按框架划分:

React

  • @pitininja/cap-react-widget:将官方 Widget 封装为 React 组件。
  • cap-widget:一个 headless(无头)React 组件,兼容 shadcn 体系,适合已经采用 shadcn/ui 的项目。

Angular

  • @espressotutorialsgmbh/cap-angular-widget:Angular 版本的 Widget 封装。

Vue

  • nuxt-cap:面向 Nuxt 的集成方案。

其他

  • better-captcha:与框架无关的 Widget,一套组件同时支持 React、SolidJS、Vue、Svelte 等最多 6 种框架,适合多框架团队统一维护。

从源码角度理解这类库:官方 Widget 通过 data-cap-api-endpoint="https://<instance_url>/<site_key>/" 属性完成接入(示例见 standalone 指南),社区封装库本质上是把这段配置与渲染逻辑收敛成框架组件。若你的项目对体积与行为有强控制需求,也可以绕过这些包装器直接使用官方 Widget,或者改用 程序化模式(new Cap({ apiEndpoint }) + cap.solve())在任意框架中手动调度。

四、Hooks 类库:把 Cap API 变成 React Hook

Hooks 分类下收录的是对 Cap 客户端 API 的 React Hook 实现,代表库为 @takeshape/use-cap。它的价值在于:把“请求挑战 → 求解 → 获取 token”这一异步过程封装成 Hook,让开发者可以在组件里直接管理加载态、错误态与 token 状态,从而完全自定义用户体验(自定义 UI、交互时机等),而不必依赖官方 Widget 的默认样式。

这类库对应的是 程序化模式 中描述的 API:new Cap({ ... }) 创建实例、cap.solve() 返回 { token }、cap.token 取最近一次的 token、cap.reset() 重置,以及通过 addEventListener("progress", ...) 监听求解进度。官方实现会创建一个隐藏的 cap-widget 元素在后台求解,Hook 库通常就是在此 API 之上做状态管理封装。

五、Server 类库:用你熟悉的后端语言重写服务器

这是社区生态最庞大的一类。警告再次强调:这些库由社区维护,未获官方背书,官方不保证其质量、安全与兼容性,且可能不支持 storage hooks 或 seeded challenge 等新特性。它们共同的目标是替代官方 standalone(或 capjs-core)完成服务器端职责:生成 challenge、签发 token、并在收到解答后验证 proof-of-work 并发行可消费的 redeem token。

Cloudflare Workers(Serverless / JavaScript / TypeScript)

  • kaerez/CFCap:基于 Cloudflare Workers 的 serverless 实现,使用 R2 Bucket 作为存储(作者认为比 Durable Objects 更省钱),支持自定义 TTL、可选使用官方托管的 JS 与 WASM 资源、全球边缘部署与自动扩缩。
  • xyTom/cap-worker:同样是 Cloudflare Workers serverless 实现,但使用 Durable Objects,同样具备全球边缘部署与自动扩缩。

两者在选型上可对比:R2 偏静态对象存储 + 自管理状态,Durable Objects 则提供类持久化协调能力,适合对状态一致性有更高要求的场景。如果你正在 Cloudflare 上运营服务且不想自建容器,这类库能把 Cap 的挑战校验直接并入边缘工作流。

Java

  • luckygc/cap-server:某 Java 服务器实现(wuhunyu 版)的替代品,修复了一个被社区标记为“重要”的问题。
  • wuhunyu/cap-server-java:另一套 Java 服务器实现。
  • schwebke/cap-captcha-keycloak:Keycloak 扩展,为注册流程加入 Cap 验证,适合已有 Keycloak 身份体系的团队,把 CAPTCHA 校验直接挂在注册环节上。

Go

  • samwafgo/cap_go_server
  • ackcoder/go-cap

两个 Go 实现适合 Go 后端团队:若你的服务栈已统一为 Go,引入这些库可以把“生成挑战 + 验证解答”留在进程内,避免额外维护 Node 服务。

Python

  • capjs-server:无状态的 Python 服务器库,专门用于校验 Cap token,不需要数据库——这与官方 capjs-core 的“无状态设计”理念一致(验证纯密码学,不依赖内存 token 列表),适合想要轻量校验逻辑的 Python 服务。
  • django-cap:基于 Django 的 Cap 服务器实现,适合 Django 单体项目,把挑战生成与验证直接并入 Django 应用。

.NET

  • izanhzh/pow-cap-server:.NET 平台的 proof-of-work 服务器实现,适合 C# / ASP.NET 技术栈。

PHP(含 WordPress / Laravel / Statamic)

PHP 是社区投入最多的语言,覆盖 CMS 与框架两大场景:

  • clysss/capito:独立的 Cap PHP 服务器实现。
  • trilbymedia/cap-php:Cap proof-of-work 服务器的 PHP 移植版。
  • oliweb-proof-of-work-for-cap:WordPress 插件,把 Cap 集成进评论、登录、注册以及 WooCommerce 结账页,同时支持可见 Widget 与隐形(programmatic)模式——对应官方文档的 程序化模式 概念。
  • laravel-cap:Laravel 集成方案,提供 Blade 指令、中间件、验证规则与 facade 用于服务端 token 校验,通过 composer require oliweb/laravel-cap 安装。
  • statamic-cap:Statamic 附加组件,把 Cap 集成进表单:负责渲染 Widget、自动校验 token,并在控制面板提供灵活配置,安装方式 composer require oliweb/statamic-cap。
  • cap-captcha-wordpress:另一个 WordPress 插件,集成进认证流程与新评论,可在 WordPress 管理后台配置实例、密钥与颜色。

从协议层面看,这些 PHP 实现最终都要对接与官方一致的验证语义:即用 secret + 挑战 token 换取 { success: true } 的结果。官方端点的行为可在 standalone/src/siteverify.js 中确认——它要求 body 携带 secret 与 response 两个字段,token 内部按 : 分段携带 site key 等信息,校验通过后才在存储中消费该 token(一次性使用)。

六、Client 类库:补全验证请求链路

Client 分类目前收录一个代表实现:

  • cap-client:面向 Node.js 的客户端库与 Express 中间件,用于发起验证请求(即调用 /siteverify 一类校验接口)。它的典型用途是:在你的 Node 后端中,把“收到前端 token → 向 Cap 实例发起 siteverify 校验”封装成一段中间件,让路由处理更简洁。

如果你已在 Express 体系中,官方路径也可以直接在 capjs-core 的 validateChallenge 之上实现同等逻辑(支持 consumeNonce 回调做防重放),社区客户端库的价值在于省去这部分样板代码。

七、如何做选型决策

结合原文档的警告与官方体系,给出四条可操作的决策准则:

  1. 优先确认特性支持:先确认目标库是否支持你依赖的新特性——seeded challenge、instrumentation challenge、storage hooks。若你的防护策略依赖 instrumentation(官方建议保持开启,因为它“显著提高机器人绕过门槛”),请优先选官方 standalone 或明确标注支持该特性的库。
  2. 评估安全责任:服务器类库未被官方安全审计。涉及生产环境时,应审查其 token 校验实现(是否校验签名、是否防重放、是否正确消费一次性 token),并与 standalone/src/siteverify.js 或 core/README.md 的语义做对照。
  3. 按运行环境匹配:边缘优先选 Cloudflare Workers 方案;已有 Java/Go/Python/.NET/PHP 后端则优先选对应语言的服务器库,避免异构部署;纯前端项目直接使用官方 Widget 即可,包装器库只是体验优化。
  4. 必要时回到官方体系:如果社区库无法满足,官方路径始终是兜底——Docker 一键部署 standalone(参考 standalone 指南 中的 docker compose up -d),或使用无状态 capjs-core 嵌入任意后端。

八、想贡献自己的库?直接开 Pull Request

原文档明确表示欢迎生态扩充:如果你为 Cap 实现了新的语言绑定、框架封装或平台适配,可以直接向该文档仓库提交 Pull Request,把你的库补充进对应的分类下。贡献时建议在描述中注明:库支持的官方特性范围(是否支持 seeded / instrumentation / storage hooks)、运行环境与依赖、以及安全模型,便于其他用户在选型时快速评估。

结语

Cap 的社区生态覆盖了 React、Angular、Vue、Svelte、Nuxt、Cloudflare Workers、Java、Go、Python、.NET、PHP(WordPress / Laravel / Statamic)、Node.js 等多个技术栈,让开发者得以在“不运行官方 standalone 服务器”的前提下,用自己熟悉的技术接入这套开源、隐私优先的 CAPTCHA 方案。需要记住的是:社区库是“锦上添花”而非“官方承诺”——在依赖最新防御特性或处理高价值流量的场景,始终以官方 standalone 与 capjs-core 的语义为准绳,并以 widget 源码、siteverify 实现 与 core 文档 作为事实核对依据。

登录后查看全文
cap