Stellar UserService深度解析:如何在特权服务进程中运行你自己的Binder服务

原创2026-10-11 12:52:421,733 阅读
文章标签:移动开发原生移动认证鉴权开发工具

Stellar UserService深度解析:如何在特权服务进程中运行你自己的Binder服务

Stellar 是基于 Shizuku 的深度定制特权 API 框架,其 UserService(用户服务) 能力允许你把自己的 Binder 服务放到 ADB/Root 启动的特权服务进程中运行,从而以 shell(uid=2000)甚至 root 身份执行系统级操作,而应用本身无需任何 Root 权限。本文完整拆解 UserService 的启动链路、安全设计与生命周期管理,并给出从零创建第一个特权 Binder 服务的操作步骤。

为什么需要 UserService?

普通应用里,你的 Service 或 Binder 只能以应用自身 uid 运行,调用隐藏 API 或访问受保护资源时会被系统拦截。Stellar 的思路是:

  • 进程分离:由特权服务进程(ADB 或 Root 启动的 server 模块)通过 app_process 拉起一个新进程;
  • 身份继承:这个新进程以 Shell/Root 身份加载你的 APK 中的 Binder 服务类;
  • 双向 Binder:服务进程把 Binder 回传给 Stellar 服务端,服务端再转发给你的应用,形成 客户端 App ↔ Stellar 服务端 ↔ 用户服务进程 的三方通信链路。

这样一来,你的业务代码(AIDL 接口实现)依然写在自己的应用里,运行时却拥有特权身份。

核心模块一览

UserService 的服务端实现集中在 server 模块,各文件职责清晰:

模块 文件 职责
服务管理器 UserServiceManager.kt 参数校验、进程拉起、记录管理
进程启动器 UserServiceStarter.kt 被 app_process 执行的入口,反射加载服务类
Binder 包装器 UserServiceBinder.kt 拦截管理事务,其余透传给你的服务
服务记录 UserServiceRecord.kt 死亡监听、优雅销毁
常量定义 UserServiceConstants.kt 启动模式、错误码、命令模板
协调层 UserServiceCoordinator.kt 对 StellarServiceCore 暴露统一入口

AIDL 入口在 StellarService.kt 中的 startUserService / stopUserService / attachUserService 三个方法;使用 Shizuku API 的应用则通过 ShizukuUserServiceAdapter.kt 无缝走同一套流程。

启动一个用户服务:完整链路解析

整个流程可以概括为 6 步,理解这条链路是掌握 UserService 的关键。

第 1 步:应用发起绑定请求

在你的应用中通过 API 调用 StellarUserService.bindUserService(args, callback),参数用 Builder 模式配置服务类名、进程后缀、版本号等。请求经 AIDL 到达服务端的 startUserService。

第 2 步:服务端校验与去重

UserServiceManager.startUserService 会先做三件事:

  1. 校验 packageName / className 非空,包必须真实存在,否则回调错误码(如 ERROR_PACKAGE_NOT_FOUND);
  2. 以 包名:类名:进程后缀 为 key 查找已存在的记录——相同 versionCode 且存活则直接复用,避免重复拉起进程;
  3. versionCode 变化时先静默停掉旧服务再启动新的,实现升级替换。

第 3 步:生成 token 并拼接启动命令

每个服务实例会分配一个 UUID 作为 token,随后由 generateStartCommand 生成形如这样的命令(模板见 UserServiceConstants.kt):

CLASSPATH='.../manager_safe.apk' /system/bin/app_process \
  --nice-name='com.example:userservice' \
  roro.stellar.server.userservice.UserServiceStarter \
  --token='...' --package='com.example' --class='com.example.MyService' \
  --uid=10123 --mode=0 --verification-token='...'

关键点:

  • --mode=0 为 ONE_TIME 一次性模式,--mode=1 为 DAEMON 守护模式;
  • CLASSPATH 指向管理器 APK 的一份安全副本(下一节详述);
  • 32 位设备可自动切换 app_process32。

第 4 步:特权进程内反射加载你的服务类

新进程执行 UserServiceStarter.main,它做了些"重活":

  1. 通过 ActivityThread.systemMain() 获取系统主线程,用 createPackageContextAsUser 以 CONTEXT_IGNORE_SECURITY 加载你的包;
  2. 反射调用 LoadedApk.makeApplication() 初始化你的 Application(失败时回退为纯 Context 方案,专门规避部分联发科设备上的兼容性问题,见 UserServiceStarter.kt);
  3. 用你的 ClassLoader 加载服务类,优先匹配 constructor(Context),找不到再试无参构造;
  4. 实例必须是 IBinder 的子类,否则启动失败。

第 5 步:Binder 回传与授权验证

服务实例会被包进一层 UserServiceBinder。它只拦截 4 个管理事务:

事务码 作用
TRANSACTION_DESTROY 延迟 100ms 后 System.exit(0),优雅退出
TRANSACTION_IS_ALIVE 存活探测
TRANSACTION_GET_UID / GET_PID 返回服务进程 uid / pid

其余所有事务原样透传给你真正的服务。随后进程通过 sendBinderToServer 以 getContentProviderExternal 方式直连管理器的 ContentProvider,调用 sendUserService 把 Binder + token 交回服务端。token 是授权凭证:服务端 attachUserService 只接受自己签发过的 token,杜绝未授权进程偷偷挂靠。

第 6 步:回调通知客户端

attach 成功后,UserServiceRecord.onServiceAttached 注册死亡监听,并向客户端回调 onServiceConnected(binder, verificationToken)。你在 onServiceConnected 里用 IMyUserService.Stub.asInterface(service) 拿到强类型接口即可直接调用。

安全设计亮点:安全 APK 与校验

拉起进程时 CLASSPATH 指向的并不是原始管理器 APK,而是 prepareSafeManagerApk 精心准备的 /data/local/tmp/stellar/manager_safe.apk,防护措施层层叠加:

  • 🔒 目录权限 0700、文件权限 0400,仅服务进程可读写;
  • 🔒 全程 lstat 检查,拒绝符号链接,防止链接攻击;
  • 🔒 复制后做 SHA-256 摘要比对,校验失败即中止;
  • 🔒 先写临时文件再 rename 原子替换,避免半截 APK 被加载。

此外每次启动都携带 verification-token,客户端在 onServiceConnected 中收到后可比对,确认拿到的 Binder 确实是服务端为本次绑定签发的。

两种运行模式:ONE_TIME 与 DAEMON

在 UserServiceArgs 中通过 serviceMode 选择模式(常量定义见 UserServiceConstants.kt):

模式 行为 适用场景
ONE_TIME 客户端进程死亡监听触发后服务进程自动退出;客户端断线时 onClientDisconnected 也会主动清理 一次性批量任务、短时特权操作
DAEMON 持续运行直到显式 unbindUserService,可用 getDaemonServices 查询存活实例 长期后台任务、跨会话服务

双向死亡监听保证了"任一端倒下另一端都知道":服务端对服务 Binder 挂了 DeathRecipient(UserServiceRecord.kt),服务进程对 Stellar 服务端和客户端也挂了监听,Stellar 服务挂掉时用户服务进程会自行退出,不会留下孤儿进程。

快速上手:在你的应用中创建特权服务

完整集成步骤(依赖添加、StellarProvider 配置)见官方集成指南 INTEGRATION_GUIDE.md,UserService 专项内容在「用户服务:StellarUserService」与示例 7~9 章节。核心四步:

  1. 定义 AIDL:接口命名建议 I<ServiceName>,如 IMyUserService;
  2. 实现服务类:继承 IMyUserService.Stub(),业务逻辑与普通 Binder 完全一致;
  3. 绑定服务:
val args = UserServiceArgs.Builder(MyUserService::class.java)
    .processNameSuffix("myservice")          // 进程名后缀
    .versionCode(BuildConfig.VERSION_CODE.toLong())
    .serviceMode(ServiceMode.ONE_TIME)      // 或 ServiceMode.DAEMON
    .build()

StellarUserService.bindUserService(args, object : StellarUserService.ServiceCallback {
    override fun onServiceConnected(service: IBinder) {
        userService = IMyUserService.Stub.asInterface(service) // 可以开始调用
    }
    override fun onServiceDisconnected() { /* 更新 UI 状态 */ }
    override fun onServiceStartFailed(errorCode: Int, message: String) { /* 处理失败 */ }
})
  1. 管理生命周期:StellarUserService.peekUserService(args) 取回存活的 Binder;StellarUserService.unbindUserService(args) 停止服务;UserServiceHelper.isAlive / getUid / getPid / destroy 提供辅助探测。

💡 实用技巧:versionCode 参与去重 key 的复用判断——应用升级后 versionCode 变化,旧服务会被自动替换重启,你无需写任何清理代码。

自动清理:包卸载与服务守护

除了死亡监听,UserServiceManager 还通过 ApkChangedObservers 监听 APK 文件变化:包被卸载时立即调用 removeSelf() 回收服务进程,包被更新时标记服务待下次请求时重启。removeSelf 会先向服务发送 TRANSACTION_DESTROY 让进程优雅退出,再解除监听、通知客户端(UserServiceRecord.kt)。

常见错误码速查

启动失败时回调会携带错误码,定义在 UserServiceConstants.kt:

错误码 含义 排查方向
1 权限被拒绝 未授予 stellar 权限
2 包未找到 检查 packageName 是否正确
3 类未找到 服务类名拼写 / 混淆问题
4 进程启动失败 查看服务日志
5 连接超时(默认 10 秒) 检查服务类是否成功加载
7 参数无效 packageName/className 不能为空
8 / 9 签名校验失败 / 未授权启动 token 或签名不匹配

另外注意:服务连接超时上限为 SERVICE_CONNECT_TIMEOUT = 10000L 毫秒,服务类构造函数里做耗时初始化可能导致超时,建议把重活推迟到首次业务调用。

总结

Stellar UserService 用一条清晰的链路——参数校验 → app_process 拉起 → 反射加载 → Binder 回传 → 授权验证 → 双向死亡监听——把你的普通 Binder 服务"搬"进了特权进程。配合安全 APK 校验、token 授权、包变更守护等机制,它既保留了 Shizuku 生态的兼容性(Shizuku 应用零改动可用),又通过 ONE_TIME / DAEMON 双模式、版本化升级替换等设计覆盖了从一次性任务到常驻守护的各种场景。如果你在开发需要系统级权限的 Android 应用,这套机制值得纳入你的工具箱。

登录后查看全文
Stellar