简介这是一份基于Java实现的阿里云直播服务接入案例面向需要快速生成推流/拉流地址并将直播能力集成到自身应用的后端开发者或企业项目。核心演示了服务端如何调用阿里云直播SDK生成加密鉴权地址从而支撑主播推流与用户拉流等常见互动场景。整个压缩包共152个文件大小约137KB其中以Maven及IntelliJ IDEA相关XML配置为主123个XML另有18个Java源码、4个YML配置、1个properties配置、1个JAR包及帮助文档等对应项目构建、接口逻辑与开发环境配置。这份案例目前已吸引245人学习适合正在研究直播推拉流鉴权地址生成的Java开发者。通过梳理源码与工程配置可掌握pom.xml中直播SDK的引入方式、src/main/java下的工具类实现以及.gitignore、mvnw等工程化细节参考HELP.md还能快速搭建运行环境理清阿里云直播接入的必备步骤降低自行摸索成本为上线直播功能提供可落地的范例。1. citizen5zf 与阿里云直播这个案例真正要解决的是链路接入问题一个叫 citizen5zf 的直播间在阿里云直播体系里能做什么推流端用 RTMP 把画面送到 CDN播流端按设备适配 FLV、HLS 或 RTS 打开服务端再把转码、录制、截图、鉴权、数据统计这五件事一起接管。很多人上手直播的第一直觉是去调编码参数实际上一周后踩的坑全在域名绑定、CNAME 生效、鉴权签算和回调抖动上。把这几层理顺直播接入这件事就完成了一大半。这篇内容写给两种人一是被分配把直播接进来的后端或全栈工程师二是要在自建直播和云直播之间做选型的团队负责人。下文把推拉流域名、协议取舍、转码录制、回调统计这条链路按可直接照做的顺序走一遍并把 citizen5zf 当作贯穿示例的直播间标识替换成自己的业务房间号就能用。2. 阿里云直播的链路模型与协议选型推流域名为什么必须和播流域名分开2.1 一次推拉流请求的完整路径CDN 节点、域名与 StreamName 的对应关系先说链路。推流端OBS、ffmpeg、移动端推流 SDK把音视频帧封装成 RTMP 流推到指定的推流域名阿里云直播在边缘节点接收后同步流状态再按播流域名把流分发给远端用户。这里存在两条逻辑链路上行推流和下行播流绝大多数线上事故出在两条链路共用一个域名或者两套鉴权策略互相干扰。一次会话对应一个三元组域名DomainName、应用名AppName、流名StreamName。以本案例为例推流地址可以写成rtmp://live-push.example.com/live/citizen5zf其中live-push.example.com是推流域名live是 AppNamecitizen5zf是 StreamName。播流地址对应另一个播流域名形如http://live-pull.example.com/live/citizen5zf.flv。StreamName 在同一 AppName 下不能重复出现同名流时后推的一路会把先推的踢下线这个机制在做直播间重建或无人直播循环推流时尤其要留意。实际项目中AppName 一般固定成一个全局值比如live或app不要按业务方拆分业务维度留在 StreamName 里表达例如citizen5zf_room1、citizen5zf_camera2。这样做的好处是控制台排查和日志检索时过滤条件只有一个维度后续接录制、转码模板时也可以按 AppName 统一匹配。2.2 RTMP、FLV、HLS、RTS 怎么选延迟、兼容性和采集端约束直播协议决定了两头的接入方式。下面这张表是按实测经验整理的取舍不是官方参数罗列协议用途延迟体验适合的场景常见坑RTMP推流与播放端无关采集端上行的默认选择1935 端口在部分办公网络被禁FLV播流较低网页/自研播放器、低延迟直播接入播放器要明确支持 HTTP-FLVHLS播流较高切片缓冲移动端 H5、回放、弱网兜底首开等待首个关键帧切片RTSARTC推拉流超低延迟接入连麦、互动教学、赛事陪看需要集成对应音视频 SDK选型逻辑一句话概括推流无脑走 RTMPPC 端和移动 App 内的直播源用 FLVH5 页面默认 HLS连麦互动再考虑 RTS。做直播流测试时优先验证 FLV 地址而不是 HLS 地址。FLV 连接建立快能立刻暴露源流问题HLS 要等切片生产出错时你分不清是拉流问题还是切片封装问题。2.3 CNAME 绑定与直播域名规划上线前最容易被卡住的环节域名规划的顺序是先在控制台分别添加推流域名和播流域名再为两个域名各自完成 CNAME 解析。CNAME 值由控制台生成指向直播服务的调度域名这一步完成后节点才能把这两个域名纳入路由。常见错误是把解析记录填成 A 记录导致控制台一直提示 CNAME 未生效。验证命令很简单# Linux/macOS 下验证推流域名的 CNAME 是否生效 dig live-push.example.com CNAME # 期望结果里出现 CNAME 记录例如 # live-push.example.com. CNAME liveservice.cn-hangzhou.alicloud.....dig的结果里如果只有 A 记录而没有 CNAME 别名说明解析类型填错或尚未生效。确认 CNAME 正常后再去地址生成器里取推流地址。控制台生成的测试地址有有效期正式环境需要按 URL 鉴权规则自行签发格式形如rtmp://推流域名/live/citizen5zf?auth_key时间戳-随机数-uid-签名值。鉴权串在控制台里有明文的拼接模板照着模板算即可。这块顺带回应热搜里的直播源问题很多 m3u8 直播源拿回来打不开除去源本身失效另一大原因是播放端拿到的 HLS 地址里的域名没有正确接入这条链路或鉴权参数顺序不对。域名层理顺后面推拉流才有意义。3. 用控制台加 OpenAPI 跑通 citizen5zf 的推流与播流3.1 控制台开通和域名配置十分钟内能完成的四个动作第一步开通阿里云视频直播产品并完成实名认证第二步在域名管理里添加推流域名和播流域名面向国内用户播放的域名需要完成 ICP 备案第三步按控制台给出的 CNAME 值到 DNS 服务商处添加解析第四步在地址生成器里输入 AppName 与 StreamName验证推流地址和播流地址都能正常生成。这四步做通基础链路已经可用了。这个阶段容易忽略两个配置项推流域名的推流协议限制以及播流域名的访问协议放行。线上事故里最常见的现象是控制台显示流在推但播放端一直黑屏此时先检查播流域名是否放行了 FLV 或 HLS而不是急着怀疑转码。另外如果两个域名共用了同一张证书也要确认证书覆盖了live-pull.example.com这一级域名很多播放器在证书不匹配时会静默失败。3.2 用 ffmpeg 和 ffplay 完成一次 rtmp 直播流测试手边准备一个短视频素材专门用来做直播流测试。Windows 命令行和 Linux 下用同一套 ffmpeg 命令不需要额外安装图形工具。# 单文件循环推流适合无人直播或链路联调 ffmpeg -re -stream_loop -1 -i city.mp4 \ -c:v libx264 -preset veryfast -tune zerolatency \ -c:a aac -b:a 128k -f flv \ rtmp://live-push.example.com/live/citizen5zf?auth_key签名串-re让 ffmpeg 按原始帧速率读取文件否则推流速度远超实时播流端会出现跳帧-stream_loop -1让素材循环播放无人直播或长时间测试时不需要反复重启进程-tune zerolatency降低编码器缓冲对延迟敏感场景更友好。如果素材没有音轨-c:a aac会直接报错换成-an去掉音频再推。推流之后立刻用播放器验证# ffplay 直接打开 FLV 直播源 ffplay http://live-pull.example.com/live/citizen5zf.flv?auth_key签名串窗口能出画面说明推拉流链路和域名绑定全部正常。如果 ffplay 卡在 Opening 阶段把地址 query 里的鉴权参数临时去掉再试能通就是鉴权串问题不能通则回头查 CNAME 和播流域名访问限制。Windows 命令行下要注意地址中符号的转义建议整个 URL 用双引号包裹。3.3 用 OpenAPI 查在线流列表把人工验证变成程序可判断链路能跑通之后把直播间是否正在推流变成接口可查询的数据。阿里云直播提供的 DescribeLiveStreamsOnlineList 可以做到这点用 Python SDK 调用# 查询 citizen5zf 是否正在推流 from aliyunsdkcore.client import AcsClient from aliyunsdklive.request.v20161101.DescribeLiveStreamsOnlineListRequest import DescribeLiveStreamsOnlineListRequest client AcsClient(AccessKeyId, AccessKeySecret, cn-shanghai) req DescribeLiveStreamsOnlineListRequest() req.set_DomainName(live-push.example.com) req.set_AppName(live) resp client.do_action_with_exception(req) print(resp.decode(utf-8))这段代码里的 DomainName 填推流域名AppName 与推流地址保持一致。返回的OnlineStreamInfoList字段里会列出在线流的 StreamName、推流时间、编码方式。常用参数对照如下OpenAPI 请求参数含义常见误用DomainName推流域名误填播流域名导致查不到流AppName应用名与推流地址不一致导致列表为空StreamName流名可选不填时列出该域下全部在线流正式环境里鉴权用的 AccessKey 不应出现在业务代码中。常见做法是后端单独起一个直播服务用临时凭证签发地址客户端拿到的直播地址本身带短期签名双重动态下发。这样播放地址即使被完整截获过期后也无法复用。判断直播间状态也不能只依赖这个接口CDN 节点状态同步存在秒级延迟要和业务房间状态结合判断。4. 转码、录制、回调与直播数据把案例从能看变成可运营4.1 直播转码与多码率输出H.264 下 GOP 和码率怎么定当播流端规模上来后不能所有用户都拿原画地址。直播转码在服务端把一路输入转成多路不同分辨率的输出播放端按网络情况选择合适直播源。控制台先配置转码模板再绑定到对应 AppName转码后的流名会追加后缀例如citizen5zf转码后变成citizen5zf_720p。参数配置的经验值如下参数建议值说明编码方式H.264兼容性最好H.265 网页端支持仍然混乱分辨率720p 推流1080p/480p 转码上行省带宽多码率服务不同终端帧率与源流一致通常 25/30转码提高帧率没有意义关键帧间隔 GOP1-2 秒GOP 过大切片等待长过小压缩率下降码率720p 建议 1.5-2.5 Mbps按画面复杂度上下浮动GOP 是最容易被忽略的参数。如果把关键帧间隔设到 10 秒HLS 首屏最早也要等第一个切片里的关键帧出现表现为播放器一直转圈。低延迟场景建议关键帧间隔和转码切片时长对齐避免跨切片起播时的回源等待。4.2 录制到 OSS直播结束自动沉淀回放文件直播场景几乎都要回放。录制配置顺序是先创建 OSS Bucket再在视频直播控制台配置录制模板指定容器格式为 HLSm3u8或 MP4然后把模板关联到 AppName 并开启自动录制。录制文件按AppName/StreamName/录制时间戳的目录结构落盘在 OSS 里很容易定位。录制格式的选择上m3u8 适合做回放列表和分段索引边录边看MP4 对用户下载后离线观看更友好但录制结束还需要服务端完成转封装文件生成有延迟。FLV 录制保留的是原始直播流适合后续接入剪辑或内容审核流程但直接给用户播放的兼容性较差。录制开始和结束的边界由服务端判断回调里如果没有明确返回录制文件 URL需要到 OSS 目录里按时间戳自行匹配。4.3 回调事件与直播数据用事件驱动把状态同步给业务录制、转码、推流状态变化可以通过事件通知推给业务服务器。在控制台配置回调地址后推流结束、录制完成、截图完成等事件会以 HTTP POST 发送到指定 URL。回调消息体是 JSON例如推流成功事件{ Event: LiveStreamPublish, DomainName: live-push.example.com, AppName: live, StreamName: citizen5zf, PublishTime: 2025-01-01T10:00:00Z, NotifyType: publish }收到回调后业务系统把 StreamName 翻译成自己的房间号更新数据库里的开播状态。回调不是强事务消息偶发重复投递是正常的接收方要做去重网络异常时也可能丢失所以核心状态还要靠定时调用在线流列表接口做补偿。如果你要的是直播数据层面的东西可以用带宽、流量、直播观看趋势这类统计 API 拉分钟级粒度的指标做活动效果盘点。把转码、录制、回调、数据四块接进同一个业务这个案例才从能看变成可运营。5. 鉴权串偶发失效时用 curl 状态码完成一次快速定界拉流地址没变但播放器报错这个现象在直播接入里出现频率很高。此时先绕过播放器用 curl 直接访问播流地址# 直接复现鉴权结果-I 只取响应头 curl -I http://live-pull.example.com/live/citizen5zf.flv?auth_key时间戳-0-0-md5签名 # 200 表示鉴权通过403 表示签名或时间窗有问题404 表示流不存在或已超过有效期返回 200 OK 说明鉴权串本身正确问题在播放器缓存或 URL 被截断返回 403 时按四个位点排查。一是时间戳是否超过生成地址时指定的有效期直播鉴权常用 300 秒或 3600 秒超时后同一串地址必然失效二是服务端时间与本地时间偏差过大鉴权按服务器时间校验本地时钟漂移一分钟就会导致判断不一致三是 URL 经过程序拼接后是否把?、转义成了%3F、%26四是确认拼接源串里的路径与访问路径一致包括 AppName 的大小写直播服务的路径校验区分大小写。如果播流域名开了 HTTPS 重定向curl 需要加-L跟随跳转否则拿到 301 后误判成异常。抓包看实际请求也是一个思路把播放器发出去的 URL 原样复制到 curl 里重放能立刻确认是播放器改写了地址还是服务端拒绝。多语言接入时鉴权签名函数要单独隔离出来配单元测试测试用例里固定时间戳和路径保证同一组输入永远输出同一签名。这个动作能省掉后面所有联调现场反复试错的时间。本文还有配套的精品资源点击获取