用 Cloudflare 免费部署属于自己的无感验证码：Lap 介绍与部署教程

零基础设施：一个 Cloudflare Worker + 一个 D1（SQLite）数据库就够了，不需要 Docker、Redis、VPS，也没有常驻进程——全 Serverless。
免费额度友好：整体能舒服地塞进 Cloudflare 的免费 Workers + D1 额度，个人项目基本零成本。
自托管 Widget：Worker 自己从 /widget.js 提供前端验证组件，不依赖任何第三方 CDN 或 npm 包，没有供应链风险。
隐私优先：没有埋点、没有 Cookie、没有跨站追踪。
跑在边缘：挑战由离用户最近的 Cloudflare 节点签发。

小知识：Lap 其实是我基于 Cap（作者 tiago，Apache-2.0 协议）做的 rebrand 分支，把原本需要 Node + Redis/Valkey 的架构移植成了纯 Cloudflare Serverless 方案，并改了组件名（<cap-widget> → <lap-widget>）。所有密码学设计和前端交互都来自 Cap 的贡献，也欢迎大家去给原项目点 Star。

它大概是怎么工作的？#

1
 1. 浏览器请求挑战  POST /:siteKey/challenge
2
        │
3
        ▼
4
   Lap Worker 签发挑战 { challenge, token }（含 c/s/d 参数）
5
        │
6
        ▼
7
 2. 浏览器暴力求解 nonce，使 sha256(salt + nonce) 以 target 开头（这就是 PoW）
8
        │
9
        ▼
10
 3. 浏览器提交答案  POST /:siteKey/redeem → Worker 校验并签发一次性 redeem token
11
        │
12
        ▼
13
 4. 你的后端用 token 去 POST /siteverify 换取 { success: true }

简单说：机器人要在极短时间内完成大量哈希计算，成本极高；真人浏览器只花一瞬间，几乎无感。每个 token 都是一次性、验证即作废。

二、部署实测（Workers + D1，推荐方案）#

Lap 提供了三种部署方式：Workers + D1（推荐）、Pages Functions、GitHub Actions 自动部署。下面我走最常用、也是 CI 采用的 Workers + D1 路径。

需要准备：

Cloudflare 账号 x1（免费即可）
Node.js 18+（推荐 Node 22）
能用的大脑 🧠 x1
良好的网络环境 x1

1. 克隆并安装依赖#

1
git clone https://github.com/lenmei233/Lap.git lap
2
cd lap/cloudflare
3
npm install
4
npx wrangler login      # 会打开浏览器授权你的 Cloudflare 账号

2. 创建 D1 数据库#

1
npx wrangler d1 create lap-serverless

命令会打印一段 TOML。把其中的 database_id 复制到 cloudflare/wrangler.toml，替换掉 REPLACE_WITH_YOUR_D1_ID：

1
[[d1_databases]]
2
binding = "DB"
3
database_name = "lap-serverless"
4
database_id = "0f9c1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b"   # <- 换成你自己的

binding = "DB" 是代码里读取时用的名字（env.DB），没特殊需求不要改，除非你也同步改 src/worker.js。

3. 应用数据库结构#

1
npx wrangler d1 migrations apply lap-serverless --remote

这条命令会创建六张表：site_keys、tokens、nonces、blocklist、ratelimit、meta。迁移是幂等的，重复执行也安全。

4. 设置管理员密钥#

管理员密钥用来保护 /admin/* 这些能签发站点密钥的接口，它是 Worker Secret，千万不要提交到代码里：

1
npx wrangler secret put ADMIN_KEY
2
# 粘贴一段足够长的随机串，例如：openssl rand -hex 32

5. 部署#

1
npm run deploy      # 先 sync-widget，再 wrangler deploy

部署成功后你的 Worker 地址形如 https://lap-serverless.<你的子域名>.workers.dev。验证一下：

1
curl https://lap-serverless.<你的子域名>.workers.dev/health
2
# {"ok":true,"service":"lap-serverless","version":"1.0.0"}

备选：Cloudflare Pages Functions#

如果你更习惯用 Pages，仓库里的 cloudflare/functions/[[path]].js 是个 catch-all 路由，会把请求转发给同一套 Worker 逻辑，两边行为完全一致。要点是：

1
cd cloudflare
2
node scripts/sync-widget.mjs        # 生成 public/ + src/assets/
3
npx wrangler pages project create lap-serverless --production-branch main
4
npx wrangler pages deploy public --project-name lap-serverless

Pages 不会读取 wrangler.toml 里的绑定，需要在控制台 Workers & Pages → 你的 Pages 项目 → Settings 里手动绑定：

Bindings → Add → D1 database：变量名填 DB，绑定到 lap-serverless，生产环境和预览环境都要加。
Environment variables → Add → Encrypt：名称 ADMIN_KEY，值填你的随机串，记得点 Encrypt。
最后重新部署一次让绑定生效。

备选：GitHub Actions 自动部署#

.github/workflows/deploy-serverless.yml 会在每次改动 cloudflare/ 或 widget/ 并推送到 main 时自动跑测试并部署。你只需在 Cloudflare 后台创建一个具备 Workers Scripts: Edit 和 D1: Edit 权限的 API Token，然后在仓库 Settings → Secrets 里添加：

CLOUDFLARE_API_TOKEN：上一步的 token
CLOUDFLARE_ACCOUNT_ID：Workers & Pages → 账户详情里的 Account ID

ADMIN_KEY 不用设为 GitHub Secret，它存在 Worker 里，wrangler secret put 设一次即可，后续部署会保留。

三、创建站点密钥并接入前端#

部署完成后，还不能直接用，得先为自己的网站签发一个 站点密钥（Site Key）。它的 secret 只显示一次，请妥善保存。

1
ORIGIN=https://lap-serverless.<你的子域名>.workers.dev
2
ADMIN_KEY=<你刚才设置的密钥>
3

4
curl -X POST "$ORIGIN/admin/keys" \
5
  -H "x-admin-key: $ADMIN_KEY" \
6
  -H "content-type: application/json" \
7
  -d '{}'

返回类似：

1
{
2
  "id": "a1b2c3d4e5f60718293a4b5c",
3
  "secret": "9f8e7d6c5b4a39281706f5e4d3c2b1a0",
4
  "config": { "difficulty": 4, "challengeCount": 80, "saltSize": 32 }
5
}

在网页里嵌入组件#

Lap 的 Worker 自己托管了 widget，所以不需要引入任何 CDN 或 npm 包：

1
<script src="https://lap-serverless.<你的子域名>.workers.dev/widget.js"></script>
2

3
<form method="POST" action="/signup">
4
  <input name="email" type="email" required />
5

6
  <lap-widget
7
    data-lap-api-endpoint="https://lap-serverless.<你的子域名>.workers.dev/<SITE_KEY>/">
8
  </lap-widget>
9

10
  <button type="submit">注册</button>
11
</form>

注意 data-lap-api-endpoint 末尾的斜杠不能丢，且路径里要带上你的站点密钥——widget 会自动在后面拼上 challenge 和 redeem。验证成功时，widget 会往所在表单里写入一个隐藏字段 lap-token，后端直接读 req.body["lap-token"] 即可。

如果想要更自定义的交互，也可以用 JS 调用：

1
<script src=".../widget.js"></script>
2
<script>
3
  const lap = new Lap({ apiEndpoint: "https://.../<SITE_KEY>/" });
4
  const { token } = await lap.solve();
5
  // 自己把 token 发给后端
6
</script>

样式方面，所有视觉属性都是 --lap- 前缀的 CSS 变量，可以随意调：

1
lap-widget {
2
  --lap-background: #11111b;
3
  --lap-border-color: #313244;
4
  --lap-border-radius: 12px;
5
  --lap-color: #cdd6f4;
6
  --lap-spinner-color: #89b4fa;
7
}

四、服务端验证（务必做）#

前端的 token 不算数，必须在后端用 /siteverify 校验，而且每个 token 验证一次即作废。

1
curl -X POST "$ORIGIN/siteverify" \
2
  -H "content-type: application/json" \
3
  -d '{"secret":"<SITE_SECRET>","response":"<SITEKEY>:<ID>:<TOKEN>"}'
4
# {"success":true}

以 Node.js / Express 为例：

1
app.post("/signup", async (req, res) => {
2
  const token = req.body["lap-token"];
3

4
  const r = await fetch(`${process.env.LAP_ORIGIN}/siteverify`, {
5
    method: "POST",
6
    headers: { "content-type": "application/json" },
7
    body: JSON.stringify({ secret: process.env.LAP_SECRET, response: token }),
8
  });
9
  const { success } = await r.json();
10

11
  if (!success) return res.status(403).send("CAPTCHA failed");
12
  // ...继续你的业务逻辑
13
});

Python / Flask 版本：

1
import os, requests
2
from flask import request, abort
3

4
@app.post("/signup")
5
def signup():
6
    r = requests.post(
7
        f"{os.environ['LAP_ORIGIN']}/siteverify",
8
        json={"secret": os.environ["LAP_SECRET"], "response": request.form.get("lap-token")},
9
        timeout=10,
10
    )
11
    if not r.json().get("success"):
12
        abort(403, "CAPTCHA failed")
13
    # ...继续

常用调参#

站点密钥的配置可以在创建（POST /admin/keys）或后续（PUT /admin/keys/:id）调整，几个常用项：

difficulty（默认 4）：目标前缀长度，每 +1 工作量约 ×16，指数增长。
challengeCount（默认 80）：子谜题数量，线性增长。
instrumentation（默认 false）：额外做浏览器行为检测。
blockAutomatedBrowsers（默认 true）：拒绝无头/自动化浏览器（需开 instrumentation）。
ratelimitMax / ratelimitDuration：单 IP 限流，默认 30 次 / 5 秒。

调优建议：默认 difficulty:4 + challengeCount:80 在现代笔记本上大约耗时 1 秒。想更严格时，优先提高 challengeCount（线性成本），而不是 difficulty（指数成本），这样耗时更平滑可控。

五、本地开发与排错小贴士#

本地调试不需要 Cloudflare 账号：

1
cd cloudflare
2
npm install
3
echo "ADMIN_KEY=dev-secret" > .dev.vars
4
npx wrangler d1 migrations apply lap-serverless --local
5
npx wrangler dev --local

Worker 会跑在 http://127.0.0.1:8787，用本地 SQLite 文件，开箱即用。

几个常见坑：

{"error":"Admin key not configured"}：ADMIN_KEY 没设置，记得 wrangler secret put ADMIN_KEY。
no such table: site_keys：迁移没跑，补上 d1 migrations apply 步骤（生产加 --remote）。
D1_ERROR：八成是 wrangler.toml 里的 database_id 还是占位符。
组件不出现：先看浏览器控制台 /widget.js 是否 404，再确认 <lap-widget> 拼写无误。
组件出现但一直不验证：data-lap-api-endpoint 必须以 / 结尾，且包含站点密钥。