易百纳玄武S3_app_portal示例部署指南_专栏

硬件平台：易百纳玄武S3

易百纳社区

简介

App Portal是运行在玄武S3（RK3588+RK182X）边缘AI终端上的应用交付与生命周期管理工具。它通过YAML catalog描述应用的安装包、资源文件、依赖、服务、健康检查和启动入口，支持DEB、Python Wheel和 Generic三类安装方式，提供应用安装、启动、停止、重启、卸载、资源清除、Portal自更新及RKNN3 Runtime更新能力。

示例功能：

统一Web控制台，默认监听18090，支持同一局域网内PC浏览器直接访问；
一键安装/启动/停止/重启/卸载catalog中登记的板端应用（如AI Hub、AI Meeting、Multistream VLM等）；
自动按RKNN3 Runtime版本匹配应用发布版本，下载并校验资源与共享模型；
支持命令行（app-portal）与网页两种操作方式，网页服务开机自启。

整体流程分为四步：

在PC将SDK中的applications/app_portal拷贝到板端/userdata；
板端执行install.sh安装CLI与Web控制台（自动安装Python依赖、校验catalog、启动服务）；
浏览器访问Web页面验证（端口18090）；
通过Web页面安装、启动和管理应用。

环境准备

项目	说明
SDK	RK182X SDK（网盘资料：【易百纳】玄武S3边缘计算AI终端_V2.0中的rk182x_ai_release.tar.gz）
目标板	玄武S3边缘计算AI终端（Debian 13，RK3588+RK182X）
Web 控制台依赖	`python3-yaml`、`python3-fastapi`、`python3-uvicorn`（`install.sh`自动安装，板端需可访问网络）

部署步骤

将app_portal拷贝至板端

在PC上执行以下命令，将SDK中的applications/app_portal目录推送到板端：

adb push <RK182X SDK\applications\app_portal> /userdata

说明：如PC连接了多台ADB设备，可先用adb devices查看设备列表，再用adb -s <设备ID> push ...指定目标板。

板端安装

推送完成后，进入板端/userdata/app_portal目录执行安装脚本：

cd /userdata/app_portal
chmod +x ./install.sh
./install.sh

安装脚本会自动完成以下工作：

安装Python依赖（python3-yaml，安装Web控制台时还会安装python3-fastapi、python3-uvicorn）；
将CLI程序安装到/usr/share/app-portal/，命令入口安装到/usr/local/bin/app-portal；
将顶层catalog复制到/etc/app-portal/catalog.yaml，应用分片同步到/etc/app-portal/apps/；
执行app-portal check校验catalog，并输出本地RKNN3 Runtime版本；
安装并启动app-portal-web.service，同时设置开机自启。

安装成功后如下所示：易百纳社区

Web 访问验证

安装完成后，在同一局域网内的PC浏览器中访问：

http://<板子IP>:18090/

本例为：http://192.168.1.168:18090/（请替换为你板端的实际IP地址）。

打开后即可看到 App Portal 页面，顶部显示已装载应用数、运行中任务数、Portal 版本与catalog路径，以及RKNN3 Runtime的版本与服务状态，共有八个应用，每个应用卡片提供「安装、启动、重启、停止、卸载、清除」操作按钮：

易百纳社区

查看服务状态

Web服务由systemd管理，可在板端通过以下命令查看运行状态：

systemctl status app-portal-web.service    //查看Web服务状态
journalctl -u app-portal-web.service -n 200 --no-pager    //查看Web服务日志

安装后服务默认已启动并设置开机自启；如需重启服务：

sudo systemctl restart app-portal-web.service

应用管理（可选）

除网页操作外，也可通过板端CLI管理应用，常用命令如下：

命令	作用
`app-portal check`	校验 catalog 及应用分片的 YAML 格式、字段约束和引用关系
`app-portal list`	列出 catalog 中登记的应用、安装方式和软件包
`app-portal runtime-version`	获取当前板端 RKNN3 Runtime 版本
`app-portal status <app-id>`	查看指定应用的安装状态、服务状态、资源和磁盘占用
`sudo app-portal install <app-id>`	安装指定应用（下载模型与资源、安装依赖并部署）
`sudo app-portal start <app-id>`	启动应用并执行健康检查
`sudo app-portal stop <app-id>`	停止指定应用
`sudo app-portal restart <app-id>`	重启应用并重新执行健康检查
`sudo app-portal uninstall <app-id>`	停止并卸载应用，默认保留模型等资源
`sudo app-portal update`	扫描并安装最新版 App Portal CLI 与 Web 软件包

常见问题

网页打不开（18090 端口无响应）：检查systemctl status app-portal-web.service是否正常、18090端口是否被占用（ss -ltnp | grep 18090）及PC与板端网络是否互通；可通过journalctl -u app-portal-web.service -n 200 --no-pager查看日志。只执行了--cli-only安装时不提供网页，需重新完整安装。
下载缓慢、中断或磁盘空间不足：下载临时文件位于/userdata/app_portal/cache（大文件支持断点续传）。确认该分区剩余空间、DNS与网盘连通性；失败或未完成的下载会计入应用资源残留，可通过网页「清除」或卸载时使用--purge-resources清理。