MistServer 3.12 配置参数详解

目标：把 MistServer 3.12 的整套配置体系一次讲透：三载体配置模型（config.json 持久层 / 启动参数 / 运行时 API 与 Web 界面）、持久化文件的逐字段拆解、六个核心协议连接器的参数表、流对象与推流设置、认证与账号配置，以及"改了不生效"类问题的实测排障。全部字段值与行为结论来自 2026-10-30 在 ddvtech/mistserver:3.12 实测环境中的实查。

本文是 MistServer 系列的第三篇。部署步骤见《MistServer 3.12 Docker Compose 部署指南》，选型与协议矩阵见《MistServer 3.12 介绍与选型指南》。本篇聚焦"配置从哪里来、改了存在哪、每个字段管什么"。

一、配置体系：三载体一持久层

MistServer 的配置操作有三个入口，但落盘只有一份状态文件：

载体	入口	适用场景
Web 管理界面	4242 端口浏览器访问	日常人工运维（流、连接器、账号、日志）
Management API	同一 4242 端口的 JSON 接口	自动化运维、批量配置（详见本系列 API 篇）
启动参数	MistController 进程参数	监听地址/端口、配置文件路径、TLS 证书等启动级行为

三个入口最终都写入同一个持久层——/config.json（路径可由启动参数改变）。实测确认：无论通过 Web 界面建号，还是通过 API 建流、改连接器，服务进程都会把变更写回该文件；反过来，停服时手工编辑该文件，下次启动也会被读取（配置文件读写在启动参数里可通过 configrw 开关细控，见第八节）。

一条重要的实测边界：三个入口的优先级是"运行时覆盖启动时"。启动参数里给的 --port、--interface 只在配置中没有对应记录时生效；一旦持久层里存过值（比如界面上改过管理口），以持久层为准。

二、持久层 config.json：顶层结构总览

以下是一次实测运行状态下的完整顶层结构（实际值，密码已按格式说明脱敏）：

{
  "account": {"root": {"password": "<md5 摘要>"}},
  "auto_push": null,
  "bandwidth": {"exceptions": ["::1", "127.0.0.0/8", "10.0.0.0/8", "192.168.0.0/16", "172.16.0.0/12"]},
  "config": { "...核心配置域，见第三节..." },
  "extwriters": null,
  "jwks": null,
  "push_settings": {"maxspeed": 0, "wait": 3},
  "streamkeys": null,
  "streams": {"cam": {"name": "cam", "source": "push://"},
               "live": {"name": "live", "source": "push://"},
               "vod": {"name": "vod", "source": "/vod/testvod.mp4"}},
  "variables": null
}

顶层六大成员的分工：

成员	管什么	对应界面位置
`account`	管理员账号表（用户名 → 密码 MD5）	Accounts（账号）页
`bandwidth`	带宽统计例外网段	Limits（限制）页
`config`	服务全局配置域（连接器、会话模式、日志等）	Settings 各分页
`push_settings`	主动外推（auto push）的全局设置	Streams 页的推送设置
`streams`	全部流对象（流名 → source）	Streams 页
`variables` / `streamkeys` / `jwks` / `extwriters`	自定义变量、流密钥、JWKS 令牌、外部写入器	高级特性，按需启用

首次启动时该文件接近全空：实测首启日志 No login configured. No protocols enabled. No streams configured.——三个"无"对应的就是上面三个核心成员。首启向导（建号 + 启用协议默认集）本质上就是往这三个成员里写第一批数据。

三、config.config 域：全局参数逐项

config 是最核心的配置域。以下是实测文件中的全部字段（值为实测默认值）：

3.1 身份与日志

参数	实测默认值	说明
`serverid`	null（未设置）	人类可读的实例名，界面 General settings 里的 "Human readable name"；仅用于识别显示，主机名仍由系统管理
`accesslog`	"LOG"	访问日志去向：`LOG` 表示随系统日志走；置空字符串关闭访问日志；其他值按文件名落盘
`debug`	未写入（服务默认级别）	调试级别（整数）。通过 API 的 `config.debug` 设置后立即生效——实测中它同时改变服务进程的实时日志级别，这是排障时临时提高日志量的正规手段
`prometheus`	""（空）	Prometheus 指标端口的路径名。设置后管理口按该路径暴露指标（如 `/prometheus`）；空为关闭

3.2 连接器与默认流

参数	实测默认值	说明
`protocols`	`[]`（首启向导后为默认五项）	协议连接器实例数组，每个元素至少含 `connector`（连接器名）与可选 `port` 等参数，逐连接器参数见第五节
`defaultStream`	null	默认流名。设置后，访问未知流名时按该流处理（配合"单流站点"场景）

首启向导采用默认协议集后，protocols 的实测值（与《MistServer 3.12 Docker Compose 部署指南》 4.5 节一致）：

[{"connector": "RTMP", "online": 1, "port": "1935"},
 {"connector": "RTSP", "online": 1, "port": "5554"},
 {"connector": "HTTP", "online": 1, "port": "8080"},
 {"connector": "HLS",  "online": 1},
 {"connector": "CMAF", "online": 1}]

online 字段由服务运行时维护（1 = 已拉起），不属于人工配置项——实测中手动写它会被服务按"运行时状态"处理，删除重算。

3.3 会话模式位掩码（session*Mode 与 tknMode）

实测默认值：sessionViewerMode: 14、sessionInputMode: 15、sessionOutputMode: 15、sessionUnspecifiedMode: 0、sessionStreamInfoMode: 1、tknMode: 15。

这一组参数控制会话（session）在多大粒度上被计数、限速与踢除，取值是位掩码组合（位 1/2/4/8 叠加）。位含义按源码与界面行为的对应关系：不同位分别对应"按流聚合计数 / 按连接计数 / 触发限制动作 / 触发踢除动作"的组合方式。实测建议：

保持默认值是安全的（Viewer 14、Input/Output 15 是官方选择的均衡组合）；
sessionUnspecifiedMode: 0 表示未明确归类会话不执行任何动作，谨慎改成带踢除位的组合，避免误杀会话；
sessionStreamInfoMode: 1 控制流信息接口暴露的会话数据粒度；
tknMode: 15 控制 URL 令牌（拉流地址里实测看到的 ?tkn= 参数）在哪些协议上启用——HLS 分片地址里实测携带 tkn=2981602234 形式的查询串，就是这套机制在工作。

在 Web 界面里这组参数位于 Settings → General settings 分组，与 serverid/accesslog 同屏。修改它们不需要重启：实测通过 API 写入后立即生效。

3.4 weights 权重组

实测默认值：

"weights": {"abr": 20, "bw": 20, "control": 20, "cpu_server": 20,
             "cpu_viewer_batt": 100, "cpu_viewer_pwrd": 60, "latency": 50,
             "permissibility": 20, "recovery": 80, "stability": 50, "ttff": 50}

这组权重服务于多轨道自适应选择与出流调度：当一条流有多个编码轨道（多码率/多分辨率）或多个候选出流路径时，服务按这些因子的相对权重决定优先级。字段含义按名称对应：abr 自适应选择、bw 带宽因子、latency 时延、ttff 首帧时间（time to first frame）、stability 稳定性、recovery 恢复能力、cpu_server 服务端 CPU、cpu_viewer_batt/cpu_viewer_pwrd 观看端电池/功耗、permissibility 允许度。数值是相对量纲，只比较大小有意义（如 cpu_viewer_batt: 100 高于 latency: 50，表示对移动观看端优先保护电池）。一般保持默认；做移动端优化时才考虑调整。

3.5 信任代理与位置

参数	实测默认值	说明
`trustedproxy`	`[]`	信任的反向代理网段列表。管理口判定来源 IP 时按此优先取 `X-Real-IP`/`X-Forwarded-For`——官方 API 文档明确：反代部署时必须配置它，否则 API 请求会被当作来自 localhost 而绕过认证（这是安全边界，不是便利开关）
`location`	未写入	地理坐标（lat/lon/name），用于展示与调度场景

四、流对象与推流设置

4.1 streams：流对象全字段

每个流对象最少两个字段（实测）：

{"live": {"name": "live", "source": "push://"}}

字段	必填	说明
`name`	是	流名；与推流地址第二段匹配（RTMP 为 `rtmp://host:port/<应用>/<流名>` 的流名段）
`source`	是	源描述串，三种典型形态见下表

source 形态实测汇总：

source	行为	实测结果
`push://`	等待任意流名匹配的推流接入	RTMP/RTSP 推流即上线（`online: 1`）
`push://<流名>`	只接受指定流名的推流	同上，但收敛了流名匹配
`/vod/testvod.mp4`	文件点播源（服务内绝对路径）	创建后立即就绪（`online: 2`，状态 "Available"）
`dtsc://<host>:<port>/<流名>`	从另一台 MistServer 拉取 DTSC 流（服务器间转发）	多级分发场景，本系列未实测
`mp4:http://...` 等网络源	按 `<输入类型>:<地址>` 语法指定输入连接器	输入连接器全清单见系列第一篇的 30 连接器矩阵

VoD 流首次被拉起时，服务会在媒体文件同目录生成同名 .dtsh 索引（实测确认 testvod.mp4.dtsh 出现在挂载目录）。该索引是解析加速文件，删除后会在下次访问时重建；但媒体目录若以只读方式挂载，索引写失败会导致流打不开（实测排障结论，部署篇 Q5 有对应处理）。

4.2 push_settings：主动外推全局设置

实测默认值：{"maxspeed": 0, "wait": 3}。

参数	默认	说明
`wait`	3	自动推送任务在流上线后等待的秒数，避免瞬时抖动触发无谓的外推
`maxspeed`	0	外推速率上限（字节/秒），0 不限制

配合流级或全局的 auto push 任务（auto_push 顶层成员），可实现"本流上线即向备份节点/CDN 推流"。本系列实测重点在收流与分发侧，外推机制在 API 篇的 push 命令族中有接口说明。

五、协议连接器参数详解

每个连接器的参数体系由服务内置的能力清单（capabilities）定义。实测通过 API 的 capabilities 命令读回全部 30 个连接器的参数定义。连接器实例写在 config.protocols 数组里，通用参数之外各有专属参数。以下 six 个最常用连接器的参数表均为能力清单实测值：

5.1 RTMP（默认端口 1935）

参数	类型	默认	说明
`port`	uint	1935	TCP 监听端口
`interface`	str	0.0.0.0	监听网卡地址
`acceptable`	select	0	收推方向：0 双向、1 仅拉、2 仅推
`maxkbps`	uint	0	收流方向最大码率（kbps），0 不限
`cert` / `key`	inputlist	空	RTMPS 的证书链/私钥文件，多条时按顺序对应
`username`	str	root	进程降权用户（安全特性）
`default_track_sorting`	select	空	无指定轨道选择器时的默认轨道排序（码率/分辨率/轨道 ID 升降序）

5.2 RTSP（默认端口 5554）

参数	类型	默认	说明
`port`	uint	5554	TCP 监听端口
`maxsend`	uint	1472	RTP 包最大字节数（以太网 MTU 友好值）
`ignsendport`	bool	false	忽略入站数据的源端口（NAT 场景下摄像头端口漂移时有用）
`interface` / `username` / `default_track_sorting`	—	同上	通用参数

5.3 HLS（寄生 HTTP 口，无独立端口）

参数	类型	默认	说明
`chunkpath`	str	空	分片文件的落盘/服务路径（空 = 内存出片）
`listlimit`	uint	0	直播播放列表最大分片数，0 无限

HLS 连接器本身没有 port——它寄生在 HTTP 连接器上，URL 前缀 /hls/ 路由（实测确认，/hls/live/index.m3u8 返回主播放列表）。

5.4 CMAF（寄生 HTTP 口，承载 DASH 与低延迟 HLS/DASH）

参数	类型	默认	说明
`packaging`	select	separate	separate（单轨 Representation）或复用音视频轨的打包方式
`partduration`	uint	500	低延迟分片（LL-HLS/LL-DASH part）目标时长，毫秒级 100–60000
`listlimit`	uint	0	直播播放列表最大完整段数（可用时最小 6）
`chunkpath`	str	空	分片服务路径；设置后禁用分片 URL 的会话 ID

实测 /cmaf/vod/index.mpd 返回的 MPD 中 SegmentTemplate media="v$RepresentationID$/chunk_$Time$.m4s" 即该连接器的产物。

5.5 TSSRT（SRT，默认 UDP 8889）

参数	类型	默认	说明
`port`	uint	8889	UDP 监听端口
`passphrase`	string	空	SRT 加密口令，设置后强制要求对端携带
`acceptable`	select	0	双向/仅拉/仅推
`streamname`	str	空	对端未给 streamid 时的兜底流名
`nostreamid`	bool	空	禁读 streamid 字段
`raw`	bool	false	原始 MPEG-TS 透传模式
`sockopts`	string	空	追加 SRT socket 选项（如 `latency=120`）
`datatrack`	select	空	数据轨解析器选择

部署篇端口表里 8889/udp 的用途即由此确认（TSSRT 默认端口）。

5.6 WebRTC（默认 UDP 18203，寄生 HTTP 口信令）

参数	类型	默认	说明
`port`	uint	18203	SRTP UDP socket 端口
`pubhost`	str	空	SDP 里通告的主机名/IP（端口映射/NAT 后必须设置，配合 `override_port`）
`override_port`	uint	0	SDP 通告端口（映射后对外端口不同时使用）
`iceservers`	json	空	ICE 服务器数组（STUN/TURN）
`preferredvideocodec`	str	H264,HEVC,AV1,VP9,VP8	视频编解码优先序
`preferredaudiocodec`	str	opus,ALAW,ULAW	音频编解码优先序
`nacktimeout` / `nacktimeoutmobile`	uint	5 / 15	丢包 NACK 等待包数（桌面/移动端分开）
`losttimeout` / `losttimeoutmobile`	uint	30 / 90	判定丢包的等待包数
`maxpktsize`	uint	1322	RTP 包上限（加密前）
`mergesessions`	bool	0	合并同一用户多观看会话
`cert` / `key`	str	空	HTTPS 信令证书（缺省取 HTTP 连接器配置）

部署篇端口表里 18203/udp 的用途即由此确认（WebRTC 默认端口）。做端口映射部署时，WebRTC 的 pubhost + override_port 是必配对——SDP 里写的是服务视角的地址，容器/内网地址对外不可达时必须显式通告公网地址。

六、认证与账号配置

6.1 account 与密码存储

账号表实测结构：{"root": {"password": "<32 位 MD5>"}}。密码以 MD5 摘要存储（实测确认 q1w2e3r4 的 MD5 与文件内摘要一致），不是明文。

认证算法（官方 API 文档，2026-10-29 查询；实测验证通过）：客户端先用明文密码的 MD5 作预计算，登录时服务端发 challenge，客户端回 MD5(密码MD5 + challenge)——服务端做同样运算比对。明文密码不出现在网络上。

6.2 localhost 免认证边界

官方文档明示：从本机访问管理口不需要任何认证（API 与界面都生效）。实测确认这一行为：4242 口的本地请求跳过登录环节。安全含义：凡与 MistServer 共享运行环境的进程都能控制管理面。把管理口映射到宿主端口（部署篇的 8132）后，"本机"指宿主侧——这是双刃剑，管理口不应对公网开放的原因又多了一条。

6.3 建号的三条路径与状态机

实测验证的认证状态机有四个值：NOACC（无账号）→ ACC_MADE（初始账号已建）→ CHALL（待认证，发 challenge）→ OK（已认证）。三条建号路径：Web 首启向导、API 的 new_username/new_password（仅 NOACC 状态可用）、启动参数 --account user:pass（第八节）。账号启用后 API 的每次请求都要重新携带认证对象（HTTP 无状态连接模型，官方文档明示）。

七、带宽例外与限制

bandwidth.exceptions 实测默认值包含五个内网网段（::1、127.0.0.0/8、10.0.0.0/8、192.168.0.0/16、172.16.0.0/12），首启日志确认这是"无配置时自动添加的默认值"：

CONF: Adding default bandwidth exception ranges (local networks) because nothing is configured

作用：这些网段的会话不计入带宽统计与限制——内网监控/推流源不会被公网带宽限额误伤。对外提供公网服务时保持默认即可；如果服务器身处大内网而限流目标是真实公网流量，需要按实际网段调整。Limits 页的其余限制项（会话数/带宽上限与踢除动作）作用于第六节 3.3 的会话模式位掩码之上，两者配合工作。

八、启动参数（MistController 命令行）

实测 MistController --help 输出的全部启动参数：

参数	短参	说明
`--config <路径>`	`-c`	指定配置文件（默认 `/config.json`）
`--configrw <模式>`	`-C`	配置文件读写策略：`r` 只读不写、`w` 变更后 60 秒落盘、`rw` 两者皆可（默认）
`--port <端口>`	`-p`	管理口监听端口（默认 4242；持久层已有值时以持久层为准）
`--interface <地址>`	`-i`	管理口监听网卡
`--account user:pass`	`-a`	启动时创建账号（`user:pass` 明文，注意进程列表可见性）
`--username <用户>`	`-u`	进程降权目标用户（默认 root 即不降权）
`--certificate <pem>`	`-x`	管理 API 的 TLS 证书链
`--key <pem>`	`-X`	管理 API 的 TLS 私钥
`--accesslog <目标>`	`-A`	访问日志去向（同 3.1 节 config.accesslog）
`--logfile <文件>`	`-L`	标准输出重定向文件
`--debug <级别>`	`-g`	调试级别
`--prometheus <路径>`	`-S`	Prometheus 指标路径
`--version` / `--help`	`-v` / `-h`	版本与帮助

实测版本行：Version: $Format:%(describe)$, release Docker_linux/amd64，构建时间 Oct 5 2026——与 3.12 发布日期吻合。启动参数与持久层的关系见第一节：运行时持久层优先。官方发行版内所有进程（MistIn*/MistOut* 系列）都由 Controller 按配置自动拉起，日常运维不应手工启动这些子进程——它们的参数体系是连接器参数（第五节）的服务端实现细节。

九、配置生效时机与"改了不生效"排障

9.1 生效路径实测

配置对象	生效时机	实测验证
协议连接器增删改	即时（连接器进程被拉起/停止）	API 添加 JSON 连接器实例后 HTTP 口路由行为即时变化
流增删改	即时（输入进程按需拉起）	API 建流后推流即接入
全局参数（debug/accesslog 等）	即时	debug 改动实时改变日志输出量
启动参数	仅进程启动时	需要重启服务进程
config.json 落盘	变更后 60 秒静默期写回（configrw 默认 rw）	实测 API 写操作后文件内容同步更新

9.2 实测排障实录

实录一：表单编码的 API 写请求不生效。 用 application/x-www-form-urlencoded 提交 command=<JSON> 参数时，认证可以通过（authorize 成员被读取，返回 OK），但同一请求里的 addstream/config 写成员不生效——读回无变化，落盘也无变化。改用 Content-Type: application/json 直接提交 JSON 请求体后全部生效（实测对比脚本与回显见本系列 API 篇）。结论：程序化对接一律用 JSON 请求体；curl -d @file.json -H 'Content-Type: application/json' 是可靠姿势。

实录二：流元数据接口的路径陷阱。 HTTP 口的流元数据接口，3.12 实测可用路径是 /<流名>.json（如 /live.json，返回编码参数/分辨率/帧率元数据）。老文档写的 json_<流名>.json 路径实测失败：HTTP 连接器把 json_live 整体当作流名去查找，日志报 Could not get stream 'json_live' config!。此外该接口要求 HTTP 连接器处于启用状态——把 HTTP 连接器从 protocols 移除后访问任何元数据路径都报 Server error - could not start connector。

实录三：dtsh 索引与只读媒体目录。 VoD 流首次访问时在媒体同目录写 <文件名>.dtsh 索引；目录只读时索引写失败、流打不开。处理：给媒体目录读写权限，或预先生成索引。

实录四：连接器实例的 online 字段是运行时状态。 手工在 config.protocols 里写 "online": 1 不会让连接器上线——online 由服务进程按实际拉起状态回写。判断连接器是否真的在线，读 config.protocols 的 online 值或看服务日志的 Started connector: {...} 记录。

十、参数速查总表

要改什么	去哪里改	本文章节
管理口地址/端口/TLS	启动参数（首次）或持久层	八 / 一
协议连接器开关与端口	Web 界面 Protocols 页或 API `config.protocols`	五 / 3.2
流与源	Web 界面 Streams 页或 API `streams`/`addstream`	四
会话计数/限制行为	General settings 的 session*Mode	3.3
ABR/调度权重	General settings 的 weights	3.4
反向代理后保持认证	`config.trustedproxy`	3.5
账号与密码	Accounts 页 / API / `--account`	六 / 八
带宽统计例外	Limits 页 `bandwidth.exceptions`	七
外推任务	Streams 页推送设置 `push_settings`	4.2

十一、参考链接

系列篇目：《MistServer 3.12 介绍与选型指南》（30 连接器矩阵与选型）、《MistServer 3.12 Docker Compose 部署指南》（部署与首启向导）、本系列 Management API 使用详解（认证协议与命令集实测）；
同域对照：《MediaMTX 1.21.3 配置参数详解》（YAML 单文件配置体系，与本文 JSON 持久层 + API 模型互为参照）；
官方文档：https://mistserver.org/documentation（Configuration / API Authentication 章节，2026-10-29 查询）；
本文全部参数值与行为结论来自 2026-10-30 对 ddvtech/mistserver:3.12 实测环境的实查（config.json 实际内容、MistController --help 全量输出、capabilities 能力清单读回）。