资讯详情

深入了解 · 专业解读

OpenHarmony_HAP_权限签名安装问题处理教程

发布时间：2026/6/27 9:32:34
OpenHarmony_HAP_权限签名安装问题处理教程 OpenHarmony 5.1 HAP 安装权限与签名 Profile 配置教程适用场景DevEco Studio 构建 OpenHarmony 应用时安装 HAP 报9568289、9568344、install parse profile prop check error、grant request permissions failed等错误。示例工程com.openharmony.jymqtt示例 SDKC:\Users\Lenovo\AppData\Local\OpenHarmony\Sdk\181. 问题现象DevEco Studio Run 应用时常见报错如下Install Failed: error: failed to install bundle. code:9568289 error: install failed due to grant request permissions failed. PermissionName: ohos.permission.INSTALL_BUNDLE或者Install Failed: error: failed to install bundle. code:9568289 error: install failed due to grant request permissions failed. PermissionName: ohos.permission.START_INVISIBLE_ABILITY或者Install Failed: error: failed to install bundle. code:9568344 error: install parse profile prop check error.2. 错误原因总结2.19568289这个错误表示应用申请了高权限但是当前签名 Profile 没有授权这些权限。典型权限包括ohos.permission.INSTALL_BUNDLE ohos.permission.START_ABILITIES_FROM_BACKGROUND ohos.permission.START_INVISIBLE_ABILITY这些权限不是普通normalAPL 应用默认能申请的需要在 HarmonyAppProvision / Profile 中配置apl:system_core以及acls:{allowed-acls:[ohos.permission.INSTALL_BUNDLE,ohos.permission.START_ABILITIES_FROM_BACKGROUND,ohos.permission.START_INVISIBLE_ABILITY]}2.29568344这个错误常见于应用使用了ServiceExtensionAbility或其他特权 Extension但是设备侧没有配置白名单。如果module.json5中有extensionAbilities:[{name:ServiceExtAbility,type:service}]则设备侧需要配置install_list_capability.json并开启allowAppUsePrivilegeExtension:true3. 三个权限分别是什么3.1ohos.permission.INSTALL_BUNDLE作用允许应用安装其他 HAP / Bundle。适用场景应用商店 系统升级工具 自动安装器 设备管理类系统应用普通 MQTT 客户端一般不需要这个权限。3.2ohos.permission.START_ABILITIES_FROM_BACKGROUND作用允许应用在后台启动 Ability。适用场景后台 ServiceExtension 主动拉起页面 后台服务启动其他 Ability 后台业务需要唤起组件3.3ohos.permission.START_INVISIBLE_ABILITY作用允许应用启动不可见 Ability。这个权限级别较高通常属于系统级或特权应用使用。4.module.json5中声明权限文件位置通常是entry/src/main/module.json5如果确实需要这三个权限可以配置requestPermissions:[{name:ohos.permission.INSTALL_BUNDLE,usedScene:{abilities:[ServiceExtAbility],when:always}},{name:ohos.permission.START_ABILITIES_FROM_BACKGROUND,usedScene:{abilities:[ServiceExtAbility],when:always}},{name:ohos.permission.START_INVISIBLE_ABILITY,usedScene:{abilities:[ServiceExtAbility],when:always}},{name:ohos.permission.INTERNET}]注意ServiceExtAbility必须和extensionAbilities中的 Ability 名称一致。例如如果实际是name:IpcServiceExtAbility则usedScene.abilities也要写abilities:[IpcServiceExtAbility]5. 获取当前 HAP 证书指纹5.1 从distribution-certificate提取证书证书通常在 HarmonyAppProvision 文件的字段中distribution-certificate:-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n复制内容新建profile.cer保存时必须把\n改成真实换行。正确格式示例-----BEGIN CERTIFICATE----- MIIC... ... -----END CERTIFICATE-----不要保留这些字符\n ,5.2 用keytool计算指纹keytool -printcert -file profile.cer输出类似SHA256: 2F:2E:84:F9:21:85:23:AD:F2:4D:91:CE:86:87:39:D4:2F:68:1B:0E:59:B8:65:EE:46:E0:9E:13:6A:5F:C0:5A去掉冒号后2F2E84F9218523ADF24D91CE868739D42F681B0E59B865EE46E09E136A5FC05A这个值后面要填到install_list_capability.json的app_signature中。6. 修改 SDK Profile 模板本次工程实际使用的 SDK 路径是C:\Users\Lenovo\AppData\Local\OpenHarmony\Sdk\18\toolchains\lib进入目录cd /d C:\Users\Lenovo\AppData\Local\OpenHarmony\Sdk\18\toolchains\lib先检查模板findstr /n /i bundle-name apl allowed-acls INSTALL_BUNDLE START_INVISIBLE_ABILITY START_ABILITIES_FROM_BACKGROUND UnsgnedReleasedProfileTemplate.jsonRelease 包实际使用的是UnsgnedReleasedProfileTemplate.json需要确认它包含bundle-name:com.openharmony.jymqtt,apl:system_core,以及acls:{allowed-acls:[ohos.permission.INSTALL_BUNDLE,ohos.permission.START_ABILITIES_FROM_BACKGROUND,ohos.permission.START_INVISIBLE_ABILITY]}完整结构示例{version-name:1.0.0,version-code:1,uuid:xxx,type:release,bundle-info:{developer-id:OpenHarmony,distribution-certificate:-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n,bundle-name:com.openharmony.jymqtt,apl:system_core,app-feature:hos_normal_app},acls:{allowed-acls:[ohos.permission.INSTALL_BUNDLE,ohos.permission.START_ABILITIES_FROM_BACKGROUND,ohos.permission.START_INVISIBLE_ABILITY]},permissions:{restricted-permissions:[]}}检查 JSON 是否正确powershell -NoProfile -Command Get-Content .\UnsgnedReleasedProfileTemplate.json -Raw | ConvertFrom-Json | Out-Null; echo OK输出OK说明 JSON 格式没有问题。7. 关键坑工程里可能固定使用旧.p7b本次真正的问题在这里。工程build-profile.json5中有signingConfigs:[{name:default,material:{certpath:C:/Users/Lenovo/.ohos/config/openharmony/default_JYMQTT_xxx.cer,keyAlias:debugKey,profile:C:/Users/Lenovo/.ohos/config/openharmony/default_JYMQTT_xxx.p7b,storeFile:C:/Users/Lenovo/.ohos/config/openharmony/default_JYMQTT_xxx.p12}}]这里的重点是profile:C:/Users/Lenovo/.ohos/config/openharmony/default_JYMQTT_xxx.p7b只要工程固定指定了这个.p7bDevEco 打包时就会使用旧的.p7b不会自动使用你刚刚修改过的 SDK 模板。所以会出现SDK 模板已经是 system_core 但是最终 HAP 反查还是 apl normal8. 反查最终 HAP 中的 Profile进入 SDK 工具目录cd /d C:\Users\Lenovo\AppData\Local\OpenHarmony\Sdk\18\toolchains\lib创建输出目录rmdir /s /q D:\hapcheck mkdir D:\hapcheck导出 HAP 里的证书链和 profilejava -jar hap-sign-tool.jar verify-app -inFile E:\baidu\arkTS_code\XJTtoMe\JYMQTT\entry\build\default\outputs\default\entry-default-signed.hap -outCertChain D:\hapcheck\out.cer -outProfile D:\hapcheck\out.p7b注意参数大小写-outCertChain不要写成-outCertchain解析 profilejava -jar hap-sign-tool.jar verify-profile -inFile D:\hapcheck\out.p7b -outFile D:\hapcheck\profile_check.json查看关键字段findstr /n /i bundle-name apl allowed-acls INSTALL_BUNDLE START_INVISIBLE_ABILITY START_ABILITIES_FROM_BACKGROUND D:\hapcheck\profile_check.json正确结果应该类似bundle-name: com.openharmony.jymqtt apl: system_core allowed-acls: [ ohos.permission.INSTALL_BUNDLE ohos.permission.START_ABILITIES_FROM_BACKGROUND ohos.permission.START_INVISIBLE_ABILITY如果还是apl: normal说明最终 HAP 仍然使用旧 profile。9. 处理固定旧.p7b的方法方案 A重新生成.p7b用修改后的UnsgnedReleasedProfileTemplate.json重新sign-profile生成新的.p7b覆盖build-profile.json5中指定的旧.p7b。大致流程是UnsgnedReleasedProfileTemplate.json ↓ sign-profile 新的 default_JYMQTT_xxx.p7b ↓ DevEco 重新签名 HAP entry-default-signed.hap生成后先验证新.p7bjava -jar hap-sign-tool.jar verify-profile -inFile C:\Users\Lenovo\.ohos\config\openharmony\default_JYMQTT_xxx.p7b -outFile D:\hapcheck\new_profile_check.json检查findstr /n /i bundle-name apl allowed-acls INSTALL_BUNDLE START_INVISIBLE_ABILITY START_ABILITIES_FROM_BACKGROUND D:\hapcheck\new_profile_check.json必须看到apl: system_core方案 B重新生成 DevEco 签名材料在 DevEco Studio 中File Project Structure Signing Configs删除旧 signing config重新创建签名配置。然后确认生成的新.p7b中apl是system_core。10. 配置板端install_list_capability.json如果应用用了ServiceExtensionAbility还需要修改设备侧白名单。查找文件hdc shell find / -name install_list_capability.json 2/dev/null常见路径/system/etc/app/install_list_capability.json拉到电脑hdc file recv /system/etc/app/install_list_capability.json D:\install_list_capability.json备份copy D:\install_list_capability.json D:\install_list_capability.json.bak添加应用项{bundleName:com.openharmony.jymqtt,app_signature:[2F2E84F9218523ADF24D91CE868739D42F681B0E59B865EE46E09E136A5FC05A],allowAppUsePrivilegeExtension:true}如果原文件结构是{install_list:[]}可以改成{install_list:[{bundleName:com.openharmony.jymqtt,app_signature:[2F2E84F9218523ADF24D91CE868739D42F681B0E59B865EE46E09E136A5FC05A],allowAppUsePrivilegeExtension:true}]}推回设备hdc target mount hdc file send D:\install_list_capability.json /system/etc/app/install_list_capability.json hdc shell chmod 644 /system/etc/app/install_list_capability.json hdc shell sync hdc shell reboot重启后确认hdc shell cat /system/etc/app/install_list_capability.json | grep -A 8 -B 2 com.openharmony.jymqtt11. 清理构建缓存并重新安装修改签名 Profile 后建议强制清理构建产物。关闭 DevEco Studio然后执行cd /d E:\baidu\arkTS_code\XJTtoMe\JYMQTT rmdir /s /q entry\build rmdir /s /q build rmdir /s /q .hvigor重新打开 DevEco StudioBuild Clean Project Build Rebuild Project Run或者手动安装hdc install E:\baidu\arkTS_code\XJTtoMe\JYMQTT\entry\build\default\outputs\default\entry-default-signed.hap12. 最终验证安装成功后板端查询包名hdc shell bm dump -a | grep -i mqtt查询指纹hdc shell bm dump -n com.openharmony.jymqtt | grep -i fingerprint如果输出类似fingerprint:2F2E84F9218523ADF24D91CE868739D42F681B0E59B865EE46E09E136A5FC05A说明签名证书、白名单和安装结果一致。13. 本次排查的核心结论本次真正踩坑点是SDK 模板已经改成 system_core但是工程 build-profile.json5 指定了固定旧 p7b。所以最终 HAP 仍然是apl:normal安装时继续报9568289 grant request permissions failed PermissionName: ohos.permission.INSTALL_BUNDLE最终解决思路1. module.json5 声明需要的权限 2. HarmonyAppProvision/Profile 设置 aplsystem_core 3. allowed-acls 加入高权限 4. 重新生成工程实际使用的 .p7b 5. 反查最终 HAP确认 aplsystem_core 6. ServiceExtension 场景配置 install_list_capability.json 7. 重新构建安装14. 常用排查命令汇总查 SDK 模板cd /d C:\Users\Lenovo\AppData\Local\OpenHarmony\Sdk\18\toolchains\lib findstr /n /i bundle-name apl allowed-acls INSTALL_BUNDLE START_INVISIBLE_ABILITY START_ABILITIES_FROM_BACKGROUND UnsgnedReleasedProfileTemplate.json查工程固定签名配置cd /d E:\baidu\arkTS_code\XJTtoMe\JYMQTT findstr /s /n /i signingConfigs profile p7b certpath storeFile keyAlias *.json5 *.json *.properties反查最终 HAPcd /d C:\Users\Lenovo\AppData\Local\OpenHarmony\Sdk\18\toolchains\lib rmdir /s /q D:\hapcheck mkdir D:\hapcheck java -jar hap-sign-tool.jar verify-app -inFile E:\baidu\arkTS_code\XJTtoMe\JYMQTT\entry\build\default\outputs\default\entry-default-signed.hap -outCertChain D:\hapcheck\out.cer -outProfile D:\hapcheck\out.p7b java -jar hap-sign-tool.jar verify-profile -inFile D:\hapcheck\out.p7b -outFile D:\hapcheck\profile_check.json findstr /n /i bundle-name apl allowed-acls INSTALL_BUNDLE START_INVISIBLE_ABILITY START_ABILITIES_FROM_BACKGROUND D:\hapcheck\profile_check.json查证书指纹keytool -printcert -file D:\hapcheck\out.cer查板端应用hdc shell bm dump -a | grep -i mqtt hdc shell bm dump -n com.openharmony.jymqtt | grep -i fingerprint15. 注意事项不要把keyPassword、storePassword、.p12私钥文件发给别人。install_list_capability.json里的app_signature必须和最终 HAP 的证书 SHA256 一致。bm dump获取指纹的前提是应用已经安装成功。没安装成功时要从证书或 HAP 中离线获取指纹。hap-sign-tool.jar verify-app的参数是-outCertChain大小写不能错。最终判断以profile_check.json为准不以 SDK 模板为准。

相关新闻