# 将 Discourse Voice 与 LiveKit 集成
**URL:** https://meta.discourse.org/t/integrating-discourse-voice-with-livekit/411585
**Category:** Integrations
**Tags:** voice
**Created:** [2026年九月3日 15:19 UTC](https://meta.discourse.org/t/integrating-discourse-voice-with-livekit/411585 "2026-09-03T15:19:01Z")
**Posts on this page:** 1
**Showing post:** 1
### Author:  [@pmusaraj](https://meta.discourse.org/u/pmusaraj)
#### Post date: [2026年九月3日 15:19 UTC](https://meta.discourse.org/t/integrating-discourse-voice-with-livekit/411585/1 "2026-09-03T15:19:01Z")
本指南将介绍如何将 Discourse 的 **Voice** 插件连接到 [LiveKit](https://livekit.io) 媒体服务器。默认情况下，语音通话采用点对点（P2P）模式：每位参与者直接将音频发送给其他所有参与者。这种模式在小房间中效果很好，但带宽需求会随房间规模增大而增加。通过 LiveKit 路由通话可以确保无论有多少人加入，每位参与者的上传带宽都保持恒定。
## 先决条件
开始之前，请确保您已具备以下条件：
- 一个已启用 Voice 插件的 Discourse 站点
- 一个可访问的 LiveKit 服务器及其 API 凭证。您可以自行托管 LiveKit，也可以使用 LiveKit Cloud 等托管服务。
- 您 Discourse 站点的管理员权限。
## 步骤 1 — 启用 Voice 插件
Voice 插件已随 Discourse 捆绑提供。请前往 **管理 → 设置 → 插件** ，并启用 **Voice** (voice\_enabled) 设置。
## 步骤 2 — 配置 LiveKit 服务器并记录凭证
您需要从 LiveKit 部署环境中获取以下三项信息： **WebSocket URL** 、 **API 密钥** 和 **API 密钥对（Secret）** 。
如果使用 LiveKit Cloud，这些步骤相对简单：
1. 在 LiveKit Cloud 仪表盘中创建一个项目。
2. 在项目的 **设置 → 密钥** 页面，显示 **API 密钥** 和 **API 密钥对（Secret）** 。
3. 记录 **WebSocket URL** （例如 `wss://my-project.livekit.cloud`）。
对于自托管的 LiveKit 安装，请参阅相关文档。
## 步骤 3 — 在 Discourse 中配置 LiveKit 连接
前往 **管理 → 插件 → Voice** ，打开设置并填写 LiveKit 部分：
| 设置项 | 输入内容 |
| --- | --- |
| `voice_livekit_url` | WebSocket URL，例如 `wss://livekit.example.com`（纯 HTTP 实验室环境可使用 `ws://`）。 |
| `voice_livekit_api_key` | 步骤 2 中获取的 API 密钥。 |
| `voice_livekit_api_secret` | 步骤 2 中获取的 API 密钥对（Secret）。 |
| `voice_livekit_room_policy` | 指定哪些房间使用 LiveKit。 |
`voice_livekit_room_policy` 设置决定了房间如何选择传输方式：
| 策略 | 行为 |
| --- | --- |
| `disabled` | 所有通话均运行在点对点模式（默认设置）。 |
| `per_room` | 房间创建者/管理员可以通过房间表单中的 **使用媒体服务器 (SFU)** 复选框，单独为特定房间启用此功能。 |
| `all_rooms` | 所有房间均通过 LiveKit 路由。 |
## 步骤 5 — 可选的额外设置
这些设置用于微调集成：
| 设置项 | 用途 |
| --- | --- |
| `voice_livekit_room_prefix` | LiveKit 上房间名称的命名空间前缀。如果多个站点共享同一个 LiveKit 服务器，请为每个站点设置唯一的前缀。留空则默认使用该站点的数据库名称。 |
| `voice_livekit_mesh_fallback` | 当无法签发 LiveKit 令牌且房间为空时，回退到点对点网格模式而不是让加入失败。默认关闭——静默降级可能会掩盖 LiveKit 的服务中断。 |
| `voice_livekit_recording_enabled` | 允许房间管理员录制运行在 LiveKit 上的通话。录音由 LiveKit Egress 生成，并存储在您的 LiveKit 部署环境的存储中（S3、GCS、本地磁盘）——不会上传到 Discourse。 |
| `voice_livekit_recording_filepath` | 传递给 LiveKit Egress 的文件路径，例如 `voice/{room_name}-{utc}`。支持 `{room_name}`、`{room_id}`、`{time}`、`{utc}` 等占位符；文件扩展名会自动添加。 |
## 步骤 6 — 可选：启用 LiveKit Webhooks
Webhooks 是一种仅用于状态同步的后备机制。当参与者的连接突然断开或房间结束时，Webhooks 可以让插件在几秒内清理在线状态和房间状态，而无需等待心跳 TTL 超时。它们是可选的——如果无法投递，通话仍然可以正常工作，只是清理过程会稍慢一些。
在 LiveKit 服务器上，添加 Webhook 端点（在收到第一个 Webhook 之前，插件会在其管理仪表板上显示确切的代码片段）：
```yaml
# livekit.yaml
webhook:
api_key:
urls:
- https://forum.example.com/voice/livekit/webhook
```
重启 LiveKit。投递请求通过 API 密钥对（Secret）进行身份验证——无需配置额外的共享密钥。
## 步骤 7 — 验证集成
### 检查 Discourse Voice 管理仪表盘
前往 **管理 → 插件 → Voice → 仪表盘** 。一旦存在任何 LiveKit 设置，仪表盘就会显示一个带有实时检查项的 **LiveKit 媒体服务器** 状态卡片：
- 配置状态（哪些设置已存在以及当前激活的策略），
- 是否可以使用密钥对签署访问令牌，
- 服务器是否可访问以及当前有多少个活动房间，
- 最后一次自动连接检查的结果，
- 是否正在接收 Webhooks。
使用 **刷新** 按钮可运行按需探测。
以下是启用 LiveKit 后的 Voice 插件仪表盘截图：
### 检查 LiveKit 仪表盘
LiveKit 仪表板上也有关于通话的详细信息。以下是一个示例：
---
_[View the full topic](https://meta.discourse.org/t/integrating-discourse-voice-with-livekit/411585)._