REST API zh

English | 中文

REST API 模块

REST API 模块提供流管理和服务器状态查询接口，同时承载 Web 管理控制台。

配置

api:
  enabled: true
  listen: ":8090"
  auth:
    bearer_token: "${API_TOKEN}"
  console:
    username: "admin"
    password: "admin"

字段	类型	默认值	说明
enabled	bool	true	是否启用 API 模块
listen	string	:8090	监听地址和端口
auth.bearer_token	string	""	API Bearer Token（支持环境变量）
console.username	string	admin	Web 控制台登录用户名
console.password	string	admin	Web 控制台登录密码

认证方式

API 接口 (/api/*)

支持以下两种认证方式（满足其一即可）：

方式	说明
Bearer Token	请求头 Authorization: Bearer YOUR_TOKEN
会话 Cookie	通过控制台登录获取的 lf_session Cookie

若 bearer_token 为空，则 API 接口无需认证。

控制台 (/console)

方式	说明
会话 Cookie	通过 /console/login 页面登录，Cookie 有效期 24 小时

API 接口列表

方法	路径	说明
GET	/api/v1/streams	获取所有流列表（含统计数据）
GET	/api/v1/streams/{app}/{key}	获取指定流的详细信息
DELETE	/api/v1/streams/{app}/{key}	删除指定流（关闭流及所有连接）
POST	/api/v1/streams/{app}/{key}/kick	踢掉推流者（保留流等待重新推流）
GET	/api/v1/server/info	获取服务器信息（版本、运行时间、模块列表）
GET	/api/v1/server/stats	获取服务器统计（流数量、连接数）
GET	/api/v1/server/health	健康检查端点
GET	/console	Web 管理控制台（HTML）
GET	/console/login	控制台登录页面
POST	/console/login	提交控制台登录凭据

响应格式

所有 API 响应使用标准 JSON 封装格式：

{
  "code": 0,
  "message": "ok",
  "data": { ... }
}

错误响应：

{
  "code": 404,
  "message": "stream not found"
}

请求与响应示例

获取流列表

curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8090/api/v1/streams

响应：

{
  "code": 0,
  "message": "ok",
  "data": {
    "streams": [
      {
        "key": "live/stream1",
        "state": "publishing",
        "publisher": "rtmp-abc123",
        "video_codec": "H264",
        "audio_codec": "AAC",
        "gop_cache_len": 45,
        "gop_video_frames": 30,
        "gop_audio_frames": 15,
        "gop_duration_ms": 2000,
        "subscribers": {
          "rtmp": 2,
          "flv": 5,
          "webrtc": 1
        },
        "stats": {
          "bytes_in": 10485760,
          "video_frames": 7500,
          "audio_frames": 15000,
          "uptime_sec": 300,
          "bitrate_kbps": 2500,
          "fps": 25.0
        }
      }
    ]
  }
}

踢掉推流者

curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8090/api/v1/streams/live/stream1/kick

响应：

{
  "code": 0,
  "message": "ok"
}

健康检查

curl http://localhost:8090/api/v1/server/health

响应：

{
  "code": 0,
  "message": "ok",
  "data": {
    "status": "healthy"
  }
}