Troubleshooting by Symptom

Start from the symptom closest to the user. First, confirm the scope of the impact, then follow the dependency chain to find the first point of inconsistency.

flowchart LR
    A[What does the user see?] --> B{All or partial?}
    B --> C[Isolate device / node / protocol / network]
    C --> D[Check each layer backward from the page]
    D --> E[First layer without evidence]
    E --> F[Fix and verify the user path]

Quick Entry

Symptom	Confirm First	Entry
Page cannot be opened or login fails	DNS, HTTPS, service health, account status	"Platform Inaccessible" on this page
Device offline, ONVIF discovery fails, GB registration fails	Network direction, time, credentials, SIP/discovery logs	Device Offline
API success but no video	Whether the MediaServer has the corresponding stream	No Video
Stream plays but recording list is empty	Which layer is disconnected: session, disk file, or index	Missing Recording
RTC only succeeds on internal network	ICE candidate, TURN, firewall	RTC Failure
Health is normal but business is unavailable	Readiness, database, MediaServer, background tasks	"Health Does Not Equal Business Availability" on this page
Configuration does not take effect after saving	Effective version, pending restart, runtime read-back	"Configuration Not Taking Effect" on this page
Agent is online but main service is offline	Host daemon, Agent responsibilities, recent operations	"Process Recovery" on this page
Abnormalities after upgrade	Version, Schema, configuration migration and rollback points	Backup and Upgrade

Platform Inaccessible

Check in the following order:

Whether the domain name resolves to the expected entry point.
Whether ports 443/5800 are reachable from the user network.
TLS certificate, chain, domain name, and validity period.
Nginx/reverse proxy upstream and WebSocket configurations.
AKStream.Next host service, process, and /health.
If health is successful, check the login interface, database, and account status.

If the platform is accessible on the server local host but not from the user network, prioritize checking DNS, firewalls, proxies, and routing; do not rebuild the database.

Health Does Not Equal Business Availability

liveness only indicates that the process can respond. readiness aggregates dependencies, but it cannot replace the actual user path. Check the database, MediaServer, protocol modules, recording root, license limits, and third-party services based on the failed function.

Configuration Not Taking Effect

Confirm that the modification is applied to the current node and environment.
View the configuration publishing results and the effective version.
Determine if the field is a hot update or requires a restart.
Check for pending restart or configuration drift status.
Read back the final value from the runtime state.
View the failure reason for the application or NodeAgent.

Directly modifying the JSON on disk may be ignored by running processes or overwritten the next time the platform saves.

Process Recovery

NodeAgent being online does not necessarily mean the main service is online. On Linux the main unit uses Restart=no; NodeAgent persists the desired state independently and recovers the process through the fixed systemd Provider. Check the Agent's desired state, observed state, recovery attempts, and backoff reason first. Other platforms follow the single recovery owner declared by the current release manifest.

Check the host service definition, failure count, startup account, working directory, port occupancy, and the most recent exit code. Save the crash logs before restarting.

Collecting Support Information

A minimum fault package includes:

Product and component versions, OS/architecture, and deployment topology;
Fault time window and time zone;
Stable IDs of affected devices/channels/nodes;
Precise reproduction steps, expected vs. actual results;
TraceId, command/task ID, Call-ID, or stream identifier;
Desensitized logs from the same time window;
Recent changes;
Checks already performed and the result of each step.

Do not submit passwords, Tokens, MediaServer secrets, full authorization codes, private keys, or Cookies.