一个界面挂四套协议:WebDAV / S3 / SFTP / FTPS 在鸿蒙上的落地取舍

一、写在前面

开源地址:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_winscp

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

本文导读

  • 要解决的问题:WinSCP 这类远程文件工具的价值全在协议栈,而鸿蒙既要重做界面,又要把 SFTP 这种绕不开 SSH 的协议用原生库接进来。
  • 你会读到的技术细节:TransportGateway 抽象(640 行)+ 四个协议实现:S3 的 SigV4 签名、FTP 的双连接状态机、SFTP 的 libssh2 原生桥接、WebDAV 的 HTTPS 强制校验。还有一处容易被忽略的设计——明文 FTP 被主动置灰。
  • 本文的实测数据:18 个文件 5576 行 + 831 行原生桥接、四协议合计 2862 行、HAP 5.1 MB、三栏工作区实测截图 4 张。
  • 适合谁读:做网络工具、关心凭据存储与后台长任务保活的开发者。

这篇文章记录的是把 WinSCP 这类远程文件传输工具,移植成鸿蒙 PC 原生应用的过程。最终落地的应用叫 云桥文件,包名 com.cloudbridge.files。

其他移植项目分别是本地工具、本地计算、云客户端、混合模式、本地服务端。这个项目是第六种形态:一个纯网络 I/O 的工具——它的全部价值在于"能不能可靠地连上各种远程文件服务,把文件搬来搬去"。

先给结论:

客户端移植完成,四协议栈(WebDAV / S3 / SFTP / FTPS)、双栏文件工作区、传输队列、站点管理全部实现,界面在真机上跑通。

验证环境是真实设备:

项值
设备型号HUAWEI MateBook Pro S(MOR-M1)
系统版本HarmonyOS 7.0.0.111(SP15C00E101R9P2)
API 版本26
设备形态2in1
构建工具DevEco Studio 内置 hvigor 6.26.4
SDKHarmonyOS SDK 26.0.0.105

二、项目背景

WinSCP(https://github.com/winscp/winscp)是 Windows 上最常用的 SFTP/FTP 客户端之一,核心场景是"本地 ↔ 远程"的文件拖拽传输。

它的技术骨架:

  • C++ + Win32 GUI,双栏文件浏览器;
  • 传输层依赖 PuTTY 的 psftp 组件(SFTP)、自研 FTP/FTPS 实现;
  • 会话配置加密存在注册表;
  • 丰富的传输选项:断点续传、同步浏览、队列、脚本化。

把这些搬到鸿蒙上,问题集中在三处:

组成部分鸿蒙上能用吗
Win32 GUI❌ 不存在
PuTTY 系 SFTP⚠️ 需要把 libssh2 交叉编译进来
FTP/FTPS✅ 可以纯 ArkTS 实现
注册表存会话❌ 换 AssetStoreKit
拖拽传输⚠️ 鸿蒙 PC 有拖拽能力,但语义不同

所以移植的判断是:

协议栈重新实现,界面按"远程文件管理器"重新设计。

最终工程 18 个 ArkTS 文件、5576 行,加一层 831 行的原生 SFTP 桥接(依赖 libssh2 + mbedTLS)。


三、总体变化概览

entry/src/main/
├── module.json5        INTERNET / GET_NETWORK_INFO / KEEP_BACKGROUND_RUNNING
├── cpp/
│   ├── cloudbridge_sftp.cpp     SFTP 原生桥接(831 行)
│   └── third_party/prebuilt/    libssh2 + mbedTLS(arm64-v8a / x86_64)
└── ets/                         18 个文件 / 5576 行
    ├── pages/Index.ets                      主界面(1691 行)
    └── services/
        ├── TransportGateway.ets             传输网关抽象(640 行)
        ├── S3TransportGateway.ets           S3 / MinIO(950 行)
        ├── FtpTransportGateway.ets          FTP / FTPS(889 行)
        ├── SftpTransportGateway.ets         SFTP(383 行)
        ├── TransferQueue.ets                传输队列(342 行)
        └── SiteStore.ets                    站点保存(148 行)

技术栈映射:

WinSCP 原方案云桥文件(鸿蒙)
Win32 双栏窗口ArkUI 三栏(列表 + 内容 + 连接信息)
PuTTY psftplibssh2 原生桥接
FTP/FTPS 自研ArkTS 实现 FtpTransportGateway(889 行)
注册表加密存会话SiteStore + AssetStoreKit
传输队列窗口常驻「传输队列」面板
拖拽上传工具栏「上传」+ 传输队列

一个值得注意的结构:四个协议客户端都实现同一个 TransportGateway 抽象(640 行),S3 是最重的一个(950 行),SFTP 最轻(383 行,因为重活交给了原生)。


四、原始项目直接跑鸿蒙会遇到什么问题

4.1 三种协议、三种完全不同的实现路径

这是本期最核心的复杂度:

协议实现方式难点
WebDAV纯 HTTP(PUT/GET/PROPFIND)相对简单
S3 / MinIO纯 HTTP + AWS SigV4 签名签名算法是硬骨头(950 行不是白写的)
FTP / FTPS裸 TCP + 控制连接 + 数据连接需要自己管理两个连接的状态机
SFTPSSH 子系统ArkTS 做不了 SSH,必须吃原生库

也就是说:同一个界面底下挂着四条差异极大的技术路线。

4.2 SFTP 绕不开原生库

SSH 的密钥交换、加密、MAC 校验,在 ArkTS 里从零实现既不现实也不安全。必须把 libssh2 交叉编译进 HAP。

这就是 cpp/cloudbridge_sftp.cpp(831 行)存在的原因,third_party/prebuilt/ 下同时准备了 arm64-v8a 和 x86_64 两套产物——照顾真机和模拟器。

4.3 明文协议必须默认关闭

登录对话框里 FTP 这一项是灰色不可选的:

在这里插入图片描述

而 FTPS 可选。这个细节说明协议栈做了安全分级:不加密的 FTP 直接不给用,只能用带 TLS 的 FTPS。

同类约束在代码里也有一道:

// TransportGateway.ets:82
if (normalizedHost.startsWith('http://')
  || (normalizedHost.indexOf('://') >= 0 && !normalizedHost.startsWith('https://'))) {
  // 拒绝非 HTTPS 的 WebDAV 地址
}

4.4 凭据不能落在普通配置里

远程文件服务的密码 / Access Key 一旦泄露,等于别人能读写你的云存储。所以"保存的连接"里的凭据走系统安全存储,而不是普通 Preferences。


五、鸿蒙适配核心路径

5.1 第一步:抽一层传输网关

四个协议差异太大,如果界面直接调各协议 API,代码会烂掉。所以先抽一个 TransportGateway:

// services/TransportGateway.ets(640 行)
// 统一抽象:list / upload / download / mkdir / delete / rename
// 上层界面只依赖这个接口,不关心底层是 WebDAV 还是 S3

四个实现:

TransportGateway
├── S3TransportGateway    950 行(SigV4 签名 + 分片上传)
├── FtpTransportGateway   889 行(控制/数据双连接状态机)
├── SftpTransportGateway  383 行(转调原生 libssh2)
└── WebDAV                (复用 HTTP 网关)

这个结构的价值在后期非常明显:加协议不用动界面。

5.2 第二步:SFTP 用原生桥接

cloudbridge_sftp.cpp 把 libssh2 的能力包成 NAPI 函数,ArkTS 侧只负责会话参数和回调。

依赖通过 third_party/prebuilt 直接随仓库提供(arm64-v8a + x86_64 双架构),CMake 按目标架构选:

# third_party/prebuilt/<arch>/lib*.a

这样开发者克隆下来不需要自己编 libssh2/mbedTLS。

5.3 第三步:三栏文件工作区

主界面不是简单的一栏列表,而是"列表 + 内容 + 连接信息"三栏:

在这里插入图片描述

左侧:文件工作区 / 传输记录 / 保存的连接 / 设置。
中间:面包屑(远程根目录)+ 刷新/上传 + 文件列表 + 传输队列。
右侧:连接信息面板,实时显示协议、服务器、端口、远程路径。

这块右侧面板是一个很实用的设计——远程文件工具最容易搞混"我现在连的是哪台机器",把它常驻在右边就解决了。

5.4 第四步:传输记录独立成页

在这里插入图片描述

传输任务列表用 文件 / 任务 两列表格展示,右上角显示 0 条记录,空态是「暂无传输任务」。

文件工作区底部还嵌了一个「传输队列」小面板(0 条记录 + 暂无传输任务),两个入口一个给概览、一个给细节。

5.5 第五步:设置页把安全策略摊开

在这里插入图片描述

设置页很短,但每一行都是关键信息:

项内容
站点配置0 个保存的连接 / 添加站点
支持的协议WebDAV (HTTPS) · S3 / MinIO · SFTP · FTPS
凭据存储HarmonyOS 系统 Asset 安全存储
隐私政策 / 用户协议上架必备
开源许可libssh2 · mbedTLS

把「凭据存储:系统 Asset 安全存储」这种技术实现直接写在设置页里,对一个文件传输工具来说是加分的——用户会想知道密码存在哪。


六、问题困难解决

6.1 困难一:S3 的 SigV4 签名

S3TransportGateway 有 950 行,是四个网关里最大的——因为它不只是 HTTP 调用,还要实现 AWS Signature Version 4:

  • 规范化请求(Canonical Request)
  • 签名密钥派生(HMAC 链)
  • 每个请求都要算 Authorization 头

这块如果实现有偏差,表现是"所有请求都 403",而且错误信息不给原因。所以它占了整个项目近 1/6 的代码量。

6.2 困难二:FTP 的双连接状态机

FTP 协议的特殊性在于它同时有控制连接和数据连接:

控制连接:USER / PASS / CWD / TYPE / PASV
数据连接:LIST / RETR / STOR 时单独建立

FtpTransportGateway(889 行)大部分代码在处理这个状态机:PASV 模式协商端口、数据连接建立、传输完成关闭、错误恢复。

6.3 困难三:把「协议」和「界面」解耦

四个协议的错误语义完全不同:

协议典型失败用户该看到什么
WebDAV401 / 404 / 507认证失败 / 路径不存在 / 空间不足
S3403 SignatureDoesNotMatch密钥错误
FTP530 Login incorrect账号密码错误
SFTP握手失败 / 公钥被拒服务器不可达 / 认证方式不支持

界面层不应该知道这些差异,所以错误统一在网关层翻译成结构化错误码,UI 只负责展示。

6.4 困难四:后台传输不能被杀

module.json5 申请了 KEEP_BACKGROUND_RUNNING。文件传输是长任务,用户切走窗口后传输必须继续——否则传大文件时切个窗口就断了,体验直接崩。


七、构建与运行方式

7.1 环境

  • DevEco Studio(内置 hvigor + SDK)
  • HarmonyOS SDK API 26(本机 26.0.0.105)
  • 原生依赖已随仓库提供,无需自行编译 libssh2/mbedTLS

7.2 构建

ohpm install
hvigorw assembleHap --mode module -p product=default -p buildMode=debug

产物:

entry-default-unsigned.hap   5.1 MB

(含 arm64-v8a / x86_64 双架构的 libssh2 + mbedTLS)

7.3 签名与安装

scripts/sign_hap.sh(环境变量方式)或 DevEco 自动签名。调试 profile 绑 UDID,换设备需重新自动签名。

hdc shell aa start -b com.cloudbridge.files -a EntryAbility

八、适配成果

8.1 三栏文件工作区

见 5.3。左侧导航、中间文件区、右侧连接信息——信息密度和 WinSCP 的双栏布局思路一致,但把"当前连接状态"独立成栏,更适合多站点场景。

8.2 连接对话框

见 4.3 / 图 2。协议切换用 chip 组(WebDAV / S3 / SFTP / FTP / FTPS),一个点击完成切换;字段随协议变化:

  • WebDAV:服务器地址(HTTPS)+ 远程路径 + 端口 443 + 用户名 + 密码
  • S3:服务器地址 + Access Key + Secret Key(界面上有示例提示)
  • SFTP:主机 + 端口 22 + 用户名 + 私钥/密码

底部一行小字:「口令仅交给系统安全存储」。

8.3 工程量

指标数值
ArkTS 源文件18 个
ArkTS 代码行数5576 行
原生桥接831 行 C++
协议实现4 个(WebDAV / S3 / SFTP / FTPS)
权限INTERNET、GET_NETWORK_INFO、KEEP_BACKGROUND_RUNNING
HAP 体积5.1 MB

8.4 同类移植项目横向对比

ClipNest澜析工程沙箱控制台晶析云MySQL云桥文件
类型本地工具本地计算云客户端混合服务端网络 I/O
ArkTS 行数478234175862347622975576
原生代码061900894831
HAP752 KB19 MB892 KB444 KB2.1 MB5.1 MB
协议数——21—4

九、功能验证结果

9.1 已在真机验证

功能结果验证方式
构建与安装✅5.1 MB HAP,hdc install 成功
应用启动✅进程稳定运行,窗口正常渲染
三栏工作区✅导航 / 文件区 / 连接信息面板布局正确
连接对话框✅5 个协议 chip、字段、端口默认值正确
协议安全分级✅FTP 置灰不可选,FTPS 可选
连接状态面板✅协议/服务器/端口/远程路径字段完整
传输记录页✅表头与空态正常
传输队列面板✅显示 0 条记录 + 空态
设置页✅协议清单、凭据存储说明、开源许可均正确
权限配置✅三个权限声明,后台保活已申请

9.2 未验证

功能说明
真实 WebDAV / S3 连接需要可访问的 HTTPS 端点与凭据
SFTP 会话需要 SSH 服务器与密钥
实际上传/下载依赖已建立连接
断点续传与队列调度需要真实传输
保存站点需要一次成功连接后保存

补充说明:应用的 WebDAV 地址做了 HTTPS 强制校验,本地起一个明文 WebDAV 服务器无法用于验证,必须配置证书。

9.3 已知限制

限制说明
不支持明文 FTP协议层主动禁用,只能用 FTPS
WebDAV 必须 HTTPS代码层校验,http:// 直接被拒
需要自备服务端无内置测试服务器
调试 profile 绑 UDID换设备需重新自动签名

十、上架复盘:审核不通过怎么办

移植跑通只是第一关。上架审核看的是另一套东西:用户会不会把这款应用误认为上游官方版,或者误认为换皮抄袭。名称、图标、截图、描述、权限、实际行为,只要有一项对不上,就可能被驳回。

10.1 名称和图标:开源许可不等于品牌许可

这是最容易踩的坑。很多人觉得“这是开源软件,保留原名和原图标很正常”,但 MIT/Apache/GPL 给的是版权许可,不是商标许可。审核看到“应用名和上游一样、图标是上游 Logo 换色、截图里还有上游品牌”,就会按“冒用/抄袭”处理。典型的三连击是:应用名直接沿用上游、图标只把颜色换一下、截图里还带着上游 Logo——即使代码全部重写,也会被判定为冒用。

我们的处理原则:

  • 应用名改成独立品牌,包名不带上游商标;
  • 图标重画,不复用、不改色、不截取上游 Logo;
  • 截图、启动图、关于页不出现上游 Logo,只保留文字致谢;
  • 关于页写明“基于 WinSCP 移植,非官方发行”,并保留上游 LICENSE/NOTICE;
  • 如果被质疑,提交《品牌与素材来源说明》:改名前后对照、图标设计稿、上游许可证、代码差异、真机录屏。

10.2 被判定“抄袭/雷同”时,交什么证据

只回“这是开源软件”通常没用。按这个顺序给材料:

  1. 上游仓库地址和 LICENSE 原文;
  2. 本仓库与上游的差异清单(UI 重写、平台层、构建脚本);
  3. 品牌变更记录(旧名→新名、旧图标→新图标);
  4. 功能差异说明(哪些是鸿蒙特有、哪些上游没有);
  5. 真机录屏,证明不是套壳。

如果确实沿用了上游 UI,先改再申诉;审核一般不看“开源所以可以一样”的解释。

10.3 这个项目的高频驳回点

  • 网络与凭据:审核会问是否收集服务器密码。说明凭据只存本地 Asset、不上传,连接由用户主动发起。
  • 后台任务:说明连续任务的用途和开关,系统拒绝时前台继续。
  • 品牌:WinSCP 的名称/图标不能用;“云桥文件”+ 自绘图标,关于页注明非官方;明文 FTP 默认禁用。

10.4 驳回后的处理顺序

先分类,再动手。审核意见通常落在六类:名称/图标/品牌、隐私与权限、功能与描述不符、技术(签名/包名/架构/体积/崩溃)、内容合规、资质(软著/授权书/备案)。

  • 一次只改一类,别在同一个版本里混改;
  • 回复时逐条对应:版本号 + 审核意见 + 改了什么 + 怎么验证;
  • 测试账号/令牌在复审前重置,写进审核备注;
  • 截图必须来自当前版本真机,不能用设计稿;
  • 换正式证书后重新打包,不要用调试签名送审;
  • 被拒后先回一条“已收到,逐条说明”,再提新包,避免被判定骚扰;
  • 上架材料提前备齐:软著/授权书、隐私政策公网 URL、测试账号、真机截图、开源许可证与 NOTICE。

回复可以按这个模板:

您好,针对第 X 条“……”:我们已在版本 A.B.C 中修改:1)……;2)……。验证路径:……。相关材料见附件/链接。

一句话:上架不是“把包传上去”,而是把“这不是官方版、也不是换皮”这件事,用名称、图标、截图、代码和材料同时证明一遍。

十一、结语

这次移植的技术密度是最高的:一个界面底下挂着四套完全不同的协议实现。

四点体会:

  1. 抽象层要早做。TransportGateway 这个 640 行的抽象,让 4 个协议(合计 2862 行实现)能被同一套界面驱动。如果没有它,1691 行的 Index.ets 会膨胀到不可维护。

  2. 该用原生就得用原生。SFTP 绕不开 SSH,ArkTS 里硬写 crypto 既不现实也不安全。831 行原生桥接 + 预编译 libssh2/mbedTLS 是正确选择,而且把双架构产物一起入库,省掉了后来者编译依赖的麻烦。

  3. 安全策略应该显性化。FTP 置灰、HTTPS 强制、凭据进 AssetStoreKit、设置页直接写明"凭据存储:系统 Asset 安全存储"——这些都让用户能看见安全边界在哪。工具类应用最忌讳"看起来能用,实际上在裸奔"。

  4. 协议错误的语义差异要收在网关层。WebDAV 的 507、S3 的 403 SignatureDoesNotMatch、FTP 的 530,不应该漏到界面上。

5.1 MB 的包,装着四个协议客户端。它现在还没连过真实的服务器——但只要给它地址和凭据,WebDAV/S3/FTPS 三条纯软件路线是完整的;SFTP 那条需要原生库在真机上跑通握手,这是下一步要验证的重点。


一句话:四套协议、一个界面——抽象层做得越早,后面的路越短。

相关链接

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐