Dvina MCP

使用 API 访问

为脚本和 MCP 客户端创建个人访问令牌，并通过 webhook 将 Livespace 的事件发送到你自己的系统。

在设置 › API 访问中，你可以创建个人访问令牌，让脚本或 MCP 客户端以你的身份使用 Dvina。管理员也可以在这里添加 webhook，将 Livespace 的事件发送到自己的系统。

Enterprise 套餐包含 API 访问功能。每位成员都可以创建自己的令牌；只有所有者和管理员能看到 Webhook。

创建令牌

  1. 打开设置，选择 API 访问。
  2. 在个人访问令牌下，选择创建令牌。
  3. 输入名称，方便日后识别令牌的用途。
  4. 选择访问权限：只读或读写。
  5. 选择到期时间：30 天后、90 天后、365 天后或永不过期。
  6. 选择创建令牌。
  7. 在复制你的令牌下，复制令牌并妥善保存。令牌只会在此时显示一次。

令牌以你的身份在创建它的 Livespace 中使用，并具有你当前在该 Livespace 中的角色权限。只读令牌可以读取内容，但不能添加或更改任何内容。

要在 MCP 客户端中使用令牌，请参阅使用 API 密钥而非 OAuth 连接。

查看、轮换或撤销令牌

你的令牌及其访问权限列在个人访问令牌下。选择一个令牌，即可查看其开头字符、访问权限、上次使用时间和到期时间。

  • 要替换令牌，选择轮换…，然后选择轮换以确认。新令牌会替换旧令牌，旧令牌立即失效。在复制你的令牌下复制新令牌。
  • 要停用令牌，选择撤销…，然后选择撤销以确认。所有使用该令牌的脚本或客户端都会立即停止工作。

创建、轮换和撤销令牌的操作都会记录在审计日志中。

添加 webhook

Webhook 会将 Livespace 的事件发送到你指定的地址。这些事件与审计日志中的记录相同。

  1. 在设置 › API 访问的 Webhook 下，选择添加 Webhook。
  2. 输入名称和 URL。请使用可公开访问的 HTTPS URL。
  3. 在事件下，留空可接收所有事件，也可以列出操作和范围，例如 member.added 或 sharing.*。
  4. 选择添加。
  5. 在复制签名密钥下，复制密钥。密钥只会在此时显示一次。

如果 Dvina 提示 Dvina 无法访问此地址，请使用可公开访问的 HTTPS URL。

验证每个请求的签名

Dvina 以 JSON 格式批量发送事件，并为每个请求签名。使用签名密钥验证请求是否来自 Dvina：

  • 每个请求都包含一个 X-Dvina-Signature 标头，格式为 t=<timestamp>,v1=<signature>。
  • 签名使用你的签名密钥，对时间戳、一个句点和请求正文依次拼接后的内容进行 HMAC-SHA256 运算，并以十六进制表示。
  • 自行计算签名并进行比较。如果请求的签名不匹配或时间戳过旧，请拒绝该请求。

查看或更改 webhook

你的 webhook 列在 Webhook 下，并显示各自的状态：已开启、已暂停或发送失败。选择一个 webhook 查看详情。

  • 更改 webhook：编辑其名称、URL 或事件，然后选择保存。
  • 暂停 webhook：关闭发送事件。再次开启即可恢复发送。
  • 查看运行情况：查看其状态和已发送的事件数量。发送失败的 webhook 会显示最近一次错误。Dvina 会持续重试，并在审计日志中记录失败情况。
  • 更改密钥：选择新建签名密钥…，然后确认。请求会立即使用新密钥签名，因此请立即更新接收端。
  • 移除 webhook：选择删除…，然后选择删除以确认。此后将不再向其发送任何内容。