获取视频会议令牌

1. 接口定位

• 接口名称: 获取视频会议令牌
• 所属域: client/user
• 业务目标: 为用户生成 LiveKit 视频会议访问令牌，用于连接视频通话服务

2. 请求定义

• Method: POST
• Path: /user/rtc/get_token
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 必填，需要通过 Header token 传入有效的登录令牌
• 幂等性: 非幂等（每次请求生成新的 token）

3. 请求参数

Header 参数

字段	必填	类型	说明
operationID	是	string	链路追踪 ID
token	是	string	登录令牌

Body 参数

字段	必填	类型	说明
room	是	string	会议室标识符（如一对一通话则为两个 ID 组合）
identity	是	string	用户在会议中的身份标识

字段约束

• room 和 identity 都不能为空。
• room 通常由业务侧定义，用于标识唯一的会议、群组或一对一通话。
• identity 通常为当前用户的 userID。

4. 响应结构

通用响应包裹

字段	类型	说明
errCode	int	错误码，0 表示成功
errMsg	string	错误简述
errDlt	string	错误详情
data	any	业务数据

data 字段结构

字段	类型	说明
token	string	LiveKit 访问令牌
liveKitURL	string	LiveKit 服务器 URL
user	string	当前用户身份
room	string	会议室标识符
canPublish	bool	是否允许发布媒体流
canPublishData	bool	是否允许发布数据流
canSubscribe	bool	是否允许订阅媒体流

5. 业务规则

• 调用 LiveKit 服务生成访问令牌。
• 返回的 token 有效期取决于 LiveKit 服务配置（通常为几小时）。
• token 包含用户身份和权限信息，客户端使用此 token 连接到 LiveKit 服务器。
• 支持一对一通话、群组通话等多种场景。
• 每次调用都会生成一个新的 token，旧 token 仍然有效。

6. 错误码与失败场景

错误码	场景	典型报错
1001	room 为空	room cannot be empty
1001	identity 为空	identity cannot be empty
500	LiveKit 服务连接失败	Failed to generate token
500	LiveKit 服务返回错误	具体错误信息由 LiveKit 返回

7. 示例

fetch 请求示例

fetch("http://localhost:10008/user/rtc/get_token", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440001",
    token: "eyJhbGciOiJIUzI1NiIs...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    room: "meeting_123456",
    identity: "user001",
  }),
})
  .then((res) => res.json())
  .then((data) => {
    if (data.errCode === 0) {
      const { liveKitURL, token } = data.data;
      // 使用 token 连接到 LiveKit 服务
      console.log(`Connect to ${liveKitURL} with token: ${token}`);
    }
  });

请求示例（JSON）

{
  "room": "meeting_123456",
  "identity": "user001"
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "liveKitURL": "wss://livekit.example.com",
    "user": "user001",
    "room": "meeting_123456",
    "canPublish": true,
    "canPublishData": true,
    "canSubscribe": true
  }
}

失败响应示例（room 为空）

{
  "errCode": 1001,
  "errMsg": "ArgsError",
  "errDlt": "room cannot be empty"
}

失败响应示例（LiveKit 服务异常）

{
  "errCode": 500,
  "errMsg": "ServerInternalError",
  "errDlt": "failed to generate livekit token"
}

8. 时序流程

1. 验证令牌和操作者身份。
2. 校验 room 和 identity 参数不为空。
3. 调用 LiveKit SDK 生成访问 token。
4. 获取 LiveKit 服务器 URL。
5. 返回 token 和服务器 URL。

9. 变更记录

• 2026-03-31: 首版发布，包含视频会议令牌获取的完整定义和示例。