OpenHarmony北向系统开发之手动推送系统SA服务文件详解

OpenHarmony 手动增加系统 SA 服务详解

概述

本文档详细介绍如何在 OpenHarmony 系统上手动增加系统能力 (System Ability, SA) 服务。通过添加必要的库文件、配置文件和服务定义，可以为 OpenHarmony 系统扩展新的系统服务功能。

SA 服务基本概念

什么是 SA 服务

SA (System Ability) 是 OpenHarmony 系统中的系统能力服务，是系统提供的基础服务组件。每个 SA 服务都有唯一的 ID，通过 SAMgr (System Ability Manager) 进行统一管理。

SA 服务特点

• 系统级服务：运行在系统进程中，提供核心系统功能
• 标准化管理：通过统一的注册、发现和调用机制
• 权限控制：受系统权限管理，普通应用无法直接调用
• 生命周期管理：由系统自动管理服务的启动、停止和重启

项目结构说明

目录结构

001replace/ ├── doc/ │ └── OpenHarmony手动增加系统SA服务详解.md # 本文档 ├── etc/ │ └── init/ │ ├── dhardwarecommon_service.cfg # 分布式硬件公共服务配置 │ └── kh_dinput.cfg # 开鸿输入服务配置 ├── lib64/ │ ├── libdistributed_mminput_source_sdk.z.so # 分布式多媒体输入源SDK库 │ ├── libdistributed_mminput_source.z.so # 分布式多媒体输入源库 │ ├── libdistributed_mminput_utils.z.so # 分布式多媒体输入工具库 │ ├── libdistributed_mminput_handler.z.so # 分布式多媒体输入处理器库 │ ├── libdistributed_mminput_sink.z.so # 分布式多媒体输入接收器库 │ ├── libdistributed_mminput_sourcetrans.z.so # 分布式多媒体输入源传输库 │ ├── libdistributed_mminput_sinktrans.z.so # 分布式多媒体输入接收器传输库 │ ├── libdistributed_mminput_sink_sdk.z.so # 分布式多媒体输入接收器SDK库 │ ├── libdhardwarecommonservice.z.so # 分布式硬件公共服务库 │ ├── libdhardware_utils.z.so # 分布式硬件工具库 │ ├── libdhardwarecommonclient.z.so # 分布式硬件公共客户端库 │ └── module/ │ └── distributedhardware/ │ ├── libkhdistributedscreen.z.so # 开鸿分布式屏幕napi库 │ └── libkhdistributedscreeninput.z.so # 开鸿分布式屏幕输入napi库 ├── system/ │ ├── etc/ │ │ └── init/ │ │ ├── dhardwarecommon_service.cfg # 系统级分布式硬件公共服务配置 │ │ └── kh_dinput.cfg # 系统级开鸿输入服务配置 │ └── profile/ │ ├── kh_dinput.json # 开鸿输入服务能力定义 │ └── kh_dscreen.json # 开鸿屏幕服务能力定义 └── replacelib64.bat # 自动推送脚本

资源下载

文件类型说明

1. 库文件 (lib64/)

• 主服务库：xxx_service.z.so- 实现 SA 服务核心逻辑
• 客户端库：xxx_client.z.so- 提供给应用使用的接口
• 工具库：xxx_utils.z.so- 通用工具函数
• 模块库：module/distributedhardware/- 特定模块的实现

2. 配置文件 (etc/init/)

• 服务配置：xxx_service.cfg- 定义服务启动参数、依赖关系等
• 系统配置：system/etc/init/xxx_service.cfg- 系统级服务配置

3. 能力定义文件 (system/profile/)

• 服务能力：xxx_service.json- 定义服务提供的系统能力

4. 推送脚本 (replacelib64.bat)

• 自动化脚本：自动检测设备并推送所有文件到对应目录

详细配置步骤

步骤 1: 准备 SA 服务文件

1.1 编译 SA 服务库

# 编译 SA 服务主库hb build -f --product-name<product>--device-type<device>--build-type release# 编译结果通常位于：# out/<product>/<device>/release/libs/

1.2 创建服务配置文件

创建etc/init/xxx_service.cfg：

# SA 服务配置文件示例 { "service": { "name": "xxx_service", # 服务名称 "path": "/system/lib64/xxx_service.z.so", # 服务库路径 "uid": 1000, # 用户ID "gid": 1000, # 用户组ID "secon": "u:r:system_app:s0", # SELinux 安全上下文 "permission": [], # 所需权限列表 "capability": [], # 所需能力列表 "start-mode": "delayed", # 启动模式 "start-timeout": 30 # 启动超时时间(秒) }, "dependencies": [ # 依赖的服务列表 "samgr", # 系统能力管理器 "system_parameter" # 系统参数服务 ] }

1.3 创建系统能力定义

创建system/profile/xxx_service.json：

{"name":"xxx_service",# 服务名称"description":"XXX System Ability",# 服务描述"version":"1.0.0",# 版本号"vendor":"OpenHarmony",# 厂商"systemAbility":{"name":"xxx_service",#SA名称"id":1234,#SAID(唯一标识)"run-on-create":false,# 是否在创建时运行"distributed":false# 是否支持分布式},"permissions":[# 权限定义{"name":"ohos.permission.XXX","grantMode":"system_grant","availableScope":["system"]}],"abilities":[# 能力定义{"name":"XXXAbility","type":"service","visible":true,"permissions":["ohos.permission.XXX"]}]}

步骤 2: 推送文件到设备

方法一：使用自动化脚本 (推荐)

# 直接运行批处理脚本replacelib64.bat

方法二：手动推送文件

# 1. 连接设备hdc tconn<device_id># 2. 推送库文件到 /lib64/hdcfilesend lib64/xxx_service.z.so /lib64/ hdcfilesend lib64/xxx_client.z.so /lib64/# 3. 推送配置文件到 /etc/init/hdcfilesend etc/init/xxx_service.cfg /etc/init/# 4. 推送系统配置文件hdcfilesend system/etc/init/xxx_service.cfg /system/etc/init/ hdcfilesend system/profile/xxx_service.json /system/profile/

步骤 3: 重启设备验证

3.1 重启设备

# 重启设备使配置生效hdc shellreboot

3.2 验证服务状态

# 检查服务是否注册成功hdc shell sa list|grepxxx_service# 查看服务进程hdc shellps|grepxxx_service# 检查服务日志hdc shell hilog -t xxx_service

3.3 测试服务功能

# 根据具体服务功能进行测试# 例如：检查 SA ID 是否可用hdc shell sa check1234

自动化脚本详解

replacelib64.bat 脚本分析

@echo off chcp 65001 >nul # 设置UTF-8编码 echo 开始部署文件到设备... # 自动检测所有连接的设备 for /f %%i in ('hdc list targets') do ( echo 连接到设备: %%i # 设置设备权限模式 hdc -t %%i shell power-shell setmode 602 # 挂载系统分区为读写模式 hdc -t %%i shell mount -o remount -o rw / hdc -t %%i shell mount -o remount -o rw /vendor hdc -t %%i shell mount -o remount -o rw /chip_prod # 推送 lib64 目录文件 dir .\lib64\ /b > lib64_list.txt for /f %%j in (lib64_list.txt) do ( if not "%%j"=="module" ( echo 发送 %%j 到 /lib64/ hdc -t %%i file send .\lib64\%%j /lib64/ ) ) # 推送模块文件 dir .\lib64\module\distributedhardware\ /b > module_list.txt for /f %%j in (module_list.txt) do ( echo 发送 %%j 到 /lib64/module/distributedhardware/ hdc -t %%i file send .\lib64\module\distributedhardware\%%j /lib64/module/distributedhardware/ ) # 推送配置文件 dir .\etc\init\ /b > etc_init_list.txt for /f %%j in (etc_init_list.txt) do ( echo 发送 %%j 到 /etc/init/ hdc -t %%i file send .\etc\init\%%j /etc/init/ ) # 推送系统级配置文件 dir .\system\etc\init\ /b > system_etc_init_list.txt for /f %%j in (system_etc_init_list.txt) do ( echo 发送 %%j 到 /system/etc/init/ hdc -t %%i file send .\system\etc\init\%%j /system/etc/init/ ) # 推送能力定义文件 dir .\system\profile\ /b > system_profile_list.txt for /f %%j in (system_profile_list.txt) do ( echo 发送 %%j 到 /system/profile/ hdc -t %%i file send .\system\profile\%%j /system/profile/ ) ) # 清理临时文件 del lib64_list.txt module_list.txt etc_init_list.txt system_etc_init_list.txt system_profile_list.txt echo 部署完成！ pause >nul

脚本执行流程

1. 设备检测：自动发现所有连接的 OpenHarmony 设备
2. 权限设置：设置设备为开发者模式
3. 分区挂载：将系统分区挂载为读写模式
4. 文件推送：按目录分类推送所有文件
5. 清理工作：删除临时文件

故障排除

常见问题

1. 推送失败

现象：文件推送过程中出现权限错误
解决：

# 检查设备连接状态hdc list targets# 重新设置开发者模式hdc shell power-shell setmode602# 检查分区挂载状态hdc shellmount|grep-E"(system|vendor)"

2. 服务启动失败

现象：服务无法正常启动
解决：

# 检查配置文件语法hdc shellcat/etc/init/xxx_service.cfg# 查看系统日志hdc shell hilog -t init# 检查依赖服务状态hdc shell sa list|grepsamgr

3. 权限问题

现象：应用无法调用 SA 服务
解决：

# 检查权限配置hdc shellcat/system/profile/xxx_service.json# 验证权限定义hdc shell perm list|grepxxx

4. 库文件冲突

现象：系统原有库文件被覆盖
解决：

# 备份原有文件hdcfilerecv /lib64/xxx_service.z.so ./backup/xxx_service.z.so# 恢复备份hdcfilesend ./backup/xxx_service.z.so /lib64/

最佳实践

1. 版本管理

• 为每个 SA 服务维护独立的版本号
• 记录每次更新的变更内容
• 保留历史版本的备份

2. 测试验证

• 在测试设备上先验证功能
• 检查服务启动日志
• 验证与其他服务的兼容性

3. 文档维护

• 详细记录 SA ID 和服务名称
• 维护服务依赖关系图
• 更新接口文档

4. 安全考虑

• 正确配置 SELinux 安全上下文
• 合理设置服务权限
• 避免过度授权

参考资料

官方文档

• OpenHarmony SA 开发指南
• 系统能力管理

相关工具

• hdc：OpenHarmony 设备连接工具
• hb：OpenHarmony 构建工具
• hilog：系统日志查看工具

更新日志

• v1.0：初始版本，包含完整的 SA 服务添加流程