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,                      # SA ID (唯一标识)
        "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/
hdc file send lib64/xxx_service.z.so /lib64/
hdc file send lib64/xxx_client.z.so /lib64/

# 3. 推送配置文件到 /etc/init/
hdc file send etc/init/xxx_service.cfg /etc/init/

# 4. 推送系统配置文件
hdc file send system/etc/init/xxx_service.cfg /system/etc/init/
hdc file send system/profile/xxx_service.json /system/profile/

步骤 3: 重启设备验证

3.1 重启设备

# 重启设备使配置生效
hdc shell reboot

3.2 验证服务状态

# 检查服务是否注册成功
hdc shell sa list | grep xxx_service

# 查看服务进程
hdc shell ps | grep xxx_service

# 检查服务日志
hdc shell hilog -t xxx_service

3.3 测试服务功能

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

自动化脚本详解

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 setmode 602

# 检查分区挂载状态
hdc shell mount | grep -E "(system|vendor)"

2. 服务启动失败

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

# 检查配置文件语法
hdc shell cat /etc/init/xxx_service.cfg

# 查看系统日志
hdc shell hilog -t init

# 检查依赖服务状态
hdc shell sa list | grep samgr

3. 权限问题

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

# 检查权限配置
hdc shell cat /system/profile/xxx_service.json

# 验证权限定义
hdc shell perm list | grep xxx

4. 库文件冲突

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

# 备份原有文件
hdc file recv /lib64/xxx_service.z.so ./backup/xxx_service.z.so

# 恢复备份
hdc file send ./backup/xxx_service.z.so /lib64/

最佳实践

1. 版本管理

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

2. 测试验证

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

3. 文档维护

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

4. 安全考虑

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

参考资料

官方文档

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

相关工具

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

更新日志

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