简介：一份面向Java开发者的阿里云直播服务端接入案例，演示如何通过服务端程序生成安全的推流与拉流地址，完成直播互动场景的集成。资源定位清晰，适合正在接入阿里云直播、需要参考地址签名与SDK调用写法的初中级开发者。压缩包共152个文件，以123个XML配置、18个Java源码为主，辅以YAML配置、Maven包装脚本、帮助文档及Git忽略文件，整体仅137KB，轻量且结构规整；Maven相关配置与包装脚本让项目可在不同系统下直接构建，IDEA工程目录和忽略文件则体现了规范的团队协作设置。Java源码中包含直播工具类、上传工具、常量定义、Redis工具等核心模块，可帮助读者快速理解直播地址生成、数据加密与云资源调用的实际写法。目前已有245人学习下载，适合作为直播功能开发时的参考蓝本或代码模板。
1. 直播不是推流就算完：liveVideo 案例里的阿里云直播解决了什么
带 liveVideo 字样的直播项目，最容易踩的坑是「能推流就以为能直播」。OBS 推到公网 RTMP 地址，播放器拉得开，这只是链路长度的十分之一。转码、录制、截图、防盗链、断流重推、数据统计，每一块单做都是几周的活，而阿里云直播把这些收敛成域名配置和 API 调用。
标题里的「案例」划定了边界：liveVideo 管业务侧，负责房间和回调事件；阿里云直播管媒体侧，把推流转成可大规模分发的 FLV/HLS，在云端完成录制与截图。工程上常见的分工是业务系统只处理流 ID 和事件通知，不碰媒体数据本身。
下文按从业者路线推进：先讲域名与地址模型，再落到转码录制配置，处理延迟与弱网，最后用直播数据反推配置是否合理。新手可照章节复现，熟手直接看参数边界与排错段落。
2. 推流与播流地址怎么生成：liveVideo 绑定阿里云直播域名的完整步骤
2.1 先分清三个角色：推流域名、播流域名与 AppName
阿里云直播把媒体链路拆成两个独立域名：推流域名负责接收 RTMP 推流，播流域名负责对外分发 HTTP-FLV、HLS 和 RTMP 拉流。两个域名都必须在控制台添加并完成 CNAME 绑定，推流域名指向推流加速节点，播流域名指向 CDN 分发节点，两者不通用。
AppName 是紧随域名后的路径段，默认值是live，也可以改成业务自定义名称。它存在的意义是隔离：同一个推流域名下，不同 AppName 可以挂不同的转码模板与录制配置。liveVideo 这类项目我一般按环境分，比如live_test与live_prod各配一套，避免测试流污染线上录制文件。
StreamName 是流的唯一标识，一般用业务房间 ID 加随机后缀拼接。拿直播带货场景举例，主播 ID 是 881203，StreamName 可设计成881203_ab12，其中ab12是本次开播的会话标记。这个命名会贯穿到后续所有回调消息、录制文件路径和截图文件名，项目一开始就要定好规则，后面再改会造成历史数据对不上。
2.2 liveVideo 的推流地址与播流地址怎么拼
推流 URL 的标准形态：
rtmp://push.example.com/live/881203_ab12?auth_key=1800000000-0-0-xxxxxxxx其中push.example.com是推流域名，live是 AppName，881203_ab12是 StreamName，auth_key是 URL 鉴权参数。播流 URL 结构相同，只把域名换成播流域名，并按播放协议追加后缀：
http://play.example.com/live/881203_ab12.flv # HTTP-FLV，低延迟优先 http://play.example.com/live/881203_ab12.m3u8 # HLS，延迟不敏感场景 rtmp://play.example.com/live/881203_ab12 # RTMP 拉流，兼容老播放器同一个 StreamName 在云端默认同时产出 FLV 和 HLS，不需要分别申请。liveVideo 做播放器选路时，我一般先默认走 flv 地址，遇到不支持 flv 的环境再降级到 m3u8，这个降级判断是播放端 SDK 的标准能力，业务侧只需要把两种地址都下发。
2.3 控制台添加域名后，CNAME 不生效怎么看
域名添加完成后，控制台会给出 CNAME 目标值，例如push.example.com.w.alikunlun.com。在 DNS 服务商处添加记录后用 dig 验证：
dig push.example.com CNAME +short返回空说明 DNS 还没生效或记录类型写错；返回目标值但拉流仍 403，多半是鉴权参数问题。auth_key 由timestamp-random-uid-flag四段组成，timestamp 是过期时间戳，超过当前时间 30 分钟后失效。排查时先用控制台内置的「地址生成器」产出一个临时播放地址，能排除 DNS 和鉴权两方面的干扰。
还有一类情况是 CNAME 已生效，但播流域名的 HTTPS 证书没配。控制台默认只开通 HTTP 播放，未配置证书时强制走 HTTPS 的播放器会直接报证书错误。域名证书可以申请免费 DV 证书后上传，也可以在控制台一键关联，这一步在正式上线前必须完成，否则 HTTPS 页面里的播放器全部拉不出画面。
2.4 用 ffprobe 验证直播链路通没通
推流成功不等于播流成功。更可靠的验证是模拟推流端推测试画面，再直接探测播流地址：
# 推流端：用测试源生成 720p 画面推送到阿里云直播 ffmpeg -re -f lavfi -i testsrc=size=1280x720:rate=25 \ -f lavfi -i sine=frequency=440 \ -vcodec libx264 -preset veryfast -tune zerolatency \ -acodec aac -f flv "rtmp://push.example.com/live/test_stream?auth_key=xxx" # 拉流端：探测播流地址，确认已产出可播放的 FLV 流 ffprobe -v error -show_entries format=format_name,start_time \ -show_streams "http://play.example.com/live/test_stream.flv?auth_key=xxx"第一段命令用 lavfi 的测试画面和正弦波推流，-tune zerolatency让编码器关闭 B 帧以降低端到端延迟，-preset veryfast平衡 CPU 占用与编码速度；第二段命令把播流地址喂给 ffprobe，输出里能看到format_name=flv和 video/audio 两个流，说明整条链路已经打通。
提示：测试流务必使用独立 StreamName，不要用线上房间 ID。直播数据里的带宽计费按并发峰值计算，测试画面分辨率越高，账单越难看。
3. 转码、录制与截图配置：直播数据在阿里云直播里如何被加工
3.1 转码模板选型与播流地址后缀
阿里云直播默认不转码，播流地址直接输出推流原始码率。但直播数据的带宽成本与码率强相关：一个 1080p、4 Mbps 的主播推流，100 人观看就要消耗 400 Mbps 下行带宽。业务上线前必须建立转码模板，至少包含三档：
| 模板名 | 分辨率 | 码率 | 适用场景 |
|---|---|---|---|
| lv_ld | 640x360 | 400 Kbps | 弱网用户、列表页小窗 |
| lv_sd | 854x480 | 800 Kbps | 手机端默认清晰度 |
| lv_hd | 1280x720 | 1500 Kbps | Web 端主档位 |
转码模板创建后，播流地址要在 StreamName 后追加模板名后缀：
http://play.example.com/live/881203_ab12_lv_sd.flv?auth_key=xxx这里最常见的误用是只创建模板但忘记让前端拼接带_lv_sd后缀的地址，导致所有用户拉到原画，转码白配。正确做法是把三档地址都下发给播放器，由播放器根据当前网速与屏幕尺寸自动选择档位，再在用户手动切清晰度时固定某一档。
3.2 录制配置与 OSS 存储路径规划
录制配置需要指定 OSS Bucket、存储路径和切片时长。切片时长默认 30 分钟，含义是录制文件按此长度切为 m3u8 分片。短视频回放可切成 5 分钟，课程回放保持 30 分钟以减少切片数量。录制文件名不支持自定义，但路径前缀可规划，常见做法是按下述模式组织：
record/{AppName}/{StreamName}/{StartTime}.m3u8 record/{AppName}/{StreamName}/{StartTime}_{EndTime}.mp4m3u8 在直播过程中持续生成，mp4 在直播结束后异步合成。liveVideo 业务侧在写回调时，只记录RecordStartTime和RecordEndTime两个字段，列表页直接拿 m3u8 地址做回放源；等收到录制完成的回调事件后，再把入口替换为 mp4 文件，同时开放下载按钮。OSS 生命周期规则可以直接按路径前缀配置过期删除，例如只保留 180 天的回放，避免存储费用随开播场次线性上涨。
3.3 截图回调与关键帧间隔的隐藏约束
截图功能在控制台打开开关并指定 OSS 路径即可，但工程上有个隐蔽约束：截图依赖推流关键帧。如果推流端 GOP 太长，截图服务要等下一个关键帧，导致截图延迟甚至超时。OBS 里把关键帧间隔设为 2 秒，是截图和录制正常工作的最小前提。
同理，录制切片的 m3u8 分片必须从关键帧开始切。GOP 大于切片时长时，切片器在下一个关键帧处强行切割，造成切片时长不均匀，播放时表现为周期性卡顿。把编码器的 keyint 设成切片时长的整数倍附近，能减少这类问题。
4. 无延迟直播接入与弱网兜底：播放器 SDK 和推流脚本的关键参数
4.1 协议选择的边界：低延迟选 FLV 不选 HLS
无延迟接入的关键在协议。HLS 的切片与索引机制天然带来 5~10 秒延迟，适合回放和不追求实时的场景；HTTP-FLV 的流式传输能把延迟压到 1~3 秒，互动直播必须选它。Web 端主流播放器直播模式都基于 flv.js 实现，移动端则用各家的视频直播 SDK 的直播模式打开 flv 地址。
延迟目标要分场景定：电商直播 3 秒内可接受，音视频连麦场景要求 1 秒内，而后者通常已经超出单靠协议优化的范围，需要引入阿里云 RTC 服务。liveVideo 这类偏内容分发的直播，把目标定在 2~3 秒是合理的，盲目追求更低延迟会牺牲弱网容忍度。
4.2 播放器 SDK 的缓冲与追帧参数
以阿里云视频直播的 Web 播放器 SDK 为例，初始化参数里有两个直接影响延迟：
var player = new Aliplayer({ id: 'player-con', source: 'http://play.example.com/live/881203_ab12_lv_sd.flv?auth_key=xxx', autoplay: true, liveStreaming: true, flushTime: 3000, });flushTime是播放器缓冲区的最大保留时长，单位毫秒，设为 3000 表示缓冲超过 3 秒就主动追帧。直播场景建议在 2000~5000 之间调：数值越小延迟越低，但网络抖动时更容易卡顿。liveStreaming: true让播放器进入直播模式，关闭对总时长的预判逻辑。调优时必须固定其他变量，只动 flushTime，逐档下降直到出现卡顿，再回退一档。
4.3 推流端断流重推：无人值守时的兜底脚本
推流进程掉线是直播事故的头号来源。ffmpeg 异常退出后，播流地址会保留一段时间的黑屏流，用户端表现为「直播中但没有画面」。常见兜底是 supervisor 拉起进程，但更可控的是循环检测脚本：
#!/bin/bash while true; do # 每 5 秒检查推流进程，异常退出时立即补拉 pgrep -f "rtmp://push.example.com/live" > /dev/null || { echo "$(date) 推流进程退出，重新拉起" >> /var/log/live_restart.log ffmpeg -re -f lavfi -i testsrc=size=1280x720:rate=25 \ -vcodec libx264 -preset veryfast -tune zerolatency \ -f flv "rtmp://push.example.com/live/881203_ab12?auth_key=xxx" & } sleep 5 done脚本每 5 秒检查一次推流进程，pgrep -f匹配命令行里的推流地址关键字，匹配不到就拉起新进程并把重启事件写入日志，方便事后对账。实际生产里还应叠加阿里云直播的「直播流事件回调」，在流中断或黑屏时通过 HTTP 回调通知业务侧发告警：脚本负责快速恢复，回调负责通知人，两者职责不冲突。
这类无人直播形态在在线教育和内部培训里越来越常见，本质是推流源远端无人值守，靠脚本与回调双保险维持链路。如果 liveVideo 面向这类业务，断流重推和黑屏检测要在第一版就设计进去。
5. 用直播数据反推配置：在线流查询与回调日志的排查顺序
5.1 先看三个指标：带宽、并发与推流帧率
直播数据看板里最有价值的指标是带宽趋势、并发峰值和推流帧率，我一般先看这三项。带宽趋势能暴露转码是否生效——如果峰值带宽接近原画码率乘以并发数，说明转码模板没被播放器用上；并发峰值要搭配推流帧率看，帧率持续低于 20 fps 时，问题大概率在推流端编码参数，而不是云端配置。帧率曲线如果是锯齿状，优先检查推流机器负载和网卡丢包；卡顿率指标要结合播放端上报看，不同播放器 SDK 的口径略有差异，比较前先统一版本。
5.2 录制缺失先查回调日志
录制备份丢失时，优先查录制回调的 POST 消息。回调体里的 event 字段记录record_started与record_end两个时间点，对比实际开播时长能判断是否中途断流；消息里的 oss_object 字段直接指向存储路径，拿它在 OSS 控制台查文件是否存在，几句话就能区分「没录上」和「路径写错」两类问题。
5.3 一条命令列出当前直播中的流
没有控制台权限或需要快速定位时，直接调在线流查询 API：
aliyun live DescribeLiveStreamsOnlineList \ --DomainName play.example.com \ --AppName live返回的 OnlineStreamInfo 数组里，PublishTime 能判断一个流是刚推起来还是推了很久。播流地址打不开但列表里有该流，说明问题在播放端；列表里没有这个流，就直接查推流进程和推流域名鉴权。把这条命令配合 4.3 的重推日志使用，绝大多数直播链路故障能在 5 分钟内完成定界。
本文还有配套的精品资源，点击获取
