Linux 从解压到首次登录

本页面向第一次安装 AKStream.Next 的 Linux 用户。目标是把 Release 安装成 systemd 服务，打开首次配置页，并知道出现问题时去哪里看。

flowchart LR
    A[核对架构与包] --> B[解压到固定目录]
    B --> C[运行安装脚本]
    C --> D[systemd 托管服务]
    D --> E[打开 5800 完成首次配置]

1. 确认机器架构

uname -m

输出	下载包
`x86_64` 或 `amd64`	`linux-x64`
`aarch64` 或 `arm64`	`linux-arm64`

不要在 ARM64 上使用 x64 的 MediaServer，也不要把 QEMU 模拟当作生产方案。

2. 准备基础依赖

Release 运行需要 .NET 7 ASP.NET Core Runtime。MySQL 应在首次配置完成前可达；FFmpeg 用于裁剪、截图或转码等文件任务。

Ubuntu/Debian 可先执行：

sudo apt-get update
sudo apt-get install -y curl ffmpeg
dotnet --list-runtimes
ffmpeg -version

如果缺少运行时，安装命令可以增加 --install-runtime，脚本会从 Microsoft 官方安装入口处理。当前项目目标仍为 net7.0；迁移到受支持的 .NET 版本属于单独升级工作。

3. 校验并解压

sha256sum -c SHA256SUMS.txt --ignore-missing
tar -xzf AKStream.Next-<版本>-linux-x64.tar.gz
cd AKStream.Next-<版本>-linux-x64

ARM64 把文件名替换为 linux-arm64。先阅读安装包结构，确认 AKStream.Next/、NodeAgent/ 和 Deploy/linux/ 存在。

4. 查看当前脚本支持的命令

./Deploy/linux/akstream-next.sh --help

不要照抄其他版本的参数；以当前包脚本帮助为准。

5. 安装

在解压后的包根目录执行：

sudo ./Deploy/linux/akstream-next.sh install \
  --package-dir "$PWD"

脚本会检查 CPU/RID、.NET Runtime、FFmpeg 和本次选定的媒体服务来源，复制程序，并安装固定以 root 运行的主服务、NodeAgent systemd unit 与受控 Nginx 管理入口；不创建专用服务账号。MediaServer 是否随包提供要看当前下载资产，未随包时按安装器与首次向导选择已有节点或受支持的本机准备方式。默认位置：

程序：/opt/AKStream.Next
主配置：/etc/akstream-next/Config/akstream.next.json
首次安装码：/etc/akstream-next/Config/.akstream-next-setup-token
Agent 数据：/var/lib/akstream-next-agent

需要自定义程序目录时使用 --install-dir。配置目录仍由脚本固定管理，不要把程序、密钥和录像混在一个临时目录。

6. 打开首次配置页

全新安装允许暂时没有 akstream.next.json。脚本会启动受限的首次配置模式并输出访问地址。

sudo cat /etc/akstream-next/Config/.akstream-next-setup-token
curl -fsS http://127.0.0.1:5800/health

在能够访问服务器的浏览器打开：

http://<服务器IP>:5800/

输入安装码，按完成首次配置走完 10 步。完成后主进程会主动退出，由独立 NodeAgent 使用固定 systemd unit 白名单重新拉起完整服务，这是正常过程；主 unit 自身保持 Restart=no。

7. 检查服务状态

./Deploy/linux/akstream-next.sh status
systemctl status akstream-next.service --no-pager
systemctl status akstream-next-agent.service --no-pager

status 同时检查主服务、NodeAgent 和 /health。只有 systemd 显示 active 还不够，健康接口也必须成功。

8. 查看日志

sudo journalctl -u akstream-next.service -n 200 --no-pager
sudo journalctl -u akstream-next-agent.service -n 200 --no-pager
sudo journalctl -u akstream-next.service -f

先记录故障时间，再保存相同时间段内主服务、Agent、MediaServer 和 Nginx 日志。不要只复制最后一行异常。

9. 常用生命周期命令

安装完成后可在任意目录使用 akn：

akn status
sudo akn start
sudo akn restart
sudo akn stop

verify-recovery 会强制终止主进程，验证 NodeAgent 在控制连接中断时仍能通过固定 Provider 恢复，必然造成短时中断，只能在维护窗口执行：

sudo akn verify-recovery

10. 升级与卸载

升级时解压新包，再执行新包中的 install --package-dir "$PWD"。先备份配置、数据库、安全目录和录像，再确认新版本数据库迁移与回退方案。

交互运行卸载时会直接选择“保留数据”或“完全清理”，选择完全清理后还会再次确认：

sudo akn uninstall

sudo akn uninstall --purge --yes 只用于已明确授权的无人值守完整清理；它会删除配置、Token、运行数据和受管 Nginx 入口，不用于修复普通故障。

下一步：管理命令速查和完成首次配置。

第三方依赖下载源

安装器优先使用国内镜像。Linux 的 Debian/Ubuntu（含 ARM Ubuntu Ports）及可映射的 RPM 发行版源，只在本次操作的临时配置中切换，保留发行版签名验证；国内源失败则回退原有官方/已配置源。macOS 通过中科大 Homebrew API 与 Bottles 安装 FFmpeg、数据库、Nginx 和构建依赖，失败后回退官方源，不永久修改用户环境。当前所需 ASP.NET Core Runtime 没有已核验稳定国内镜像，仍使用微软官方源。下载来源不改变目标架构、运行时类型或版本要求。