鸿蒙 PC:云桥文件(ohos_winscp)远程文件管理器移植全记录
一个界面挂四套协议: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 |
| SDK | HarmonyOS 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 psftp | libssh2 原生桥接 |
| 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 + 控制连接 + 数据连接 | 需要自己管理两个连接的状态机 |
| SFTP | SSH 子系统 | 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 困难三:把「协议」和「界面」解耦
四个协议的错误语义完全不同:
| 协议 | 典型失败 | 用户该看到什么 |
|---|---|---|
| WebDAV | 401 / 404 / 507 | 认证失败 / 路径不存在 / 空间不足 |
| S3 | 403 SignatureDoesNotMatch | 密钥错误 |
| FTP | 530 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 行数 | 4782 | 3417 | 5862 | 3476 | 2297 | 5576 |
| 原生代码 | 0 | 619 | 0 | 0 | 894 | 831 |
| HAP | 752 KB | 19 MB | 892 KB | 444 KB | 2.1 MB | 5.1 MB |
| 协议数 | — | — | 2 | 1 | — | 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 被判定“抄袭/雷同”时,交什么证据
只回“这是开源软件”通常没用。按这个顺序给材料:
- 上游仓库地址和 LICENSE 原文;
- 本仓库与上游的差异清单(UI 重写、平台层、构建脚本);
- 品牌变更记录(旧名→新名、旧图标→新图标);
- 功能差异说明(哪些是鸿蒙特有、哪些上游没有);
- 真机录屏,证明不是套壳。
如果确实沿用了上游 UI,先改再申诉;审核一般不看“开源所以可以一样”的解释。
10.3 这个项目的高频驳回点
- 网络与凭据:审核会问是否收集服务器密码。说明凭据只存本地 Asset、不上传,连接由用户主动发起。
- 后台任务:说明连续任务的用途和开关,系统拒绝时前台继续。
- 品牌:WinSCP 的名称/图标不能用;“云桥文件”+ 自绘图标,关于页注明非官方;明文 FTP 默认禁用。
10.4 驳回后的处理顺序
先分类,再动手。审核意见通常落在六类:名称/图标/品牌、隐私与权限、功能与描述不符、技术(签名/包名/架构/体积/崩溃)、内容合规、资质(软著/授权书/备案)。
- 一次只改一类,别在同一个版本里混改;
- 回复时逐条对应:版本号 + 审核意见 + 改了什么 + 怎么验证;
- 测试账号/令牌在复审前重置,写进审核备注;
- 截图必须来自当前版本真机,不能用设计稿;
- 换正式证书后重新打包,不要用调试签名送审;
- 被拒后先回一条“已收到,逐条说明”,再提新包,避免被判定骚扰;
- 上架材料提前备齐:软著/授权书、隐私政策公网 URL、测试账号、真机截图、开源许可证与 NOTICE。
回复可以按这个模板:
您好,针对第 X 条“……”:我们已在版本 A.B.C 中修改:1)……;2)……。验证路径:……。相关材料见附件/链接。
一句话:上架不是“把包传上去”,而是把“这不是官方版、也不是换皮”这件事,用名称、图标、截图、代码和材料同时证明一遍。
十一、结语
这次移植的技术密度是最高的:一个界面底下挂着四套完全不同的协议实现。
四点体会:
-
抽象层要早做。
TransportGateway这个 640 行的抽象,让 4 个协议(合计 2862 行实现)能被同一套界面驱动。如果没有它,1691 行的Index.ets会膨胀到不可维护。 -
该用原生就得用原生。SFTP 绕不开 SSH,ArkTS 里硬写 crypto 既不现实也不安全。831 行原生桥接 + 预编译 libssh2/mbedTLS 是正确选择,而且把双架构产物一起入库,省掉了后来者编译依赖的麻烦。
-
安全策略应该显性化。FTP 置灰、HTTPS 强制、凭据进 AssetStoreKit、设置页直接写明"凭据存储:系统 Asset 安全存储"——这些都让用户能看见安全边界在哪。工具类应用最忌讳"看起来能用,实际上在裸奔"。
-
协议错误的语义差异要收在网关层。WebDAV 的 507、S3 的 403 SignatureDoesNotMatch、FTP 的 530,不应该漏到界面上。
5.1 MB 的包,装着四个协议客户端。它现在还没连过真实的服务器——但只要给它地址和凭据,WebDAV/S3/FTPS 三条纯软件路线是完整的;SFTP 那条需要原生库在真机上跑通握手,这是下一步要验证的重点。
一句话:四套协议、一个界面——抽象层做得越早,后面的路越短。
相关链接
- 适配仓库:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_winscp
- 上游项目 WinSCP:https://github.com/winscp/winscp
- OpenHarmony PC 开发者社区:https://atomgit.com/OpenHarmonyPCDeveloper
更多推荐



所有评论(0)