nanoMuse手机本地运行时揭秘:APK内塞入Alpine Linux+Proot,让AI在手机上跑完整Linux

原创2026-10-15 09:38:071,670 阅读

nanoMuse手机本地运行时揭秘:APK内塞入Alpine Linux+Proot,让AI在手机上跑完整Linux

nanoMuse 手机本地运行时把一套 Alpine Linux(aarch64)根文件系统和 PRoot 直接塞进 APK,让 AI Agent 无需 root 权限就能在手机上运行完整 Linux:真实 shell、文件读写、git、Python、定时任务全部在这台“口袋里的 Linux 小机器”里执行。这篇文章带你拆解这个 APK 里到底藏了什么,以及 PRoot 是如何绕过 Android 沙箱跑起一个操作系统的。

nanoMuse 多设备运行时架构:Android 手机在屏幕上执行任务,与桌面、Web 共享同一个 Agent

一、为什么 AI 助手需要一部“手机里的 Linux”

大多数 AI 助手只会聊天,而 nanoMuse 的 Agent 要动手干活:跑脚本、克隆仓库、处理文件、调用 MCP 工具、执行定时任务。这些事光靠云端 API 做不到——你需要一个真实的执行环境。

把执行环境做成云端服务会带来网络依赖和数据出境问题;而 nanoMuse 的选择是:把整个运行时打包进 APK,全部跑在手机本地。模型推理走云端(或你自己的 Key),但 shell、文件和工具执行都在设备内完成,断网了定时任务照样记账,隐私数据不出手机。

这套“手机本地运行时”是 nanoMuse 在 Android、iOS 上最核心的工程之一。

二、APK 里到底塞了哪三样东西

拆开 APK 看,本地运行时由三个部分组成:

组件 作用 构建脚本
Alpine Linux aarch64 minirootfs 一个约几十 MB 的完整 Linux 根文件系统(busybox、ash、apk 包管理器) prepare_android_sandbox.sh
PRoot 5.1(静态编译的 aarch64 二进制) 用户态“伪 chroot”,不需要 root 就能挂载并运行 rootfs build_proot.sh
ELF Loader(libproot-loader.so) 绕过 Android W^X 限制、让 PRoot 能启动 guest 进程的关键 同上

构建脚本的思路非常直接:prepare_android_sandbox.sh 从 Alpine 官方源下载 alpine-minirootfs-3.21.3-aarch64.tar.gz,从 Termux 软件源解出 PRoot 的 aarch64 静态二进制,然后全部放进 app/src/main/assets/,随 APK 一起分发。build_proot.sh 则用 Android NDK r28+(minSdk 26)把 OpenMinis 的 proot 分支和 talloc 2.4.2 交叉编译成三个产物:

assets/proot-aarch64                        # 沙箱二进制
jniLibs/arm64-v8a/libproot.so               # 以 .so 身份进入 nativeLibraryDir
jniLibs/arm64-v8a/libproot-loader.so        # 64 位 loader
jniLibs/arm64-v8a/libproot-loader32.so     # 32 位 loader

⚠️ 注意那两个“挂着 .so 后缀的可执行文件”——这不是笔误,而是 Android 10+ 的 W^X 策略逼出来的:标记为 app_data_file 的文件(包括解压后的整个 rootfs)永远不可执行,只有从 jniLibs 解压到 nativeLibraryDir 的 .so 才能执行。loader 伪装成 .so 才能过这一关,细节可见 build_proot.sh 开头的设计注释。

三、PRoot 原理:无 root 的“用户态 chroot”

传统 chroot 需要 root 权限来切换根目录、伪造设备节点;手机上没有 root,怎么办?PRoot 的答案是 ptrace:

  1. 以普通进程启动,fork 出 guest 进程;
  2. 用 ptrace 拦截 guest 的每一次系统调用;
  3. 在拦截点上重定向路径——把 guest 眼中的 / 映射到 app 私有目录下的 alpine-rootfs/,把 /dev、/proc、/sys 绑定到真实文件;
  4. 伪造 getuid() 返回 0,让 guest 里的 apk add、pip install 以为自己是 root。

每次 shell 执行时,Kotlin 侧的 PRootKernel.kt 会拼出一条这样的命令行:

proot -0 --link2symlink \
      -r <files>/alpine-rootfs \
      -b /dev -b /proc -b /sys \
      -w /root \
      -b <host>:<guest> ... \
      --native-offload=<socket>:<handlers> \
      /bin/sh -c "<command>"

几个参数各有讲究:

  • -0:伪 root。guest 里的包管理器都要求 uid 0,PRoot 在 ptrace 拦截层里骗过它们;
  • --link2symlink:Android 的 /data 文件系统拒绝应用 uid 创建跨目录硬链接(EPERM),而 Alpine 的 apk 安装 busybox 工具时就靠硬链接——这个开关把所有 link() 系统调用翻译成符号链接,apk 才能正常工作;
  • -b 绑定挂载:除了 /dev、/proc、/sys,还会把 app 私有目录里的 memory/、skills/、shared/、mcp-servers/ 挂到 guest 的 /var/minis/ 下,用户在设置页挂载的外部文件夹(Obsidian 库、Downloads 等)也挂到 /var/minis/mounts/<name>,guest 里改文件就是直接改手机上的真实文件。

四、首次启动:进度条背后的解压与装配

第一次打开 App 时,RootfsManager.kt 会从 assets 里取出压缩的 alpine-minirootfs.tar.gz,用自带的 POSIX tar 解析器逐条解压到 files/alpine-rootfs/,并对外发布 Preparing → Extracting(进度) → Finalizing → Installed 状态流——界面上的进度条正是这个 StateFlow 驱动的,进度按压缩字节消耗计算,所以全程平滑单调。

解压完成后,PRootKernel.boot() 还会做一套“开机仪式”:

  • 把 default_mount/ 覆盖层叠到 rootfs 上(每次开机重新覆盖,保证 pip/npm/apk 的镜像配置随版本更新);
  • 刷新 DNS,把系统代理注入 guest 环境变量;
  • 注入一批环境变量:HOME=/root、手机时区转成的 POSIX TZ、NO_COLOR=1、GOMAXPROCS=2、UV_LINK_MODE=symlink 等;
  • 启动 native-offload 服务,在 guest 的 /usr/local/bin/ 里为每个已注册的宿主处理器放置一个空壳脚本(stub)。

五、AI 如何驱动这台 Linux:shell 工具与审批卡片

Agent 的 shell_execute 工具本质就是走上面那条 proot /bin/sh -c "..." 通道:命令在 Alpine 里真实执行,stdout/stderr 原样回到对话里。而 native-offload 机制则让一些“必须回到宿主执行”的操作(打开系统浏览器、设备能力调用)也能像普通命令一样运行:guest 执行 stub 时触发 execve,PRoot 扩展会把它通过 abstract unix socket 转给 Kotlin 侧的 NativeOffloadServer,宿主执行完再把输出写成 guest /tmp 里的文件,并重写执行流为 /bin/cat <文件>——guest 视角里这只是一次普通的命令输出。

nanoMuse 审批卡片:Agent 执行敏感操作前先征求用户同意

安全是这套本地沙箱的重要部分:由于 Agent 真的能在 Linux 里跑任意命令,nanoMuse 对删除、发送、支付这类不可撤销的操作会弹出审批卡片(如上图),允许/拒绝完全由用户决定;同时所有 /var/minis/... 路径在解析时会被限制在沙箱内,.. 和越界符号链接一律失效。

六、已知局限:ptrace 的代价

无 root 的强大能力来自 ptrace,代价也来自 ptrace,官方设计文档里写得很坦率:

  • 系统调用密集的场景变慢:PRoot 拦截每一个 syscall,纯计算的 Python 几乎无感,但 git clone 大仓库、pip install 大量小文件这类操作会比原生慢 2–5 倍;
  • musl 而非 glibc:Alpine 用 musl libc,预编译二进制要选 musllinux 版本,否则需要 apk add gcompat;
  • 没有真 root 的能力:绑定 1024 以下端口、改 uid 等操作不可用;/proc 里读到的是 Android 的真实值或替代品;
  • 内存压力:Android 在后台仍可能回收服务,服务用 START_STICKY 加闹钟补跑机制兜底。

这些权衡的设计记录见 docs/local-runtime.md,整体 Android 侧说明见 docs/android.md。

七、动手构建:自己编译一个含 Linux 沙箱的 APK

如果你想完整体验这套手机本地运行时,构建门槛并不高(JDK 17/21 + Android SDK + NDK r28+):

git clone --recurse-submodules https://gitcode.com/gh_mirrors/na/nanoMuse
cd nanoMuse
bash scripts/android/env.sh            # 裸机环境初始化
./deps/build_proot.sh                  # 交叉编译 PRoot + loader
./scripts/prepare_android_sandbox.sh  # 下载 Alpine aarch64 rootfs
cd android/src/android && ./gradlew :app:assembleDebug

构建顺序有讲究:loader 缺失时故障很隐蔽——PRoot 能启动、日志看起来一切正常,但第一条 execve("/bin/sh") 就会 Permission denied,所有命令都返回 <a href="https://link.gitcode.com/i/32f4fc674cc7682ad3c8da72cc87721a" target="_blank">Shell not running] (exit code: -1)。unzip -l app-debug.apk | grep libproot 确认三个 .so 都在,再跑一条真实命令断言退出码为 0,才算通过。完整的依赖清单和排错指南在 [android/BUILDING.md。

八、总结

nanoMuse 用手机本地运行时证明了一件事:一个 APK 可以装下一整台 Linux。Alpine minirootfs 提供系统,PRoot 用 ptrace 在用户态伪造出 root 与文件系统视图,Kotlin 侧负责装配、挂载、offload 和审批。没有虚拟机镜像、没有 root、没有模拟器——只是更聪明的系统调用拦截。对想在移动端跑 AI Agent 的开发者来说,这套“APK 内嵌 Linux 沙箱”的方案值得一读:核心代码都集中在 android/src/android/app/src/main/java/com/openminis/app/sandbox/ 和 android/deps/ 下,路径清晰,注释详尽。

登录后查看全文
nanoMuse