> For the complete documentation index, see [llms.txt](https://docs.goassay.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.goassay.ai/developers/zh/shang-jia-ni-de-api-ru-men/cloudflare-worker.md).

# 用 Cloudflare Worker 验证（无需代码）

在 API 前部署现成的签名检查网关。

现成的 Worker 会先检查 Assay 签名，再将请求转发到 API。无需修改应用代码。你需要 Cloudflare 账户，并且能够限制对源站服务器（即 Worker 后的 API）的访问。

## 工作原理

Assay 调用 Worker 的公开 HTTPS 地址。Worker 使用 Assay 公钥验证请求，然后将有效调用发送到 `ORIGIN_URL`。无效签名会收到 `401`；不会调用源站。

## 部署和配置

1. 打开 [Deploy to Cloudflare](https://deploy.workers.cloudflare.com/?url=https://github.com/assay-ai/assay-provider-verify/tree/main/worker)，登录 Cloudflare 并部署现成的 Worker。
2. 在 Cloudflare 为你创建的仓库中，将 `wrangler.toml` 里 `[vars]` 下的 `ORIGIN_URL` 设为源站，例如 `https://origin.example.com`，并提交。可以带路径前缀。不要指回 Worker 自身。只在 Cloudflare 控制台中设置的值，会在下次部署时被 `wrangler.toml` 覆盖。
3. 通过路由或自定义域，将 Worker 绑定到 Assay 将调用的公开主机名。例如，Worker 使用 `api.example.com`，源站使用 `origin.example.com`。
4. 将源站限制为仅接受 Worker 的请求。如果网关已检查机密请求头，请用 `npx wrangler secret put ORIGIN_SECRET` 设置 Worker 的 `ORIGIN_SECRET` 机密值，并要求源站的 `x-assay-origin-secret` 与之匹配。否则，请使用 Cloudflare Tunnel 等私有源站连接，且不能留下公开绕过路径。只配置 Worker 机密值不会限制源站。
5. 登录 Assay，打开上架条目的 **Connect & test** 步骤。
6. 将 **Your API's address** 设为 Worker 的 HTTPS 地址，包括工具需要的路径。Assay 必须为 Worker 的主机名签名，而非源站主机名。
7. 在 **Authentication** 下选择 **Assay signature (recommended)**。
8. 填写工具测试输入，点击 **Save and run test** 或 **Run the test again**。

## 确认是否成功

签名调用应到达源站并通过测试，不应出现 **Signature not enforced** 警告。检查直接调用源站是否无法绕过网关。

也可以不带签名检查公开路由。将此示例替换为 Worker 地址及其保护的路径：

```sh
curl -i https://api.example.com/v1/search
```

预期状态为 `401`，`content-type: application/json`，响应体如下：

```json
{"error":"invalid_assay_signature","reason":"MISSING"}
```

## 详情

| 设置或行为           | 默认值 / 结果                                                                                  |
| --------------- | ----------------------------------------------------------------------------------------- |
| `ORIGIN_URL`    | 必填部署设置；替换模板中的 `https://origin.example.com`。Worker 将传入路径和查询参数附加到源站路径前缀。                    |
| `JWKS_URL`      | 保持未设置，即从 `https://api.goassay.ai/.well-known/assay-request-keys.json` 获取 Assay 公钥。        |
| `ORIGIN_SECRET` | 未设置。设置后，Worker 会在转发调用中添加 `x-assay-origin-secret`。                                         |
| 请求体上限           | 5 MiB（5,242,880 字节），验证前先缓冲。更大的请求体会收到 `413 {"error":"payload_too_large"}`。                 |
| 转发请求            | 方法和请求体不变。移除 `Signature`、`Signature-Input`、`Content-Digest` 和 `Host`；保留 `X-Assay-Call-Id`。 |
| 源站重定向           | 返回调用方；Worker 不跟随重定向。请使用直接响应的源站 URL。                                                       |
| 重放存储            | 每个 Worker 实例各自在内存中保存。签名仍有效时，被截获的请求可能在另一个实例上再次被接受。                                         |

{% hint style="danger" %}
默认部署检查签名真实性和有效期，但不提供共享重放防护。Assay 签名请求的有效期为五分钟，验证器允许签名时间前后各 60 秒的时钟容差。要跨实例拒绝重放，请启用下方的 Durable Object。
{% endhint %}

<details>

<summary>可选：跨 Worker 实例拒绝重放</summary>

在 `worker/wrangler.toml` 中启用提供的 `NONCE_STORE` Durable Object 绑定和 `NonceStore` 迁移，然后重新部署。同时在 `[vars]` 下将 `NONCE_LOCATION_HINT`（例如 `weur` 或 `enam`）设为靠近源站的区域。这会修改部署配置，并为每个已验证请求增加一次共享存储调用。如果存储不可用，Worker 返回 `503 {"error":"replay_store_unavailable"}`，不会转发调用。

</details>

## 错误

| 现象                         | 解决方法                                              |
| -------------------------- | ------------------------------------------------- |
| 有效 Assay 调用收到 `401`。       | 验证前保持传入方法、主机、路径、查询参数和请求体不变。在 Assay 中使用 Worker 地址。 |
| **Signature not enforced** | 检查路由是否确实运行 Worker，且源站不存在公开绕过路径。                   |
| 调用收到 `413`。                | 将请求体控制在 Worker 上限以内。                              |

## 延伸阅读

* 上架你的 API（可选）：[或者：发布你自己的 API](https://docs.goassay.ai/list-your-api/zh/publish-your-own-api)。

## 下一步

* [在代码中验证（Node、Python、Go）](/developers/zh/shang-jia-ni-de-api-ru-men/verify-in-your-code.md)——这是 Worker 之外的另一种方式。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.goassay.ai/developers/zh/shang-jia-ni-de-api-ru-men/cloudflare-worker.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.