Restreamer 2.12.0 API 使用详解

‍‍‌> 目标：把 Restreamer 2.12.0 的管理 API 一次讲透——路由总览与版本差异、认证启用全流程、进程流水线增删改查与生命周期控制、配置热加载、GraphQL 查询，以及一个「假目标转推校验」端到端实战——全部端点与回显在 Ubuntu 24.04 实测运行实例上逐一验证。

一、环境信息

本文所有调用与回显均在以下真实环境实测通过（实测日期 2026-10-30）：

操作系统：Ubuntu 24.04.5 LTS（x86_64）
Restreamer：2.12.0（datarhei/restreamer:2.12.0），API 基址 http://<服务器>:8080（本文实测环境宿主映射端口为 8156）
内核组件：datarhei-core 16.16.0（实测 GET /api 回显 "number":"16.16.0","commit":"6872ba0498f87eb3313d298a9046d2f5637ee136","build_date":"2024-06-07T10:01:49Z","compiler":"go1.22.4"）
实测时刻运行实例中常驻流水线：live（外部 FFmpeg 经 RTMP 入口推流自动创建，状态 running）——各回显中的 runtime_seconds 等动态字段以实测时刻为准
环境变量 RS_USERNAME=admin、RS_PASSWORD=q1w2e3r4（演示凭据），API 认证默认关闭，第四章演示开启流程

二、前置条件

服务已按[《Restreamer 2.12.0 Docker Compose 部署指南》](https://www.quzuo.net/document/3IVvGXTSwFYs)部署并可访问 /ping；
明确 API 的安全边界：默认 api.auth.enable=false，局域网内任何能访问 8080 端口的人都可以增删流水线——对外暴露前按第四章开启认证；
准备 curl（本文全部示例）或任意 HTTP 客户端；写操作（POST/PUT/DELETE）需 Content-Type: application/json 请求头。

三、API 总览与版本差异

本节先给出实测确认的路由全景，再说明与上游文档的差异——这直接影响你按官方 Swagger 抄的接口能不能跑通。

3.1 实测确认的可用路由（datarhei-core 16.16.0）

分组	路由（实测方法）	用途
探活	`GET /ping`	存活探针
实例	`GET /api`	版本/构建/运行时长概要
认证	`POST /api/login`	取 JWT（需先启用认证，见第四章）
配置	`GET/PUT /api/v3/config`、`GET /api/v3/config/reload`	读改配置与热加载
日志	`GET /api/v3/log?lines=N`	内核日志环形缓冲
存储	`GET /api/v3/fs`	存储后端清单
能力	`GET /api/v3/skills`	内置 FFmpeg 版本与滤镜目录
指标	`GET /api/v3/metrics`	指标目录（名称/描述/标签）
入口	`GET /api/v3/rtmp`、`GET /api/v3/srt`	RTMP 应用与 SRT 连接列表
会话	`GET /api/v3/session`、`GET /api/v3/session/active`	会话统计与活跃会话
挂件	`GET /api/v3/widget/process/{id}`	播放挂件统计
流水线	`GET/POST /api/v3/process`；`GET/PUT/DELETE /api/v3/process/{id}`	流水线 CRUD
生命周期	`PUT /api/v3/process/{id}/command`	start/stop/restart
流水线观测	`GET /api/v3/process/{id}/{state,config,probe,report,metadata/{key}}`	状态/配置/探针/报告/元数据
GraphQL	`GET /api/graph`（GraphiQL 界面）、`POST /api/graph/query`	图查询（第八章）

3.2 与上游 Swagger 文档的差异（选型/集成前必读）

官方上游仓库 datarhei/core 的 docs/swagger.json 定义了 38 条路径，但 2.12.0 打包的 core 16.16.0 实测少于一页文档：/api/version、/api/about、/api/swagger（内置 Swagger 页）、/metrics（Prometheus 端点）、/api/v3/fs/{storage}（存储文件读写）、/api/v3/process/{id}/progress、/api/v3/process/{id}/logs、/api/v3/process/{id}/playout/*、/api/login/refresh（未启用认证时）实测均返回 404。结论：以本文 3.1 表为该版本的可用路由基准；上游 swagger 可作未来版本升级后的对照清单（仓库地址见参考链接）。对「进程进度/日志」需求，实测用 /state（内含 progress 与 last_logline 字段）与 /api/v3/log 替代，见第六章。

四、认证流程实测

默认无认证时任何客户端可直接调用全部 API。生产化流程分四步，全部实测：

第一步：启用认证。PUT /api/v3/config 把 api.auth 改为 {"enable":true,"username":"admin","password":"q1w2e3r4"}，再热加载（实测回显 "OK"，内核重启生效，进行中流水线按 reconnect 恢复）：

curl http://127.0.0.1:8156/api/v3/config/reload

"OK"

第二步：验证拦截。生效后无凭据访问受保护端点（实测回显）：

curl -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8156/api/v3/process

{"code":401,"message":"Unauthorized","details":["Missing or invalid JWT token"]}

第三步：登录取令牌。凭据走 JSON 体，必须带 Content-Type: application/json（实测漏带该头会得到 400 {"code":400,"message":"Bad Request","details":["Missing authorization credentials"]}）：

curl -X POST http://127.0.0.1:8156/api/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}'

{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleGkiOjYwMCwiZXhwIjoxNzkzMzE5ODk3LCJpYXQiOjE3OTMzMTkyOTcsImlzcyI6ImRhdGFyaGVpLWNvcmUiLCJzdWIiOiJhZG1pbiIsInVzZWZvciI6ImFjY2VzcyJ9.5w0YbBBvzKmMuq4fUQQzYWfxYbC-x1Z4b2U4lLUBcLQ","refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleGkiOjYwMCwiZXhwIjoxNzkzMzE5ODk3LCJpYXQiOjE3OTMzMTkyOTcsImlzcyI6ImRhdGFyaGVpLWNvcmUiLCJzdWIiOiJhZG1pbiIsInVzZWZvciI6InJlZnJlc2gifQ.ZGfGBQZPzBfHX2xdVXpVHDWyOYxjb3uJnLI5EsvqbtE","expires_in":600}

第四步：携带令牌调用（实测 200）：

curl -H 'Authorization: Bearer <access_token>' http://127.0.0.1:8156/api/v3/process

[{"id":"live","type":"ffmpeg","reference":"","created_at":1793295802,…}]

验毕把 api.auth.enable 改回并 reload 即恢复无认证模式（内网环境）。注意 access_token 有效期 600 秒（实测回显 expires_in:600），到期重取。

五、系统与观测端点

5.1 探活与实例概要

curl http://127.0.0.1:8156/ping

pong

curl http://127.0.0.1:8156/api

{"app":"datarhei-core","auths":[],"name":"quiet-lake-3440","id":"f4dfa3ba-d69a-4b59-80b8-88c26011eb40","created_at":"2026-10-30T00:14:58Z","uptime_seconds":1083,"version":{"number":"16.16.0","repository_commit":"6872ba0498f87eb3313d298a9046d2f5637ee136","repository_branch":"main","build_date":"2024-06-07T10:01:49Z","arch":"linux/amd64","compiler":"go1.22.4"}}

解读：auths:[] 即认证未启用；uptime_seconds 是内核本次启动时长——巡检脚本可用它识别「内核是否被重启过」（/api/v3/config/reload 会重启内核，见第七章）。

5.2 日志、能力与指标目录

curl 'http://127.0.0.1:8156/api/v3/log?lines=2'

["ts=2026-10-30T00:14:58Z level=INFO component=\"Core\" application=\"datarhei-core\" arch=\"linux/amd64\" build=\"2024-06-07T10:01:49Z\" commit=\"6872ba0498f87eb3313d298a9046d2f5637ee136\" compiler=\"go1.22.4\" version=\"16.16.0\"","ts=2026-10-30T00:14:58Z level=INFO component=\"Core\" msg=\"Read config file\" path=\"/core/config/config.json\""]

GET /api/v3/skills 返回内置 FFmpeg 的版本、编译配置、依赖库版本与全量滤镜目录（实测回显 "version":"6.1.1"，--enable-libx264 --enable-libsrt --enable-libvpx 等）——编排转码流水线前先查它确认目标编码器/滤镜可用，避免创建后 FFmpeg 报「Unknown encoder」。

GET /api/v3/metrics 返回指标目录（该版本无 Prometheus 抓取端点，目录供对接参考），实测节选：

[{"name":"cpu_idle","description":"Percentage of idle CPU","labels":[]},{"name":"cpu_ncpu","description":"Number of logical CPUs in the system","labels":[]},…]

5.3 会话与流媒体入口观测

curl http://127.0.0.1:8156/api/v3/rtmp

[{"name":"/live/test.stream"}]

curl http://127.0.0.1:8156/api/v3/srt

{"publisher":{},"subscriber":{},"connections":{},"log":{}}

curl http://127.0.0.1:8156/api/v3/session

{"":{"active":{"list":[],"sessions":0,"bandwidth_rx_mbit":0,"bandwidth_tx_mbit":0,"max_sessions":0,"max_bandwidth_rx_mbit":0,"max_bandwidth_tx_mbit":0},"summary":{"remote":{},"local":{},"reference":{},"sessions":0,"traffic_rx_mb":0,"traffic_tx_mb":0}}}

解读：/api/v3/rtmp 列出当前 RTMP 服务端上的应用路径（有推流者注册才出现，实测 /live/test.stream）——巡检「入站推流是否在」比看流水线更直接；/api/v3/session 的 active.sessions 是观看会话数、summary.traffic_* 是累计收发流量（对接自建监控面板的数据源）。GET /api/v3/widget/process/{id} 返回播放挂件统计（实测 {"current_sessions":0,"total_sessions":0,"uptime":1281}）。

六、进程流水线端点

6.1 数据模型与自动创建

流水线（process）= 1 个输入 + N 个输出 + FFmpeg 选项，实测查看当前流水线（经 RTMP 推流后 core 自动创建）：

curl http://127.0.0.1:8156/api/v3/process

[{"id":"live","type":"ffmpeg","reference":"","created_at":1793295802,"updated_at":1793295802,
  "config":{"id":"live","type":"ffmpeg","reference":"",
    "input":[{"id":"input_0","address":"rtmp://localhost:1935/live/test.stream","options":[]}],
    "output":[{"id":"output_0","address":"{memfs}/live.m3u8",
      "options":["-map","0:v","-map","0:a","-c","copy","-f","hls","-start_number","0","-hls_time","2","-hls_list_size","6","-hls_flags","append_list+delete_segments"]}],
    "reconnect":true,"reconnect_delay_seconds":5,"autostart":true}}]

解读要点：入站 RTMP 推流会自动创建这条流水线（input 指向内部 RTMP 地址，output 的 {memfs} 是内存文件系统占位符，HLS 参数 2 秒分片）；autostart:true 使内核每次启动都拉起它。转推到外部平台 = 在 output 数组追加一个 rtmp:///srt:// 地址，或单建一条「输入取 memfs、输出指外部」的流水线。

6.2 增删改查与生命周期（实测全流程）

用一条 memfs→memfs 的转码流水线演示完整生命周期（输入拉主清单、输出另存 copy.m3u8）：

curl -X POST http://127.0.0.1:8156/api/v3/process \
  -H 'Content-Type: application/json' -d '{
  "id":"loop-copy","type":"ffmpeg","reference":"",
  "input":[{"id":"input_0","address":"http://localhost:8080/memfs/live.m3u8","options":[]}],
  "output":[{"id":"output_0","address":"{memfs}/copy.m3u8",
    "options":["-c","copy","-f","hls","-hls_time","2","-hls_list_size","6","-hls_flags","append_list+delete_segments"]}],
  "reconnect":true,"reconnect_delay_seconds":2,"autostart":true}'

（HTTP 200，回显完整流水线对象；autostart:true 即自动拉起）

验证运行态 → 重启 → 停止 → 删除（实测逐条回显）：

curl http://127.0.0.1:8156/api/v3/process/loop-copy/state

{"order":"start","exec":"running","runtime_seconds":6,"reconnect_seconds":-1,
 "last_logline":"[hls @ 0x7ddc82e5a840] Opening 'http://admin:q1w2e3r4@localhost:8080/memfs/copy3.ts' for writing"}

注意 last_logline 中 FFmpeg 访问 memfs 时由内核自动注入了存储认证凭据——这是流水线与 memfs 鉴权的联动机制，凭据不会出现在流水线配置里。

curl -X PUT http://127.0.0.1:8156/api/v3/process/loop-copy/command \
  -H 'Content-Type: application/json' -d '{"command":"restart"}'

"OK"

curl -X PUT http://127.0.0.1:8156/api/v3/process/loop-copy/command \
  -H 'Content-Type: application/json' -d '{"command":"stop"}'

"OK"

停止后 GET /api/v3/process/loop-copy/state 实测回显 "exec":"finished"；删除与确认：

curl -X DELETE http://127.0.0.1:8156/api/v3/process/loop-copy

"OK"

curl -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8156/api/v3/process/loop-copy

{"code":404,"message":"Unknown process ID","details":["unknown process"]}

生命周期命令实测小结：command 仅接受 start/stop/restart（PUT /api/v3/process/{id}/command）；修改流水线配置用 PUT /api/v3/process/{id}（改完自动按新配置重启该流水线）；POST /api/v3/process 是唯一创建入口（对已存在 id 返回 409，实测同 id 重复创建被拒绝）。

6.3 观测端点：state / config / probe / report / metadata

端点	实测回显要点
`GET …/{id}/state`	`order/exec/runtime_seconds/reconnect_seconds/last_logline/progress{inputs[],outputs[]}`，巡检主数据源（`exec: running/finished/failed`）
`GET …/{id}/config`	流水线当前生效配置（与 6.1 结构一致）
`GET …/{id}/probe`	对输入地址探测流参数：实测回显 `"codec":"h264","fps":25,"width":640,"height":360,"type":"video"`（音视频逐条列出）
`GET …/{id}/report`	FFmpeg 报告：实测回显 `prelude` 含 `"ffmpeg version 6.1.1-datarhei"` 与完整编译配置
`GET/PUT …/{id}/metadata/{key}`	流水线级自定义键值（实测未设置时返回 `null`）

七、配置端点与热加载

curl http://127.0.0.1:8156/api/v3/config

{"created_at":"2026-10-30T00:14:57.766181348Z","loaded_at":"2026-10-30T00:14:58.540430933Z","updated_at":"…",
 "config":{ …主配置全文，结构见配置参数详解篇… },
 "overrides":["db.dir","api.auth.username","api.auth.password","storage.disk.dir","storage.memory.auth.username","storage.memory.auth.password","rtmp.enable","srt.enable","router.ui_path"]}

解读：config 是生效配置全文；overrides 列出被环境变量覆盖的键（本文部署设了 CORE_RTMP_ENABLE 等，故 rtmp.enable 在列）——修改配置前先看 overrides，被覆盖的键改文件无效。修改配置：PUT /api/v3/config（JSON 体为完整配置对象）即改内存并回写 config.json；GET /api/v3/config/reload 从文件重读并重启内核（实测回显 "OK"）。两者都会触发内核重启（Swagger 描述原文 "This will trigger a restart of the Core."），流水线短暂中断后自动恢复。参数语义逐项见[《Restreamer 2.12.0 配置参数详解》](https://www.quzuo.net/document/u6Yi2xGp3c4T)。

八、GraphQL 端点

打包版自带 GraphiQL 交互界面（浏览器打开 GET /api/graph）与查询端点，适合一次取多对象的集成场景。实测流程：先内省拿 schema，再查询：

curl -X POST http://127.0.0.1:8156/api/graph/query \
  -H 'Content-Type: application/json' \
  -d '{"query":"{process(id:\"live\"){id state{state runtime_seconds memory_bytes cpu_usage}}}"}'

{"data":{"process":{"id":"live","state":{"state":"running","runtime_seconds":1318,"memory_bytes":23556096,"cpu_usage":0}}}}

解读：Process 类型实测可查字段 id/type/reference/created_at/config/state/report/metadata，ProcessState 可查 order/state/runtime_seconds/reconnect_seconds/last_logline/progress/memory_bytes/cpu_usage/command——写错字段名会得到带 GRAPHQL_VALIDATION_FAILED 的报错并列出位置，配合内省查询 {__type(name:"ProcessState"){fields{name}}} 可自举探索全部 schema。

九、端到端实战：假目标转推校验

场景：上线「转推到外部平台」前，先用不可达目标验证失败路径与告警链路（不真推第三方）。实测全程：

1. 负例校验（缺 input/output 的非法创建，实测回显）：

curl -X POST http://127.0.0.1:8156/api/v3/process \
  -H 'Content-Type: application/json' -d '{"id":"bad-no-type"}'

{"code":400,"message":"Bad Request","details":["[Input] required","[Output] required"]}

2. 建立假目标转推（输出指向端口 9 的不可达地址）：

curl -X POST http://127.0.0.1:8156/api/v3/process \
  -H 'Content-Type: application/json' -d '{
  "id":"push-fake-target","type":"ffmpeg","reference":"",
  "input":[{"id":"input_0","address":"http://localhost:8080/memfs/live.m3u8","options":[]}],
  "output":[{"id":"output_0","address":"rtmp://127.0.0.1:9/live/fake-key","options":["-c","copy","-f","flv"]}],
  "reconnect":true,"reconnect_delay_seconds":2,"autostart":true}'

（HTTP 200；10 秒后查状态）

curl http://127.0.0.1:8156/api/v3/process/push-fake-target/state

{"order":"start","exec":"failed","reconnect_seconds":2,
 "last_logline":"Error opening output files: Connection refused"}

3. 清理（实测回显 "OK"，再 GET 得 404）：

curl -X DELETE http://127.0.0.1:8156/api/v3/process/push-fake-target

实测结论：目标不可达时流水线进入 exec:"failed" 且按 reconnect_delay_seconds:2 自动重试（reconnect_seconds:2 回显）——巡检脚本对 exec:failed 告警即可覆盖「转推断链」场景；日志关键字 Error opening output files 区分于入站断流的 Error opening input files。

十、外部集成与巡检脚本

该打包版本无 Prometheus 端点（实测 /metrics 404，指标能力以 /api/v3/metrics 目录与 /api/v3/session 统计为准），推荐用脚本轮询 /state 做巡检。生产可用的最小巡检脚本（crontab 每 5 分钟）：

#!/bin/bash
# restreamer-inspect.sh —— 巡检全部流水线与入站会话
API="http://127.0.0.1:8156"
for id in $(curl -s $API/api/v3/process | grep -o '"id":"[^"]*"' | cut -d'"' -f4); do
  exec=$(curl -s $API/api/v3/process/$id/state | grep -o '"exec":"[^"]*"' | cut -d'"' -f4)
  echo "$(date +%FT%T) process=$id exec=$exec"
  [ "$exec" != "running" ] && echo "ALERT: $id not running" # 接你的告警通道
done
curl -s $API/api/v3/rtmp || echo "ALERT: rtmp entry empty"

实测口径说明：exec 取值 running（在跑）/finished（手动 stop 后）/failed（异常退出待重连）；/api/v3/rtmp 返回空数组即「无任何入站推流」。两判据组合可覆盖「流水线挂了」与「推流端断了」两类故障。集成提醒：/api/v3/config/reload 与 PUT /api/v3/config 会重启内核并使 JWT 会话失效，自动化里避免高频调用。

十一、常见问题（FAQ）

Q1：按上游 Swagger 文档抄的接口 404？

见 3.2——2.12.0 打包版 core 16.16.0 的路由集小于上游 swagger.json（/api/about、/metrics、/api/v3/fs/{storage}、/{id}/progress、/{id}/logs 等实测 404）。以本文 3.1 表为准；升级到更新内核后可用上游文档对照。

Q2：/api/login 一直 400？

实测两种原因：漏带 Content-Type: application/json 头（报 Missing authorization credentials）；或认证未启用（api.auth.enable=false 时 /api/login 路由不存在，404）。先 GET /api/v3/config 看 api.auth.enable。

Q3：删除流水线后它又出现了？

两条路都会「复活」：入站 RTMP 推流仍连着（core 自动重建对应流水线）——先断推流端再删；或 autostart:true 且 DB 中有持久化记录——先 PUT 该流水线把 autostart 改 false 再删。

Q4：改了配置 API 行为没变？

PUT /api/v3/config 写内存即生效；若改的是 config.json 文件则必须调 GET /api/v3/config/reload（回显 "OK"）。两处都会重启内核，调用后 JWT 失效、流水线短暂中断——实测建议变更窗口内执行并随后复核 GET /api 的 uptime_seconds 归零确认重启完成。

十二、参考链接

上游 API 权威定义（datarhei/core 仓库 swagger.json，38 条路径）：https://github.com/datarhei/core
官方文档站 API 章节：https://docs.datarhei.com/restreamer
本平台系列：[《Restreamer 介绍与选型指南》](https://www.quzuo.net/document/T9V4T9qaPrlq)、[[《Restreamer 2.12.0 Docker Compose 部署指南》](https://www.quzuo.net/document/3IVvGXTSwFYs)](https://www.quzuo.net/document/3IVvGXTSwFYs)、[[《Restreamer 2.12.0 配置参数详解》](https://www.quzuo.net/document/u6Yi2xGp3c4T)](https://www.quzuo.net/document/u6Yi2xGp3c4T)