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

woaizhuliya

112人浏览 · 2026-06-26 14:26:14

woaizhuliya · 2026-06-26 14:26:14 发布

OpenHarmony 5.1 HAP 安装权限与签名 Profile 配置教程

适用场景：DevEco Studio 构建 OpenHarmony 应用时，安装 HAP 报 9568289、9568344、install parse profile prop check error、grant request permissions failed 等错误。
示例工程：com.openharmony.jymqtt
示例 SDK：C:\Users\Lenovo\AppData\Local\OpenHarmony\Sdk\18

1. 问题现象

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.1 `9568289`

这个错误表示：

应用申请了高权限，但是当前签名 Profile 没有授权这些权限。

典型权限包括：

ohos.permission.INSTALL_BUNDLE
ohos.permission.START_ABILITIES_FROM_BACKGROUND
ohos.permission.START_INVISIBLE_ABILITY

这些权限不是普通 normal APL 应用默认能申请的，需要在 HarmonyAppProvision / Profile 中配置：

"apl": "system_core"

以及：

"acls": {
  "allowed-acls": [
    "ohos.permission.INSTALL_BUNDLE",
    "ohos.permission.START_ABILITIES_FROM_BACKGROUND",
    "ohos.permission.START_INVISIBLE_ABILITY"
  ]
}

2.2 `9568344`

这个错误常见于应用使用了 ServiceExtensionAbility 或其他特权 Extension，但是设备侧没有配置白名单。

如果 module.json5 中有：

"extensionAbilities": [
  {
    "name": "ServiceExtAbility",
    "type": "service"
  }
]

则设备侧需要配置：

install_list_capability.json

并开启：

"allowAppUsePrivilegeExtension": true

3. 三个权限分别是什么

3.1 `ohos.permission.INSTALL_BUNDLE`

作用：允许应用安装其他 HAP / Bundle。

适用场景：

应用商店
系统升级工具
自动安装器
设备管理类系统应用

普通 MQTT 客户端一般不需要这个权限。

3.2 `ohos.permission.START_ABILITIES_FROM_BACKGROUND`

作用：允许应用在后台启动 Ability。

适用场景：

后台 ServiceExtension 主动拉起页面
后台服务启动其他 Ability
后台业务需要唤起组件

3.3 `ohos.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.json

Release 包实际使用的是：

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"

只要工程固定指定了这个 .p7b，DevEco 打包时就会使用旧的 .p7b，不会自动使用你刚刚修改过的 SDK 模板。

所以会出现：

SDK 模板已经是 system_core
但是最终 HAP 反查还是 apl normal

8. 反查最终 HAP 中的 Profile

进入 SDK 工具目录：

cd /d "C:\Users\Lenovo\AppData\Local\OpenHarmony\Sdk\18\toolchains\lib"

创建输出目录：

rmdir /s /q D:\hapcheck
mkdir D:\hapcheck

导出 HAP 里的证书链和 profile：

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"

注意参数大小写：

-outCertChain

不要写成：

-outCertchain

解析 profile：

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

正确结果应该类似：

"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

生成后先验证新 .p7b：

java -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.jymqtt"

11. 清理构建缓存并重新安装

修改签名 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 Studio：

Build > Clean Project
Build > Rebuild Project
Run

或者手动安装：

hdc install "E:\baidu\arkTS_code\XJTtoMe\JYMQTT\entry\build\default\outputs\default\entry-default-signed.hap"

12. 最终验证

安装成功后，板端查询包名：

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 设置 apl=system_core
3. allowed-acls 加入高权限
4. 重新生成工程实际使用的 .p7b
5. 反查最终 HAP，确认 apl=system_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

反查最终 HAP

cd /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 fingerprint"

15. 注意事项

不要把 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 模板为准。

开源鸿蒙跨平台开发者社区

开源鸿蒙跨平台开发社区汇聚开发者与厂商，共建“一次开发，多端部署”的开源生态，致力于降低跨端开发门槛，推动万物智联创新。

更多推荐

react native 0.72遇到react-native-screens库出现cxx编译问题的解决方案

《React Native轻量化编译C++错误排查全记录》摘要：本文记录了程序员千里马在维护React Native相簿应用时遭遇的棘手编译问题。项目在轻量化编译时频繁出现react-native-screens的C++编译错误，而完整编译却能通过。作者先后排查了路径限制、缓存污染、网络依赖、版本兼容等问题，尝试了换包、重建工程等多种方案。最终发现是node_modules中老旧的react-na

开源鸿蒙跨平台开发者社区

分布式软总线核心代码分析（二）

本文分析了OpenHarmony分布式软总线5.1版本中"发现服务"的核心实现机制。发现服务通过DiscMgrInit初始化三个通信介质（BLE/CoAP/USB），建立发布服务链表（g_publishInfoList）、发现服务链表（g_discoveryInfoList）和16个能力匹配桶（g_capabilityList）。当设备被发现时，系统会根据设备能力位图与订阅者进

开源鸿蒙跨平台开发者社区

动态化方案：React Native, Weex, 自研引擎

React Native、Weex和自研引擎是当前主流的动态化方案，它们通过不同的技术路径实现了“一次编写，多端运行”的目标。本文将围绕这三种方案，从性能、生态支持、开发体验、社区活跃度和定制化能力五个方面展开对比，帮助开发者选择最适合的技术栈。React Native基于JavaScriptCore引擎，通过桥接机制与原生组件通信，性能接近原生但存在一定损耗。总结来看，React Native适

开源鸿蒙跨平台开发者社区

所有评论(0)

查看更多评论

woaizhuliya

@woaizhuliya

已为社区贡献3条内容

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

woaizhuliya

OpenHarmony 5.1 HAP 安装权限与签名 Profile 配置教程

1. 问题现象

2. 错误原因总结

2.1 9568289

2.2 9568344

3. 三个权限分别是什么

3.1 ohos.permission.INSTALL_BUNDLE

3.2 ohos.permission.START_ABILITIES_FROM_BACKGROUND

3.3 ohos.permission.START_INVISIBLE_ABILITY

4. module.json5 中声明权限

5. 获取当前 HAP 证书指纹

5.1 从 distribution-certificate 提取证书

5.2 用 keytool 计算指纹

6. 修改 SDK Profile 模板

7. 关键坑：工程里可能固定使用旧 .p7b

8. 反查最终 HAP 中的 Profile

9. 处理固定旧 .p7b 的方法

方案 A：重新生成 .p7b

方案 B：重新生成 DevEco 签名材料

10. 配置板端 install_list_capability.json

11. 清理构建缓存并重新安装

12. 最终验证

13. 本次排查的核心结论

14. 常用排查命令汇总

查 SDK 模板

查工程固定签名配置

反查最终 HAP

查证书指纹

查板端应用

15. 注意事项

所有评论(0)

温馨提示：您尚未绑定手机号

woaizhuliya

2.1 `9568289`

2.2 `9568344`

3.1 `ohos.permission.INSTALL_BUNDLE`

3.2 `ohos.permission.START_ABILITIES_FROM_BACKGROUND`

3.3 `ohos.permission.START_INVISIBLE_ABILITY`

4. `module.json5` 中声明权限

5.1 从 `distribution-certificate` 提取证书

5.2 用 `keytool` 计算指纹

7. 关键坑：工程里可能固定使用旧 `.p7b`

9. 处理固定旧 `.p7b` 的方法

方案 A：重新生成 `.p7b`

10. 配置板端 `install_list_capability.json`