startup_appspawn/docs/architecture.md

appspawn 系统架构文档

1. 系统概述

appspawn 是 OpenHarmony 操作系统的应用进程孵化器（Application Process Spawner），负责接收应用框架（如 Ability Manager Service）的命令，孵化（fork）出应用进程，并为其配置安全沙箱、权限、UID/GID 等运行时环境。appspawn 在系统启动时由 init 进程拉起，通过本地 socket 监听来自客户端的孵化请求。

appspawn 支持多种孵化模式，包括标准应用孵化（appspawn）、NWeb 渲染进程孵化（nwebspawn）、原生进程孵化（nativespawn）、混合孵化（hybridspawn）以及 CJ 应用孵化（cjappspawn）。此外还支持冷启动模式（cold run），即在已 fork 的子进程中直接执行应用，跳过 fork 步骤以加速启动。

系统采用模块化 Hook 架构：核心服务通过 Hook 机制（appspawn_hook.h 中定义的 AppSpawnHookStage）将各个功能模块（沙箱、权限、SPM、ACE 适配等）以插件形式挂载到孵化流程的不同阶段。模块通过 MODULE_CONSTRUCTOR 宏在加载时自动注册 Hook，实现了核心逻辑与扩展功能的解耦。

---

2. 架构图

2.1 系统组件架构

graph TD
    subgraph 客户端
        AMS[Ability Manager Service]
        CLIENT[appspawn_client<br/>客户端 SDK]
    end

    subgraph appspawn服务端
        MAIN[appspawn_main<br/>主入口]
        SERVICE[appspawn_service<br/>核心服务]
        MSGMGR[appspawn_msgmgr<br/>消息管理]
        APPMGR[appspawn_appmgr<br/>应用管理]
        FDMGR[appspawn_fd_manager<br/>FD管理]
        SERVER[appspawn_server<br/>通用服务层]
    end

    subgraph Hook模块系统
        MODULEMGR[modulemgr<br/>模块管理器]
        HOOKENGINE[module_engine<br/>Hook引擎]
        SANDBOX[sandbox<br/>沙箱模块]
        SPM[spm<br/>权限管理模块]
        COMMON[common<br/>通用模块]
        ACEADAPTER[ace_adapter<br/>ACE适配器]
        NATIVEADAPTER[native_adapter<br/>原生适配器]
        NWEBADAPTER[nweb_adapter<br/>NWeb适配器]
        SYSEVENT[sysevent<br/>系统事件]
        ASAN[asan<br/>ASAN检测器]
    end

    subgraph 客户端接口
        API[appspawn.h<br/>公共API]
        MSG[msg.h<br/>消息定义]
    end

    subgraph 工具层
        UTIL[util<br/>工具类]
    end

    AMS -->|Socket IPC| CLIENT
    CLIENT -->|Socket| MSGMGR
    MSGMGR --> SERVICE
    MAIN --> SERVICE
    SERVICE --> SERVER
    SERVICE --> APPMGR
    SERVICE --> FDMGR
    SERVICE --> MODULEMGR
    MODULEMGR --> HOOKENGINE
    HOOKENGINE --> SANDBOX
    HOOKENGINE --> SPM
    HOOKENGINE --> COMMON
    HOOKENGINE --> ACEADAPTER
    HOOKENGINE --> NATIVEADAPTER
    HOOKENGINE --> NWEBADAPTER
    HOOKENGINE --> SYSEVENT
    HOOKENGINE --> ASAN
    SERVICE --> UTIL
    SANDBOX --> UTIL
    SPM --> UTIL

2.2 进程孵化数据流

flowchart TD
    A[客户端构建请求<br/>AppSpawnReqMsg] -->|Socket发送| B[appspawn_msgmgr<br/>接收消息]
    B --> C{消息类型判断}
    C -->|SPAWN| D[创建AppSpawningCtx]
    C -->|TERMINATE| E[查找进程并终止]
    D --> F[Pre-Fork Hooks<br/>STAGE_PARENT_PRE_FORK]
    F --> G[fork子进程]
    G -->|父进程| H[Post-Fork Hooks<br/>STAGE_PARENT_POST_FORK]
    G -->|子进程| I[Child Execute Hooks<br/>STAGE_CHILD_EXECUTE]
    I --> J[设置沙箱/权限/UID/GID]
    J --> K[exec应用入口]
    H --> L[等待子进程响应]
    L --> M[返回结果给客户端]

2.3 Hook 阶段流程

sequenceDiagram
    participant Client as 客户端
    participant MsgMgr as 消息管理器
    participant Service as 核心服务
    participant HookMgr as Hook引擎
    participant Child as 子进程

    Client->>MsgMgr: Socket发送TLV消息
    MsgMgr->>Service: ProcessRecvMsg
    Service->>HookMgr: STAGE_PARENT_PRE_FORK
    HookMgr->>HookMgr: 执行沙箱预配置/权限准备
    Service->>Child: fork()
    Child->>HookMgr: STAGE_CHILD_EXECUTE
    HookMgr->>HookMgr: 沙箱挂载/UID/GID设置/DEC策略
    Child->>Service: 通过pipe返回结果
    Service->>HookMgr: STAGE_PARENT_POST_FORK
    Service->>Client: 返回AppSpawnResult

---

3. 模块清单

Module: standard（标准系统核心）

• 位置: standard/
• 职责: appspawn 标准系统核心实现，包含主入口、核心服务、消息管理器、应用管理器、FD 管理器、看门狗等
• 关键文件:
  • standard/appspawn_main.c - 主入口，解析参数并启动服务
  • standard/appspawn_service.c - 核心服务实现（fork、消息处理、子进程管理）
  • standard/appspawn_msgmgr.c - 消息接收与分发
  • standard/appspawn_appmgr.c - 已孵化应用进程的管理
  • standard/appspawn_fd_manager.c - 文件描述符管理
  • standard/appspawn_manager.h - 核心数据结构定义（AppSpawnMgr、AppSpawningCtx 等）
• 依赖: common, modules/module_engine, modules/modulemgr, util
• 被依赖: 无（顶层模块）

Module: common（通用服务层）

• 位置: common/
• 职责: 提供 appspawn 服务注册和 trace 追踪等通用功能
• 关键文件:
  • common/appspawn_server.c - 服务创建与 socket 监听
  • common/appspawn_server.h - AppSpawnContent 结构体和运行模式定义
  • common/appspawn_trace.cpp - 性能追踪（HiTrace）
• 依赖: util, interfaces/innerkits
• 被依赖: standard, lite

Module: sandbox（沙箱模块）

• 位置: modules/sandbox/
• 职责: 应用沙箱的创建、挂载管理、DEC 策略、权限控制
• 关键文件:
  • modules/sandbox/normal/sandbox_core.cpp - 沙箱核心逻辑
  • modules/sandbox/normal/sandbox_common.cpp - 沙箱通用工具
  • modules/sandbox/normal/sandbox_shared_mount.cpp - 共享挂载管理
  • modules/sandbox/normal/sandbox_unlock_mount.cpp - 解锁挂载
  • modules/sandbox/appspawn_permission.c - 沙箱权限
  • modules/sandbox/sandbox_dec.c - DEC（分布式加密）策略
• 依赖: modules/module_engine, util, common
• 被依赖: 通过 Hook 被 standard 调用

Module: spm（安全进程管理器）

• 位置: modules/spm/
• 职责: SPM（Security Process Manager）内核安全进程管理，包括 tokenid/uid 引用计数管理、权限位图重建
• 关键文件:
  • modules/spm/spm.c - SPM 核心逻辑
  • modules/spm/spm_permission.c - 权限操作
  • modules/spm/tlv_builder.c - TLV 消息构建
• 依赖: modules/module_engine, interfaces/innerkits/permission
• 被依赖: 通过 Hook 被 standard 调用

Module: modulemgr（模块管理器）

• 位置: modules/modulemgr/
• 职责: 管理动态模块的加载/卸载，Hook 注册与执行
• 关键文件:
  • modules/modulemgr/appspawn_modulemgr.c - 模块管理实现
  • modules/modulemgr/appspawn_modulemgr.h - 模块类型定义和接口
• 依赖: modules/module_engine
• 被依赖: standard

Module: module_engine（Hook 引擎）

• 位置: modules/module_engine/
• 职责: 定义 Hook 阶段、Hook 优先级、扩展数据结构等基础设施
• 关键文件:
  • modules/module_engine/include/appspawn_hook.h - Hook 阶段和接口定义
  • modules/module_engine/include/appspawn_msg.h - TLV 消息类型定义
• 依赖: interfaces/innerkits/include
• 被依赖: 几乎所有其他模块

Module: common_modules（通用功能模块）

• 位置: modules/common/
• 职责: 提供 namespace 管理、cgroup 配置、ASAN 检测、DFX 转储、进程隔离等通用 Hook 模块
• 关键文件:
  • modules/common/appspawn_adapter.cpp - 适配层
  • modules/common/appspawn_cgroup.c - Cgroup 配置
  • modules/common/appspawn_namespace.c - 命名空间管理
  • modules/common/appspawn_isolate.c - 进程隔离
  • modules/common/appspawn_custom_config.cpp - 自定义配置
  • modules/common/appspawn_encaps.c - 封装工具
  • modules/common/appspawn_silk.c - SILK 引擎集成
• 依赖: modules/module_engine
• 被依赖: 通过 Hook 被 standard 调用

Module: ace_adapter（ACE 适配器）

• 位置: modules/ace_adapter/
• 职责: ACE（ArkUI Cross-platform Engine）适配，包括 checkpoint 管理、命令解析、预加载
• 关键文件:
  • modules/ace_adapter/ace_adapter.cpp - ACE 适配主文件
  • modules/ace_adapter/appspawn_checkpoint.c - Checkpoint 管理
  • modules/ace_adapter/command_lexer.cpp - 命令解析器
  • modules/ace_adapter/dfx_preload.cpp - DFX 预加载
• 依赖: modules/module_engine
• 被依赖: 通过 Hook 被 standard 调用

Module: client（客户端 SDK）

• 位置: interfaces/innerkits/client/
• 职责: 提供 appspawn 客户端 API，供 AMS 等外部服务调用
• 关键文件:
  • interfaces/innerkits/client/appspawn_client.c - 客户端实现
  • interfaces/innerkits/client/appspawn_msg.c - 请求消息构造
  • interfaces/innerkits/client/appspawn_client.h - 客户端数据结构
  • interfaces/innerkits/include/appspawn.h - 公共 API 头文件
• 依赖: 无（独立客户端库）
• 被依赖: AMS, 外部服务

Module: util（工具类）

• 位置: util/
• 职责: 通用工具函数，包括错误码定义、JSON 工具、parcel 序列化、DFX 工具
• 关键文件:
  • util/include/appspawn_utils.h - 通用工具宏和函数
  • util/include/appspawn_error.h - 错误码定义
  • util/src/appspawn_utils.c - 工具函数实现
  • util/src/appspawndf_utils.cpp - DFX 工具实现
• 依赖: 无
• 被依赖: 几乎所有模块

Module: lite（小型系统）

• 位置: lite/
• 职责: 小型系统（轻量级设备）的 appspawn 实现
• 关键文件:
  • lite/main.c - 主入口
  • lite/appspawn_service.c - 服务实现
  • lite/appspawn_message.c - 消息处理
  • lite/appspawn_process.c - 进程孵化
• 依赖: interfaces/innerkits
• 被依赖: 无（独立于标准系统）

Module: hnp（原生包管理服务）

• 位置: service/hnp/
• 职责: HNP（Harmony Native Package）原生包安装和管理服务
• 关键文件:
  • service/hnp/hnp_main.c - HNP 服务主入口
  • service/hnp/installer/src/hnp_installer.c - 安装器
  • service/hnp/pack/src/hnp_pack.c - 打包器
  • service/hnp/base/hnp_file.c - 文件操作
  • service/hnp/base/hnp_json.c - JSON 处理
• 依赖: interfaces/innerkits/hnp
• 被依赖: 无（独立服务）

Module: devicedebug（设备调试服务）

• 位置: service/devicedebug/
• 职责: 设备调试功能，包括进程 kill 操作
• 关键文件:
  • service/devicedebug/devicedebug_main.c - 主入口
  • service/devicedebug/kill/src/devicedebug_kill.c - Kill 操作
• 依赖: 无
• 被依赖: 无（独立服务）

---

4. 数据流

4.1 应用孵化请求流程

1. 客户端构建请求: AMS 调用 AppSpawnReqMsgCreate() 构建请求消息句柄，通过 AppSpawnClientAddBundleInfo() 等 API 填充 TLV 字段（bundle name, DAC info, permission 等），定义在 interfaces/innerkits/include/appspawn.h:39-45

2. Socket 发送: 客户端通过 AppSpawnClientSendMsg() 将消息通过本地 socket 发送给 appspawn 服务端，实现在 interfaces/innerkits/client/appspawn_client.c

3. 消息接收与解析: appspawn_msgmgr 在 socket 上收到数据后，通过 GetAppSpawnMsgFromBuffer() 解析 TLV 格式消息，验证 magic（APPSPAWN_MSG_MAGIC 0xEF201234），定义在 modules/module_engine/include/appspawn_msg.h:45

4. Hook 执行与 fork: 核心服务在 appspawn_service.c 中按顺序执行 Hook：

   • STAGE_PARENT_PRE_FORK: fork 前准备（沙箱路径计算、权限准备）
   • fork(): 创建子进程
   • STAGE_CHILD_EXECUTE（子进程中）: 沙箱挂载、UID/GID 设置、DEC 策略
   • STAGE_PARENT_POST_FORK（父进程中）: 结果收集

5. 结果返回: 子进程通过 pipe 向父进程返回 AppSpawnResult（包含 pid 和 result），父进程通过 socket 返回给客户端

4.2 消息格式

消息采用 TLV（Type-Length-Value）格式，定义在 modules/module_engine/include/appspawn_msg.h:54-66:

TLV 类型	说明
TLV_BUNDLE_INFO	应用包信息（bundle name, index）
TLV_MSG_FLAGS	消息标志位
TLV_DAC_INFO	DAC 信息（UID, GID, GID 表）
TLV_DOMAIN_INFO	域信息（APL 等级）
TLV_OWNER_INFO	所有者信息
TLV_ACCESS_TOKEN_INFO	AccessToken
TLV_PERMISSION	权限位图
TLV_INTERNET_INFO	网络权限
TLV_RENDER_TERMINATION_INFO	渲染终止信息
TLV_CHECK_POINT_INFO	Checkpoint 信息

---

5. 关键接口

接口	提供方	使用方	机制
AppSpawnClientInit/SendMsg	client SDK	AMS 等外部服务	Socket IPC
AppSpawnReqMsgCreate	client SDK	AMS 等外部服务	函数调用
StartSpawnService	standard/service	main 入口	函数调用
AddAppSpawnHook	各功能模块	module_engine	Hook 注册
AppSpawnHookExecute	modulemgr	standard/service	Hook 执行
SetAppSandboxProperty	sandbox	通过 CHILD_EXECUTE Hook	Hook 调用
OnMessageRebuildFromSPM	spm	通过 PARENT_MSG_DECODE Hook	Hook 调用
AppSpawnCreateContent	common/server	standard/service	函数调用

---

6. 外部依赖

依赖	用途	来源
init_socket	Socket 创建与连接	OpenHarmony init
loop_event	事件循环（IO 多路复用）	OpenHarmony
hookmgr	Hook 管理器框架	OpenHarmony
modulemgr	动态模块加载框架	OpenHarmony
cJSON	JSON 解析	第三方
parameter	系统参数读取	OpenHarmony
securec	安全 C 函数库	OpenHarmony
hisysevent	系统事件上报	OpenHarmony
access_token	访问令牌	OpenHarmony
selinux	SELinux 安全上下文	系统
seccomp	系统调用过滤	系统

---

7. 跨模块关系 (Cross-Module Relationships)

7.1 跨模块数据流

sequenceDiagram
    participant Client as 客户端(client_api)
    participant Standard as 核心(standard)
    participant Engine as Hook引擎(modulemgr_engine)
    participant Sandbox as 沙箱(sandbox)
    participant SPM as 权限(spm)
    participant Child as 子进程

    Client->>Standard: TLV消息(Socket)
    Standard->>Engine: STAGE_PARENT_MSG_DECODE
    Engine->>SPM: OnMessageRebuildFromSPM
    SPM-->>Standard: 重建后的权限消息
    Standard->>Engine: STAGE_PARENT_PRE_FORK
    Standard->>Child: fork()
    Child->>Engine: STAGE_CHILD_EXECUTE
    Engine->>Sandbox: SetAppSandboxProperty
    Sandbox-->>Child: 沙箱挂载完成
    Child->>Standard: pipe返回结果
    Standard->>Engine: STAGE_PARENT_POST_FORK
    Standard->>Client: AppSpawnResult

7.2 共享数据结构

Structure	Used By	Purpose
AppSpawnMgr	standard, sandbox, spm, common_modules	全局管理器（孵化队列、服务状态）
AppSpawningCtx	standard, sandbox, spm, ace_adapter	孵化请求上下文（消息、fork pipe、SPM 引用计数）
AppSpawnMsg	client_api, standard, modulemgr_engine	TLV 消息头（magic、msgType、processName）
AppSpawnContent	standard, server_common, sandbox	服务内容（模式、函数指针表）
AppSpawnHookStage	modulemgr_engine, sandbox, spm, common_modules	Hook 阶段枚举

7.3 接口契约

Contract	Provider	Consumer	Description
TLV 消息格式	client_api	standard	客户端构造 TLV，服务端解析 TLV
Hook 注册	modulemgr_engine	所有功能模块	通过 MODULE_CONSTRUCTOR + AddAppSpawnHook
AppSpawningCtx 生命周期	standard	sandbox, spm	standard 创建/销毁，其他模块读取
沙箱配置 JSON	sandbox（读取）	根目录（定义）	appdata-sandbox-*.json 配置文件

---

8. 系统级模式 (System-Level Patterns)

8.1 Hook 驱动模式

所有功能扩展通过 Hook 实现。模块使用 MODULE_CONSTRUCTOR 在 .so 加载时注册 Hook，核心服务通过 AppSpawnHookExecute 按优先级执行。

8.2 函数指针表多态

AppSpawnContent 使用函数指针（runAppSpawn、runChildProcessor、coldStartApp）实现不同孵化模式的多态分发。

8.3 UID 白名单安全

仅允许特定 UID（root / foundation / app_fwk_update / storage_manager）的客户端连接，开发者模式下允许 shell。

8.4 引用计数资源管理

SPM 模块使用位图（spmRefAdded）跟踪 tokenid/uid 引用计数，确保 spawn abort 和进程退出时正确回收。