akn 全局管理命令使用说明
akn 是 AKStream.Next 安装完成后的统一运维入口。它不是另一套服务管理逻辑，而是调用当前部署方式随包交付的受控管理器：Linux 对接 systemd，macOS 对接 launchd，Windows 对接 SCM，Docker 对接宿主机上的 Docker Compose。这样用户不需要记住安装目录，也不会因为在错误目录执行旧版脚本而管理错实例。
正式包升级的完整前置检查、页面步骤、状态和回滚说明见在线升级完整指南。
flowchart LR
A[管理员运行 akn] --> B[识别当前部署方式]
B --> C[systemd · launchd · Windows SCM · Docker Compose]
安装后会发生什么
| 部署方式 | akn 注册位置 |
应在哪里运行 | 底层管理对象 |
|---|---|---|---|
| Linux 原生 | /usr/local/bin/akn |
Linux 宿主机终端 | akstream-next.service、NodeAgent、托管 MediaServer |
| macOS 原生 | /usr/local/bin/akn |
macOS 宿主机终端 | 两个 LaunchDaemon 与托管 MediaServer |
| Windows 原生 | akn（管理入口目录加入系统 PATH），目录加入机器 PATH |
新打开的 CMD 或 PowerShell | AKStream.Next、AKStream.Next.NodeAgent Windows 服务 |
| Docker | /usr/local/bin/akn 或当前运维用户的 ~/.local/bin/akn |
Docker 宿主机；Windows Docker Desktop 在执行安装的 WSL 发行版 | 当前 AKStream.Next Compose 栈 |
安装器只会覆盖带有 AKStream.Next 管理标记的旧 akn。如果同名命令属于其他程序，安装会明确停止，不会强行覆盖。Windows 和用户级 Docker 安装修改 PATH 后需要重新打开终端。
最常用的命令
akn info
akn status
akn upgrade <正式升级包>
sudo akn admin-password status
sudo akn admin-password reset
akn start
akn restart
akn stop
akn verify-recovery
akn uninstall
akn help
Docker 额外提供：
akn update
安装人员只使用交付包提供的 install、upgrade、status、start、restart、stop 和 uninstall 等命令，不在生产服务器制作发布包。Docker 的 update 只用于更新已保存的源码或镜像来源，不替代正式包事务升级。
命令的准确含义
| 命令 | 实际动作 | 业务影响 | 权限 |
|---|---|---|---|
akn info |
汇总安装/运行版本、节点与集群、角色、部署与性能模式、入口、数据库类型、关键目录、录像根和进程健康 | 只读；绝不显示密码、连接串、Token 或密钥 | 普通终端；Docker 需 daemon 权限 |
akn status |
检查主服务、NodeAgent 和 /health；Docker 同时显示 Compose 状态 |
只读 | 普通终端；Docker 账号需有 daemon 权限 |
akn upgrade <包> |
校验与当前平台/RID 匹配的更高版本正式包，建立事务备份，切换并验收；失败自动回滚 | 明确中断网页、API、媒体和 Agent | 原生部署需 root/管理员；Docker 需 daemon 权限 |
akn admin-password status |
显示超级管理员账号启用、失败、锁定、最后登录/改密和哈希算法状态 | 只读；密码明文从未保存，因此不能查看 | 原生部署需 root/管理员；Docker 需 daemon 权限 |
akn admin-password reset |
隐藏输入两次新密码，按生产密码策略重新哈希，清除账号锁定、轮换安全戳、撤销活动会话并写安全审计 | 管理员现有会话立即失效 | 原生部署需 root/管理员；Docker 需 daemon 权限 |
akn start |
按依赖顺序启动，并等待主服务健康后启动/验收 Agent | 会恢复对外服务 | 原生部署需 root/管理员 |
akn restart |
重启主服务，等待健康，再处理 Agent 和托管 MediaServer | 会短暂中断 | 原生部署需 root/管理员 |
akn stop |
停止 AKStream.Next、托管 MediaServer 和 NodeAgent；Docker 停止整套 Compose 服务 | 中断业务 | 原生部署需 root/管理员 |
akn update |
Docker 开发/自建环境按已保存的源码或镜像来源重新构建并重启 | 会更新并重启；不执行正式包事务校验与自动回滚 | 仅 Docker，需 daemon 权限 |
akn verify-recovery |
真实强制终止主进程/PID 1，验证当前平台声明的恢复所有者；Linux 验证 NodeAgent 在主服务控制连接中断后恢复 | 明确中断 | 仅维护窗口 |
akn uninstall |
交互选择仅卸载服务/容器并保留数据，或完全清理 | 中断业务；完整清理不可恢复 | 需高权限 |
akn help |
显示当前部署管理器支持的完整参数 | 只读 | 普通终端 |
执行正式包升级
upgrade 先校验版本、平台与包完整性；失败时停止并返回可诊断结果，新版不可用时按升级结果处理回滚。
| 部署方式 | 命令示例 | 正式包格式 |
|---|---|---|
| Linux | sudo akn upgrade ./AKStream.Next-1.0.0.136-linux-arm64.tar.gz |
linux-x64 或 linux-arm64 的 .tar.gz |
| macOS | sudo akn upgrade ./AKStream.Next-1.0.0.136-osx-arm64.tar.gz |
osx-x64 或 osx-arm64 的 .tar.gz |
| Windows | akn upgrade .\AKStream.Next-1.0.0.136-win-arm64.zip |
win-x64 或 win-arm64 的 .zip |
| Docker | akn upgrade ./AKStream.Next-1.0.0.136-docker-linux-arm64.tar.gz |
docker-linux-amd64 或 docker-linux-arm64 的 .tar.gz |
升级会中断当前网页、API、媒体会话和录像写入，只能在维护窗口执行。终端返回成功后仍要运行 akn status，核对 /health 的版本，并验证一条真实视频和录像；完整预检、备份目录、状态与回滚说明见在线升级完整指南。
Linux 与 macOS
查看状态和帮助不需要提权；生命周期动作使用 sudo：
akn info
akn status
akn help
sudo akn admin-password status
sudo akn admin-password reset
sudo akn upgrade ./AKStream.Next-<版本>-<RID>.tar.gz
sudo akn start
sudo akn restart
sudo akn stop
sudo akn verify-recovery
sudo akn uninstall
命令会直接询问“保留数据”或“完全清理”，完整清理还会再次确认。--purge --yes 仅供已明确授权的无人值守操作：
sudo akn uninstall --purge --yes
Linux 的 akn 调用安装目录中的 Deploy/linux/akstream-next.sh，macOS 调用 Deploy/macos/akstream-next.sh。升级时安装器会同步更新这份管理器，所以不要把全局命令手工改为某个解压目录的软链接。
Windows
安装完成后关闭并重新打开终端：
akn status
akn help
在“以管理员身份运行”的 CMD 或 PowerShell 中执行生命周期动作：
akn start
akn restart
akn stop
akn upgrade .\AKStream.Next-1.0.0.136-win-arm64.zip
akn verify-recovery
akn uninstall
管理员账号状态与密码恢复也必须在管理员终端执行：
akn admin-password status -Username admin
akn admin-password reset -Username admin
密码采用带随机盐、pepper 的不可逆 PBKDF2-SHA256 摘要，数据库里不存在可供 akn 回显的明文。reset 默认直接从终端隐藏读取两次；不得把密码写进命令行参数、Shell 历史或工单。自动化确有需要时只能通过受保护管道传入两行相同密码，并显式使用 Unix --password-stdin 或 Windows -PasswordStdin。
Windows 参数保持 PowerShell 风格。永久清理示例：
akn uninstall -Purge -Yes
CMD 与 PowerShell 都直接使用 akn，无需输入文件扩展名。管理器会注册系统 PATH 并发送环境更新通知。Windows Terminal 请关闭整个应用再重开；已有终端也可以执行 set "PATH=%PATH%;%ProgramData%\AKStream.Next\Tools"（CMD）临时刷新。不要向不同 PATH 目录复制多个管理入口。通过 SSH 或 SYSTEM 后台安装时，已有桌面会话可能需要注销后重新登录。
完整清理会检查删除结果。若当前终端或资源管理器正占用安装/数据目录，关闭这些窗口，后台清理会最多重试三分钟；未清理的路径及错误会写入卸载器提示的诊断文件，不会把尚有残留报告为完全删除。
Docker：必须在宿主机运行
Docker 版 akn 是“宿主机 Compose 管理命令”，不是容器内命令。主容器无法可靠地停止、重建或重新拉起自己；把 Docker socket 挂入业务容器也会扩大权限边界。因此请在最初运行 Deploy/docker/akstream-next.sh install 的同一宿主环境中执行：
akn info
akn status
akn admin-password status
akn admin-password reset
akn start
akn restart
akn stop
akn upgrade ./AKStream.Next-1.0.0.136-docker-linux-arm64.tar.gz
akn update
akn verify-recovery
akn uninstall
安装器已经把 Docker 部署根目录固化到该包装命令中，不再要求每次输入 --root。如果命令安装到 ~/.local/bin/akn 且目录尚未进入 PATH，安装完成提示会给出完整路径；把 ~/.local/bin 加入 PATH 并重新打开终端即可。
Docker 正式发布包必须使用 akn upgrade。akn update 不读取正式包，也不提供相同的备份、健康验收和数据库回滚保证。
Windows Docker Desktop 的规则是：
- 如果安装脚本在 WSL Ubuntu 中执行，
akn也在该 WSL Ubuntu 中运行。 - Windows 原生
akn管理 Windows 服务，不会自动管理 WSL 中的 Docker 栈。 - 不要在
docker exec -it akstream-next ...进入的容器 Shell 中执行akn restart。
同一运维用户同时管理多套 Docker 根目录时，只允许其中一套占用默认 akn，安装器发现它已指向另一套根目录会停止，避免一个短命令误重启错误实例。其他栈继续使用带显式 --root 的 Docker 管理脚本。
Docker 的永久清理：
akn uninstall --purge
它会删除 Compose 容器以及部署根目录中的 Config、MySQL、录像和媒体数据。执行前必须做独立备份。
怎样判断启动成功
至少核对四层：
akn status返回成功，主服务和 NodeAgent 均为运行状态。GET /health返回健康和预期版本。- 系统 readiness 中数据库、MediaServer 和已启用模块没有阻断项。
- 使用一条已知通道验证拉流和播放；启用录像时确认产生文件与索引。
脚本显示服务进程存在但 /health 失败时，先查看主服务日志。/health 成功但没有画面时，问题通常在设备、媒体、播放协议、NAT 或浏览器层，不应反复重启主服务。
卸载与 purge 边界
交互运行 uninstall 会询问是保留恢复数据还是完全清理；完整清理会删除配置、安装码、密钥和运行数据，并按平台清理 AKStream.Next 受管的 Nginx 入口。--purge --yes（Linux、macOS、Docker）或 -Purge -Yes（Windows）只用于已明确授权的无人值守操作。
普通故障、配置错误和升级失败都不应首先使用 purge。先参考 备份、升级与回滚。