本指南将介绍如何将 Discourse 的 Voice 插件连接到 LiveKit 媒体服务器。默认情况下，语音通话采用点对点（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，这些步骤相对简单：
- 在 LiveKit Cloud 仪表盘中创建一个项目。
- 在项目的 设置 → 密钥 页面，显示 API 密钥 和 API 密钥对（Secret）。
- 记录 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 之前，插件会在其管理仪表板上显示确切的代码片段）：
# livekit.yaml
webhook:
api_key: <your-api-key>
urls:
- https://forum.example.com/voice/livekit/webhook
重启 LiveKit。投递请求通过 API 密钥对（Secret）进行身份验证——无需配置额外的共享密钥。
步骤 7 — 验证集成
检查 Discourse Voice 管理仪表盘
前往 管理 → 插件 → Voice → 仪表盘。一旦存在任何 LiveKit 设置，仪表盘就会显示一个带有实时检查项的 LiveKit 媒体服务器 状态卡片：
- 配置状态（哪些设置已存在以及当前激活的策略），
- 是否可以使用密钥对签署访问令牌，
- 服务器是否可访问以及当前有多少个活动房间，
- 最后一次自动连接检查的结果，
- 是否正在接收 Webhooks。
使用 刷新 按钮可运行按需探测。
以下是启用 LiveKit 后的 Voice 插件仪表盘截图：
检查 LiveKit 仪表盘
LiveKit 仪表板上也有关于通话的详细信息。以下是一个示例：
