Files
itxiaohui 463dbb1566 feat: XLive 直播平台初始版本
多用户网页直播平台:OBS/FFmpeg 鉴权 RTMP 推流到 SRS,HLS 低延迟播放;
Fastify 5 + Prisma + PostgreSQL + Redis 后端,Vue 3 前端,Docker Compose 部署。
2026-09-14 17:57:59 +08:00

65 lines
3.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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|logs`
- `PATCH /api/admin/users/{id}`
- `POST /api/admin/users/{id}/reset-password`
- `POST /api/admin/rooms/{roomNumber}/stop|ban|unban`
- `POST/PATCH/DELETE /api/admin/categories`
- `GET /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/settings`
- `POST /api/admin/settings/smtp/test|sms/test`
- `POST /api/admin/admins`
## 状态码
- `400` 业务参数不满足规则
- `401` 未登录、Token/Hook 签名无效
- `403` RBAC、账号或直播权限拒绝
- `404` 资源不存在
- `409` 唯一约束或资源状态冲突
- `422` Zod 参数校验失败
- `423` 登录失败次数过多导致临时锁定
- `429` 发送频率或接口速率限制
- `502` SMTP/SMS 上游真实调用失败