多用户网页直播平台:OBS/FFmpeg 鉴权 RTMP 推流到 SRS,HLS 低延迟播放; Fastify 5 + Prisma + PostgreSQL + Redis 后端,Vue 3 前端,Docker Compose 部署。
3.2 KiB
3.2 KiB
XLive REST API
完整、可交互的 OpenAPI UI 运行于 /api/docs。所有 JSON API 使用 /api 前缀;认证信息放在 HttpOnly Cookie 中。
认证与用户
| Method | Path | 说明 |
|---|---|---|
| POST | /api/auth/register |
按后台注册模式创建账号 |
| POST | /api/auth/login |
登录并设置 Access/Refresh Cookie |
| POST | /api/auth/refresh |
轮换短期 Access Token |
| POST | /api/auth/logout |
撤销 Refresh Token |
| GET | /api/auth/captcha |
生成图形验证码图片(发码前需通过校验) |
| POST | /api/auth/email/send-code |
真实发送邮箱验证码(需 captchaId + captchaText) |
| POST | /api/auth/sms/send-code |
真实发送阿里云短信验证码(需 captchaId + captchaText) |
| POST | /api/auth/reset-password |
验证码重置密码并撤销会话 |
| POST | /api/auth/change-password |
当前用户修改密码 |
| GET/PATCH | /api/users/me |
当前用户资料 |
| POST | /api/uploads/images |
登录用户上传图片(JPG/PNG/WebP,≤5MB),用于头像/封面 |
直播间
| Method | Path | 说明 |
|---|---|---|
| GET/POST | /api/rooms |
公开列表 / 创建房间 |
| GET/PATCH | /api/rooms/{roomNumber} |
房间详情 / 主播修改 |
| GET | /api/users/me/rooms |
主播房间和近期 Session |
| GET | /api/rooms/{roomNumber}/stream |
仅房主读取推流参数 |
| POST | /api/rooms/{roomNumber}/stream/rotate |
立即轮换密钥并断开旧流 |
| POST | /api/rooms/{roomNumber}/viewers/heartbeat |
45 秒 TTL 观看心跳 |
| GET | /api/categories |
启用的公开分类 |
媒体服务器
POST /api/media/hooks?secret=... 仅供内部 SRS 调用,公网 Nginx 明确返回 404。支持 on_publish、on_unpublish 和 on_dvr。on_publish 校验流名、Token Hash、用户状态和直播权限;非 2xx 响应使 SRS 拒绝推流。on_dvr 将录制文件关联到直播场次;若该房间关闭了「生成直播回放」(record_replay),录制文件会被立即删除且不产生回放。
GET /api/rooms/:roomNumber/replays 返回房间的可用回放;GET /api/replays/:sessionId/danmaku 返回按直播时间偏移排序的回放弹幕。
管理后台
/api/admin/** 需要 ADMIN 或 SUPER_ADMIN;设置、管理员创建和外部服务测试仅 SUPER_ADMIN。
GET /api/admin/dashboard|users|rooms|categories|logsPATCH /api/admin/users/{id}POST /api/admin/users/{id}/reset-passwordPOST /api/admin/rooms/{roomNumber}/stop|ban|unbanPOST/PATCH/DELETE /api/admin/categoriesGET /api/admin/files、DELETE /api/admin/files/{id}、GET /api/admin/files/{id}/download(上传文件管理)GET /api/admin/replays、DELETE /api/admin/replays/{id}、GET /api/admin/replays/{id}/download(回放管理)GET/PUT /api/admin/settingsPOST /api/admin/settings/smtp/test|sms/testPOST /api/admin/admins
状态码
400业务参数不满足规则401未登录、Token/Hook 签名无效403RBAC、账号或直播权限拒绝404资源不存在409唯一约束或资源状态冲突422Zod 参数校验失败423登录失败次数过多导致临时锁定429发送频率或接口速率限制502SMTP/SMS 上游真实调用失败