Files
xlive/README.md
T
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

9.5 KiB
Raw Blame History

XLive

License: MIT Node Docker

一个可部署的多用户网页直播平台。主播使用 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

🏗 技术架构

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 不包含密钥。

📁 目录结构

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. 克隆仓库并复制环境变量模板:

    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. 构建并启动:

    docker compose up -d --build
    docker compose ps
    

数据库迁移与首次管理员创建由 API 容器自动完成。初始化只在用户名/邮箱不存在时创建管理员,不会在重启时覆盖密码。

默认开发管理员取自 .env 的 ADMIN_USERNAME / ADMIN_PASSWORD。首次登录后请立即更换密码。

🛠 本地开发

基础设施使用 Docker,前后端热更新:

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 执行:

.\scripts\rtmp-smoke.ps1 -StreamKey 'room_10001?token=从页面复制的密钥' -Seconds 60

打开 http://localhost/room/10001 验证画面。另一个终端可观察:

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。

💾 数据库、备份与升级

备份:

docker compose exec -T postgres pg_dump -U xlive -Fc xlive > xlive.dump

恢复到空库前先停止 API,并验证备份。升级时先备份,再拉取代码并运行 docker compose up -d --build;API 启动会执行尚未应用的 Prisma migration。不要删除已经在生产使用的 migration。

🧪 测试

npm run build
npm test
docker compose config --quiet

测试覆盖密码策略/Argon2id、敏感配置加密,以及 SRS 无效密钥与停播 Webhook。完整直播验证使用上述 rtmp-smoke.ps1,它生成动态测试源并真实经过 RTMP → SRS → HLS → 浏览器,不使用静态视频冒充。

📚 API 与错误格式

运行后 Swagger/OpenAPI 位于 /api/docs。主要端点见 API 文档。错误统一返回:

{"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 中披露细节。
  • 部署后请立即修改默认管理员密码,并定期备份数据库。

👤 作者

有问题或建议欢迎到社区交流,或在本仓库提交 Issue / Pull Request。

📄 许可证

MIT © 2026 itxiaohui