配置来源与生效规则

配置可能同时来自 JSON、环境变量、命令行、数据库版本和安装向导。看到磁盘文件变化，不代表运行值已经变化。

flowchart LR
    A[设计值 / JSON] --> B[环境变量或命令行覆盖]
    B --> C[数据库发布版本]
    C --> D[当前运行值]
    D --> E{热更新还是待重启?}

优先级与有效值

平台显示配置时应区分：

• 设计或磁盘值；
• 环境变量/命令行外部覆盖；
• 当前有效运行值；
• 计划发布值；
• 是否需要重启；
• 最近发布与回滚版本。

外部覆盖字段不能通过写 JSON 改变实际值。处理配置问题时先找出最高优先级来源。

生效级别

一次变更包含多个字段时，以影响最大的级别为准。发布前先预览差异、影响范围和敏感字段摘要。

推荐修改流程

1. 从系统读取当前有效值与版本。
2. 创建配置计划并预览差异。
3. 检查端口冲突、路径、权限、依赖与重启级别。
4. 在维护窗口发布。
5. 等待热更新、重载或重启完成。
6. 从运行时回读最终值。
7. 验证受影响的真实用户路径。

不要把数据库密码、MediaServer secret、Token 和设备凭据放进差异日志。

按管理上下文修改流媒体服务

在 系统管理 → 流媒体服务 中，先用顶部“管理上下文”选择范围，再读取目标配置。控制端和被管理节点都需支持目标化配置命令；旧节点未上报该能力时会拒绝下发，不会改成本机操作。

媒体地址需要逐节点设置。 范围含多个媒体服务时，先切换为具体 MediaServer，再编辑“媒体地址”页：

• 对外媒体地址（Candidate）：GB28181 客户端能访问的目标媒体地址，不包含端口。RTC 未设独立覆盖时也跟随此值。它不是 SIP 服务器 IP；NAT/VPN 环境下可与本地地址不同。
• 本地 IPv4：目标 MediaServer 主机的本地网卡地址。页面同时显示已上报值，便于核对配置写入与节点同步。
• 原有 Secret、API BaseUrl、其他节点及未知新参数不会被此表单整体覆盖。

**RTC 地址来源：**已有 AkStream:Zlm:Managed:Rtc:ExternalIp 不为空时，继续作为独立覆盖；适用于 RTC 走公网、GB28181 走专网的情况。要让两者一致，在媒体地址页点击 让 RTC 跟随媒体地址，预览并保存清空覆盖的差异。RTC 随后依次使用当前节点 Candidate、本地 IPv4；两者都为空才由媒体服务自动探测。仅本地 IPv4 不会自动改写 RTC 的绑定网卡参数。

页面分别显示“RTC 候选目标”和 config.ini 中的值。保存地址后，进入 配置同步 检查并写入 rtc.externIP，再明确确认重启目标媒体服务；重启会中断该节点现有媒体/RTC 会话，系统不会因保存地址自动重启。GB28181 新会话使用新公告地址，不需要为此重启 SIP 服务。

通用参数模式搜索 Candidate 或 IP 也能找到这两个节点参数的入口，点击后沿用顶部管理上下文进入同一个节点地址编辑器；不会把节点数组当作控制机的单个标量参数覆盖。

协议产物、流治理、延迟与端口、托管安全和配置同步也从同一上下文确定目标。不同节点值不同时显示“混合值”，只有明确编辑的字段进入变更；套用档位只填充草稿，不自动保存。

修改后点击 预览各目标配置差异 → 确认向以上目标执行。每个节点独立回报执行结果、备份及是否待重载/重启；跨节点不是一个同时提交的事务，部分失败不能视为全部生效。同一次预览的网络重试不会重复生成写入或重启任务。

协议产物和流治理覆盖保存到对应 AkStream.Zlm.Nodes[] 条目，并通过节点心跳把有效策略同步给集中接收 WebHook 的控制端。新协议产物影响重新发布的流，不强制中断现有播放。原生 INI/进程操作只支持该实例默认托管的 MediaServer；不支持的目标会明确拒绝。

FFmpeg 文件浏览只用于当前连接节点的单目标范围；远端或多节点请填写路径，预览时由各目标节点验证。RTSP 账号列表按管理范围过滤，但账号操作仍只针对下方明确选中的媒体节点，不批量复制密码。

路径配置

服务器文件选择器读取服务器端文件系统。选择可执行文件时检查系统/架构与执行权限；选择目录时用实际运行账号做可写探针。录像、裁剪、配置和证书路径必须落在允许范围，拒绝软链接逃逸。

配置失败的处理

• 摘要冲突：重新读取最新版本，不覆盖他人变更。
• 路径失败：核对目标节点、运行账号和挂载。
• 端口冲突：确认实际监听进程，不只看配置。
• 应用失败：查看计划、NodeAgent/MediaServer 结果和回滚点。
• 页面显示旧值：检查待重启、缓存和外部覆盖。

完整字段字典

随版本交付的《完整配置参数字典》从当前配置类型自动生成，包含字段路径、类型、默认值和安全提示。生产修改仍以当前平台预览和有效值回读为准。