在线升级：akn upgrade 与页面升级完整指南

AKStream.Next 提供两条正式包在线升级入口：在服务器终端执行 akn upgrade，或者在 WebUI 的“系统管理 → 系统升级”上传并执行。两条入口最终调用同一套平台升级管理器，共享版本校验、备份、程序切换、健康验收和失败回滚规则。

重要：这里的“在线升级”不是从互联网自动下载版本。 操作者必须先取得与当前操作系统和 CPU 架构一致的官方完整发布包，再通过 CLI 或页面提交本地文件。系统不会根据一个 URL、镜像标签或 Git 分支直接覆盖生产程序。

升级会中断网页、API、NodeAgent、托管 MediaServer 和正在进行的媒体业务。 必须在维护窗口执行。开始后不要关机、重启宿主、删除升级目录或重复提交另一项升级。

先选择正确入口

页面与命令都应使用对应平台的正式安装包；选择入口后等待其最终结果，避免同时启动两次升级。

flowchart LR
  operator[运维人员]
  cli[`akn upgrade`]
  page[系统升级页面]
  api[主服务升级 API]
  record[(持久化升级记录)]
  agent[NodeAgent]
  job[独立系统任务]
  manager[平台升级管理器]
  backup[(配置、程序与系统文件备份)]
  health{新版健康验收通过?}
  success[保留新版并记录成功]
  rollback[恢复上一版并重新验收]

  operator --> cli --> manager
  operator --> page --> api
  api --> record
  api --> agent --> job --> manager
  manager --> backup --> health
  health -- 是 --> success
  health -- 否 --> rollback
  job -. 状态文件 .-> record
  record -. 页面轮询 .-> page

升级前必须完成

1. 阅读目标版本说明、已知限制、数据库和配置兼容说明。
2. 下载原始完整发布包，不要只复制 AKStream.Next.dll、NodeAgent 或 WebUI 文件。
3. 核对包名、四段版本、操作系统、CPU 架构和扩展名。
4. 从发布渠道独立核对归档 SHA-256。页面显示的 SHA-256 是接收完成后的本机计算值，应与发布值一致。
5. 按备份、恢复、升级与回滚准备数据库、Config、安全材料、代理配置、录像索引和回滚点。
6. 停止新建裁剪、转码、大批录像扫描和其他高 I/O 任务，等待关键写入收尾。
7. 确认系统盘和数据盘同时有足够空间保存原包、展开目录、当前安装备份和事务备份。
8. 确认 FFmpeg、数据库、NodeAgent 和当前健康检查正常。页面升级要求 NodeAgent 最近 15 秒内在线。
9. 明确维护窗口、回滚决策人和升级后观察时间。

包名和平台矩阵

只允许升级到严格更高的四段版本。同版本重装、降级或把 x64 包交给 ARM64 实例都会在停服务前被拒绝。需要降级时必须使用明确的回滚/恢复方案，不能把旧包伪装成“升级包”。

使用 akn upgrade

CLI 是主服务不可访问时的重要恢复入口。它使用当前已安装的管理器读取当前程序集版本，再用新包中的管理器完成安装和健康验收。

Linux 与 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

macOS 可用 shasum -a 256，并把文件名替换为 osx-x64 或 osx-arm64 包：

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

在管理员 PowerShell 中运行：

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

必须在最初安装该 Compose 栈的宿主环境运行，不要进入业务容器执行：

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 不是事务升级入口。Docker 正式版本使用 akn upgrade，因为它会保存 Compose、配置和数据库备份，并在新容器不健康时恢复旧镜像与数据库。

老版本没有 akn upgrade

不要手工覆盖安装目录。解压新包后，用新包内管理器读取原始归档并升级当前安装：

 # 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 必须是当前部署根
./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

Windows 在新包目录的管理员 PowerShell 中运行：

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

升级成功后，全局 akn 会被新版本受控管理器更新，后续继续使用短命令。

使用系统升级页面

页面入口位于“系统管理 → 系统升级”。查看页面需要 system.upgrade.view；上传、确认和开始升级需要 system.upgrade.manage，该权限还依赖系统查看、升级查看和生命周期管理能力。

第一步：上传并预检

1. 只选择一个未经改名或重新打包的正式发布包。
2. 把文件拖入上传区，或者点击上传区选择文件。
3. 页面先检查扩展名、单文件数量和 8 GB 上限，但这只是即时提示。
4. 点击“上传并验证安装包”。服务端以原始请求体流式写入临时文件，同时计算 SHA-256；不会把整个包放入浏览器或服务端托管内存。
5. 等待记录显示“已预检”。预检不停止服务，也不会自动开始升级。

如果入口前还有 Nginx、网关、WAF 或负载均衡，它们的请求体大小和超时也必须支持大包上传。应用只把本次 Kestrel 上传请求提高到 8 GB；上游返回 413 时应修正代理限制，不能拆包或绕过保护检查。

第二步：核对并执行

1. 核对当前版本、目标版本、RID、包大小和完整 SHA-256。
2. 确认状态为 Prepared、阶段为 validated，且没有另一项 Queued 或 Running 升级。
3. 输入区分大小写的固定文本 UPGRADE。
4. 点击“开始升级”。服务端只使用已保存记录中的目标版本和固定路径，浏览器不能在这一步替换归档或管理器。
5. 页面显示任务已进入 NodeAgent 队列后，不要再次提交。

第三步：等待重连和最终结果

页面空闲时每 8 秒刷新；升级执行或连接中断时每 2 秒重连。主服务停止后短暂出现“无法连接”属于预期，独立系统任务仍会继续执行。

flowchart LR
  A[上传正式包] --> B[核对并确认]
  B --> C[等待重新连接]
  C --> D[查看最终结果]

系统会检查什么

以页面或命令返回的预检和执行结果为准；不要自行更改任务文件。

理解升级状态

stateDiagram-v2
  [*] --> Prepared: 上传与预检通过
  Prepared --> Queued: 输入 UPGRADE
  Queued --> Running: 独立任务写入状态
  Running --> Succeeded: 新版健康验收通过
  Running --> RolledBack: 新版失败且旧版恢复成功
  Running --> RollbackFailed: 新版失败且旧版也未恢复
  Queued --> Failed: 调度或包装器启动失败
  Running --> Failed: 管理器异常且没有终态
  Succeeded --> [*]
  RolledBack --> [*]
  RollbackFailed --> [*]
  Failed --> [*]

常见阶段包括 validated、agent-queue、manager-start、backup、install、rollback、complete、upgrade-schedule、upgrade-launch 和 manager-failed。平台管理器可以增加更具体阶段；判断成功或回滚必须以终态 status 为准，不能只看阶段文字。

备份、切换和回滚怎样工作

flowchart LR
  A[上传正式包] --> B[核对并确认]
  B --> C[等待重新连接]
  C --> D[查看最终结果]

升级包不会用包内 Config 覆盖当前正式配置，也不会主动覆盖录像目录。程序回滚能否安全读取升级期间产生的数据仍取决于数据库和配置向后兼容性；存在不可逆迁移时，必须按版本说明执行完整备份恢复。

查找记录和日志

Linux 页面任务由 transient unit 执行，可结合升级 ID 检查：

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

CLI 会直接在终端显示包、目标版本、SHA-256 和事务目录。无论页面还是 CLI，RolledBack 或 RollbackFailed 后都不要先删除事务目录；它是定位失败和人工恢复的权威证据。

常见失败怎么处理

升级后验收

升级工具的健康通过只是第一层。继续按生产上线验收执行：

1. akn info 显示目标四段版本、RID、安装目录和配置目录正确。
2. akn status 显示主服务、NodeAgent 和 /health 正常。
3. readiness 中数据库、MediaServer、存储、授权和后台任务没有阻断项。
4. 查看配置版本和来源，确认没有待重启或路径漂移。
5. 验证一条真实设备实时流、一次停止与资源释放。
6. 验证新录像文件产生、索引查询、Range 播放或下载。
7. 使用 GB28181/ONVIF/RTSP/RTC 的现场必需路径做最小回归。
8. 观察错误率、数据库超时、协议命令超时、磁盘和进程资源。
9. 在观察期结束前保留原包、上一版本和事务目录。

多节点应先升级验证节点，完成观察后再分批扩大；不要同时升级所有控制、协议和媒体节点。已有直播、录像、RTP 或 RTC 会话不保证无损跨版本迁移。

完成标准

• 使用的是目标平台、架构和更高四段版本的正式完整包。
• 包外 SHA-256、包内版本、保护清单和核心文件哈希均已核对。
• 升级状态为 Succeeded，或者失败时明确为 RolledBack 且旧版关键业务恢复。
• 主服务、NodeAgent、数据库、MediaServer、录像和必需协议路径通过验收。
• 升级日志、事务目录、操作者、时间、目标版本和观察结论已归档。
• RollbackFailed、未知状态或长期 Running 不能作为完成。

CLI 参数的其他含义见服务管理命令；一致性备份和灾难恢复边界见备份、恢复、升级与回滚。