企业官网建设流程全解析

Monibuca gRPC API完全参考：跨语言调用流媒体服务的终极指南

【免费下载链接】monibucaMonibuca（简称 m7s）是一款纯 Go 开发的开源流媒体服务器开发框架。项目地址: https://gitcode.com/langhuihui/monibuca

Monibuca（简称 m7s）是一款纯 Go 开发的开源流媒体服务器开发框架，其内置的gRPC API让你可以用任意编程语言（Python、Java、Node.js、C# 等）像调用本地函数一样，远程管理流媒体服务：拉流、推流、录像、查询在线流列表、控制任务……本文带你从零开始，完整掌握 Monibuca 的 gRPC 接口体系。

一、为什么用 gRPC 调用流媒体服务？

很多流媒体服务器只提供 HTTP 接口，参数松散、没有类型约束。而 Monibuca 的 gRPC API 带来三大优势：

• 🚀强类型契约：接口定义在 pb/global.proto 等 proto 文件中，请求/响应字段一目了然，不会拼错参数名
• 🌍跨语言客户端：同一套 proto 文件可生成 Python、Java、C++ 等各语言 SDK，一份定义，处处调用
• 🔁双协议复用：Monibuca 的 gRPC 服务同时生成了 HTTP Gateway（见 scripts/protoc.sh），同一个接口既能用 gRPC 调用，也能用普通 HTTP 调用

二、服务端口与鉴权：连接前的两件事

2.1 监听端口在哪配置？

gRPC 服务复用全局 TCP 配置，监听端口在配置文件global.tcp中指定（定义见 pkg/config/tcp.go）：

global: tcp: listenaddr: :8080 # gRPC / HTTP 服务监听地址 listentls: :8443 # 启用 TLS 时的监听地址

默认情况下，gRPC 与 HTTP 接口都走8080 端口，客户端连接127.0.0.1:8080即可。

2.2 开启登录后的 Token 机制

如果服务端开启了管理员登录（admin.enable_login），所有 gRPC 调用都需要在请求头携带 JWT Token：

authorization: Bearer <你的token>

• 通过 pb/auth.proto 中的Auth.Login接口（用户名+密码）获取 Token
• Token 有效期 24 小时，服务端会在临近过期时通过响应头new-token自动下发新 Token
• 鉴权拦截器实现见 server_grpc.go，登录接口本身无需鉴权

💡 未开启登录时，任何调用都以 anonymous 身份直接放行，开发环境可以省去这一步。

三、核心 API 速查表：全局服务 28 个方法

核心接口全部定义在 pb/global.proto 的global.api服务中，按功能可分为 6 大类：

每个方法都同时暴露了对应的 HTTP 路径，例如StreamList对应GET /api/stream/list，你可以用浏览器或 curl 直接验证。

跨语言调用示例（Python）

import grpc from pb import global_pb2, global_pb2_grpc channel = grpc.insecure_channel("127.0.0.1:8080") stub = global_pb2_grpc.ApiStub(channel) res = stub.StreamList(global_pb2.StreamListRequest(pageNum=1, pageSize=10)) print(res.data) # 当前在线流列表

生成代码的方式很简单：拿到 proto 文件后运行protoc即可，仓库内置的生成脚本 scripts/protoc.sh 展示了完整的参数配置（--go-grpc_out+--grpc-gateway_out一次生成 gRPC 与 HTTP 两套代码）。

四、插件 API：每个插件都有独立的服务

Monibuca 采用插件化架构，每个插件自带一套 gRPC 服务，接口定义在各自的pb/目录中：

• 📼FLV 插件：plugin/flv/pb/flv.proto ——StartRecord开始录像、List查询录像文件
• 📡RTMP 插件：plugin/rtmp/pb/rtmp.proto ——PushOut将流转发到其他 RTMP 地址
• 🎥GB28181 插件：plugin/gb28181/pb/gb28181.proto —— 60+ 个方法，覆盖设备管理、PTZ 云台控制、广播、录像下载
• ⏰定时任务：plugin/crontab/pb/crontab.proto —— 增删改查录像计划
• 🔍调试插件：plugin/debug/pb/debug.proto —— 获取 CPU/堆内存分析图

插件 gRPC 服务的注册机制很简洁：插件在InstallPlugin时传入自己 proto 生成的ServiceDesc即可挂载到同一端口，无需单独配置端口号。详细说明见 doc_CN/arch/grpc.md。

五、响应规范与错误处理

所有响应结构体遵循统一的三段式设计：

code // 状态码，0 表示成功 message // 提示信息 data // 业务数据

跨语言调用时只需判断code是否为 0，再用data即可，各语言处理逻辑完全一致。错误场景下服务端直接返回 gRPC 标准错误码（如UNAUTHENTICATED、NOT_FOUND），无需解析自定义格式，框架统一处理（机制见 doc/arch/grpc.md）。

六、最佳实践清单

1. 一次生成，多语言复用：将 proto 文件纳入版本管理，各语言团队用同一份文件生成客户端
2. 合理设置超时：查询类接口建议 3~5 秒超时，控制类（如StartPull）建议 10 秒
3. 生产环境启用 TLS：配置listenaddrtls并挂载证书，避免 Token 明文传输
4. 善用分页参数：StreamList、GetSubscribers等均支持pageNum/pageSize，避免大列表拉取
5. 先查后控：执行StopTask、DeleteRecord等破坏性操作前，先用TaskTree、GetRecordList确认目标

从查询在线流到一键录像，从 Python 脚本到 Java 平台，Monibuca 的 gRPC API 为跨语言集成流媒体能力提供了最直接的通道——打开 pb/global.proto，你的多语言流媒体集成之旅就从此开始。

【免费下载链接】monibucaMonibuca（简称 m7s）是一款纯 Go 开发的开源流媒体服务器开发框架。项目地址: https://gitcode.com/langhuihui/monibuca