SMNETSTUDIO/StarLive · 上手攻略

• 仓库：SMNETSTUDIO/StarLive
• 链接：https://github.com/SMNETSTUDIO/StarLive
• 分类：直播平台 · 自部署 · Socket.IO
• 作者：Jay
• 更新：2026-08-21

是什么

StarLive 是一个可完全自部署的直播互动平台（StarLive 星播），重构自旧版 LDLive（Netlify Serverless 无状态函数方案），升级为「独立 NestJS 后端 + Socket.IO 实时长连接」架构。核心功能包括：直播推流（RTMP 入 / HLS 出）、实时弹幕/礼物/红包/抽奖等互动玩法，以及内置星币（StarCoin）虚拟货币经济系统（充值、提现、交易流水）。支持 MediaMTX 自托管和云端 Mux 两种推流方案后台一键切换，带完整管理后台（RBAC、审计、用户/房间/订单管理）和录播转码 Worker（FFmpeg）。

解决什么问题

个人主播或小团队想搭建有自己的虚拟礼物经济、互动玩法完整的直播平台时，通常面临两条路：要么用商业平台（抖音、B站）交保护费+受平台规则限制；要么自建方案工程量大（RTMP 协议理解、实时通信、支付对接、管理后台）。StarLive 把这些全部打包成一个开箱即用的 monorepo，用 Docker 一键跑起来，不需要懂 RTMP/HLS/Socket.IO 也能运营一个完整直播间。

快速安装

方式一：Docker 一键部署（推荐）

# 1. 准备环境变量
cp .env.example .env

# 2. 基本启动（server + 内置 redis + mediamtx）
docker compose up -d

# 3. 如需开启录播 Worker（FFmpeg）
docker compose --profile recording up -d

# 4. 或直接用 GHCR 预构建镜像运行（需提前准备好 Redis）
docker run -d -p 3000:3000 \
  -e REDIS_URL=rediss://default:TOKEN@xxx.upstash.io:6379 \
  -e JWT_SECRET=$(openssl rand -hex 32) \
  ghcr.io/smnetstudio/starlive:main

首次访问 http://<host>:3000 会自动进入初始化向导，创建管理员账号。

方式二：本地开发调试

# 需要 Node 20 + pnpm
pnpm install
pnpm dev:server   # NestJS 后端 (:3000)
pnpm dev:web      # Vite 前端热更新 (:5173，/api 代理到 :3000)
pnpm dev:worker   # 录播 Worker

# 或一体化构建
pnpm build
pnpm start        # http://localhost:3000

本地运行需要独立启动 Redis（docker compose up -d redis mediamtx）和 MediaMTX。

核心用法

关键文件结构

StarLive/
├── apps/
│   ├── server/   # NestJS 后端（REST API + Socket.IO 网关）
│   ├── web/      # React 18 前端
│   └── worker/  # 录播/转码 FFmpeg Worker
├── packages/shared/  # 共享 TS 类型、DTO、WS 事件定义、Redis Key 约定
└── infra/
    ├── docker-compose.yml
    └── mediamtx.yml

必填环境变量

REDIS_URL=redis://:password@localhost:6379          # 自托管 Redis
JWT_SECRET=$(openssl rand -hex 32)                   # JWT 签名密钥

其余配置（站点地址、支付网关、插件功能开关等）可在 /admin 管理后台直接配置，存储在 Redis 中，即时生效且优先于环境变量。

Socket.IO 实时事件（关键）

后端在用户完成写操作后通过 RealtimeGateway 向 room:{roomId} 广播，事件类型包括：

REST API 与 WebSocket 共用同一套 JWT 鉴权，私密房间在 WS 层也做了密码校验。

推流路径

• 自托管（默认）：OBS → MediaMTX（RTMP :1935/{streamKey}）→ HLS → 前端 hls.js 播放
• 云端切换：管理后台一键切换为 Mux（RTMPS 推流 + 自动录制 VOD 回放）

OBS 推流配置示例

服务器：rtmp://<your-host>:1935/live
推流密钥：<roomId>（在 /admin 创建房间后获取）

典型适用场景

• 个人/小团队自建直播平台：有自己的虚拟货币经济，不依赖抖音/B站等平台
• 私有化直播系统：企业内训、闭门活动，不想用商业平台
• 二次开发基础：基于 NestJS + Socket.IO + React 的完整直播架构，适合作为深度定制起点
• 直播功能集成：将直播互动能力嵌入已有产品（如教育平台的实时答疑场景）

坑与注意

1. 首次部署必须配置 Redis：没有 Redis 连接串服务无法启动，两个必填环境变量是 REDIS_URL 和 JWT_SECRET。
2. 生产环境注意 JWT_SECRET 安全：openssl rand -hex 32 每次生成随机值，重启后若不持久化会导致所有已登录用户 token 失效。
3. MediaMTX 推流鉴权兼容 SRS：项目自带 auth hook 兼容 SRS，但若使用纯 MediaMTX 默认配置，推流端无需额外鉴权（按 streamKey 做隔离），生产环境建议开启 MediaMTX 的 readToken/publishToken。
4. 录播 Worker 默认关闭：如需录播必须用 docker compose --profile recording up -d 显式开启，录播文件默认落盘在 recordings-data volume。
5. 多支付网关配置：支付宝/微信 APIv3 需申请商户号和 API 密钥；Stripe 需境外商户资质；项目内置 mock 模式可先跑通全流程再接真实网关。
6. 提现功能含资金冻结机制：星币提现有手续费和资金冻结期，运营时需注意现金流规划；测试阶段建议用 mock 网关。
7. Socket.IO 与 REST 鉴权一致：项目用同一 JWT 验证两种请求，自定义 Token 时注意 jose HS256 算法兼容。

与同类对比

核心差异：StarLive 是目前 GitHub 上工程最完整的自部署直播方案，NestJS monorepo 结构清晰，Socket.IO 实时交互和支付经济系统一步到位，比自己从零搭 nginx-rtmp + Node Socket.IO 方案节省约 2-4 周工作量。

一句话推荐结论

想零平台抽成、自建直播经济的小团队或个人，StarLive 是目前自部署直播开源方案中工程最完整、交互功能最丰富的选择，用 Docker 一键跑起来后可直接运营或作为深度二开的基础。

⚠️ 注意：生产环境请务必配置 MediaMTX 推流鉴权、支付网关真实资质、以及 JWT_SECRET 持久化；提现功能涉及资金需确保当地合规。