wsl-setup 鸿蒙 PC 适配全记录：从 WSL 首启配置到安全远程管理

淼学派对

302人浏览 · 2026-09-13 16:34:42

淼学派对 · 2026-09-13 16:34:42 发布

欢迎加入开源鸿蒙 PC 社区：https://harmonypc.csdn.net/

欢迎在 PC 社区平台申请新建项目：https://atomgit.com/OpenHarmonyPCDeveloper

适配开源地址：https://atomgit.com/OpenHarmonyPCDeveloper/ohos_wsl-setup

一、为什么要适配 wsl-setup

wsl-setup 原本服务于 Ubuntu on WSL 的首次配置流程。它处理的不是单一命令，而是一组和系统环境强绑定的工作：初始化用户环境、整理 locale、等待 cloud-init、配置 systemd 单元、同步 Ubuntu Insights 授权状态，以及补齐 Windows Terminal、字体和 Windows 互操作相关体验。对习惯在 Windows + WSL 中开发的人来说，这些步骤决定了一个 Ubuntu 实例能不能从“刚安装”顺滑进入“可长期使用”。

鸿蒙 PC 进入桌面生产力场景后，同样需要面向开发者和运维人员的基础工具。问题在于，HarmonyOS PC 本地并不存在 WSL、Windows 注册表、PowerShell 互操作、cloud-init 登录流程和传统 Linux systemd 环境。直接把上游 shell、Debian 包和 systemd 文件搬进 HAP，不仅跑不起来，也会把平台边界说得很含糊。

本次适配选择的是更稳妥的工程路径：在鸿蒙侧提供一个原生 ohos-setup 命令和轻量 2in1 HAP，把本地能完成的初始化、状态查询、配置保存、终端资源导出、安全 HTTPS 请求做成 HarmonyOS PC 原生能力；真正依赖 Ubuntu、Linux 或 WSL 的系统操作，则交给用户明确配对的远程 Agent 执行。这样既保留了 wsl-setup 的核心使用价值，也不会在鸿蒙本地伪造不存在的 WSL 运行时。

当前适配版本为 0.1.0，BundleName 为 org.openharmony.wslsetupremote，公共 HNP 命令为 ohos-setup。已在 HarmonyOS PC 2in1 真机 HAD-W32、arm64-v8a、系统版本 HAD-W24 6.1.0.117(SP78C00E100R13P3) 上完成签名安装、HAP 启动、系统 HiShell 公共命令、Network Kit HTTPS 请求和 Mac TLS mock Agent 远程链路验证。

二、先划清边界：不能把 WSL 当成本地能力

上游 wsl-setup 面向的是 Ubuntu under WSL。它默认可以访问 Linux 根文件系统、systemd、cloud-init、Windows 用户信息和 PowerShell。HarmonyOS PC 普通应用运行在 HAP/HNP 的交付和权限模型下，普通进程也不能越过应用边界修改另一台机器上的 /etc/wsl.conf 或 Windows Terminal 配置。

适配时首先把能力拆成三层：

层次	需要解决的问题	当前实现
鸿蒙本地命令层	让用户在系统 HiShell 中使用统一入口	C++17 编写 `ohos-setup`，交叉编译为 ARM64 OpenHarmony/musl ELF
HNP/HAP 交付层	把命令作为公共工具安装到 HarmonyOS PC	使用 public HNP 随 2in1 HAP 交付，HAP 声明网络权限并展示常用命令
远程 Agent 层	执行必须发生在 Ubuntu/Linux/WSL 上的系统操作	Python 3 标准库实现 HTTPS Agent，只开放固定 API 和允许名单

这个边界决定了文档里不会把 Mac mock Agent 的测试结果说成真实 Linux systemd 修改已经完成。它证明的是 HarmonyOS PC 到远程 Agent 的 TLS、bearer token、Network Kit、HDC 反向通道和 API 路由能够打通；真实 Ubuntu/WSL 上的用户创建、cloud-init、Insights、Windows 字体安装等破坏性或半破坏性操作，还需要在可丢弃目标机上继续验收。

三、鸿蒙版本的工程结构

仓库根目录保留了上游 wsl-setup 的 shell、cloud-init、systemd 和 Debian 打包文件。鸿蒙适配集中在 ports/harmonyos/，没有用新代码覆盖原始实现：

ohos_wsl-setup/
├── wsl-setup                              # 上游 WSL 首次配置脚本
├── ubuntu-insights.sh                     # 上游 Insights 集成脚本
├── cloud/                                 # 上游 cloud-init 配置
├── systemd/                               # 上游 systemd 配置
├── debian/                                # 上游 Debian 打包文件
└── ports/harmonyos/
    ├── CMakeLists.txt                     # C++17 CLI 构建入口
    ├── cli/src/
    │   ├── main.cpp                       # ohos-setup 参数路由与本地/远程命令
    │   ├── config.cpp                     # 配置目录、授权状态、远端配置保存
    │   ├── http_client_posix.cpp          # 主机测试 HTTP 后端
    │   └── http_client_ohos.cpp           # HarmonyOS Network Kit HTTP 后端
    ├── cmake/ohos-aarch64.cmake           # OpenHarmony ARM64 交叉编译工具链
    ├── packaging/ohos-setup/              # HNP staging 与 hnp.json
    ├── scripts/
    │   ├── build_hnp.sh                   # 编译、strip、打包并审计 HNP
    │   ├── audit_hnp.sh                   # 检查 ELF、资源和公共命令链接
    │   ├── build_hap.sh                   # 构建 ArkTS HAP 并注入 HNP
    │   └── audit_hap.sh                   # 检查权限、模块和嵌套 HNP
    ├── ohos/                              # DevEco / Hvigor 2in1 HAP 工程
    │   ├── AppScope/                      # 应用配置、图标和版本信息
    │   ├── hnp/arm64-v8a/ohos-setup.hnp   # 公共 HNP 产物
    │   └── entry/src/main/ets/pages/Index.ets
    ├── agent/
    │   ├── wsl_setup_agent.py             # 远程 Ubuntu/Linux/WSL 受限 Agent
    │   └── wsl-setup-agent.service        # systemd 服务单元
    ├── tests/test_agent.py                # Agent 与安全边界测试
    ├── artifacts/                         # HAP 产物
    ├── evidence/                          # 真机截图和 hilog
    └── reports/                           # 迁移、签名、运行状态与验收报告

一次远程状态查询的实际路径如下：

HarmonyOS PC HiShell
  └── ohos-setup remote status office-wsl
        ├── 读取本地远端配置：URL、token 文件、CA、可选客户端证书
        ├── Network Kit 发起 HTTPS 请求
        ├── bearer token / CA 校验 / 可选 mTLS
        └── 远程 wsl_setup_agent.py
              └── 固定 API：/v1/system/status
                    └── JSON 结果返回 HiShell

远程配置中保存的是 token、CA、客户端证书和私钥的路径，不会把敏感内容打进 HNP/HAP。Agent 侧也不提供任意 shell 接口，systemd 服务名必须同时通过格式检查和允许名单。

四、真机上的五个核心功能验证

以下五张截图均来自同一台 HarmonyOS PC 真机，原始分辨率为 3120×2080。本次于 2026 年 8 月 25 日重新启动 HAP，并在系统 HiShell 中现场重跑全部命令；终端截图首行保留了此次运行的设备时间，便于核对截图与运行结果。

1. HAP 能够安装并展示公共 HNP 使用入口

应用启动后显示 WSL Setup Remote 页面，页面列出 ohos-setup init、doctor、remote add、remote status、remote service、remote cloud-init 等常用命令，并提示远程地址默认使用 HTTPS、令牌和私钥不会打包进应用。

在这里插入图片描述

这一屏验证了签名 HAP 的安装、Stage 模型 Ability 启动、2in1 桌面窗口渲染，以及 HNP 随包交付后的用户入口展示。HAP 页面本身不伪造远程执行结果，只承担说明和交付外壳的职责。

2. 系统 HiShell 能直接调用公共 HNP 命令

在系统 HiShell 中执行 ohos-setup version，终端返回 ohos-setup 0.1.0。随后同一窗口继续输入后续命令，说明公共 HNP 已经进入系统可执行路径，而不是只存在于某个应用沙箱内部。

在这里插入图片描述

这一步覆盖的是交付底座：ARM64 OpenHarmony/musl ELF 被 HNP 正确打包，HAP 安装后公共命令链接可被系统终端发现。对命令行工具来说，这比单纯打开一个图形页面更关键。

3. 本地初始化、环境检查和状态查询形成闭环

真机中依次执行 ohos-setup init、ohos-setup doctor 和 ohos-setup status。init 创建配置目录，doctor 返回配置目录与传输策略检查通过，status 输出版本、配置目录、授权状态、远端数量和时间戳。

在这里插入图片描述

这里验证的是鸿蒙本地可以独立完成的部分：配置目录可写、状态可持久化、授权状态可查询，且传输策略明确要求 HTTPS，普通远程 HTTP 不会被悄悄接受。

4. Network Kit HTTPS 请求和进程稳定性通过真机验证

远程配置写入后，真机通过 Network Kit 发起 HTTPS 请求。测试中的 example.com 不是 wsl-setup Agent，因此返回 HTTP 404 属于预期结果；关键在于 DNS、TLS 和 HTTP 响应处理都已经走到设备端网络栈。本次请求返回 404 后，同一 HiShell 会话紧接着执行 ohos-setup version，仍正常返回 0.1.0。

在这里插入图片描述

适配过程中曾遇到过独立 HNP 进程在 Network Kit 请求完成后触发退出阶段异常的问题。当前实现会在远程命令结束前完成请求资源清理、刷新标准输出和错误输出，并规避有问题的库退出 hook。最终 hilog 中不再出现 SIGTRAP，后续 ohos-setup version 也能继续执行。

5. HarmonyOS PC 到远程 Agent 的固定 API 链路跑通

最后一组截图展示的是 HarmonyOS PC 通过 TLS 连接 Mac 上本次新启动的 mock Agent。测试现场重新生成了临时证书与 token，通过 HDC 反向端口将真机 127.0.0.1:9443 映射到 Mac Agent。终端写入名为 live 的远端配置后，现场调用 remote status、remote service ... status 和 remote cloud-init ... wait，三次请求均返回成功的 JSON 响应。

在这里插入图片描述

这一步证明了远程配置、CA 校验、bearer token 认证、HDC 反向通道、Network Kit 请求和 API 路由可以协同工作。截图中的 mock 响应不代表真实 Linux 服务已经被修改，它验证的是安全通信链路和接口边界；真实 Ubuntu/WSL 目标上的系统变更仍应在一次性测试机上继续完成。

五、适配过程中最棘手的几个问题

难点一：原项目不是普通应用，而是 WSL 系统配置流程

wsl-setup 的很多能力天然依赖 WSL 环境：/etc/wsl.conf、Windows 用户信息、PowerShell、Windows Terminal profile、cloud-init 和 systemd。HarmonyOS PC 侧没有这些本地语义，如果强行迁移为一个“本地 WSL 配置器”，最后只能得到一个看起来像工具、实际没有可靠操作对象的应用。

适配方案因此把本地能力和远程能力分开。本地只做 HarmonyOS PC 合法范围内的命令、配置、资源导出和安全网络连接；系统级变更全部放到用户明确配对的远程 Ubuntu/Linux/WSL Agent 上执行。这个取舍让功能边界更清楚，也便于后续在真实 WSL 目标上逐项验收。

难点二：HNP 公共命令与 HAP 权限要一起成立

命令行工具迁移到鸿蒙 PC 时，不能只编出一个 ELF。用户希望在系统 HiShell 里直接输入 ohos-setup，这要求 HNP 声明 public link；远程请求又需要 HAP 声明 ohos.permission.INTERNET，并把 HNP 作为嵌套内容随应用安装。

构建脚本把这两部分绑定在一起：先使用 OpenHarmony Native SDK 编译 ARM64/musl ELF，再打包 ohos-setup.hnp，最后通过 HAP packing 工具注入 HNP。audit_hnp.sh 和 audit_hap.sh 会分别检查 ELF 类型、公共命令链接、模块文件、网络权限和嵌套 HNP，避免出现“页面能打开但命令没装好”的情况。

难点三：远程管理必须克制，不能提供任意 shell

直接提供一个远程 shell 看起来最省事，但它会把权限、审计和误操作风险全部交给用户。wsl-setup 适配面向的是系统初始化和管理场景，越是接近系统层，越不能把安全边界做成一个字符串拼接入口。

当前 Agent 只开放固定 API：系统状态、诊断、locale、cloud-init、用户创建、WSL 默认用户、Windows 状态与字体、Ubuntu Insights、systemd 服务操作等。服务名既要合法，也必须位于允许名单；用户创建和 WSL 默认用户修改默认关闭，需要管理员显式启动开关；生产通信要求 TLS 和至少 24 个随机字符的 token，可进一步启用 mTLS。

难点四：Network Kit 请求完成后的退出稳定性

真机调试时，HTTPS 请求本身能够完成，但独立 HNP 进程退出阶段可能受到 libnet_http 退出 hook 影响，出现 double free / SIGTRAP。这个问题很隐蔽，因为从用户视角看，请求已经返回，异常却发生在进程收尾阶段。

适配层最终把请求生命周期收束在 requestRemote 内部，远程命令完成后先释放请求资源并刷新输出，再用专门的退出路径规避异常 hook。设备侧 hilog 与后续命令执行结果一起作为证据保存，确保问题不是被日志淹没，而是真的不再影响用户继续使用。

难点五：mock Agent 与真实 Ubuntu/WSL 验收必须分开表述

Mac TLS mock Agent 可以很好地验证证书、token、路由和返回格式，但它不能证明 systemd、cloud-init 或 Windows 注册表修改已经在真实目标上发生。文档和报告中如果把两者混在一起，后续维护者会误判项目成熟度。

因此当前报告采用明确口径：HarmonyOS PC 侧的原生命令、HNP/HAP 交付、签名安装、安全 HTTPS 通信和 mock Agent 链路已经真机通过；依赖真实 Ubuntu/WSL 系统状态的修改操作已经实现接口和安全约束，但仍需要可丢弃目标机完成最终端到端验证。

六、构建、安装与运行

本项目不是 Electron 或 Qt 工程。鸿蒙端由 ArkTS/ArkUI HAP、C++17 原生命令、public HNP 和 Python 远程 Agent 组成。开发机需要安装 DevEco Studio、HarmonyOS/OpenHarmony SDK、CMake、Ninja，并确保 SDK 中存在 aarch64-unknown-linux-ohos-clang++、llvm-strip、hnpcli、ohpm、hvigor 和 hdc。

先运行主机侧构建和测试：

cd ohos_wsl-setup/ports/harmonyos

cmake -S . -B build/host -G Ninja -DBUILD_TESTING=ON
cmake --build build/host
ctest --test-dir build/host --output-on-failure
python3 tests/test_agent.py -v

随后交叉编译并打包公共 HNP：

cd ohos_wsl-setup/ports/harmonyos
scripts/build_hnp.sh

脚本会生成并审计：

ohos/hnp/arm64-v8a/ohos-setup.hnp

继续构建包含 HNP 的 HAP：

cd ohos_wsl-setup/ports/harmonyos
scripts/build_hap.sh

未签名产物会复制到：

artifacts/wsl-setup-remote-unsigned.hap

在具备授权签名材料后生成签名 HAP，并通过 hap-sign-tool verify-app 校验。当前已验证的签名产物路径为：

artifacts/wsl-setup-remote-signed.hap

连接 HarmonyOS PC 真机后安装并启动：

hdc install -r ports/harmonyos/artifacts/wsl-setup-remote-signed.hap
hdc shell aa start -b org.openharmony.wslsetupremote -m entry -a EntryAbility

在系统 HiShell 中可以直接运行：

ohos-setup version
ohos-setup doctor
ohos-setup init
ohos-setup status
ohos-setup consent enable
ohos-setup assets terminal-profile

部署远程 Agent 时，在 Ubuntu、Linux 或 Ubuntu under WSL 主机上准备 TLS 证书和 token 文件：

python3 wsl_setup_agent.py \
  --listen 0.0.0.0 --port 9443 \
  --token-file /etc/wsl-setup-agent/token \
  --cert-file /etc/wsl-setup-agent/server.crt \
  --key-file /etc/wsl-setup-agent/server.key \
  --ca-file /etc/wsl-setup-agent/client-ca.crt

随后在 HarmonyOS PC 上添加远端并调用固定操作：

ohos-setup remote add office-wsl https://host.example:9443 \
  --token-file /path/to/token \
  --ca /path/to/ca.crt \
  --cert /path/to/client.crt \
  --key /path/to/client.key

ohos-setup remote status office-wsl
ohos-setup remote service office-wsl multipathd.service status
ohos-setup remote cloud-init office-wsl wait
ohos-setup remote diagnostics office-wsl

如需开放用户创建和 WSL 默认用户修改，Agent 启动时必须由管理员额外加入：

--allow-user-provisioning --allow-wsl-default-user

七、当前已覆盖的能力与明确边界

当前已经在构建、审计或 HarmonyOS PC 真机上跑通：

主机 C++ CLI 构建、CTest 和 Python Agent 测试；
ARM64 OpenHarmony/musl ELF 交叉编译；
HNP 打包、公共命令链接和内容审计；
ArkTS 类型检查、HAP 构建、HNP 注入和网络权限审计；
授权签名、签名校验、真机安装和 HAP 启动；
系统 HiShell 中执行 ohos-setup version、doctor、init、status；
本地配置目录、Insights consent 状态和 terminal profile 资源导出；
Network Kit HTTPS 请求、CA 校验、bearer token 认证和请求后的进程稳定性；
HarmonyOS PC 到 Mac TLS mock Agent 的 status、service status、cloud-init wait 和 diagnostics 路由验证。

当前没有作为完整完成能力承诺的部分包括：

在真实 Ubuntu/WSL Agent 上执行 systemd 允许名单动作；
在真实 cloud-init 环境中完成状态查询与等待；
在可丢弃 Linux/WSL 主机上进行用户创建；
修改真实 WSL 的默认用户；
Ubuntu Insights 与 Windows 注册表同步的端到端验证；
Windows 字体安装和 Windows Terminal 自动注册；
HarmonyOS 本地直接实现 WSL、systemd、cloud-init 或 Windows 注册表语义；
任意远程 shell、任意系统命令执行和未审计服务名操作。

因此，当前成果更准确的定位是“面向 HarmonyOS PC 的 wsl-setup 原生客户端与安全远程管理入口”。鸿蒙侧的交付、启动、公共命令和安全通信已经真机验证；远程 Linux/WSL 系统修改接口已经完成实现和约束，等待真实目标机补齐最终验收。

八、总结

wsl-setup 的鸿蒙 PC 适配不是把一组 WSL 脚本塞进安装包，而是重新定义它在新平台上的责任边界。HarmonyOS PC 侧负责可靠的原生命令、公共 HNP 交付、配置保存和安全网络连接；Ubuntu/Linux/WSL 侧负责真正需要系统语义的操作。这个拆分让项目既能落地，也能避免把平台缺失能力包装成已经完成。

五组真机结果表明，应用页面、公共 HNP 命令、本地初始化、Network Kit HTTPS 和远程 Agent 固定 API 链路已经跑通。适配中最重要的工程经验，是在保留 wsl-setup 用户价值的同时，保持对安全边界和验证口径的克制：已经真机验证的能力清楚标出，尚需真实 Ubuntu/WSL 验收的部分也不提前透支结论。

后续推进的重点应放在一次性真实 Ubuntu/WSL 目标上，逐项完成 systemd、cloud-init、用户创建、WSL 默认用户、Insights 和 Windows 互操作验证。只要远程系统侧验收补齐，这套 HAP + public HNP + 受限 Agent 的架构就能成为鸿蒙 PC 迁移系统管理类开发工具的一条可复用路径。