HarmonyOS 局域网测试包自动构建与链接安装方案

脱敏说明：本文中的项目名、包名、模块名、域名、IP、版本号和文件名均为示例占位符，例如 your-harmony-project、com.example.demo、app-entry-signed.hap 和 harmony-test.corp.example.com，不对应任何真实项目或生产环境。

1. 目标

本方案用于实现以下流程：

代码提交或合并到指定 GitLab 分支
        ↓
GitLab CI 自动创建流水线
        ↓
macOS GitLab Runner 构建测试 HAP/HSP
        ↓
生成并签名 manifest.json5
        ↓
上传至局域网 HTTPS 文件服务器
        ↓
测试人员点击固定链接安装

1.1 这是局域网方案，不是公网发布方案

本方案中的文件服务器部署在公司局域网，HAP、HSP、图标和 manifest 不需要上传到公网，也不需要申请公网 IP。

需要特别区分：

局域网/公网：决定服务器能被哪些网络访问
HTTP/HTTPS：决定客户端与服务器之间使用哪种传输协议

因此，“局域网服务器使用 HTTPS”完全成立。服务器可以只有 192.168.x.x 或 10.x.x.x 的内网 IP，但测试手机访问时需要使用一个能够在内网解析的域名。

本方案的网络要求如下：

项目 是否需要 说明
公网服务器 否 Ubuntu/Nginx 可以只部署在公司局域网
公网 IP 否 服务器可以只有固定的局域网 IP
允许互联网访问服务器 否 防火墙可以只允许公司 Wi-Fi 或 VPN 网段访问
局域网域名 是 手机安装链接不能直接使用 IP，需要通过域名访问
内部 DNS 是 将局域网域名解析到服务器的私网 IP
HTTPS 是 华为指定设备发布的下载地址要求使用 HTTPS
手机信任 HTTPS 证书 是 使用公共可信证书，或在手机安装公司内部 CA
测试手机连接公司网络 是 手机需要连接公司 Wi-Fi 或 VPN 才能下载资源

最小可用示例：

Ubuntu/Nginx 服务器：192.168.10.20
局域网域名：harmony-test.corp.example.com
内部 DNS：harmony-test.corp.example.com → 192.168.10.20
开放范围：仅公司 Wi-Fi 和 VPN 网段
服务端口：443

测试手机实际访问的是：

https://harmony-test.corp.example.com/harmony/latest/manifest.json5

虽然 URL 使用 HTTPS，但请求只在公司局域网或 VPN 中传输，文件不会因此被发布到公网。

本方案对应华为官方能力：指定设备发布（原内部测试），不使用 AppGallery 邀请测试或公开测试。

官方文档：

2. 核心结论

2.1 测试代码与签名类型是两件事

代码可以继续使用测试环境配置和 Debug 构建能力，但用于链接安装时，不能继续使用普通调试 Profile 签名。

指定设备发布需要：

  • 发布证书及对应的 .p12 密钥库。
  • 指定设备发布类型的 .p7b Profile。
  • .p7b 中包含所有测试设备的 UDID。
  • 使用上述证书和 Profile 生成已签名的 HAP/HSP。

建议在 build-profile.json5 中单独增加：

signingConfig: internalTest
product: internalTest

不要直接把普通 Debug Profile 用于最终的链接安装。

2.2 HAR、HSP、HAP 是否需要上传

产物 是否上传 说明
HAR 否 编译期静态库，已经合并进最终 HAP/HSP
HAP 是 实际安装模块，包括 entry、feature
HSP 视项目而定 存在应用内 HSP 时需要单独上传
manifest.json5 是 描述应用、模块下载地址和 Hash
应用图标 是 系统安装界面展示使用

一个包含 entry HAP 和应用内 HSP 的工程，构建后可能产生类似以下文件：

app-entry-signed.hap
feature-example-signed.hap
shared-module-a-signed.hsp
shared-module-b-signed.hsp

3. 安装链接的工作原理

安装 Deeplink 格式：

store://enterprise/manifest?url=https://harmony-test.corp.example.com/harmony/latest/manifest.json5

store:// 不是普通网络协议，而是由 HarmonyOS 系统安装组件处理的自定义协议。

测试人员点击 store:// 链接
        ↓
HarmonyOS 安装组件读取 url 参数
        ↓
通过 HTTPS 下载 manifest.json5
        ↓
从 manifest 中读取 HAP/HSP 和图标地址
        ↓
校验 manifest 签名、包签名和 SHA256
        ↓
检查当前设备 UDID 是否包含在 Profile 中
        ↓
下载并安装应用

即使其他人员获得安装链接，只要其设备 UDID 不在 .p7b 中，安装也会失败。

4. manifest.json5 示例

以下仅展示结构，sign 必须按照华为文档使用对应证书生成，不能填写普通字符串。

{
  "app": {
    "bundleName": "com.example.demo",
    "bundleType": "app",
    "versionCode": 10203,
    "versionName": "1.2.3",
    "label": "测试应用",
    "deployDomain": "harmony-test.corp.example.com",
    "icons": {
      "normal": "https://harmony-test.corp.example.com/harmony/10203/icon.png",
      "large": "https://harmony-test.corp.example.com/harmony/10203/icon-large.png"
    },
    "minAPIVersion": "<项目实际最小 API 版本>",
    "targetAPIVersion": "<项目实际目标 API 版本>",
    "modules": [
      {
        "name": "entry",
        "type": "entry",
        "deviceTypes": ["phone", "tablet"],
        "packageUrl": "https://harmony-test.corp.example.com/harmony/10203/app-entry-signed.hap",
        "packageHash": "entry HAP 的 SHA256"
      },
      {
        "name": "shared_module_a",
        "type": "shared",
        "deviceTypes": ["phone", "tablet"],
        "packageUrl": "https://harmony-test.corp.example.com/harmony/10203/shared-module-a-signed.hsp",
        "packageHash": "shared_module_a HSP 的 SHA256"
      }
    ]
  },
  "sign": "manifest 描述文件签名"
}

manifest 中必须列出应用实际安装依赖的全部 HAP 和应用内 HSP。

5. 局域网部署架构

这里使用的是局域网 HTTPS 文件服务器：服务器不对互联网开放，只允许公司内网或 VPN 访问。HTTPS 仅用于满足 HarmonyOS 下载和安装过程的安全校验要求，并不改变服务器的局域网属性。

推荐正式架构：

macOS 构建机
├── DevEco Studio
├── HarmonyOS SDK
└── GitLab Runner

Ubuntu 文件服务器
├── Nginx
├── HTTPS 证书
└── HAP/HSP/manifest 静态文件

推荐的 Ubuntu 文件服务器配置：

系统：Ubuntu Server 22.04 或 24.04
CPU：2 核
内存：2 GB
磁盘：20 GB 以上
网络：固定局域网 IP
端口：443、22

完整的局域网访问关系：

测试手机
  └── 连接公司 Wi-Fi 或 VPN
        └── 查询公司内部 DNS
              └── harmony-test.corp.example.com → 192.168.10.20
                    └── 访问局域网 Nginx 的 443 端口

服务器无需配置公网 IP，也无需在公网 DNS 中将域名解析到这台服务器。测试手机只要连接公司 Wi-Fi 或 VPN，并能通过内部 DNS 解析和访问该域名即可。

5.1 HTTPS 证书选择

推荐使用公司真实子域名和公共可信证书：

harmony-test.corp.example.com

可以通过 DNS-01 申请证书，但只在公司内部 DNS 中将该域名解析到局域网 IP。这样服务器仍然只在内网访问，测试手机也不需要额外安装 CA。

也可以使用公司内部 CA 或自签证书，但需要在每台测试手机中安装并信任对应 CA 根证书。

5.2 文件服务器要求

  • 必须使用 HTTPS。
  • 服务器本身可以使用局域网 IP，但安装链接和资源 URL 不能直接写 IP 地址，必须写内部域名。
  • 建议使用标准 HTTPS 端口 443。
  • manifest、HAP、HSP、图标使用同一个域名。
  • 文件 URL 必须可以直接访问，不能依赖网页登录或 Cookie。
  • 服务器必须正确支持 GET 和 HEAD 请求。
  • HEAD 请求需要返回正确的文件大小。
  • 防火墙可以只允许公司 Wi-Fi、办公网段和 VPN 网段访问 443，不需要向互联网开放。

6. 服务器目录设计

建议每个版本使用独立目录：

/srv/harmony/
├── releases/
│   ├── 10201/
│   ├── 10202/
│   └── 10203/
└── latest/
    └── manifest.json5

单个版本目录示例：

/srv/harmony/releases/10203/
├── app-entry-signed.hap
├── feature-example-signed.hap
├── shared-module-a-signed.hsp
├── shared-module-b-signed.hsp
├── manifest.json5
├── icon.png
└── icon-large.png

上传新版本时，应先完整上传版本目录，全部成功后再更新 latest/manifest.json5，避免测试人员在上传过程中拿到不完整版本。

7. GitLab CI 配置位置

流水线配置文件放在仓库根目录：

your-harmony-project/
├── .gitlab-ci.yml
├── build-profile.json5
├── hvigorfile.ts
├── oh-package.json5
├── entry/
└── modules/

GitLab 页面中的 CI/CD → 管道 用于查看运行结果，不用于编写流水线。

其他配置位置：

设置 → CI/CD → Runner
设置 → CI/CD → 变量

8. GitLab Runner 要求

HarmonyOS 构建 Runner 推荐使用安装了 DevEco Studio 的 macOS 机器，Runner 使用 Shell executor，并配置标签：

harmony-macos

如果工程仓库没有内置 hvigorw，Runner 可以调用 DevEco Studio 安装目录中的命令：

/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw
/Applications/DevEco-Studio.app/Contents/tools/ohpm/bin/ohpm

9. 第一阶段 GitLab CI 示例

建议先完成“提交 main 后自动构建并保留产物”，验证 Runner 稳定后，再接入 manifest 和上传步骤。

workflow:
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
    - when: never

stages:
  - build

harmony_build:
  stage: build
  tags:
    - harmony-macos
  interruptible: true

  before_script:
    - export DEVECO_HOME="/Applications/DevEco-Studio.app/Contents"
    - export DEVECO_SDK_HOME="$DEVECO_HOME/sdk"
    - export JAVA_HOME="$DEVECO_HOME/jbr/Contents/Home"
    - export PATH="$DEVECO_HOME/tools/node/bin:$DEVECO_HOME/tools/ohpm/bin:$PATH"
    - test -x "$DEVECO_HOME/tools/hvigor/bin/hvigorw"
    - test -x "$DEVECO_HOME/tools/ohpm/bin/ohpm"
    - java -version
    - node --version
    - ohpm --version

  script:
    - ohpm install --all
    - >
      "$DEVECO_HOME/tools/hvigor/bin/hvigorw"
      clean assembleApp
      --mode project
      -p product=internalTest
      -p buildMode=debug
      --parallel
      --no-daemon
    - mkdir -p ci-dist
    - |
      find . -type f \
        -path "*/build/*/outputs/*" \
        \( -name "*-signed.hap" -o -name "*-signed.hsp" \) \
        -exec cp {} ci-dist/ \;
    - test -n "$(find ci-dist -type f | head -1)"
    - shasum -a 256 ci-dist/* > ci-dist/SHA256SUMS
    - ls -lh ci-dist
    - cat ci-dist/SHA256SUMS

  artifacts:
    name: "harmony-${CI_COMMIT_REF_SLUG}-${CI_PIPELINE_IID}"
    expire_in: 7 days
    paths:
      - ci-dist/

注意：使用该示例前，需要在工程的 build-profile.json5 中配置 internalTest product。未完成前，可以临时使用工程已有的 product 验证 Runner 是否能够构建，但普通 Debug Profile 产物不能用于最终的 store:// 安装链路。

10. 完整 CI 阶段

Runner 验证完成后，完整流水线建议拆分为：

stages:
  - build
  - package
  - deploy

各阶段职责：

build
├── 安装 OHPM 依赖
├── 设置或生成 versionCode
├── 调用 hvigorw 构建
└── 收集 signed.hap / signed.hsp

package
├── 计算每个文件的 SHA256
├── 生成 manifest.json5
├── 对 manifest.json5 进行签名
└── 校验 manifest 与构建产物是否一致

deploy
├── 上传到 releases/{versionCode}/
├── 检查所有 HTTPS 文件可以访问
├── 原子更新 latest/manifest.json5
└── 输出或通知固定安装链接

固定安装链接示例：

store://enterprise/manifest?url=https://harmony-test.corp.example.com/harmony/latest/manifest.json5

为了方便在微信、企业微信或浏览器中打开，也可以提供一个普通 HTTPS 安装页面，由页面按钮拉起上述 store:// Deeplink。

11. GitLab CI 变量

证书密码、SSH 私钥和服务器信息不能直接写入 .gitlab-ci.yml，应配置在：

GitLab 项目 → 设置 → CI/CD → 变量

建议变量：

DEPLOY_HOST
DEPLOY_USER
DEPLOY_PATH
SSH_PRIVATE_KEY
SSH_KNOWN_HOSTS
HARMONY_STORE_PASSWORD
HARMONY_KEY_PASSWORD
HARMONY_KEY_ALIAS

敏感变量应开启：

Masked
Protected

证书、Profile、密钥库和密码不应提交到普通代码仓库。若相关凭据曾进入仓库历史，应安排轮换并清理使用方式。

12. 新增测试设备时

增加新的测试人员设备需要：

  1. 获取测试设备 UDID。
  2. 在 AppGallery Connect 中将设备加入指定设备发布 Profile。
  3. 下载更新后的 .p7b。
  4. 更新 Runner 使用的 Profile。
  5. 重新签名并构建 HAP/HSP。
  6. 重新部署测试版本。

只修改远程 manifest 不能让未包含在 Profile 中的新设备获得安装权限。

13. 实施顺序

建议按以下顺序逐步落地：

  1. 准备一台安装 DevEco Studio 的 macOS Runner。
  2. 注册 GitLab Runner，并设置 harmony-macos 标签。
  3. 创建 .gitlab-ci.yml，先跑通自动构建。
  4. 在 AGC 申请发布证书和指定设备发布 Profile。
  5. 在项目中增加 internalTest signingConfig 和 product。
  6. 验证 Runner 能生成完整 signed HAP/HSP。
  7. 准备局域网域名、HTTPS 证书和 Nginx 文件服务器。
  8. 开发 manifest 生成及签名脚本。
  9. 开发上传和 latest 切换脚本。
  10. 使用一台已登记 UDID 的 HarmonyOS 测试机验证完整安装链路。

14. 验收标准

以下条件全部满足即表示方案落地完成：

  • 提交或合并代码到指定分支后，GitLab 自动创建流水线。
  • Runner 无需人工打开 DevEco Studio 即可完成构建。
  • 构建产物包含所有需要的 signed HAP/HSP。
  • manifest 中的版本号、模块、URL 和 SHA256 与实际文件一致。
  • manifest 签名验证成功。
  • 测试手机通过公司 Wi-Fi 或 VPN 可以访问全部 HTTPS URL。
  • 已登记 UDID 的手机点击固定链接可以安装或更新。
  • 未登记 UDID 的手机无法安装。
  • 新版本发布失败时不会破坏当前 latest 可安装版本。
# harmonyos # 华为
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

【开发者实战】HarmonyOS AI开发提效完全指南：从DevEco Code到CLI，一套工具链搞定端侧AI应用

端侧 AI 的核心不在于模型有多强，而在于如何稳定地调度任务、管理资源。HarmonyOS 的 Taskpool 和 AOT 编译解决了大部分性能问题，但开发者需要理解它们的限制：Native 对象的跨线程传递、AOT 编译的 profile 匹配、多 Target 的版本一致性。DevEco Code 和 DevEco CLI 把工具链完整了，但真正的工程经验在于知道什么时候该用什么配置，什么时

avatar HarmonyOS开发者社区
cover

从0到1打造燃力Fit：HarmonyOS API 24智慧健身房应用的橙红主题、数据可视化与打卡闭环全解析

avatar HarmonyOS开发者社区
cover

芯笺 Markdown：面向 HarmonyOS PC 的本地优先 Markdown 编辑器

avatar HarmonyOS开发者社区