自定义挑战

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

选游戏还是勾选框

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

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

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

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

钉住一种语言或一个主题

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

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

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

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

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

给 Cookie 和回调路径改名

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

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

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

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

把门禁限定到部分路径

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

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

一个典型的登录门户：

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

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

另见

• 设置代理页面门禁：nginx 演练。
• 反向代理食谱：回调契约和其他代理。
• 总览：概念和通行 Cookie。