---
type: how-to
title: 自定义挑战
summary: 选游戏还是一次点选的勾选框、钉住语言和主题，并给门禁在你源上用的 Cookie 和回调路径改名。
---

门禁展示的那个验证页是按站点密钥配置的，配置位置在仪表盘里它的 **代理门禁** 页，也可以像其他任何设置一样，通过 [管理 API](/docs/automation/management-api)、MCP 和 Terraform 来配置。下面每一个选项的默认值都是你现在已有的行为，所以一个你从不去碰的站点密钥，会和以前一模一样地继续工作。

## 选游戏还是勾选框

**挑战类型** 决定访客实际做什么：

| 类型 | 访客做什么 | 什么时候合适 |
|---|---|---|
| **玩一个游戏** | 在页面里玩一局短的验证游戏 | 对机器人的信号更强。这是默认值。会花访客几秒钟。 |
| **勾选复选框确认** | 点一下，同时跑一个工作量证明检查 | 更快、更轻，没有游戏要装。信号更弱。 |

有两条规则约束这个选择：

- **一个要求游戏的站点密钥总是展示游戏。** 如果站点密钥自己的 **要求玩游戏才能验证** 设置开着，或者你的团队对每个密钥都要求游戏，勾选框这个选项就不可用，仪表盘会说明是哪个设置把它钉住的。通过 API 去设会返回 `409 gate-forces-game-mode`。
- **选游戏需要装了游戏。** 站点密钥需要至少一个已安装、带可重放产物的游戏，自己的或从团队继承的都行。一个都没有时，会返回 `409 no-games` 的是把类型选成游戏这一步。单是开启门禁不会：不要求游戏的站点密钥会退回到勾选框，所以在你把游戏安排妥当之前，门禁仍然能用。

<Callout type="info">
如果最后一个已安装的游戏之后被移走，一个要求游戏的站点密钥会停止提供验证，而不是悄悄退回到别的方式，因为在一个要求游戏的密钥上，勾选框无法完成验证。一个 *不* 要求游戏的密钥会退回到勾选框，好让你的站点保持可达。
</Callout>

最后这种情况值得学会识别，因为它会让已设门禁的站点下线：门禁会以一个「验证不可用」页面回应每一位访客，直到重新有游戏可用为止。它也可能在没人动过设置的情况下发生，因为一个游戏要等它已固定的版本通过我们的确定性校验才算数。代理门禁页面会在站点密钥处于这种状态时发出警示，并同时链到游戏列表和那个正在要求游戏的设置，这样你既可以装一个游戏，也可以撤掉这项要求、让勾选框接手。

## 钉住一种语言或一个主题

**语言** 和 **主题** 的默认值都是 *跟随访客*，那几乎总是你想要的：

- **语言** 跟随访客自己的浏览器语言，覆盖组件支持的同样那十一种语言。
- **主题** 跟随访客系统的明暗偏好，并随之切换。

当受门禁的站点只有一种语言时，或者当它认定了一个主题、而你想让验证与之相配而不是跟着访客的设备走时，就改为钉住一个。

无论选哪种，验证页都带着 **这个站点密钥的品牌**：和你的组件一样的品牌名、标志、颜色和链接，从同一个站点密钥里解析出来。这些你只配置一次，在你的组件外观设置里，门禁会自己取用。自定义品牌预设需要 Apex 套餐，和组件一样；语言和主题选项本身，在门禁可用的每个套餐上都能用。

验证页自身的措辞不可自定义。

## 给 Cookie 和回调路径改名

只在默认值和你的应用冲突时才改这些。

**Cookie 名称**（默认 `cpt_gate`）就是你的代理依据通行证设置的那个第一方 Cookie。如果你的应用已经在用这个名字，或者你在一个域名上跑着好几个受门禁的应用、想让它们各自独立放行，就给它改名。

<Callout type="warn">
**从一个自定义名字改到另一个自定义名字，会让你设了门禁的站点下线，直到你从站点密钥的代理门禁页重新复制一遍反向代理片段并重载你的代理。** 门禁找的是新名字，而你的代理还在写旧名字，于是访客被送去验证，通过了验证，又立刻被送回验证，形成一个直到撞上速率限制才停的循环。而从默认的 `cpt_gate` 改走则是安全的：可以先改、后接线，因为门禁仍然认得默认名字。
</Callout>

**POST 到你回调的那个字段始终是 `cpt_gate`**，无论你把 Cookie 叫成什么。也就是说，你回调的正文解析永远不用改；变的只是它写进 `Set-Cookie` 的那个名字。门禁的响应里含一个 `cookie_name` 字段，告诉你的回调该用哪个名字。

**回调路径**（默认 `/__cpt/callback`）是你自己源上那条接收通行证并设置 Cookie 的路由。如果你应用的路由器已经占了这条路径，就把它挪走。它必须是你源上的一条纯路径：没有协议、没有主机、没有查询串、没有片段。

## 把门禁限定到部分路径

**只对这些路径设门禁** 和 **绝不对这些路径设门禁** 每行接受一个模式，并塑形生成的反向代理配置。两个都留空，则每条路径都设门禁。

它们是建议性的：它们改变你复制的那段片段，而执行它们的是你的代理。始终让授权方子请求和你的回调路径不设门禁，生成的配置已经替你这么做了。

一个典型的登录门户：

```
只对这些路径设门禁：
/
/api/firstfactor

绝不对这些路径设门禁：
/api/verify
/healthz
```

## 另见

- [设置代理页面门禁](/docs/proxy-page-gate/set-up)：nginx 演练。
- [反向代理食谱](/docs/proxy-page-gate/reverse-proxy-recipes)：回调契约和其他代理。
- [总览](/docs/proxy-page-gate/overview)：概念和通行 Cookie。