---
title: "运行时配置"
description: "通过简单的 API 调用动态调整应用中的协作设置。调整密钥、Webhook URL 等。"
canonical_url: "https://tiptap.zhcndoc.com/collaboration/operations/configure"
---

# 运行时配置

通过简单的 API 调用动态调整应用中的协作设置。调整密钥、Webhook URL 等。

在 Tiptap 协作中配置运行时设置，以通过 REST API 直接管理您的协作环境。

这些设置允许您在不重新启动应用程序的情况下，修改密钥、Webhook URL 等，特别是在适应项目需求或安全协议变化时。

## 设置概述

可以动态调整多个设置：

| Key                                            | Description                                                                                                                                                                                                                                                                                                                      |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `secret`                                       | [JWT 密钥](https://tiptap.zhcndoc.com/collaboration/getting-started/authenticate.md)，在首次启动时自动生成                                                                                                                                                                                                                                    |
| `api_secret`                                   | 用于 Authorization 请求头中的 API 密钥，在首次启动时自动生成                                                                                                                                                                                                                                                                                         |
| `allowed_origins`                              | 根据提供的值验证 `Origin` 请求头（逗号分隔），例如：`https://test.tiptap.dev,https://*.tiptap.dev`；如果未设置，则禁用验证                                                                                                                                                                                                                                        |
| `authentication_disabled`                      | 设置为 `1` 可禁用身份验证，设置为 `0` 可启用（默认：`0`）                                                                                                                                                                                                                                                                                              |
| `webhook_url`                                  | 用于接收 webhook 回调的 URL                                                                                                                                                                                                                                                                                                             |
| `webhook_loader_url`                           | 可选的 webhook URL，用于初始加载文档。更多信息请参见 [webhooks](https://tiptap.zhcndoc.com/collaboration/core-concepts/webhooks.md#loader-webhook)。                                                                                                                                                                                                  |
| `webhook_version`                              | webhook 的版本                                                                                                                                                                                                                                                                                                                      |
| `webhook_awareness`                            | 为用户活动启用 awareness webhook，跟踪 `user.connected` 和 `user.disconnected` 事件（`1` 为启用，`0` 为禁用）                                                                                                                                                                                                                                          |
| `webhook_log_errors_only`                      | 仅记录 webhook 错误；成功的 webhook 日志将被禁用                                                                                                                                                                                                                                                                                                |
| `default_auto_versioning`                      | 设置为 `1` 可启用自动版本控制，设置为 `0` 可禁用（默认：`0`）                                                                                                                                                                                                                                                                                            |
| `default_auto_versioning_interval`             | 自动版本控制的时间间隔，单位为秒（默认：`30` 秒）                                                                                                                                                                                                                                                                                                      |
| `auto_versioning_all_fragments`                | 设置为 `1` 可让版本控制监听文档任意片段/字段的变更（默认是 `0`，仅监视 `default` 片段）。这会同时影响自动版本控制和手动版本控制；当此设置为 `0` 时，手动版本控制需要使用 `force=true`。更改此设置后需要服务器重新加载文档才会生效。                                                                                                                                                                                            |
| `jwt_explicit_access`                          | 设置为 `1` 可在 JWT 中未设置 `"allowedDocumentNames"` 时阻止文档访问。                                                                                                                                                                                                                                                                            |
| `skip_s3_health_check`                         | 设置为 `1` 可关闭 s3 健康检查（仅限本地部署）。如果你的 s3 存储不支持 `getCalledIdentity`，这会很有用。                                                                                                                                                                                                                                                             |
| `name`                                         | 用于标识的实例名称                                                                                                                                                                                                                                                                                                                        |
| `webhook_include_ydoc_state`                   | 设置为 `1` 可在所有 `document.saved` webhook 中包含完整的 yjs 文档                                                                                                                                                                                                                                                                              |
| `thread_authenticator`                         | 设置为 `1` 可启用线程认证器。线程/评论将自动分配为 JWT 中的用户 ID，且无法编辑或删除其他人的线程。不过，通常仍然可以解决其他人的线程（除非使用下面的设置禁用）                                                                                                                                                                                                                                           |
| `user_mapping_authenticator`                   | 设置为 `1` 可强制编辑归因中记录的用户身份与已认证的 JWT `sub` 一致。启用后，客户端只能为自己的 `sub` 注册用户映射；尝试映射、覆盖或删除其他用户身份的操作都会被拒绝。启用此功能时，**客户端必须将 `TiptapCollabProvider.user` 设置为与其 JWT `sub` 相同**，否则连接将被拒绝。这会保护 [版本元数据](https://tiptap.zhcndoc.com/collaboration/documents/snapshot.md#automatic-version-metadata) 中的 `changesBy` 字段以及任何其他使用用户映射的消费者。需要启用 JWT 身份验证。 |
| `commentonly_disallow_resolve_foreign_threads` | 设置为 `1` 可在仅评论连接中禁止解决其他人的线程。                                                                                                                                                                                                                                                                                                      |
| `webhook_include_fields`                       | 设置为 `1` 可在 webhook 中包含自定义 yjs 字段（参见 [webhooks](https://tiptap.zhcndoc.com/collaboration/core-concepts/webhooks.md#custom-fields)）。                                                                                                                                                                                               |

## Manage settings via API

The collaboration platform provides a simple API to manage these settings. Replace `:key` with the settings key you want to update, and replace `YOUR_APP_ID` with your document server ID (marked as "Document server ID" in the [Cloud dashboard](https://cloud.tiptap.dev/v2/configuration/document-server)).

### Create or overwrite a setting

Use this call to add or update a setting:

```bash
curl --location --request PUT 'https://YOUR_APP_ID.collab.tiptap.cloud/api/admin/settings/:key' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' --header 'Content-Type: text/plain' \
-d 'your value'
```

### List current settings

Use this call to retrieve a list of all current settings:

```bash
curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/admin/settings' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA'
```

### Retrieve a specific setting

Use this call to retrieve the value of a specific setting:

```bash
curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/admin/settings/:key' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA'
```

### Delete a setting

Use this call to delete a setting:

```bash
curl --location --request DELETE 'https://YOUR_APP_ID.collab.tiptap.cloud/api/admin/settings/:key' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA'
```

## 服务器性能指标

使用 `/api/statistics` 端点收集服务器性能数据，包括文档总数、峰值并发连接、过去 30 天的总连接数以及生命周期连接计数。
有关更多信息，请查看 [指标](https://tiptap.zhcndoc.com/collaboration/operations/metrics.md) 页面。

```bash
curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/statistics' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA'
```