凌晨两点设备刷完新固件卡在开机动画上不动了抓 logcat 只看到一段不断重复的堆栈Signature|privileged permissions not in privapp-permissions allowlist。这种场景在预装应用、ROM 定制、系统裁剪这类活儿里出现的频率远比想象中高——你只是往/system/priv-app里多塞了一个 APK整个系统就起不来了。privapp-permissions 这套机制从 Android 9 开始成为特权应用的一道硬门槛它管的是谁有资格拿特权权限而不是谁能装进 priv-app。搞不清这条界线排查方向就会一路跑偏。这篇内容面向的是做系统定制、预装应用、ROM 裁剪的工程师也适合被这个问题卡住的 Android 应用开发者。我会把 privapp-permissions 的判定链路、白名单文件的写法、落盘位置、分区差异、SELinux 上下文、以及不生效时的排查路径完整拆开顺带讲讲我在几个量产项目里踩过的具体坑。看完你应该能独立定位并修掉这类开机异常。1. 从开机卡死说起privapp-permissions 到底在管什么1.1 priv-app 目录的历史和它的特权含义/system/priv-app这个目录是 Android 4.4 引入的当时的目的很明确把普通系统应用和需要更高权限的系统应用分开。放在/system/app里的应用本质上和用户从应用商店装的 APK 差别不大只是不可卸载而放在/system/priv-app里的应用会被 PackageManagerService 打上一个FLAG_PRIVILEGED标记这个标记决定了它能申请一类特殊权限。所谓特殊权限指的是protectionLevel中带privileged标志位的那些权限。比如android.permission.WRITE_SECURE_SETTINGS、android.permission.MODIFY_PHONE_STATE、android.permission.INSTALL_PACKAGES、android.permission.READ_PRIVILEGED_PHONE_STATE它们的定义大致长这样permission android:nameandroid.permission.WRITE_SECURE_SETTINGS android:protectionLevelsignature|privileged /这里的signature|privileged是两个条件的组合写法。signature表示签名匹配才授予privileged表示只有 priv-app 里的应用才有资格走这条路径。两者都写意思是既要签名对又要位置对。很多人误以为只要签名对了就万事大吉实际上位置不对照样拿不到。把 protectionLevel 的常见取值和它们与白名单的关系整理成表方便对照protectionLevel数值谁能拿到是否受 privapp-permissions 约束normal0x0任何应用安装即授予否dangerous0x1任何应用运行时弹窗授权否signature0x2与声明方签名相同的应用否privileged0x10仅 priv-app 目录下的应用是signature|privileged0x12签名相同且位于 priv-app是signature|privileged|development0x32上述条件且为开发签名是且 user 版本通常拒绝这张表里最关键的一列是最后一列。判断是否需要白名单看的是权限的protectionLevel里是否含privileged位只要含了就必须出现在白名单里。1.2 Android 9 突然收紧的原因在 Android 9 之前priv-app 里的应用申请特权权限基本是申请就给。这带来一个现实问题设备厂商、渠道商、甚至某些第三方预装环节只要能把 APK 塞进 priv-app 分区就能拿到系统级权限。而 priv-app 分区在不少定制链路上是可写的这就让权限体系出现了一个很大的敞口。Android 9 引入了 allowlist 机制早期文档里叫 whitelist所以你在老代码和旧日志里会看到 whitelist 这个词核心逻辑是priv-app 应用申请任何带 privileged 标志的权限都必须在一个显式声明的 XML 清单里出现否则系统在启动阶段直接抛异常。这个异常发生在 SystemServer 启动过程中会导致系统崩溃重启表现出来就是无限开机动画。这个设计的意图是把授予权收回系统镜像本身。因为白名单文件位于只读分区随固件一起构建改它需要重新打包镜像链路比替换一个 APK 复杂得多。对厂商来说这是约束对安全模型来说是必要的收口。1.3 白名单文件的位置与形态AOSP 的约定是/system/priv-app里的应用白名单放在/system/etc/permissions//vendor/priv-app对应的放在/vendor/etc/permissions//product/priv-app放在/product/etc/permissions//system_ext/priv-app放在/system_ext/etc/permissions/。这个对应关系是一条铁律放错分区等于没放系统照样起不来。文件内容的格式很简单permissions privapp-permissions packagecom.example.demo permission nameandroid.permission.WRITE_SECURE_SETTINGS/ permission nameandroid.permission.MODIFY_PHONE_STATE/ /privapp-permissions /permissions外层permissions是 SystemConfig 解析器要求的根节点中间privapp-permissions的package属性必须精确匹配应用的packageName内层每个permission的name必须是完整权限字符串不能简写、不能带空格。文件命名本身没有强制规则SystemConfig 会扫描权限目录下所有.xml后缀的文件但业界普遍写成privapp-permissions-包名.xml一是可读二是方便批量管理。这个命名习惯在排查时很有用——看到一个陌生文件你能立刻知道它服务于哪个包。2. 判定链路拆解开机时系统到底比对了什么2.1 SystemConfig 的扫描与解析系统启动早期SystemConfig会遍历一组固定的权限目录。这组目录来自Environment和分区配置通常包括/system/etc/permissions、/system_ext/etc/permissions、/vendor/etc/permissions、/product/etc/permissions、/odm/etc/permissions。它会读取每个目录下的.xml文件把privapp-permissions节点收集成一张映射表键是包名值是该包被允许的特权权限集合。这里有个容易忽略的细节SystemConfig 只扫描目录的第一层不会递归子目录。我见过有同事把白名单放到/system/etc/permissions/xxx/子目录里然后疑惑为什么完全不生效——文件确实进了镜像只是根本没被读到。另一个细节是解析失败的处理。如果 XML 格式有误比如根节点写成了单个permission、标签没闭合、或者出现了非法字符SystemConfig 通常会打一条警告日志然后跳过整个文件而不会让系统崩溃。这意味着白名单文件写错了和白名单文件没放对位置表现是一样的应用照样被判违规。所以排查时不能只看有没有文件要看有没有解析成功的日志。2.2 PackageManagerService 的检查时机与豁免条件权限校验发生在包扫描完成之后的系统就绪阶段具体代码在PermissionManagerServiceImplAndroid 13 之前叫PermissionManagerService的checkPrivilegedPermissionAllowlist方法里。这个方法会对每个已安装的 priv-app 应用做一次遍历。判断逻辑大致是这样的不同版本有细微差异理解意图即可先看这个应用所在的分区据此选出对应的白名单表然后遍历应用声明requested的权限逐个检查其protectionLevel里是否含privileged位如果含且该权限不在白名单里就把这一条记进违规列表遍历结束后如果违规列表非空抛IllegalStateException。这里有三个关键点值得单独拎出来。第一判定基准是应用声明的权限不是最终被授予的权限。我实测过的 Android 9、10、13 版本都遵循这一点。也就是说如果你的应用声明了WRITE_SECURE_SETTINGS但因为签名不匹配实际上根本没拿到这个权限它依然需要出现在白名单里。这个行为经常让人困惑我都没有获得权限为什么还要报错答案是校验逻辑关注的是申请动作本身因为在扫描阶段就判定授予结果存在时序问题。第二targetSdkVersion是个明确的豁免变量。代码里有一条对targetSdkVersion Build.VERSION_CODES.P即 28的跳过逻辑。这就是为什么有些老应用塞进 priv-app 后一直没事直到某天你把它的 targetSdk 从 27 提到 29开机就炸了。关于这条豁免是否会长期存在我的建议是不要依赖它——新版本 AOSP 对老 targetSdk 的限制一直在收紧把它当成历史遗留的兼容缓冲更稳妥。第三检查是分区的。系统级 priv-app 走 system 白名单表vendor 分区走 vendor 表product 和 system_ext 各自独立。一个包只能匹配它自己所在分区的那张表跨分区不生效。2.3 调试开关 ro.control_privapp_permissions 的行为差异系统提供了一个属性开关来调节这套机制的严格程度ro.control_privapp_permissions。它支持三个值。enforce默认行为发现违规直接抛异常系统起不来。log只把违规情况打成警告日志不阻断启动。disable完全跳过校验连日志都不打。在device.mk或产品配置里加一行就能改PRODUCT_PROPERTY_OVERRIDES ro.control_privapp_permissionslog或者如果项目已经迁移到 Android 10 之后的属性写法PRODUCT_SYSTEM_PROPERTIES ro.control_privapp_permissionslog我在开发阶段的标准做法是新加任何 priv-app 应用之前先把属性切成log刷机跑一轮从 logcat 里把违规清单捞全再一次性补齐白名单最后切回enforce做验证。这样能避免反复刷机把调试周期从几次循环压缩到一次。需要提醒的是这个属性是ro.前缀只读改不了运行时值必须重新构建镜像。而且量产版本上不推荐用log蒙混过去量产固件的权限收紧要求通常会把它当作一项检查项。disable更不要碰那等于把整套机制关掉安全模型直接失效。3. 报错现场还原从 logcat 到白名单的完整定位路径3.1 异常信息在不同版本的措辞差异这个报错的文本形态随版本变化认准几个关键片段就不会看错Android 版本典型异常文本关键词9 ~ 11Signature|privileged permissions not in privapp-permissions whitelistwhitelist12 及以后Signature|privileged permissions not in privapp-permissions allowlistallowlist部分版本Package pkg requires permission perm which is not in the privapp-permissions allowlistrequires permission在 logcat 里最有效的过滤命令是直接搜关键词adb logcat -b all | grep -i -E privapp|privileged permission|allowlist加-b all是因为这类日志会落在 main、system、crash 多个缓冲区里只抓默认缓冲区可能漏掉。如果设备已经在无限重启建议用adb logcat -b all -d抓一次性快照保存到文件再分析比盯着滚动输出高效得多。异常的完整文本里通常会带上包名和具体权限名形如{com.example.demoandroid.permission.WRITE_SECURE_SETTINGS}。这个映射关系就是你的修复清单直接照着写白名单即可。如果一条异常里带了多个包要一次性全部处理因为系统在发现第一个违规后就会中断流程你看到的信息可能是最严重的那一批其他包的问题会在下一次启动才暴露出来。3.2 定位应用所在分区与真实包名拿到包名之后第一步是确认它到底在哪个分区。最直接的方式是查安装路径adb shell pm path com.example.demo返回类似package:/system/priv-app/DemoApp/DemoApp.apk前面的路径就说明了分区归属。如果返回的是/vendor/priv-app/...那么白名单必须放/vendor/etc/permissions/如果返回/system_ext/priv-app/...就放/system_ext/etc/permissions/。有时候pm path会因为系统已经在崩溃循环中而不可用这时可以从另一条路走直接用find扫目录。adb shell find /system /vendor /product /system_ext -name DemoApp.apk 2/dev/null包名和 APK 文件名不一致是常态别被文件名误导。pm path返回的是包名对应的安装路径这才是可信的。如果手头只有 APK 文件可以用aapt2 dump badging看它的包名aapt2 dump badging DemoApp.apk | head -3同时这条命令还能顺手把应用声明的权限全列出来为下一步写白名单做准备。3.3 一份可以照做的排查流程把上面的动作串起来形成一个固定流程。我在项目里一般按这个顺序走基本不会绕弯抓 log确认是 privapp-permissions 类异常记录违规的包名与权限名清单。用pm path或find确认应用所在分区。检查该分区对应的etc/permissions目录下是否已存在对应包的白名单文件。如果文件存在adb shell cat出来核对根节点是否正确、package属性是否与包名完全一致、权限名是否写全。在 logcat 里搜SystemConfig相关的警告看白名单文件是否解析失败。检查文件权限和 SELinux 上下文。补齐内容后重启验证同时观察 logcat 里是否还有残留违规。第 6 步经常被跳过但它是文件明明放对了却不生效的常见原因下一节会展开讲。4. 手写一份白名单从权限清单到落盘验证4.1 抓准应用真正声明了哪些特权权限写白名单最忌讳凭印象填。正确做法是从 APK 里把requestedPermissions完整导出再逐条判断哪些带privileged标志。aapt2 dump permissions DemoApp.apk输出里会有一组uses-permission条目。但这条命令只告诉你应用申请了什么不告诉你这个权限的 protectionLevel。要判断 protectionLevel需要去框架层的frameworks/base/core/res/AndroidManifest.xml里搜权限定义或者反编译/system/framework/framework-res.apk。一个更省事的办法是直接把所有这些权限都写进白名单。因为白名单只做允许判定多写几条不会报错只有漏写才会。代价是白名单文件会显得啰嗦但对功能没影响。我在赶进度的时候经常这么干等版本稳定了再精简。如果应用已经在设备上跑起来过哪怕是启动失败前的某一轮也可以直接查系统里的记录adb shell dumpsys package com.example.demo | grep -A 60 requested permissions输出的每一条后面会带grantedtrue或grantedfalse。注意grantedfalse不代表不需要白名单理由在前面讲过。判断特权权限还是得看权限定义本身。4.2 XML 的写法与命名约定假设应用声明了三个权限其中两个是特权权限白名单可以这样写?xml version1.0 encodingutf-8? permissions privapp-permissions packagecom.example.demo permission nameandroid.permission.WRITE_SECURE_SETTINGS/ permission nameandroid.permission.READ_PRIVILEGED_PHONE_STATE/ /privapp-permissions /permissions几个格式上的注意事项都是实际踩过的权限名必须完整WRITE_SECURE_SETTINGS这种简写会被当成未知权限静默失效。命名空间前缀不要乱加android.permission.就是完整前缀不需要再补什么。如果同一个包有多个白名单文件分散在不同目录只有它所在分区的那一个会被读取。一个 XML 文件里可以写多个privapp-permissions节点服务多个包但可维护性差不建议。文件名按privapp-permissions-包名.xml走跟其他同事协作时不会互相踩。4.3 编译进镜像的两种方式正式产品走构建系统。最通用的是PRODUCT_COPY_FILESPRODUCT_COPY_FILES \ vendor/example/permissions/privapp-permissions-com.example.demo.xml:$(TARGET_COPY_OUT_SYSTEM)/etc/permissions/privapp-permissions-com.example.demo.xml注意目标路径的写法。Android 10 之前可以直接写system/etc/permissions/...之后推荐用$(TARGET_COPY_OUT_SYSTEM)、$(TARGET_COPY_OUT_VENDOR)、$(TARGET_COPY_OUT_PRODUCT)这类变量避免分区布局变化后路径失配。如果项目使用 Soong 构建用prebuilt_etc更规范prebuilt_etc { name: privapp-permissions-com.example.demo, src: privapp-permissions-com.example.demo.xml, sub_dir: permissions, product_specific: true, }product_specific: true决定文件落在/product分区system_ext_specific: true落在/system_ext需要跟应用所在分区保持一致。这个属性写错是新手最容易犯的错构建能过镜像能刷但开机就是起不来。调试阶段不需要重新构建整个镜像直接推文件更快adb root adb remount adb push privapp-permissions-com.example.demo.xml /system/etc/permissions/ adb shell chmod 644 /system/etc/permissions/privapp-permissions-com.example.demo.xml adb shell restorecon /system/etc/permissions/privapp-permissions-com.example.demo.xml adb rebootadb remount在 Android 10 及以后依赖 overlayfs如果提示 remount 失败需要先执行adb disable-verity然后重启一次再 remount。这个步骤会打乱分区校验只适合调试机量产机不要这么干。4.4 文件权限和 SELinux 上下文chmod 644是必须的。权限目录下的文件如果权限过宽或过窄SystemConfig 读取时可能直接跳过日志里表现为文件存在但没解析出内容。SELinux 上下文同样关键。系统级权限文件应该是u:object_r:system_file:s0vendor 分区的是u:object_r:vendor_file:s0。验证方式adb shell ls -Z /system/etc/permissions/ | head -20复制文件时如果用了cp而不是带上下文的工具新文件可能继承了错误的标签或者在 permissive 之外的环境被直接拒绝读取。restorecon会根据路径规则恢复默认标签是修这个问题的标准动作。我在一个项目上遇到过一个特别隐蔽的情况白名单文件通过PRODUCT_COPY_FILES进了镜像权限 644上下文也对就是不生效。最后发现是文件末尾多了一个不可见字符导致 XML 解析在根节点之前就失败了。用xxd一看才现形。所以写完 XML 之后有条件的话用xmllint过一遍总没坏处。5. 那些年踩过的坑白名单不生效的典型情形5.1 分区归属判断错位这是出现频率最高的一类。应用装在/product/priv-app白名单写到了/system/etc/permissions两边都做对了但机制上就是不匹配。这种问题在 Android 10 引入 product 分区、Android 11 引入 system_ext 分区之后显著增多因为分区划分方案在不同项目里差异很大。判断标准只有一个白名单文件所在分区的etc/permissions目录必须和 APK 所在分区的priv-app目录同源。用pm path拿到 APK 路径看路径里第一个分区名然后对照选择目标目录。别凭经验猜不同项目把同一个应用放在不同分区是常事。5.2 权限名的拼写陷阱android.permission.READ_PRIVILEGED_PHONE_STATE和android.permission.READ_PHONE_STATE是两回事前者是特权权限后者是运行时的 dangerous 权限。我见过有人把两者搞混白名单里写了后者然后疑惑为什么特权权限还是拿不到。类似的还有android.permission.PACKAGE_USAGE_STATS这个是 signature|privileged|appop 的组合和android.permission.WRITE_SECURE_SETTINGSsignature|privileged。名字看起来差不多实际等级完全不同。核对时最稳妥的办法是去框架的AndroidManifest.xml里搜一遍确认protectionLevel属性。另外一点权限名是大小写敏感的。Android.permission.xxx这种首字母大写的写法不会被识别而且不会报错只会静默失效。5.3 sharedUserId 与包名匹配有些系统应用共享android.uid.system这样的 uidsharedUserId写在一起。这时候白名单的package属性依然要写各自的包名不是写 uid 名字。有人看到应用共享系统 uid就以为白名单要按 uid 组织这是误解。还有一种情况是应用改过包名但白名单没同步。改包名在预装应用里挺常见尤其是把第三方应用改名后重新签名的场景。改完之后 APK 里的packageName变了白名单的package属性必须跟着变否则匹配不上。5.4 OTA 升级后的残留增量 OTA 或者本地升级时旧版本的白名单文件可能残留在分区里新版本又推了一份不同命名的文件。两份文件同时存在内容不一致时SystemConfig 会把它们合并合并结果是权限集合的并集所以通常不会出问题。但如果旧文件里有非法内容导致解析失败新文件也可能被连带影响。清理策略是升级脚本里显式删除旧的权限文件或者保持命名稳定永远用同一个文件名覆盖。我在项目里倾向于后者简单可靠。5.5 厂商定制 ROM 的额外白名单目录部分厂商 ROM 在 AOSP 之外增加了自己的权限目录或者对privapp-permissions做了二次封装。遇到按 AOSP 规则做了一切还是不生效的情况值得去init.rc或者SystemConfig相关的厂商补丁里看看有没有额外的目录被加进来。这类信息一般在厂商的 BSP 文档里或者直接 grep 一下frameworks/base里SystemConfig的改动记录。5.6 调试属性被用户版本覆盖开发阶段设了ro.control_privapp_permissionslog切到 user 版本构建时这个属性被产品配置覆盖成enforce于是之前被日志掩盖的违规全部爆发成开机异常。这种情况在版本切换时很常见。稳妥做法是把属性设置和构建类型解耦不要在userdebug和user之间用不同的值而是统一按enforce的标准把白名单补齐。让编译期配置保持一致能省掉大量为什么这个版本可以那个版本不行的排查时间。5.7 签名匹配导致的误判有一种情况特别容易让人困惑应用申请的是普通的signature权限不带privileged标志理论上不需要白名单但系统还是报错。原因通常是这个权限在某个版本里被改成了signature|privileged。AOSP 的权限定义随版本演进而调整同一个权限在不同 Android 版本上的 protectionLevel 可能不同。处理办法是查当前版本框架里的定义而不是查网上搜到的旧资料。搜索路径是frameworks/base/core/res/AndroidManifest.xml找到对应permission节点看android:protectionLevel。这也是为什么我一直建议把权限定义的核对作为排查的第一步而不是最后一步。6. 不想加白名单几条替代路线的取舍6.1 改动 targetSdkVersion 的代价把targetSdkVersion降到 27 确实能绕过检查因为代码里对 28 以下的包有跳过逻辑。但代价不小应用商店的提交政策会拦截低 targetSdk 的应用新版本系统对老 targetSdk 的兼容行为也在持续收紧比如后台限制、存储访问、通知渠道这些都要按新规则适配。更麻烦的是这个豁免本身是历史遗物未来某个版本取消掉你的应用会突然失效。除非是内部专用、不打算长期维护的小工具否则不建议走这条路。6.2 把应用移出 priv-app如果把应用从priv-app挪到app目录特权权限直接不给功能会缺失。这种情况下要评估的是应用到底需不需要这些权限。有些应用申请特权权限只是图省事比如用WRITE_SECURE_SETTINGS改系统设置实际可以用Settings.System配合用户交互替代用INSTALL_PACKAGES静默安装可以换成PackageInstaller的会话式安装。功能体验会打折扣但合规性和可维护性更好。6.3 自研签名权限配合系统签名另一种思路是不申请系统预定义的特权权限而是自己声明一套signature级别的权限不带privileged标志然后把应用和平台用同一套签名签出来。这样应用能拿到自研权限不受白名单约束。前提是你的构建流程能拿到平台签名而这在很多项目里本身就是个门槛。需要提醒的是signature权限的授予依赖签名一致如果客户端设备上运行的是别人签名的系统这个方案直接失效。它适合自建生态或者内部项目不适合面向通用设备的应用。6.4 打开 log 模式的风险用ro.control_privapp_permissionslog把机制降级短期看确实能让系统起来。但它只是把报错换成警告权限依然没有被授予——应用该拿不到的权限还是拿不到功能照旧残缺。真正的区别是系统不会崩你能进系统慢慢修。这是个调试手段不是修复方案。把它留在量产版本里等于给系统留了一个权限敞口后续任何能往 priv-app 塞应用的人都能绕过这道检查。6.5 系统服务代理方案最后一条路是权限不下放。让需要特权能力的应用通过系统里已有的组件间接完成操作比如通过 Binder 调用一个已经持有权限的系统服务。代价是要在框架层写一套接口工作量大但安全边界最清晰。我在做过的一个项目里就是这么处理设备管理类操作的预装应用只负责界面和交互真正的设备控制走一个自研的系统服务。白名单文件从此只剩寥寥几条维护成本大幅下降。7. 几个实测有效的调试习惯adb remount推送的方式在调试期能省下大量时间但每次重启后 overlayfs 的改动可能丢失所以一旦确定内容正确就要立刻把改动落到设备构建配置里。我一般会在本地维护一份permissions/目录推送和构建共用同一份源文件避免两边内容不一致。另一个习惯是在白名单文件头部加注释记录这个包为什么需要这些权限permissions !-- DemoApp 需要修改系统设置与读取特权电话状态用于设备管理场景 -- privapp-permissions packagecom.example.demo permission nameandroid.permission.WRITE_SECURE_SETTINGS/ permission nameandroid.permission.READ_PRIVILEGED_PHONE_STATE/ /privapp-permissions /permissions版本迭代几轮之后你大概率会忘了当初为什么给某个包开了某条权限。有注释在清理无用权限时心里有底。这个机制的本质是让每一次权限授予都留下痕迹白名单文件本身就该承担这份记录职责。最后说一个排查顺序上的经验遇到开机异常先看是不是 privapp-permissions 引起的再确认分区最后才看内容。我见过太多次有人一头扎进 XML 内容里逐条核对结果问题出在文件被放到了另一个分区。顺序对了大部分问题在前两步就能收敛。