macOS 从解压到首次登录

macOS 包通过 launchd LaunchDaemon 托管主服务和 NodeAgent，支持 Intel 与 Apple Silicon。开发机可前台调试，但长期运行仍应安装为系统服务。

flowchart LR
    A[确认 Intel / Apple Silicon] --> B[解压并运行安装脚本]
    B --> C[launchd 托管主服务和 Agent]
    C --> D[打开 5800 完成首次配置]

1. 确认架构

uname -m

arm64 使用 osx-arm64，x86_64 使用 osx-x64。本机还需要 .NET 7 ASP.NET Core Runtime；可以用 dotnet --list-runtimes 检查。

2. 校验和解压

shasum -a 256 AKStream.Next-<版本>-osx-arm64.tar.gz
tar -xzf AKStream.Next-<版本>-osx-arm64.tar.gz
cd AKStream.Next-<版本>-osx-arm64
./Deploy/macos/akstream-next.sh --help

将计算结果与同一 Release 的 SHA256 记录对比。包中目录含义见安装包结构。

3. 安装 LaunchDaemon

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

默认位置：

程序和数据：/Library/Application Support/AKStream.Next
配置：/Library/Application Support/AKStream.Next/Config
主服务标签：com.akstream.next
Agent 标签：com.akstream.next.agent

安装器会注册 /Library/LaunchDaemons 下的 plist，并由 launchd 负责自动拉起。不要把服务文件安装到个人用户的临时目录。

安装前必须确认 5800 没有被另一个 AKStream.Next、Docker 端口映射或其他程序占用。新版安装器会核对监听 PID 与 com.akstream.next LaunchDaemon，不能再以任意进程返回的 HTTP 200 作为本次安装成功。浏览器下载产生的 com.apple.quarantine 只会在固定发布包边界内从 AKStream.Next、NodeAgent 与 ZLMediaKit 组件移除；Gatekeeper 本身保持启用，发布包之外的文件不会被放行。

lsof -nP -iTCP:5800 -sTCP:LISTEN
docker ps --format '{{.Names}}\t{{.Ports}}'

4. 完成首次配置

sudo cat '/Library/Application Support/AKStream.Next/Config/.akstream-next-setup-token'
curl -fsS http://127.0.0.1:5800/health
curl -fsS http://127.0.0.1:5800/api/v2/setup/status

首次安装时，最后一条命令必须返回 "required": true。如果返回 "required": false，或 /health 显示另一个版本/节点，请先停止占用 5800 的旧实例或 Docker 容器，再执行 sudo akn restart。浏览器打开 http://127.0.0.1:5800/ 或局域网可达地址，按首次配置向导完成安装。完成时主进程退出并由 launchd 拉起完整模式。

5. 状态、启停与日志

akn status
sudo akn restart
sudo akn stop
sudo akn start

还可以检查 launchd：

sudo launchctl print system/com.akstream.next
sudo launchctl print system/com.akstream.next.agent

应用已经运行但页面打不开时，先检查 /health、监听端口和 macOS 防火墙，再检查配置和 MediaServer，不要反复重装。

6. Apple Silicon 常见误区

osx-arm64 主程序、MediaServer、FFmpeg 和动态库必须都是 ARM64，不能只替换其中一个。
Homebrew 在 Apple Silicon 上常位于 /opt/homebrew，但脚本会按实际命令位置探测，不应把路径写死到业务配置。
正式发布包已经包含需要的媒体组件；安装服务器不需要准备媒体组件编译工具链。

7. 升级、恢复和卸载

使用新包脚本再次执行 install --package-dir "$PWD" 完成升级。程序和 Agent 的上一版本保留为 *.backup，但仍需单独备份配置、数据库和录像。

verify-recovery 会中断主进程，仅在维护窗口使用：

sudo akn verify-recovery

交互运行卸载时会选择“保留数据”或“完全清理”，完整清理会再次确认；--purge --yes 只用于无人值守：

sudo akn uninstall

下一步：管理命令速查。

第三方依赖下载源

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