Stellar UserService深度解析:如何在特权服务进程中运行你自己的Binder服务
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 会先做三件事:
- 校验
packageName/className非空,包必须真实存在,否则回调错误码(如ERROR_PACKAGE_NOT_FOUND); - 以
包名:类名:进程后缀为 key 查找已存在的记录——相同 versionCode 且存活则直接复用,避免重复拉起进程; - 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,它做了些"重活":
- 通过
ActivityThread.systemMain()获取系统主线程,用createPackageContextAsUser以CONTEXT_IGNORE_SECURITY加载你的包; - 反射调用
LoadedApk.makeApplication()初始化你的Application(失败时回退为纯 Context 方案,专门规避部分联发科设备上的兼容性问题,见 UserServiceStarter.kt); - 用你的 ClassLoader 加载服务类,优先匹配
constructor(Context),找不到再试无参构造; - 实例必须是
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 章节。核心四步:
- 定义 AIDL:接口命名建议
I<ServiceName>,如IMyUserService; - 实现服务类:继承
IMyUserService.Stub(),业务逻辑与普通 Binder 完全一致; - 绑定服务:
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) { /* 处理失败 */ }
})
- 管理生命周期:
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 应用,这套机制值得纳入你的工具箱。