使用文档

最后更新 2026-09-17

本页是 https://corx.envx.cn 实例的说明书：四种调用方式、全部控制参数、鉴权层级、缓存行为、会遇到的限额，以及背后的安全模型。自托管自己的一份，以仓库里的 README.md 为准。

调用代理

下面四种写法最终都会走同一条链路：鉴权、SSRF 防护、上游注入、缓存、日志。CORS 预检（`OPTIONS`）在进入代理前就已应答，浏览器的 `fetch` 可以直接用。

查询参数（推荐）

本文档统一使用的写法：目标 URL 经过百分号编码后放进 `?url=`。`/fetch` 和任何其他代理路由都支持。

fetch("https://corx.envx.cn/fetch?url=" + encodeURIComponent("https://api.example.com/data"))

路径式

把目标接在 `/proxy/` 之后，便于阅读，也能直接粘进浏览器；目标自己的查询串在第一个 `?` 之后完整保留。

fetch("https://corx.envx.cn/proxy/https://api.example.com/data")

裸路径

与 `/proxy/` 相同，只是少一段：任何不是 CORX 页面、又看起来像 URL 的路径都会走代理。

fetch("https://corx.envx.cn/https://api.example.com/data")

子域名模式

部署绑定了泛解析域名时，每个目标可以拥有自己的主机名：点变连字符、连字符翻倍（`api.example.com` → `api-example-com.<zone>`）。该请求的查询串就是目标的查询串，因此 `corx-*` 名字会被剔除。

fetch("https://api-example-com.<zone>/data")

GET 和 HEAD 响应会被缓存并计入配额，其他方法一律直接透传、不缓存。调用方自带的目标会完整保留自己的查询串：目标自己的 `key`、`ttl`、`callback` 参数原样转发，CORX 只消费属于自己的名字。

fetch、axios、ky 以及 Cloudflare Pages、Vercel、Netlify 的可复制示例，都在代码示例页。或者用 CORS 测试器直接在浏览器里测试任意 URL。

corx-* 命名空间

`corx-*` 是 CORX 的命名空间：这些参数由代理消费，绝不会转发给目标。其余参数都归目标所有，原样转发。表中没有的 `corx-*` 名字会直接 400，而不会被悄悄转发。

参数	作用
`corx-ttl` `corx-ttl=300`	本次 GET 响应的缓存 TTL（秒）。会被部署上限（以及公共 key 自身的 TTL）压低，避免调用方把条目钉死一整天。
`corx-no-cache` `corx-no-cache=1`	本次请求跳过 R2 缓存：直接回源、返回，且不写入缓存。Range 请求、JSONP 和携带凭证的请求本来就会绕过缓存。
`corx-key` `corx-key=corx_…`	本次请求使用的 API key，等价于 `X-Api-Key` 或 `Authorization: Bearer`。公共档位不能控制缓存。
`corx-callback` `corx-callback=handleData`	JSONP：当 CSP 拦住 `fetch` 时，把 `application/json` 响应包成 `fn(<json>);`（上限 2 MiB）供 `<script>` 使用。JSONP 永不缓存。
`corx-charset` `corx-charset=utf-8`	用指定编码重新解码文本、JSON 或 XML 响应，并以 UTF-8 重新输出——上游把编码标错时的救命参数。未知编码名返回 400。
`corx-wrap` `corx-wrap=json`	把文本响应包成 `{"contents":"…"}`（`application/json`），让 HTML 也能用 `r.json()`。二进制响应会直接 400；包装方式属于缓存键的一部分。
`corx-scheme` `corx-scheme=http`	子域名模式：目标协议。默认 `https`，另一个可选值是 `http`。
`corx-port` `corx-port=8443`	子域名模式：目标端口（1–65535），若不是该协议的默认端口（http 为 80、https 为 443）则拼接在主机名之后。

子域名模式是唯一一种「代理请求的查询串就是目标的查询串」的场景，因此在那里会把控制参数剔除。如果目标确实需要一个叫 `corx-*` 的参数，请改用 `?url=` 或路径式调用。

鉴权

三种进入方式，大致就是自托管部署逐步启用的顺序。

API key（按调用方）

在控制台创建的 key 形如 `corx_<随机串>`，库里只存 SHA-256 哈希，原始值只展示一次。它可以携带允许来源、每分钟频率限制、缓存 TTL、免密钥授权、允许主机、SSRF 检查开关和上游注入。用下面任意一种形式发送即可。

X-Api-Key: corx_…
Authorization: Bearer corx_…
?corx-key=corx_…

三种形式完全等价，用你手头客户端支持的那种即可。

免密钥来源授权

给 key 开启免密钥（keyless）后，其允许来源的浏览器调用代理时完全无需携带 key。授权按 `Origin` 匹配（同源 GET 时回退到 `Referer` 的来源），并按访客 IP 计量，因此单个嵌入站点无法耗尽整个 key。来源是便利措施而非凭证——脚本可以伪造——请配合允许主机和频率限制使用。

公共档位

托管实例可能在落地页公开一个共享 key，它是刻意削减过的：仅 GET/HEAD、按调用站点／目标站点／整个实例的每日配额、不能控制缓存、不能注入、不支持子域名模式；转发前会剥掉 `Cookie` 和 `Authorization`。适合公开数据、演示和原型。

key 该放在哪，绝不能放在哪

只能放在服务端。出现在浏览器打包产物、公开仓库或页面源码里的 key，就等于已经泄露；需要从浏览器调用代理的站点应该使用免密钥来源授权（如果数据确实是公开的，就用公共 key）。无论如何，都不要让凭证或个人数据经过共享实例。

缓存

GET 响应会缓存在 R2 并从边缘返回，重复请求通常根本到不了上游。每个响应上的 `X-Corx-Cache: HIT|MISS` 会告诉你走了哪条路。

缓存标记

调试时最该盯的就是 `X-Corx-Cache`：`MISS` 表示响应来自上游（并已写入缓存），`HIT` 表示由 R2 直接返回。`X-Corx-Target` 给出上游主机名，`X-Corx-Latency-Ms` 是代理消耗的时间。

TTL

默认使用部署的 TTL，除非用 `?corx-ttl=` 调低或调高（不超过上限）。key 也可以设定自己的默认 TTL，或设成 `0` 表示永不写入；公共档位完全不能设置 TTL。

哪些请求绕过缓存

以下情况一定绕过共享缓存：非 GET/HEAD 方法、携带 `Authorization` 或 `Cookie`、`?corx-no-cache=1`、JSONP（`corx-callback`）、Range 请求，以及会注入上游请求头的 key。带响应头规则的 key 仍然会缓存——其解析后的规则属于缓存键的一部分，改写过的响应绝不会返回给另一个 key。

限额与错误

有两层彼此独立的限制在保护实例：按 key（匿名时按 IP）的每分钟频率限制，以及公共档位的每日配额。

每分钟限制按 key 计数，匿名调用按 IP 计数。命中缓存的请求同样计入；底层 D1 故障时这些检查会放行（fail open），以免代理整体不可用。

公共 key 的每日计数按调用站点、目标站点和整个实例三个维度，以 UTC 自然日为单位。命中缓存也计入——配额算的是请求数，不是上游压力。`X-Corx-Quota-{Origin,Host,Day}-{Limit,Remaining}` 会报告你的剩余额度。

触碰任一限制时，代理返回 `429`，JSON body 形如 `{ error, scope, limit, resetAt }`，并带 `Retry-After`——距离窗口或 UTC 零点重置的秒数。普通响应也会带 `X-RateLimit-Limit` 和 `X-RateLimit-Remaining`。所有面向机器的路径（代理、`/api/*`、`/health`）出错都是 JSON `{ error }`；浏览器页面则是带品牌的 HTML 错误文档。

安全

CORX 是 CORS 代理，因此本质上就是中间人：运行实例的人可以读取、修改并重放经过它的所有内容。下面的防护只能限制不可信调用方能碰到什么，并不能让共享实例变得适合承载机密。

SSRF 防护：私有、链路本地、CGNAT、组播和保留网段的 IP 字面量会被拦截；主机名会通过 DoH 解析并复核，防止重绑定到内网；D1 黑名单按域名及其子域生效。可信的 key 可以关掉 IP/主机名检查和 DNS 检查，但黑名单与 Cloudflare 自身的规则永远不会被绕过。

请求头卫生：逐跳头和代理自有头（`Host`、`Connection`、`X-Forwarded-For`、`CF-*` 等）在进出两个方向都会被剥掉，`Set-Cookie` 不会转发，公共档位在转发前剥离 `Cookie` 和 `Authorization`。

代理能看到什么：目标 URL、请求与响应体，以及调用方的 IP、`Origin` 与国家/地区。托管实例会记录请求并汇总成每日聚合；自托管可以自行决定是否记录、保留多久（`LOG_REQUESTS`、`LOG_RETENTION_DAYS`）。

所以运行 CORX 最诚实的方式就是自托管：一个 MIT 许可的 Worker，放在你自己掌控的账号里。托管实例只是共享的尽力而为演示——在把流量交给它之前，请先读一读使用条款和信任模型。

使用条款 · 信任模型

自托管

本页上的每一项限制——配额、频率、保留时长、允许主机——在自托管之后都是你自己 Worker 上的设置。README 覆盖了约十分钟的部署流程（D1 + R2 + `wrangler deploy`）；CONTRIBUTING.md 写明了本地开发和改动必须通过的检查。

部署指南贡献指南