> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/ship-a-secure-build.md).

# 发布安全构建

以 Auth Token 模式构建 Convai Unity SDK 玩家，使账户 API Key 永远不会进入已发布构建，并满足 WebGL 的 CORS 要求。

生成一个不包含 Convai 账户 API 密钥的玩家构建，并配置一个 WebGL 构建实际上能够访问的令牌端点。请在构建前使用此页面： [配置 Auth Token 模式](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/configure-auth-token-mode.md)，就在你构建之前。

### 构建处理器的作用

`ConvaiApiKeyStripBuildProcessor` 会在每次构建之前运行。如果 **认证模式** 为 **Auth Token**，它会将 `_apiKey` 和 `_apiKeyObfuscated` 字段置零，作用于项目的 `ConvaiSettings` 资产，持续整个构建过程，然后在之后恢复保存的密钥。如果 **认证模式** 为 **API 密钥**，处理器不会执行任何操作——账户密钥会像往常一样包含在构建中。

移除操作只会触及 `ConvaiSettings` ，且仅在构建运行期间。它会在移除前将备份写入 `Library/Convai/AuthTokenBuildCredentialBackup.json` ，因此即使 Editor 崩溃或构建进程被终止，密钥也能保留，并且会自动恢复：

* 在构建完成后（`OnPostprocessBuild`),
* 如果构建被中断或取消（`EditorApplication.update`),
* 在 Editor 退出前且仍有待处理备份时（`EditorApplication.quitting`).

{% hint style="warning" %}
你已保存的 API 密钥在整个过程中仍然可供 Editor 工具使用——播放模式、仅 Editor 的后备令牌提供程序以及其他 Editor 工作流都会继续正常工作。只有用于构建的磁盘上的 `ConvaiSettings` 资产会被清除，而且只在构建持续期间生效。
{% endhint %}

### 构建以关闭方式失败，而不是放行

如果处理器无法保证密钥不存在，它会以 `BuildFailedException` 停止构建，而不是发出未移除密钥的发布版本。你可能会遇到以下这些确切消息之一：

| 控制台消息                                                                       | 原因                                                                                                                        |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `Convai 无法恢复先前一次被中断的构建留下的凭据。新的构建已停止，以避免丢失已保存的 API 密钥。`                      | 之前的构建留下了一个从未恢复的待处理备份。打开 **Convai > Settings > 凭据** 以触发恢复，或检查 `Library/Convai/AuthTokenBuildCredentialBackup.json`，然后再次构建。 |
| `Convai 认证令牌模式要求在构建前保存一个 ConvaiSettings 资产。`                                | 项目中没有已保存的 `ConvaiSettings` 资产。打开 **Convai > 设置** 一次，以便 SDK 创建它。                                                           |
| `Convai 认证令牌模式要求 ConvaiSettings 资产位于此项目中，而不是位于包内——从包资产中移除密钥不会以构建所依赖的方式被保存。` | 该设置资产解析到了包路径，而不是项目路径。请将该资产移动到项目中或在项目内重新创建。                                                                                |
| `Convai 无法定位已序列化的 API 密钥字段。构建已停止，因为认证令牌模式无法保证账户密钥不存在。`                      | 该 `ConvaiSettings` 资产的序列化布局与处理器预期的不一致，通常是在对该资产进行了自定义修改之后。请从已知良好的副本恢复该资产。                                                  |

当移除成功时，控制台会记录 `[Convai] 已临时移除为此次认证令牌玩家构建保存的 API 密钥。构建完成后，它将会在项目设置中恢复。`，并且在构建恢复后， `[Convai] 已在玩家构建完成后恢复项目设置中的 API 密钥。`

### 已保存的密钥是混淆的，不是加密的

`ConvaiApiKeyObfuscation` 使用一个 XOR 密码与固定密钥字符串进行处理，然后再用 `cnv1:` 前缀对结果进行 Base64 编码。这样可以避免 API 密钥在序列化资产和版本控制差异中被轻易检索——这并不是加密。任何拥有 SDK 源码的人都可以将其还原，而任何随客户端构建一起发布的密钥最终都可以被提取出来。

{% hint style="danger" %}
不要把混淆当作安全措施。如果你将 API Key 模式构建发布给你无法完全控制的受众，那么账户密钥可以从该构建中被恢复。凡是会离开你自己机器的构建，都应使用认证令牌模式发布。
{% endhint %}

### 满足 WebGL 的 CORS 要求

WebGL 构建会从浏览器访问你的令牌端点，因此该端点需要的不只是 HTTPS。在以认证令牌模式分发 WebGL 构建之前，请确认你的后端满足以下所有条件：

* 使用 HTTPS。SDK 会拒绝任何非 HTTPS 的端点或 HTTP 回环地址，而且浏览器无论如何都会阻止从 HTTPS 页面发起的混合内容请求。
* 通过 CORS 允许已部署游戏的准确源，而不是通配符源，尤其是在请求携带凭据或 cookie 时。
* 允许 `Authorization` 和 `Content-Type` 请求头。
* 响应 CORS 预检（`OPTIONS`）请求。

如果你的登录系统使用 cookie 而不是 bearer token，还要配置 `Secure`, `HttpOnly`，以及合适的 `SameSite` 值，添加 CSRF 防护，并在依赖它之前确认浏览器在 Unity WebGL 中实际发送凭据的方式。

原生构建和 WebGL 构建都会使用相同的头发送解析后的令牌， `API-AUTH-TOKEN` ——没有 WebGL 专用的头。之所以存在上述 CORS 要求，是因为浏览器会对发往你端点的出站请求强制执行这些限制；原生构建没有这种限制。

### 验证构建是否干净发布

生成认证令牌模式构建后，确认账户 API 密钥不存在：

1. 在构建过程中检查控制台中的 `[Convai] 已临时移除为此次认证令牌玩家构建保存的 API 密钥。` 如果没有出现这一行，则构建是在 **认证模式** 设置为 **API 密钥**，而不是 **Auth Token**模式下运行的，并且密钥被包含进去了。
2. 构建完成后，确认 `[Convai] 已在玩家构建完成后恢复项目设置中的 API 密钥。` 出现，并且 **Convai > Settings > 凭据** 在 Editor 中仍显示你已保存的密钥。
3. 运行已构建的玩家并确认角色成功连接。成功连接表示你注册的提供程序或配置的端点在运行时提供了有效令牌。

### 下一步

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>排查认证问题</strong><br>两种认证模式的控制台消息和错误代码。</td><td><a href="/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/troubleshooting.md">身份验证故障排查</a></td></tr><tr><td><strong>配置 Auth Token 模式</strong><br>切换到认证令牌模式，并在项目设置中配置令牌端点。</td><td><a href="/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/configure-auth-token-mode.md">配置 Auth Token 模式</a></td></tr></tbody></table>


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/ship-a-secure-build.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.