--- type: explanation title: 在你的反向代理上为整个站点设一道门禁 summary: 代理门禁是什么、给谁用、以及一位访客如何解一局游戏来赢得一张短命的通行证，从而放行他的请求，好让你保护那些无法嵌入组件的应用。 --- 用 Caputchin 的常规方式是把 [组件](/docs/site-keys/embedding-the-widget) 嵌入一个页面，并从你的后端核验令牌。那需要一个放组件的地方和一个检查令牌的后端。代理门禁两者都不需要。它在你的 **反向代理** 上，把一次全页验证摆在整个站点或路由之前：一位访客解一局游戏，赢得一张短命的通行证，然后在站点里漫游，直到通行证过期。受保护的应用从不被触碰。 因为不给应用本身添加任何东西，这就是保护那些你无法嵌入脚本的主机的办法，一个编译好的单页登录门户、一台设备、或者一个坐在认证代理之后的内部工具。 代理门禁在 Alpha 套餐及以上提供，按站点密钥启用。Caputchin 托管挑战并签发通行证；你把你现有的反向代理（nginx、Traefik、Caddy，或任何挡在你应用前面的东西）指向它。 ## 给谁用 当内联组件不合适时，就伸手去拿门禁： - **应用没有放组件的地方。** 一个封死的登录门户（比如 Authelia）、一台供应商设备、或任何你无法编辑的界面。 - **你想给整个面给一道门禁，而不是一个表单。** “在到达这个站点之前先证明你是人”，而不是在单次提交上的一次检查。 - **你没有后端来核验令牌。** 由代理来执行；没有 `/siteverify` 调用要写。 对于一个你控制的普通页面或表单，改为嵌入 [组件](/docs/site-keys/embedding-the-widget)，它更轻，且不重定向访客。如果你有一个表单但没有后端，[托管验证](/docs/hosted-verification/overview) 更合适。 ## 它如何运作 一次解题买下许多请求。访客玩一次游戏；之后一个第一方 Cookie 放行他的请求，直到它过期。 ```mermaid sequenceDiagram participant V as 访客 participant P as 你的反向代理 participant C as Caputchin V->>P: 请求一个受门禁的 URL P->>C: authz 检查（转发 cpt_gate Cookie） C-->>P: 401，还没有有效通行证 P-->>V: 302 到托管挑战 V->>C: 玩游戏 C-->>V: 通行证，auto-POST 到你的回调 V->>P: 把通行证 POST 到 /__cpt/callback P-->>V: 设置 cpt_gate Cookie，重定向回去 V->>P: 再次请求（Cookie 在场） P->>C: authz 检查 C-->>P: 204 允许 P-->>V: 你的应用响应 ``` 代理在每个请求上对 Caputchin 做一次小小的 **授权方** 调用。当请求不带有效通行证时，Caputchin 回 `401`，代理把访客重定向到托管挑战。当通行证在场且有效时，Caputchin 回 `204`，代理把请求放行到你的应用。 ## 通行 Cookie 通行证住在一个名为 `cpt_gate` 的第一方 Cookie 里，由一个你托管的小回调在你自己的域名上设置。它是一个已签名、短命的令牌，不绑定设备，所以它的安全性全然来自 Cookie 属性（`HttpOnly`、`Secure`、`SameSite=Lax`）和一段你选定的短 TTL。因为它在你的访客身上设置 Cookie，请在你的 Cookie 政策里披露它。[设置指南](/docs/proxy-page-gate/set-up) 走过回调和所需的属性。 ## 什么被有意略去 - **没有自托管的门禁。** Caputchin 托管挑战并核验通行证；你不跑一个核验器。你的代理只转发一个 Cookie 并跟随重定向。 - **一个逐请求的检查，而非本地令牌验证。** 代理在每个请求上问 Caputchin。你选的 **失败模式**（开放或关闭）决定了如果 Caputchin 短暂不可达时会怎样。 - **按站点密钥、以 Cookie 为界的通行。** 一张通行证放行一个源，而非整个账户或多个域名，因为它是一个普通的第一方 Cookie。 - **不是会话也不是登录。** 门禁证明一个人到达了站点；你的应用仍然处理认证和它自己的速率限制。两者相叠。 ## 另见 - [设置代理门禁](/docs/proxy-page-gate/set-up)：启用它并把你的代理从头到尾接好。 - [反向代理食谱](/docs/proxy-page-gate/reverse-proxy-recipes)：nginx、Traefik、Caddy，以及 Authelia 的完整范例。 - [代理门禁统计](/docs/proxy-page-gate/statistics)：读直接放行对挑战的比率。 - [托管验证](/docs/hosted-verification/overview)：当你确实有一个表单要指向我们时的那个无后端选项。