Configuration Sources and Effective Rules

Configurations may originate from JSON files, environment variables, command-line arguments, database versions, and the setup wizard. Changes to disk files do not necessarily mean the runtime values have changed.

flowchart LR
    A[Design value / JSON] --> B[Environment or CLI override]
    B --> C[Database-published version]
    C --> D[Effective runtime value]
    D --> E{Hot update or restart required?}

Priority and Effective Values

When the platform displays configurations, it should distinguish between:

• Design or disk values;
• External overrides via environment variables/command-line;
• Current effective runtime values;
• Planned release values;
• Whether a restart is required;
• Recent release and rollback versions.

External override fields cannot change the actual value by writing to the JSON. When troubleshooting configuration issues, first identify the source with the highest priority.

Effective Levels

When a single change involves multiple fields, the level with the greatest impact takes precedence. Before releasing, preview the differences, scope of impact, and summaries of sensitive fields.

Recommended Modification Workflow

1. Read the current effective values and version from the system.
2. Create a configuration plan and preview the differences.
3. Check for port conflicts, paths, permissions, dependencies, and restart levels.
4. Release during a maintenance window.
5. Wait for hot updates, reloads, or restarts to complete.
6. Read back the final values from the runtime.
7. Verify the actual user paths affected.

Do not include database passwords, MediaServer secrets, tokens, or device credentials in the difference logs.

Configure media services in the management context

Open System Management → Media Service, select the scope in the top Management Context, then read the target configuration. Both the controller and target nodes must support scoped configuration commands. Unsupported older nodes are rejected; operations never fall back to the controller's local service.

Configure media addresses one target at a time. Select a specific MediaServer before editing the Media Address section:

• Advertised media address (Candidate) is the target media address reachable by the GB28181 client, without a port. RTC follows it when no independent override is set. It is not the SIP server address and can differ from the local address behind NAT or a VPN.
• Local IPv4 is an interface address on the target MediaServer host. Reported values are shown separately to verify node synchronization.
• The form preserves the existing Secret, API BaseUrl, other node entries, and unknown newer parameters.

RTC address source: A nonempty AkStream:Zlm:Managed:Rtc:ExternalIp remains an independent override, supporting public RTC clients alongside private-network GB28181 devices. To use the same address, select Let RTC follow the media address, preview the override removal, and save it. RTC then uses the current node's Candidate, followed by local IPv4, and falls back to MediaServer discovery only when both are empty. Local IPv4 does not automatically rewrite RTC interface-binding settings.

The page distinguishes the RTC target address from the value in config.ini. After saving, use Configuration synchronization to preview and write rtc.externIP, then explicitly confirm a target MediaServer restart. Restarting interrupts that node's active media/RTC sessions; saving an address never restarts it automatically. New GB28181 sessions use the new advertised address without requiring a SIP-service restart.

Searching for Candidate or IP in parameter mode also exposes these node-address entries. They open the same editor with the current management context rather than replacing a node array through a controller-local scalar field.

Protocol outputs, stream policies, latency and ports, managed-service settings, and INI synchronization use the same context. Different node values appear as mixed values. Only explicitly edited fields enter the change set, and presets only fill the draft.

Select Preview changes for each target, review all targets and differences, then confirm execution. Each node reports its own result, backup and reload/restart requirements. Cross-node changes are not one atomic transaction; partial failure must not be treated as complete success. Retrying the same preview does not create duplicate write or restart commands.

Protocol-output and stream-policy overrides are stored in the corresponding AkStream.Zlm.Nodes[] entry. Heartbeats report the effective policies to the central WebHook receiver. Output changes affect newly published streams without forcibly interrupting existing playback. Native INI/process operations require the instance's default managed MediaServer; unsupported targets are rejected explicitly.

The FFmpeg file browser is available only for a single target on the currently connected node. For remote or multiple targets, enter a path and let each target validate it during preview. RTSP account lists follow the management scope, but account operations affect only the explicitly selected media service and never copy passwords in bulk.

Path Configuration

The server file picker reads the server-side file system. When selecting executable files, check the system/architecture and execution permissions; when selecting directories, use the actual runtime account as a write-access probe. Recording, clipping, configuration, and certificate paths must fall within the allowed range; symbolic link escapes are rejected.

Handling Configuration Failures

• Summary Conflict: Re-read the latest version; do not overwrite changes made by others.
• Path Failure: Verify the target node, runtime account, and mounts.
• Port Conflict: Confirm the actual listening process, do not rely solely on the configuration.
• Application Failure: Check the plan, NodeAgent/MediaServer results, and rollback points.
• Page Displays Old Value: Check for pending restarts, cache, and external overrides.

Complete Field Dictionary

The Complete Configuration Reference delivered with each version is automatically generated from the current configuration types and includes field paths, types, default values, and security guidance. Production changes should still be based on the current platform preview and read-back effective values.