Restreamer 2.12.0 配置参数详解

‍‍‌> 目标：逐项拆解 Restreamer 2.12.0 的主配置文件 config.json 全部配置段与环境变量覆盖机制，覆盖查看/修改/热加载三种途径与两套生产模板——全部参数取值取自 Ubuntu 24.04 实测运行实例的实际配置，关键行为（环境变量覆盖优先级、认证启用、热加载重启）均实测验证。

一、环境信息

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

操作系统：Ubuntu 24.04.5 LTS（x86_64）
Restreamer：2.12.0（datarhei/restreamer:2.12.0，内核 datarhei-core 16.16.0，启动日志实测回显）
配置文件位置：/core/config/config.json（容器内路径；宿主持久化目录按[《Restreamer 2.12.0 Docker Compose 部署指南》](https://www.quzuo.net/document/3IVvGXTSwFYs)为 /opt/restreamer/config）
实测配置版本：config.json 顶层 version: 3（schema 版本，首次启动自动生成）
API 认证/热加载等行为验证均在运行实例上完成，回显逐行照抄

二、前置条件

已按部署指南完成服务安装并能访问 http://<服务器>:8080（实测环境映射到 8156）；
知晓三个修改入口的分工：环境变量（部署期）、config.json（持久化细粒度）、REST API/Web 界面（运行期）；三者优先级见第三章；
修改配置前备份 config.json（cp config.json config.json.bak）——错误配置会导致服务无法启动，回退靠备份文件。

三、参数查看与修改方式

本节先把「配置从哪看、从哪改、改了怎么生效」讲清，后面章节才好逐项展开。

3.1 查看当前生效配置

最权威的方式是 REST API——返回的是运行中生效的配置（含环境变量覆盖后的最终值）。实测回显（节选）：

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":{"name":"quiet-lake-3440","address":":8080","log":{"level":"info","max_lines":1000},…},
 "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=true 等部署变量，故 rtmp.enable、db.dir 等 9 个键在列）——这是排障「改了文件不生效」的第一入口。

3.2 三种修改途径与优先级

途径	生效方式	适用场景
环境变量 `CORE_<路径>`	部署期，随服务启动固化，覆盖 config.json 同名键	开关类、目录类、凭据类部署常量
config.json 文件	编辑后 `GET /api/v3/config/reload` 热加载	细粒度参数（日志、会话、限流、TLS）
REST API/Web 界面	`PUT /api/v3/config` 即改内存并回写文件	运行期调整、自动化脚本

环境变量 > config.json 的覆盖关系有实测铁证：本文实例首次启动时 config.json 文件里 rtmp.enable 值为 false，但因部署时设了 CORE_RTMP_ENABLE=true，服务日志实测回显 RTMP 服务已启动：

ts=2026-10-29T17:38:53Z level=INFO component="RTMP" msg="Server started" address=":1935"

同理，文件里 storage.memory.auth.password 首次启动时是自动生成的随机串（实测首启快照为 a1j8I94YEd0Mt1E3Yq），被 CORE_STORAGE_MEMORY_AUTH_PASSWORD 覆盖后实际生效为部署设定的值。另有一个实测发现要特别提醒：经 PUT /api/v3/config 修改配置时，内核会把环境变量解析后的最终值回写 config.json（对比本文首启快照与当前文件，db.dir、rtmp.enable、storage.disk.dir、router.ui_path 等 9 个键的文件值都被规范化为生效值）——但 overrides 数组仍持续声明这些键受环境控制，文件值仅供参考。结论：改文件前先查 overrides 清单，键被覆盖时改环境变量才有效。

3.3 修改与热加载实测

API 方式（改内存 + 回写文件，实测）：

curl -X PUT http://127.0.0.1:8156/api/v3/config \
  -H 'Content-Type: application/json' -d @config.json

（HTTP 200，返回更新后的完整配置对象）

文件方式改完后触发热加载（实测回显）：

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

"OK"

⚠️ 注意：热加载会重启内核进程（Swagger 描述原文 "This will trigger a restart of the Core."），进行中的推流水线短暂中断后按 reconnect 策略自动恢复；Web 界面会话需重新登录。

四、参数总览

config.json 共 21 个顶层键（实测全文统计），按职能分组如下：

分组	顶层键	职能
身份与入口	`id`、`name`、`address`、`update_check`、`host`	服务实例标识、HTTP 监听入口、版本检查
日志与数据	`log`、`db`	内核日志级别/容量、内置数据库目录
控制面	`api`、`router`	REST API 鉴权与访问控制、UI 路由
安全接入	`tls`	HTTPS 监听与证书
存储与分发	`storage`	磁盘/内存两级存储、缓存、CORS、S3
流媒体入口	`rtmp`、`srt`	RTMP(S)/SRT 服务端开关、端口、令牌
执行器	`ffmpeg`	FFmpeg 二进制、进程数上限、进出地址白名单、日志
监控与会话	`metrics`、`debug`、`sessions`、`playout`、`service`	指标采集、性能剖析、观看会话统计与限流、临时播放会话、云服务上报

如何读这张表：控制面（api/tls/storage）决定「谁能访问、走什么协议」；流媒体入口（rtmp/srt）决定「流从哪进来」；执行器（ffmpeg）决定「流怎么被处理」——三类键合起来就是一次完整直播链路的全部配置点。

五、核心参数分类详解

5.1 身份与入口：id / name / address / update_check / host

实测配置原文（节选）：

{
    "id": "f4dfa3ba-d69a-4b59-80b8-88c26011eb40",
    "name": "quiet-lake-3440",
    "address": ":8080",
    "update_check": true,
    "host": { "name": [], "auto": true }
}

逐项解读：

id：实例 UUID，首次启动生成且不可改（内置数据库用它绑定数据）；
name：实例显示名，首次启动自动起随机名（实测 quiet-lake-3440），集群/多实例场景建议改成有语义的名字（如 edge-office-01）；
address：HTTP 总入口监听地址。一个端口承载 Web 界面、REST API、HLS 分发三重身份，:8080 表示全部网卡；只内网可改 127.0.0.1:8080 收紧；
update_check：启动时向官方检查新版本，内网隔离环境改 false 消除外呼；
host.name + host.auto：播放页/嵌入代码自动生成的主机名列表，auto: true 按请求 Host 头自适应（默认即可，固定域名分发时把域名写进 name 数组）。

5.2 日志：log

"log": { "level": "info", "topics": [], "max_lines": 1000 }

逐项解读：level 支持 debug/info/warn/error（排障改 debug，实测默认 info 已包含推拉流会话明细，见部署指南第九章日志样例）；topics 按组件过滤日志（留空即全部）；max_lines 是 API /api/v3/log 内存环形缓冲行数（默认 1000，够一次完整排障回看）。

5.3 数据库：db

"db": { "dir": "./config" }

解读：内置数据库（管理员账号、流水线定义、播放器页面）的落盘目录，默认 ./config 即 /core/config——与主配置同目录，所以部署指南强调「整个 /core/config 目录必须持久化」。该键没有单独改值的必要：改了会与挂载路径错位，除非容器内路径同步调整。

5.4 控制面：api（REST API 鉴权与访问控制）

实测配置原文（全文保留）：

"api": {
    "read_only": false,
    "access": {
        "http":  { "allow": [], "block": [] },
        "https": { "allow": [], "block": [] }
    },
    "auth": {
        "enable": false,
        "disable_localhost": false,
        "username": "",
        "password": "",
        "jwt": { "secret": "/J4&m/t$<.;C]w,kJWw,k+hS%=V.dfh:" },
        "auth0": { "enable": false, "tenants": [] }
    }
}

逐项解读：

read_only：true 时 API 只读（监控场景把只读账号给采集器，防误删流水线）；
access.http.allow/block：按 IP/CIDR 的 API 访问控制（留空即不限制；block 优先于 allow）；
auth.enable：API 认证总开关，默认 false——局域网内免认证，对外暴露前必须开启（实测行为：false 时 GET /api/v3/process 无凭据 200；改 true 并 reload 后实测返回 401 {"code":401,"message":"Unauthorized","details":["Missing or invalid JWT token"]}）；
auth.username/password：本地认证账号（演示值 admin/q1w2e3r4，生产务必改强口令）；
auth.jwt.secret：JWT 签名密钥，首次启动自动生成随机串（实测见上），泄露等于 API 全面沦陷，勿提交到代码库；
auth.disable_localhost：true 时连本机请求也要认证（安全收敛场景用，默认 false 方便本机探针）；
auth.auth0：对接 Auth0 外部身份源的开关与租户配置（本文未启用）。

认证启用后的登录流程实测（凭据为 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…","refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.…","expires_in":600}

之后带 Authorization: Bearer <access_token> 访问 API（实测回显 200）。完整端点用法见《Restreamer 2.12.0 API 使用详解》。

5.5 安全接入：tls

"tls": {
    "address": ":8181",
    "enable": false,
    "auto": false,
    "email": "cert@datarhei.com",
    "cert_file": "",
    "key_file": ""
}

逐项解读：address HTTPS 监听端口（默认 8181，与 8080 并存）；enable 总开关（实测默认关闭，8181 仅明文镜像）；auto: true 走 Let's Encrypt 自动签发（需公网可达 80 端口与 email）；cert_file/key_file 手工证书路径（自签或商业证书场景）。生产对公网分发时建议 enable: true + 固定证书，并把 Web 界面嵌入的播放地址同步改成 https。

5.6 存储与分发：storage（本组件配置量最大的一段）

实测配置原文（全文保留）：

"storage": {
    "disk": {
        "dir": "./data",
        "max_size_mbytes": 0,
        "cache": {
            "enable": true,
            "max_size_mbytes": 0,
            "ttl_seconds": 300,
            "max_file_size_mbytes": 1,
            "types": { "allow": [], "block": [".m3u8", ".mpd"] }
        }
    },
    "memory": {
        "auth": { "enable": true, "username": "admin", "password": "q1w2e3r4" },
        "max_size_mbytes": 0,
        "purge": false
    },
    "s3": [],
    "cors": { "origins": ["*"] },
    "mimetypes_file": "./mime.types"
}

逐项解读：

disk.dir：磁盘存储目录（memfs 产物同步落点，实测默认 ./data 即 /core/data）；disk.max_size_mbytes 磁盘配额（0 不限，共享磁盘时务必设上限防打满）；
disk.cache：磁盘读缓存——从磁盘读文件时先入内存缓存。ttl_seconds: 300 缓存有效期；max_file_size_mbytes: 1 单文件超过 1MB 不缓存；types.block 明确把 .m3u8/.mpd 清单排除在缓存外（清单要求始终最新，缓存会造成播放器拿到旧分片列表）。录像回放为主时调大 ttl_seconds 可显著降 IO，纯直播可维持默认；
memory：memfs（内存文件系统）配置。auth.enable/username/password 控制 HLS 等内存产物的读认证——实测未带凭据访问 /memfs/live.m3u8 返回 200，是因为播放链路走「主清单下发 session= 令牌 → 令牌换分片」的会话机制（见 5.6 末尾说明）；直接裸拉分片时该凭据才强制生效；max_size_mbytes 内存配额（0 不限，多路高码率直播建议按「码率 × 缓冲秒数 × 路数」估算后设上限，防内存打爆）；purge: false 重启不自动清空 memfs 持久化产物；
s3：S3 兼容对象存储归档（数组，可配多目标；本文未启用，无本地实测）；
cors.origins：HLS 等静态分发的 CORS 白名单，默认 ["*"] 全放开——嵌入到自己网站播放必须放行你的站点域名，生产收敛为具体域名列表；
mimetypes_file：MIME 类型映射文件路径（发行包自带 mime.types）。

💡 技术拓展：HLS 分发的鉴权有两种主流做法——「签名 URL」（服务端下发带令牌的清单，播放器透明续期）与「每请求认证」（代理层校验 Cookie/Token）。Restreamer 采用前者（实测主清单返回 live.m3u8?session=…），优点是嵌入播放零配置，代价是令牌外泄期间任何人可拉流（配合短 session_timeout_sec 收敛）。

5.7 RTMP 服务端：rtmp

"rtmp": {
    "enable": false,
    "enable_tls": false,
    "address": ":1935",
    "address_tls": ":1936",
    "app": "/",
    "token": ""
}

逐项解读：enable 内置 RTMP 服务端开关（本文实测实例由 CORE_RTMP_ENABLE=true 环境变量覆盖为开启，文件值仍为 false——第三章的优先级实证）；enable_tls + address_tls 启用 RTMPS（1936）；app 接受推流的应用前缀（默认 / 即任意 path 都建流，实测推 rtmp://…/live/test.stream 自动建 live 流水线）；token 推流令牌——非空时推流地址须带 ?token=<值>，是防恶意推流最简单有效的一道闸，公网入站强烈建议设置。

5.8 SRT 服务端：srt

"srt": { "enable": false, "address": ":6000", "passphrase": "", "token": "", "log": { "enable": false, "topics": [] } }

逐项解读：enable 开关（实测实例由 CORE_SRT_ENABLE=true 覆盖开启，GET /api/v3/srt 实测返回 {"publisher":{},"subscriber":{},"connections":{}} 证明服务在线）；address 监听端口（UDP，compose 映射必须带 /udp）；passphrase SRT 加密口令（发布端与拉流端两侧一致才能建连）；token 与 RTMP 同理的拉/推令牌。公网弱网回传场景（异地导播）比 RTMP 抗丢包，但两侧都要配口令。

5.9 执行器：ffmpeg

"ffmpeg": {
    "binary": "ffmpeg",
    "max_processes": 0,
    "access": {
        "input":  { "allow": [], "block": [] },
        "output": { "allow": [], "block": [] }
    },
    "log": { "max_lines": 50, "max_history": 3 }
}

逐项解读：binary FFmpeg 可执行文件路径（发行包内置定制版，输出结构化 JSON 进度供界面展示，不要替换成系统版，会丢失进度回传）；max_processes 并发流水线上限（0 不限，多租户/防失控场景建议设为物理核数相关值）；access.input/output 按协议+地址的黑白名单（实测默认全空即不限制），公网环境下把 output.block 用于禁止流水线把流推到任意地址是防数据外带的关键闸；log.max_lines/max_history 每条流水线的 FFmpeg 日志环形缓冲行数与保留代数（界面「日志」页的数据源）。

5.10 监控与剖析：metrics / debug

"metrics": { "enable": false, "enable_prometheus": false, "range_sec": 300, "interval_sec": 2 },
"debug": { "profiling": false, "force_gc": 0, "memory_limit_mbytes": 0 }

逐项解读：metrics.enable 打开内置指标采集（Web 界面图表数据源），enable_prometheus 额外暴露 /metrics 端点给 Prometheus 抓取；range_sec/interval_sec 指标保留窗口与采样间隔（默认 300 秒窗口、2 秒粒度，长趋势靠外部 Prometheus）。debug.profiling 打开 Go pprof 性能剖析（/profiling 端点，仅排障时临时开启）；debug.memory_limit_mbytes 内存软限（0 不限，配合容器内存限额使用）。

5.11 观看会话与会话限流：sessions

"sessions": {
    "enable": true,
    "ip_ignorelist": ["127.0.0.1/32", "::1/128"],
    "session_timeout_sec": 30,
    "persist": false,
    "persist_interval_sec": 300,
    "max_bitrate_mbit": 0,
    "max_sessions": 0
}

逐项解读：enable 观看会话统计（Web 界面「观众数」的数据源，实测默认开启）；ip_ignorelist 不计为观众的地址（默认两个环回地址，本机监控探针不污染观众数，按需加入反代/采集器地址）；session_timeout_sec 会话无活动判定超时（观众关页后 30 秒人数回落）；persist/persist_interval_sec 会话数据落盘持久化与间隔（重启不丢历史，按需开启）；max_bitrate_mbit/max_sessions 单会话/总会话硬限流（0 不限，公网开放时设 max_sessions 防盗刷打满带宽）。

5.12 其余两键：service / playout / router

"service": { "enable": false, "token": "", "url": "https://service.datarhei.com" },
"playout": { "enable": false, "min_port": 0, "max_port": 0 },
"router": { "blocked_prefixes": ["/api"], "routes": {}, "ui_path": "" }

逐项解读：service 是 datarhei 官方云监控/远程管理服务的上报开关（默认关，内网环境保持关闭无外呼）；playout 临时播放会话（Playout API）的端口区间，默认关闭，本文未启用；router 是 Web 服务器的路由定制——blocked_prefixes 默认禁掉把 /api 当普通路径转发（保护 API 不被外部路径伪装），routes 可挂自定义反向代理路由（如把 /stream 指到别的内部服务），ui_path 覆盖界面资源目录（发行层已用环境变量 CORE_ROUTER_UI_PATH=/core/ui 指定，此处留空即继承）。

六、生产配置模板

以下两套模板基于本文实测参数整理，标明适用资源规格，直接替换对应段即可。

6.1 小型网站直播（1-3 路流、观众 < 200）：4 GB 内存 / 40 GB SSD

{
    "name": "live-edge-01",
    "address": ":8080",
    "log": { "level": "info", "max_lines": 1000 },
    "api": { "auth": { "enable": true, "username": "admin", "password": "q1w2e3r4",
                       "jwt": { "secret": "请用 openssl rand -base64 48 生成后替换" } } },
    "rtmp": { "enable": true, "token": "请自行生成推流口令" },
    "storage": { "disk": { "dir": "./data", "max_size_mbytes": 20480 },
                 "memory": { "max_size_mbytes": 1024 },
                 "cors": { "origins": ["https://www.example.com"] } },
    "sessions": { "max_sessions": 200 },
    "ffmpeg": { "max_processes": 4 }
}

适用说明：API 认证必开（模板含 JWT 密钥生成命令提示）、RTMP 入站加 token、存储双配额防打满、CORS 收敛到自己站点、观众与流水线双双限额——即第三章实测确认过的四个「默认裸奔」点的收敛形态。

6.2 内网单节点（监控回传/实验室）：2 GB 内存 / 20 GB SSD

{
    "name": "lab-restreamer",
    "address": "127.0.0.1:8080",
    "update_check": false,
    "api": { "auth": { "enable": false } },
    "rtmp": { "enable": true },
    "metrics": { "enable": true, "enable_prometheus": true },
    "sessions": { "persist": true, "persist_interval_sec": 60 }
}

适用说明：仅本机访问（127.0.0.1 入口）时 API 免认证风险可控；关版本检查消除外呼；开 Prometheus 指标对接内网监控栈；会话数据落盘保留历史。两套模板共同点是先按网络边界决定认证与入口，再按业务量设定额——这是 config.json 21 个键里最需要按环境定夺的主线。

七、常见问题（FAQ）

Q1：改了 config.json 完全不生效？

先看 GET /api/v3/config 返回的 overrides 数组（实测见 3.1）——键被 CORE_* 环境变量覆盖时文件改动无效，要么改环境变量后 docker compose up -d 重建，要么删掉对应环境变量再 reload。其次确认执行了 GET /api/v3/config/reload（回显 "OK" 才算加载）。

Q2：开启 api.auth.enable 后把自己锁在外面了？

本地请求默认仍可免认证（disable_localhost 默认 false），先从本机 curl 登录拿 token；若同时把 disable_localhost 改了 true 且忘记口令，停服务 → 编辑 config.json 把 auth.enable 改回 false → 启动服务（配置在挂载目录，可离线改）。

Q3：memfs 内存持续增长怎么办？

多路直播的切片常驻内存是 memfs 设计行为。给 storage.memory.max_size_mbytes 设上限（模板见 6.1），超限后内核按 LRU 淘汰旧分片；仍增长则排查异常流水线（GET /api/v3/process 逐条看输出是否写满 {memfs}）。

Q4：HLS 播放器偶发黑屏、报 404 分片？

先查 disk.cache.types.block 是否仍包含 .m3u8（实测默认包含，被移除后播放器会拿到缓存的过期清单）；再确认观众侧没有对分片 URL 做长缓存；最后看 session_timeout_sec 是否被调得过短（清单里的 session= 令牌换分片需要窗口期）。

八、参考链接

配置文件权威定义（datarhei/core 源码与 Swagger）：https://github.com/datarhei/core
官方文档站配置章节：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 API 使用详解》](https://www.quzuo.net/document/DAWPhSW0QKsb)