API 参考

本文档详细介绍 live-webrtc-go 的所有 HTTP API 端点。

认证方式

系统支持两种认证方式，按优先级依次尝试：

1. Bearer Token

Authorization: Bearer <token>

2. X-Auth-Token Header

X-Auth-Token: <token>

认证优先级

房间级 Token (ROOM_TOKENS)
全局 Token (AUTH_TOKEN)
JWT (JWT_SECRET)
无认证（未配置认证时）

流媒体接口

WHIP 推流

发布媒体流到指定房间。

POST /api/whip/publish/{room}
Content-Type: application/sdp
Authorization: Bearer <token>

参数

参数	位置	类型	必需	说明
`room`	path	string	是	房间名，匹配 `^[A-Za-z0-9_-]{1,64}$`

请求体

SDP Offer (text/plain)

响应

状态码	说明
201	成功，返回 SDP Answer
400	无效的 SDP 或房间名
401	认证失败
409	房间已有发布者
429	请求频率超限

示例

curl -X POST "http://localhost:8080/api/whip/publish/demo" \
  -H "Content-Type: application/sdp" \
  -H "Authorization: Bearer mytoken" \
  --data-binary @offer.sdp

WHEP 播放

从指定房间订阅媒体流。

POST /api/whep/play/{room}
Content-Type: application/sdp
Authorization: Bearer <token>

参数

参数	位置	类型	必需	说明
`room`	path	string	是	房间名

请求体

SDP Offer (text/plain)

响应

状态码	说明
201	成功，返回 SDP Answer
400	无效的 SDP 或房间名
401	认证失败
403	订阅者数量已达上限（`MAX_SUBS_PER_ROOM`）
404	房间无活跃发布者
429	请求频率超限

示例

curl -X POST "http://localhost:8080/api/whep/play/demo" \
  -H "Content-Type: application/sdp" \
  -H "Authorization: Bearer mytoken" \
  --data-binary @offer.sdp

状态查询接口

获取前端配置

返回前端应用所需的运行时配置。

GET /api/bootstrap

响应

{
  "authEnabled": true,
  "recordEnabled": true,
  "iceServers": [
    {
      "urls": ["stun:stun.l.google.com:19302"]
    }
  ],
  "features": {
    "rooms": true,
    "records": true
  }
}

字段说明

字段	类型	说明
`authEnabled`	boolean	是否启用认证
`recordEnabled`	boolean	是否启用录制
`iceServers`	array	ICE 服务器配置
`features`	object	功能开关

获取房间列表

返回所有活跃房间及其状态。

GET /api/rooms

响应

[
  {
    "name": "demo",
    "hasPublisher": true,
    "tracks": 2,
    "subscribers": 5
  },
  {
    "name": "test",
    "hasPublisher": false,
    "tracks": 0,
    "subscribers": 0
  }
]

字段说明

字段	类型	说明
`name`	string	房间名
`hasPublisher`	boolean	是否有发布者
`tracks`	number	活跃媒体轨道数量
`subscribers`	number	活跃订阅者连接数量

获取录制列表

返回所有录制文件的元数据。

GET /api/records

响应

[
  {
    "name": "demo_video0_1710123456.ivf",
    "size": 1048576,
    "modTime": "2024-03-10T12:34:56Z",
    "url": "/records/demo_video0_1710123456.ivf"
  }
]

字段说明

字段	类型	说明
`name`	string	文件名
`size`	number	文件大小（字节）
`modTime`	string	修改时间（ISO 8601 / RFC 3339 UTC）
`url`	string	下载录制文件的相对 URL

管理接口

关闭房间

强制关闭指定房间，断开所有连接。

POST /api/admin/rooms/{room}/close
Authorization: Bearer <admin-token>

参数

参数	位置	类型	必需	说明
`room`	path	string	是	要关闭的房间名

响应

状态码	说明
200	成功关闭
401	认证失败（需要 Admin Token）
404	房间不存在

示例

curl -X POST \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  http://localhost:8080/api/admin/rooms/demo/close

健康与监控

健康检查

GET /healthz

响应

ok

状态码：200

Prometheus 指标

GET /metrics

可用指标

指标名	类型	标签	说明
`live_rooms`	Gauge	-	活跃房间数
`live_subscribers`	GaugeVec	`room`	每房间订阅者数
`live_rtp_bytes_total`	CounterVec	`room`	RTP 字节总数
`live_rtp_packets_total`	CounterVec	`room`	RTP 包总数

示例

curl http://localhost:8080/metrics

错误响应

WHIP/WHEP 的领域错误使用以下 JSON 格式：

{
  "error": "错误描述"
}

由通用校验、认证、请求体大小、HTTP 方法或限流逻辑产生的通用 HTTP 错误，仍可能返回纯文本响应。

常见错误码

状态码	错误信息	原因
400	`invalid room name`	房间名格式错误
400	`invalid SDP`	SDP 格式错误
401	`unauthorized`	认证失败或未提供
403	`subscriber limit reached`	已达订阅者上限（WHEP）
404	`no active publisher in room`	房间无发布者（WHEP 播放时）
409	`publisher already exists in this room`	房间已有发布者（WHIP）
429	`too many requests`	触发限流
500	`internal server error`	服务器内部错误

CORS 配置

所有 API 响应包含 CORS 头：

Access-Control-Allow-Origin: <ALLOWED_ORIGIN>
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization, X-Auth-Token

预检请求 (OPTIONS) 自动返回 204。

请求限制

限制	值	配置
SDP 请求体大小	1 MB	硬编码
房间名长度	1-64 字符	正则 `^[A-Za-z0-9_-]{1,64}$`
请求频率	可配置	`RATE_LIMIT_RPS`, `RATE_LIMIT_BURST`
每房间订阅者	可配置	`MAX_SUBS_PER_ROOM`

房间名规则

允许字符：A-Z、a-z、0-9、_、-
最大长度：64 个字符
正则模式：^[A-Za-z0-9_-]{1,64}$

有效示例：room1、my-room、live_stream_01

无效示例：my room（含空格）、room@123（含特殊字符）

API 参考

目录

认证方式

1. Bearer Token

2. X-Auth-Token Header

认证优先级

流媒体接口

WHIP 推流

WHEP 播放

状态查询接口

获取前端配置

获取房间列表

获取录制列表

管理接口

关闭房间

健康与监控

健康检查

Prometheus 指标

错误响应

常见错误码

CORS 配置

请求限制

房间名规则