Files
2026-09-14 18:01:37 +08:00

218 lines
10 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
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/Node-22%2B-green.svg)](package.json)
[![Docker](https://img.shields.io/badge/Docker-Compose-2496ED.svg)](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