---
title: "集成协作提供者"
description: "设置并配置协作提供者，实现跨用户的实时文档同步管理。"
canonical_url: "https://tiptap.zhcndoc.com/collaboration/provider/integration"
---

# 集成协作提供者

设置并配置协作提供者，实现跨用户的实时文档同步管理。

协作提供者与协作后端一起，构成了实时协同编辑的基础架构。它们建立并管理用户之间的通信通道，确保文档的更新和更改在所有参与者之间同步。

提供者处理实时数据交换的复杂性，包括冲突解决、网络可靠性和用户在线状态感知。

`TiptapCollabProvider` 增加了针对协作环境的高级功能，如 WebSocket 消息认证、调试模式和灵活的连接策略。

## 设置提供者

首先，在您的项目中使用以下命令安装提供者包（确保使用提供者 v2，因为 v3 需要 Tiptap v3，而 Tiptap v3 仍处于测试阶段）：

> **设置私有注册表:**
>
> 请注意，您需要按照[这里](https://cloud.tiptap.dev/pro-extensions)的说明设置对私有注册表的访问。
>
> 此外，您可能需要将以下行添加到您的 .npmrc 文件中：
>
> ```
> @tiptap-cloud:registry=https://registry.tiptap.dev/
> ```

```bash
npm install @tiptap-pro/provider
```

对于基本设置，请通过指定文档名称、您的文档服务器 ID（在您的[云仪表板](https://cloud.tiptap.dev/v2/configuration/document-server)中标记为"Document server ID"）用于云部署，或用于本地部署的基础 URL，以及您的 JWT，来连接到协作后端。

根据您的框架，注册连接到协作后端的回调，如 React 中的 `useEffect()` 或 Vue.js 中的 `onMounted()`。

```ts
const doc = new Y.Doc()

useEffect(() => {
  const provider = new TiptapCollabProvider({
    name: note.id, // 文档标识符
    appId: 'YOUR_APP_ID', // 从云仪表板替换为您的文档服务器 ID
    token: 'YOUR_JWT', // 认证令牌
    document: doc,
    user: userId,
  })
}, [])
```

> **本地部署用户的提示:**
>
> 如果您在本地托管协作环境，请在提供者配置中用 `baseUrl` 替换 `appId` 参数，以连接到您的服务器。

## 配置协作提供者

Tiptap 协作提供者支持多种设置，用于自定义配置。请查看下表，了解所有参数、实际用例及诸如“[awareness](https://tiptap.zhcndoc.com/collaboration/core-concepts/awareness.md)”等关键概念。

| 设置                  | 默认值           | 说明                                                                                                             |
| ------------------- | ------------- | -------------------------------------------------------------------------------------------------------------- |
| `appId`             | `''` （空）      | 您的文档服务器 ID（在[云仪表板](https://cloud.tiptap.dev/v2/configuration/document-server)中标记为"Document server ID"），用于协作云部署 |
| `baseUrl`           | `''` （空）      | 用于连接本地部署服务器的 URL。在本地部署设置中用作 `appId` 的替代方案                                                                      |
| `shardKey`          | `''` （空）      | 仅在使用 Tiptap Collab HA 时使用。通常这会设置为文档名称或团队 ID                                                                    |
| `name`              | `''` （空）      | 文档的名称                                                                                                          |
| `token`             | `''` （空）      | 用于安全连接的认证令牌。支持字符串、函数和 Promises                                                                                 |
| `document`          | `new Y.Doc()` | Yjs 文档实例。如果未提供，默认为新文档                                                                                          |
| `user`              | `null`        | 用于归因文档更改的用户 ID 或名称                                                                                             |
| `forceSyncInterval` | `false`       | 以毫秒为单位，强制定期与服务器同步                                                                                              |

### 优化重连时间

提供者的重连设置预设为生产环境的最佳性能。如需针对特定场景调整这些参数，可通过延迟配置完成。

您可以调整初始延迟、应用指数退避，或设置最大等待时间，以微调应用的重连行为，平衡响应速度和服务器效率。

| 设置名                       | 默认值     | 说明                                                  |
| ------------------------- | ------- | --------------------------------------------------- |
| `delay`                   | `1000`  | 两次重连尝试之间的基础延迟，单位毫秒                                  |
| `factor`                  | `2`     | 延迟倍率，每次尝试后指数级增加                                     |
| `initialDelay`            | `0`     | 第一次重连尝试前的延迟时间，单位毫秒                                  |
| `maxAttempts`             | `0`     | 最大重连尝试次数。`0` 表示无限次                                  |
| `jitter`                  | `true`  | 是否添加抖动，通过在 `minDelay` 和计算延迟之间随机选取值增加重连的随机性          |
| `minDelay`                | `1000`  | 启用抖动时的最小延迟。如果禁用抖动则无效                                |
| `maxDelay`                | `30000` | 重连尝试之间允许的最大延迟。设置为 `0` 时，延迟将无限制增长，遵循指数退避（`factor`）规律 |
| `timeout`                 | `0`     | 每次重连尝试的最大持续时间，单位毫秒，超时则停止尝试                          |
| `messageReconnectTimeout` | `30000` | 等待服务器消息的时间上限，单位毫秒。若未收到消息，连接将自动关闭                    |

> 注意：这些设置仅能在单独创建 `TiptapCollabProviderWebsocket` 实例时配置。然后，您需要将其传递给 `TiptapCollabProvider`（作为 `websocketProvider` 参数）。

## 未同步的更改

提供者维护一个整数，跟踪未同步的更改数量。每当服务器接收到一项更改后，会发送确认，提供者则减少计数。

您应监控此计数器，并在用户离开页面前或经过一定超时或未同步更改数量后，通知用户其更改尚未同步。

“更改”可以是单个字符、单个节点或整个文档，取决于您的自定义用例，因此通常计数应为 `0` 或略高，但仅在很短时间内存在（主要是连接延迟）。

您可以通过访问 `TiptapCollabProvider.unsyncedChanges` 获取当前计数，或订阅 `unsyncedChanges` 事件。

```js
TiptapCollabProvider.on('unsyncedChanges', n => console.log(`${n.number} 个未同步的更改`))
```

## 速率限制

为维护系统稳定性并防止配置错误的客户端，我方基础设施（包括管理 API 和通过 `TiptapCollabProvider` 的 WebSocket 连接）均受速率限制管理。

### 默认速率限制（每来源 IP）：

- **请求数：** 100 次
- **时间窗口：** 5 秒
- **突发容量：** 最多 200 次请求

如在正常使用情况下遇到限制，请通过[电子邮件](mailto:humans@tiptap.dev)联系我们。