> 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/web-plugins/convai-web-sdk/self-hosted-deployments.md).

# 连接到自托管部署

将 Web SDK 指向你自己的 Convai 部署，而不是 Convai 的托管服务，设置它调用的每个主机，并将请求和 API 密钥保留在你的网络内。

将 Web SDK 指向您自行运行的 Convai 部署，例如本地部署或私有云安装，而不是 Convai 托管服务。当您的角色运行在 `api.convai.com`以外的位置，或者浏览器不得访问 Convai 公共主机时，请使用此页面。

SDK 不会使用单个基础 URL。它会与多个服务通信，而在 Convai 托管服务上，每个服务都有自己的主机。请将您使用的每个服务设置为部署中对应的主机。

### 前提条件

* Convai Web SDK 2.0 或更高版本。如果您使用预构建聊天小组件， `@convai/web-widget` 也需要安装在它旁边。
* 部署中每个服务的公共 URL。部署管理员可以向您提供这些 URL。

### 设置主机

| 选项                  | 服务         | 托管服务默认值                           | 调用方                                                                                                                               |
| ------------------- | ---------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `url`               | 核心服务（实时）   | `https://realtime-api.convai.com` | `connect()`，它会向 `{url}/connect`                                                                                                   |
| `characterInfoUrl`  | 角色信息       | `https://api.convai.com`          | 来自 `@convai/web-widget`的聊天小组件会通过 `POST /character/get`                                                                            |
| `characterApiUrl`   | 角色 REST 平台 | `https://api2.convai.com`         | `client.characterVersions`                                                                                                        |
| `interactionApiUrl` | 交互 API     | 无                                 | SSE 传输。请参阅 [通过 SSE 传输进行聊天](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/sse-transport.md). |

将它们与凭据一起传入同一个配置对象。对于 `new ConvaiClient(...)` （来自 `@convai/web-sdk/core` ）和 React 中的 `useConvaiClient(...)` ，用法相同。

```ts
import { ConvaiClient } from '@convai/web-sdk/core';

const client = new ConvaiClient({
  apiKey: 'YOUR_API_KEY',
  characterId: 'YOUR_CHARACTER_ID',
  url: 'https://realtime-api.example.com',
  characterInfoUrl: 'https://api.example.com',
  characterApiUrl: 'https://api2.example.com',
});

await client.connect();
```

将 `example.com` 主机替换为您部署中的主机。仅使用源地址，不要包含路径，也不要添加类似 `/connect`.

您无需配置 LiveKit。核心服务会在其 `/connect` 响应中返回 LiveKit 房间 URL，因此设置 `url` 对于 WebRTC 传输已足够。在 WebSocket 传输中，客户端会使用 `wss://` 只要你的页面或 `url` 通过 HTTPS 提供服务。

### 即使聊天显示正常，也要设置 characterInfoUrl

SDK 本身不会向此主机发送请求；它会将该值存储在客户端的 `client.characterInfoUrl`中，而来自 `@convai/web-widget` 的聊天小组件会从那里读取该值。如果你未设置 `characterInfoUrl` ，小组件会将角色查询请求发送到 `https://api.convai.com`，并在该请求中附带你的 API 密钥。在受限网络中，这会导致请求失败，同时凭据也会被发送到网络外部的主机。

这种故障很难察觉。即使查询失败，小组件仍可正常工作。它会显示备用名称 `Convi` 且不显示头像，因此缺少设置看起来像是外观问题，而不是错误。如果小组件标题显示 `Convi` 而不是角色名称，请先检查此设置。

查询请求会通过以下标头进行身份验证：传入 `CONVAI-API-KEY` 标头（如果传入 `apiKey`），或者传入 `API-AUTH-TOKEN` 标头（如果传入 `authToken`）。请将部署的 `POST /character/get` 配置为接受相同的标头。最高至 1.9.2 版本的 SDK 会将 API 密钥作为 `X-API-Key`发送；自托管部署会拒绝这种请求。 `401`.

`characterInfoUrl` 和 `characterApiUrl` 是两个独立的选项，因为它们对应不同的服务。Character REST 平台不提供 `/character/get`，因此不能对两者使用同一个值。

### 设置其他 API 的主机

SDK 的某些部分在客户端之外创建，并使用各自的主机：

* **长期记忆。** 将部署的 API 源站作为第四个参数传入： `new MemoryManager(apiKey, characterId, endUserId, 'https://api.example.com')`。默认值为 `https://api.convai.com`。请参阅 [使用长期记忆](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/long-term-memory.md).
* **已发布的文本聊天。** 同时传入发布 API 源站和核心源站，例如 `loadPublishedChatSession(publicationId, 'https://api.example.com')` 和 `connectWithPublicationGrant(launchToken, { url: 'https://realtime-api.example.com' })`。请参阅 [连接到已发布的文本聊天](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/published-text-chat.md).

### 连接到不使用 TURN 的 LiveKit 服务器

客户端默认使用 `iceTransportPolicy: 'relay'`，这会使媒体仅通过 TURN 服务器传输。Convai 托管的 LiveKit 提供了 TURN 服务器。如果你的 LiveKit 部署没有 TURN 服务器，请设置 `iceTransportPolicy: 'all'` 以便浏览器也能使用直接连接：

```ts
const client = new ConvaiClient({
  apiKey: 'YOUR_API_KEY',
  characterId: 'YOUR_CHARACTER_ID',
  url: 'https://realtime-api.example.com',
  iceTransportPolicy: 'all',
});
```

SSE 和 WebSocket 传输不使用 WebRTC，因此会忽略此选项。

### 故障排查

| 症状                                                                                  | 原因                                                        | 解决方法                                                                                                                                              |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| 小组件标题栏显示 `Convi` ，且没有头像。                                                            | `characterInfoUrl` 未设置或设置错误，因此角色查询失败。                     | 将 `characterInfoUrl` 设置为你的部署的 API 源。                                                                                                              |
| `POST {characterInfoUrl}/character/get` 返回 `401`，适用于 SDK 1.9.2 或更早版本。               | 这些版本会将 API 密钥作为 `X-API-Key`发送，而你的部署要求使用 `CONVAI-API-KEY`. | 升级 SDK。                                                                                                                                           |
| 浏览器的网络日志中出现了对 `api.convai.com` 的请求。                                                 | 本页中的某个选项未设置。                                              | 对照上表检查请求路径，并设置对应的选项。                                                                                                                              |
| 首次连接失败，并显示 `v1 RTC path not found. Consider upgrading your LiveKit server version`. | 你的 LiveKit 服务器版本早于 SDK 所使用的 `livekit-client` 2.x 版本。      | 请升级 LiveKit 服务器。升级 SDK 版本无法解决此问题。                                                                                                                 |
| 使用 `characterVersion` 连接时失败，并显示 `503 Character version resolution is unavailable`.  | 你的部署不支持解析角色版本。                                            | 省略 `characterVersion`。请参阅 [连接到角色版本](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/character-versioning.md). |
| 在没有 TURN 的 LiveKit 服务器上，WebRTC 已连接，但没有音频传输。                                         | 默认值 `relay` 策略仅允许 TURN 连接。                                | 设置 `iceTransportPolicy: 'all'`.                                                                                                                   |

### API 参考

| 选项                   | 类型                 | 默认值                               | 说明                                                                                               |
| -------------------- | ------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------ |
| `url`                | `string`           | `https://realtime-api.convai.com` | 核心服务的源地址。客户端会向 `{url}/connect`.                                                                  |
| `characterInfoUrl`   | `string`           | `https://api.convai.com`          | 提供 `POST /character/get`的源地址，供 `@convai/web-widget` 聊天组件获取角色名称和头像。可通过 `client.characterInfoUrl`. |
| `characterApiUrl`    | `string`           | `https://api2.convai.com`         | 读取该地址。Character REST 平台的源地址，供 `client.characterVersions`.                                        |
| `interactionApiUrl`  | `string`           | 无                                 | 使用的 SSE 端点。设置该值后，如果省略 `transport` ，则会选择 SSE 传输方式。                                                |
| `iceTransportPolicy` | `"relay" \| "all"` | `"relay"`                         | WebRTC ICE 策略。对于不使用 TURN 的 LiveKit 服务器，请使用 `"all"` 。                                             |


---

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/self-hosted-deployments.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
