218 lines
10 KiB
Markdown
218 lines
10 KiB
Markdown
# XLive
|
||
|
||
[](LICENSE)
|
||
[](package.json)
|
||
[](docker-compose.yml)
|
||
|
||
一个可部署的多用户网页直播平台。主播使用 OBS / FFmpeg 通过鉴权 RTMP 推送到 SRS,SRS 输出低延迟 HLS,浏览器通过 hls.js 播放;业务状态由 SRS HTTP Hooks 自动驱动,不依赖主播手动点击「开始直播」。
|
||
|
||
**XLive** is a self-hostable multi-user live-streaming platform. Streamers push RTMP (authenticated by stream key) to SRS via OBS/FFmpeg; SRS produces low-latency HLS played back in the browser with hls.js. Room state is fully driven by SRS HTTP Hooks — no manual "go live" needed.
|
||
|
||
## ✨ 功能特性
|
||
|
||
- 邮箱/手机号注册模式、Argon2id 密码、HttpOnly Cookie Access/Refresh Token、登录失败锁定
|
||
- 邮箱与短信一次性验证码:5 分钟 TTL、60 秒冷却、IP 限流、Hash 存储、失败次数限制
|
||
- 用户资料、直播间、公开/私有房间、唯一房间号、分类、搜索、直播记录与可播放回放
|
||
- OBS Stream Key 显示/复制/立即轮换;数据库中 Hash 鉴权 + AES-256-GCM 加密备份
|
||
- SRS RTMP 鉴权、HLS 输出、开播/停播/录制 Webhook、自动强制断流、禁播
|
||
- 实时聊天与画面弹幕,回放时按原直播时间轴同步重放弹幕
|
||
- Redis ZSET 心跳在线人数,刷新/断网后自动过期;LiveSession 峰值与采样统计
|
||
- HLS.js 播放、原生 HLS 回退、自动播放降级、断线重连、离线状态
|
||
- USER / ADMIN / SUPER_ADMIN 后端 RBAC
|
||
- 管理后台:指标、系统资源、用户、房间、分类、日志、站点/注册/SMTP/SMS 等配置
|
||
- SMTP 连接验证和真实测试邮件;阿里云 Dysmsapi 真实签名请求与测试短信
|
||
- 站点名称、Logo、暗色 Logo、Favicon、SEO、备案、页脚动态配置;浅色/深色/跟随系统
|
||
- requestId、统一错误结构、日志敏感字段脱敏、参数校验、限流
|
||
- PostgreSQL 迁移、首次超级管理员初始化、Docker Compose、Nginx、Swagger
|
||
|
||
## 🏗 技术架构
|
||
|
||
```text
|
||
OBS / FFmpeg --RTMP--> SRS --HTTP Hooks--> Fastify API
|
||
|
|
||
+--HLS--> Nginx --> hls.js --> Browser
|
||
|
||
Vue 3 + TypeScript + Pinia + Naive UI
|
||
Fastify 5 + Prisma + PostgreSQL 16 + Redis 7
|
||
SRS 6 + Nginx + Docker Compose
|
||
```
|
||
|
||
推流名称与密钥分离。OBS 中显示的 Stream Key 形式为 `room_10001?token=<secret>`;SRS 实际流名是 `room_10001`,因此公开的 HLS URL 不包含密钥。
|
||
|
||
## 📁 目录结构
|
||
|
||
```text
|
||
apps/api 后端、Prisma 模型/迁移、测试、Swagger
|
||
apps/web Vue SPA 与管理后台
|
||
infra/srs SRS 配置
|
||
infra/nginx 入口代理、HLS MIME/缓存、上传文件
|
||
scripts RTMP 全链路测试脚本
|
||
docs/ API 文档
|
||
docker-compose.yml 生产/完整部署编排
|
||
docker-compose.dev.yml 本地开发热更新覆盖层
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Docker Desktop 4.x 或 Docker Engine 25+(含 Docker Compose v2)
|
||
- 本地开发可选 Node.js 22+
|
||
- OBS Studio,或用项目脚本自动拉取 FFmpeg 容器
|
||
|
||
### 启动
|
||
|
||
1. 克隆仓库并复制环境变量模板:
|
||
|
||
```bash
|
||
git clone https://github.com/itxiaohui66/xlive.git
|
||
cd xlive
|
||
cp .env.example .env
|
||
```
|
||
|
||
2. 修改 `.env`,至少替换以下值(生产环境请使用密码管理器生成随机值):
|
||
|
||
- `JWT_SECRET`、`CONFIG_ENCRYPTION_KEY`、`SRS_HOOK_SECRET`
|
||
- `ADMIN_PASSWORD`
|
||
- `POSTGRES_PASSWORD`(如不使用模板中的开发默认值)
|
||
|
||
3. 构建并启动:
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
docker compose ps
|
||
```
|
||
|
||
数据库迁移与首次管理员创建由 API 容器自动完成。初始化只在用户名/邮箱不存在时创建管理员,不会在重启时覆盖密码。
|
||
|
||
- 网站:<http://localhost>
|
||
- Swagger:<http://localhost/api/docs>
|
||
- 健康检查:<http://localhost/health>
|
||
- RTMP:`rtmp://localhost/live`
|
||
|
||
默认开发管理员取自 `.env` 的 `ADMIN_USERNAME` / `ADMIN_PASSWORD`。首次登录后请立即更换密码。
|
||
|
||
## 🛠 本地开发
|
||
|
||
基础设施使用 Docker,前后端热更新:
|
||
|
||
```bash
|
||
docker compose up -d postgres redis srs
|
||
npm install
|
||
$env:DATABASE_URL="postgresql://xlive:xlive_dev_password@localhost:5432/xlive?schema=public"
|
||
$env:REDIS_URL="redis://localhost:6379"
|
||
npm run dev
|
||
```
|
||
|
||
也可使用 `docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build`。提交数据库变更前运行 `npx prisma migrate dev --schema apps/api/prisma/schema.prisma --name <name>`。
|
||
|
||
## 🎥 OBS 与真实直播测试
|
||
|
||
1. 注册并登录,进入「我的直播间」,创建直播间。
|
||
2. 在推流设置复制 RTMP Server 和完整 Stream Key。
|
||
3. OBS → 设置 → 直播 → 自定义:Server 填 `rtmp://localhost/live`,Stream Key 填页面值。
|
||
4. 视频编码使用 H.264、音频 AAC,建议关键帧间隔 2 秒。
|
||
5. 开始推流后,SRS 鉴权成功并回调 API,房间自动变为 LIVE,公开房间出现在首页。
|
||
6. 停止推流后,房间自动 OFFLINE,SRS 将本场直播录制为 FLV 回放,并生成带时间轴弹幕的直播记录。
|
||
|
||
无本机 FFmpeg 时,在 PowerShell 执行:
|
||
|
||
```powershell
|
||
.\scripts\rtmp-smoke.ps1 -StreamKey 'room_10001?token=从页面复制的密钥' -Seconds 60
|
||
```
|
||
|
||
打开 `http://localhost/room/10001` 验证画面。另一个终端可观察:
|
||
|
||
```bash
|
||
docker compose logs -f srs api
|
||
```
|
||
|
||
## ⚙️ 配置说明
|
||
|
||
所有运行配置通过 `.env` 注入(模板见 `.env.example`),关键项:
|
||
|
||
| 变量 | 说明 |
|
||
|---|---|
|
||
| `DATABASE_URL` / `REDIS_URL` | PostgreSQL / Redis 连接串 |
|
||
| `JWT_SECRET` / `CONFIG_ENCRYPTION_KEY` | Token 签名与敏感配置加密密钥 |
|
||
| `ADMIN_USERNAME` / `ADMIN_PASSWORD` / `ADMIN_EMAIL` | 首次启动创建的超管账号 |
|
||
| `SRS_API_URL` / `SRS_HOOK_SECRET` | SRS HTTP API 地址与 Webhook 鉴权 |
|
||
| `RTMP_PUBLIC_URL` / `HLS_PUBLIC_URL` | 对外推流/播放地址 |
|
||
| `UPLOAD_DIR` / `LIVE_DIR` | 上传文件与直播切片目录 |
|
||
|
||
> ⚠️ **永远不要把真实的 `.env` 提交到仓库**。它已被 `.gitignore` 排除;`.env.example` 只含占位符模板。
|
||
|
||
SMTP 与阿里云短信配置在管理后台「系统设置」中完成:SMTP 填写 Host、Port、用户名、密码、加密方式(NONE/SSL/STARTTLS);短信填写 AccessKey、签名与模板编号,密码/Secret 使用 AES-256-GCM 加密保存,接口仅返回 `********`。建议使用仅授予 `dysms:SendSms` 的 RAM 子账号。
|
||
|
||
## 🌐 生产部署与 HTTPS
|
||
|
||
1. 使用独立 PostgreSQL/Redis 凭据,Redis 不暴露公网。
|
||
2. 将域名写入 Nginx `server_name`,把 `.env` 的 `PUBLIC_URL`、`RTMP_PUBLIC_URL`、`HLS_PUBLIC_URL` 改为真实域名。
|
||
3. 用 Certbot/Let's Encrypt 申请证书,将证书只读挂载到 `/etc/nginx/certs`,启用 443 server 并将 80 重定向至 HTTPS。
|
||
4. 页面、API、HLS 必须统一 HTTPS;聊天室使用 WSS。RTMP 可继续使用 `rtmp://`(或在专用入口配置 RTMPS),不会产生浏览器 Mixed Content。
|
||
5. 设置 `COOKIE_SECURE=true`,限制防火墙只开放 80/443/1935。SRS API 1985 不应暴露公网。
|
||
6. 反向代理已为 HLS 配置正确 MIME、无缓存、CORS;上传限制为 10 MB。
|
||
|
||
## 💾 数据库、备份与升级
|
||
|
||
备份:
|
||
|
||
```bash
|
||
docker compose exec -T postgres pg_dump -U xlive -Fc xlive > xlive.dump
|
||
```
|
||
|
||
恢复到空库前先停止 API,并验证备份。升级时先备份,再拉取代码并运行 `docker compose up -d --build`;API 启动会执行尚未应用的 Prisma migration。不要删除已经在生产使用的 migration。
|
||
|
||
## 🧪 测试
|
||
|
||
```bash
|
||
npm run build
|
||
npm test
|
||
docker compose config --quiet
|
||
```
|
||
|
||
测试覆盖密码策略/Argon2id、敏感配置加密,以及 SRS 无效密钥与停播 Webhook。完整直播验证使用上述 `rtmp-smoke.ps1`,它生成动态测试源并真实经过 RTMP → SRS → HLS → 浏览器,不使用静态视频冒充。
|
||
|
||
## 📚 API 与错误格式
|
||
|
||
运行后 Swagger/OpenAPI 位于 `/api/docs`。主要端点见 [API 文档](docs/API.md)。错误统一返回:
|
||
|
||
```json
|
||
{"code":"ROOM_NOT_FOUND","message":"直播间不存在","requestId":"2cb…"}
|
||
```
|
||
|
||
数据库异常、堆栈、内部地址和密钥不会直接返回。
|
||
|
||
## ❓ 常见问题
|
||
|
||
- **Docker CLI 存在但无法连接**:先启动 Docker Desktop;Windows 可检查 `dockerDesktopLinuxEngine`。Docker Desktop 自身崩溃时查看 `%LOCALAPPDATA%\Docker\log\host\com.docker.backend.exe.log`。
|
||
- **推流被拒绝**:确认复制了完整 Stream Key、用户/房间未禁播,查看 `docker compose logs api srs`。
|
||
- **有推流但播放器 404**:等待首个 HLS 分片(通常 2–4 秒),确认编码是 H.264 + AAC,并检查挂载的 `srs_hls` volume。
|
||
- **自动播放失败**:浏览器要求首次自动播放静音;页面会提示用户点击播放。
|
||
- **SMTP/SMS 未配置**:系统检测应显示「未配置」,不是「正常」;测试接口不会伪造成功。
|
||
|
||
## 🔒 安全
|
||
|
||
- 真实 `.env`、数据库备份、上传内容与证书均被 `.gitignore` 排除,请勿强行提交。
|
||
- 发现安全漏洞请通过私密渠道联系维护者,不要在公开 Issue 中披露细节。
|
||
- 部署后请立即修改默认管理员密码,并定期备份数据库。
|
||
|
||
## 👤 作者
|
||
|
||
- 作者:**itxiaohui**
|
||
- 网站:<http://www.itxiaohui.top>
|
||
- 作者社区:<http://www.itky.cc>
|
||
|
||
有问题或建议欢迎到社区交流,或在本仓库提交 Issue / Pull Request。
|
||
|
||
## ⚠️ 免责声明
|
||
|
||
- 本项目仅供学习、研究和技术交流使用。
|
||
- 使用者应遵守所在国家/地区的法律法规,不得将本项目用于任何违法违规用途(包括但不限于传播违法内容、侵犯他人合法权益等)。
|
||
- 由使用者自行部署所产生的内容、行为及后果均由使用者本人负责,与作者及贡献者无关。
|
||
- 本项目按「现状」提供,作者不对其可用性、安全性或适用性作任何明示或暗示的保证。
|
||
|
||
## 📄 许可证
|
||
|
||
[MIT](LICENSE) © 2026 itxiaohui
|