Online upgrade: complete guide to akn upgrade and page-based upgrade

AKStream.Next provides two formal-package online upgrade entry points: run akn upgrade in the server terminal, or upload and execute the package from “System management → System upgrade” in WebUI. Both entry points ultimately call the same platform upgrade manager and share the same version checks, backups, program switch, health acceptance, and failure rollback rules.

“Online upgrade” does not mean downloading a version automatically from the Internet. The operator must first obtain a complete official release package matching the current operating system and CPU architecture, then submit that local file through CLI or the page. The system never overwrites production from a URL, image tag, or Git branch.

An upgrade interrupts the page, APIs, NodeAgent, the managed MediaServer, and active media workloads. Run it only in a maintenance window. After it starts, do not power off or reboot the host, remove upgrade directories, or submit another upgrade.

Choose the correct entry point first

These are not two different implementations. The page adds authenticated permissions, streamed upload, deep archive preflight, NodeAgent scheduling, and polling across restarts. CLI enters the same platform transaction manager directly from a local package.

flowchart LR
  operator[Operator]
  cli[`akn upgrade`]
  page[System upgrade page]
  api[Main-service upgrade API]
  record[(Persistent upgrade record)]
  agent[NodeAgent]
  job[Detached system job]
  manager[Platform upgrade manager]
  backup[(Config, program, and system-file backup)]
  health{New version healthy?}
  success[Keep new version and record success]
  rollback[Restore previous version and verify again]

  operator --> cli --> manager
  operator --> page --> api
  api --> record
  api --> agent --> job --> manager
  manager --> backup --> health
  health -- yes --> success
  health -- no --> rollback
  job -. state file .-> record
  record -. page polling .-> page

Complete these checks before upgrading

1. Read the target release notes, known limitations, and database/configuration compatibility notes.
2. Download the original complete package; never copy only AKStream.Next.dll, NodeAgent, or WebUI files.
3. Verify the filename, four-part version, operating system, CPU architecture, and extension.
4. Independently compare the archive SHA-256 with the release channel. The SHA-256 shown on the page is computed after local receipt and must match the published value.
5. Follow Backup, recovery, upgrade, and rollback to prepare database, Config, security material, proxy configuration, recording index, and rollback points.
6. Stop creating new clips, transcodes, large recording scans, and other high-I/O jobs; wait for critical writes to finish.
7. Ensure both system and data disks can hold the original package, expanded package, current-install backup, and transaction backup.
8. Verify FFmpeg, database, NodeAgent, and current health. Page upgrade requires NodeAgent to have been seen within the last 15 seconds.
9. Define the maintenance window, rollback decision owner, and post-upgrade observation period.

Filename and platform matrix

Only a strictly higher four-part version is accepted. Same-version reinstall, downgrade, or an x64 package submitted to ARM64 is rejected before services stop. A downgrade must use an explicit rollback or restore procedure; do not disguise an old package as an “upgrade.”

Use akn upgrade

CLI is the essential recovery entry when the main service is unavailable. It uses the installed manager to read the installed assembly version, then lets the manager in the new package perform installation and health acceptance.

Linux and macOS

akn info
akn status
sha256sum ./AKStream.Next-1.0.0.136-linux-arm64.tar.gz
sudo akn upgrade ./AKStream.Next-1.0.0.136-linux-arm64.tar.gz

On macOS, use shasum -a 256 and substitute the osx-x64 or osx-arm64 package:

shasum -a 256 ./AKStream.Next-1.0.0.136-osx-arm64.tar.gz
sudo akn upgrade ./AKStream.Next-1.0.0.136-osx-arm64.tar.gz

Windows

Run in an elevated PowerShell window:

akn info
akn status
Get-FileHash .\AKStream.Next-1.0.0.136-win-arm64.zip -Algorithm SHA256
akn upgrade .\AKStream.Next-1.0.0.136-win-arm64.zip

Docker

Run in the host environment where the Compose stack was initially installed. Do not execute it inside the application container:

akn info
akn status
sha256sum ./AKStream.Next-1.0.0.136-docker-linux-arm64.tar.gz
akn upgrade ./AKStream.Next-1.0.0.136-docker-linux-arm64.tar.gz

akn update in a formal customer package is not the transactional upgrade entry. Use akn upgrade for formal Docker releases because it saves Compose, configuration, and database backups and restores the old image and database when the new containers fail health acceptance.

When the old version has no akn upgrade

Do not overwrite the installation directory manually. Extract the new package and use the manager inside the new package to process the original archive against the current installation:

 # Linux
sudo ./Deploy/linux/akstream-next.sh upgrade /absolute/path/AKStream.Next-1.0.0.136-linux-arm64.tar.gz

 # macOS
sudo ./Deploy/macos/akstream-next.sh upgrade /absolute/path/AKStream.Next-1.0.0.136-osx-arm64.tar.gz

 # Docker; --root must be the current deployment root
./Deploy/docker/akstream-next.sh upgrade /absolute/path/AKStream.Next-1.0.0.136-docker-linux-arm64.tar.gz --root /absolute/path/to/current-deployment

On Windows, run from the new package in an elevated PowerShell window:

.\Deploy\windows\akstream-next.ps1 upgrade C:\Packages\AKStream.Next-1.0.0.136-win-arm64.zip

After a successful upgrade, the global akn is replaced by the controlled manager from the new version, so later upgrades can use the short command.

Use the system upgrade page

Open “System management → System upgrade.” Viewing requires system.upgrade.view. Uploading, confirming, and starting require system.upgrade.manage, which also depends on system view, upgrade view, and lifecycle management capabilities.

Step 1: upload and preflight

1. Select exactly one unrenamed and unrepacked formal release archive.
2. Drag it into the upload area or click the area to choose the file.
3. The browser checks the extension, file count, and 8 GB limit, but these are immediate hints only.
4. Click “Upload and validate package.” The server streams the raw request body to a temporary file while calculating SHA-256; neither the browser nor managed server memory holds the complete package.
5. Wait until the record shows “Prepared.” Preflight does not stop services or start an upgrade automatically.

If Nginx, a gateway, WAF, or load balancer is in front, its request-body and timeout limits must also support the package. The application raises only this Kestrel upload request to 8 GB. If an upstream returns 413, correct the proxy limit; do not split the package or bypass integrity checks.

Step 2: review and execute

1. Compare current version, target version, RID, package size, and full SHA-256.
2. Confirm status Prepared, phase validated, and no other upgrade in Queued or Running.
3. Enter the case-sensitive confirmation text UPGRADE.
4. Click “Start upgrade.” The server uses only the saved target version and fixed paths; the browser cannot substitute an archive or manager at this step.
5. After the page reports that NodeAgent has queued the task, do not submit it again.

Step 3: wait for reconnect and terminal result

The page refreshes every 8 seconds while idle and every 2 seconds while an upgrade is active or the connection is recovering. A temporary connection failure after the main service stops is expected; the detached system job continues.

flowchart LR
  A[Upload official package] --> B[Review and confirm]
  B --> C[Wait for reconnection]
  C --> D[Inspect final result]

What the system validates

The page retains at most 50 recent metadata records and never exposes archive absolute paths. After receiving a task, NodeAgent validates again that archive, status, and manager paths all remain inside the automatically configured upgrade root, preventing browser or database content from becoming an arbitrary privileged command.

Understand upgrade status

stateDiagram-v2
  [*] --> Prepared: Upload and preflight pass
  Prepared --> Queued: Enter UPGRADE
  Queued --> Running: Detached job writes state
  Running --> Succeeded: New version health passes
  Running --> RolledBack: New version fails, old version recovers
  Running --> RollbackFailed: New and old versions both fail
  Queued --> Failed: Scheduler or wrapper launch fails
  Running --> Failed: Manager fails without terminal rollback state
  Succeeded --> [*]
  RolledBack --> [*]
  RollbackFailed --> [*]
  Failed --> [*]

Common phases include validated, agent-queue, manager-start, backup, install, rollback, complete, upgrade-schedule, upgrade-launch, and manager-failed. Platform managers may add more specific phases. Use terminal status, not phase wording alone, to decide success or rollback.

How backup, switch, and rollback work

flowchart LR
  A[Upload official package] --> B[Review and confirm]
  B --> C[Wait for reconnection]
  C --> D[Inspect final result]

The package does not overwrite the formal Config or recording directory with package content. Whether an old binary can read data created during the upgrade still depends on database and configuration backward compatibility. For irreversible migrations, use the complete backup/restore instructions in the release notes.

Find records and logs

On Linux, a page upgrade runs as a transient unit. Use the upgrade ID to inspect it:

sudo systemctl status akstream-next-upgrade-<32-char-upgrade-id>.service --no-pager -l
sudo journalctl -u akstream-next-upgrade-<32-char-upgrade-id>.service --no-pager
sudo tail -n 200 /var/lib/akstream-next-agent/upgrades/jobs/<32-char-upgrade-id>/upgrade.log

CLI prints package, target version, SHA-256, and transaction directory directly. After RolledBack or RollbackFailed, do not delete the transaction directory first; it is authoritative evidence for diagnosis and manual restoration.

Handle common failures

Perform post-upgrade acceptance

Upgrade-manager health is only the first layer. Continue with Production deployment acceptance:

1. akn info reports the target four-part version, RID, installation directory, and configuration directory.
2. akn status reports the main service, NodeAgent, and /health healthy.
3. Readiness has no blocking database, MediaServer, storage, licensing, or background-task issue.
4. Inspect configuration version and source for pending restart or path drift.
5. Verify one real-device live stream, stop, and resource release.
6. Verify new recording output, index query, and Range playback or download.
7. Exercise the required GB28181/ONVIF/RTSP/RTC path for the site.
8. Observe error rate, database timeouts, protocol-command timeouts, disk, and process resources.
9. Retain the source package, previous version, and transaction directory until observation completes.

For multiple nodes, upgrade a validation node first, observe it, and then expand in batches. Do not upgrade every control, protocol, and media node together. Existing live streams, recordings, RTP, and RTC sessions are not guaranteed to migrate losslessly across versions.

Completion criteria

• The package is a complete formal release for the target platform and architecture with a higher four-part version.
• External SHA-256, internal version, protection manifest, and core-file hashes are verified.
• Upgrade status is Succeeded, or failure is explicitly RolledBack with critical old-version paths restored.
• Main service, NodeAgent, database, MediaServer, recording, and required protocol paths pass acceptance.
• Upgrade logs, transaction directory, operator, time, target version, and observation decision are archived.
• RollbackFailed, unknown status, or long-running Running is not completion.

For other CLI parameters, see Service management commands. For consistent backup and disaster-recovery boundaries, see Backup, recovery, upgrade, and rollback.