DirBridge：一个基于 C++/Qt 的 Windows 远程文件管理工具

最近我在做一个 Windows 桌面端远程文件管理工具项目名叫DirBridge。DirBridge 的目标是提供一个类似 Xftp 的本地与远程双栏文件管理体验左侧管理本地文件右侧连接远程服务器通过图形界面完成目录浏览、文件上传、文件下载、拖拽传输、多会话管理等操作。项目地址GitHubhttps://github.com/shy117/DirBridge目前项目已经完成了第一阶段 MVP 的主要流程并且可以进行打包发布。本文主要介绍这个项目的设计目标、当前能力、技术选型和开发过程中的一些实践思考。一、为什么做 DirBridge在日常开发和部署过程中经常会遇到本地和远程服务器之间传输文件的场景。常见需求包括把本地构建产物上传到服务器从服务器下载日志或配置文件浏览 FTP / SFTP 远程目录同时连接多个远程站点查看文件传输状态、速度和失败原因成熟工具当然已经很多但我还是希望自己做一个远程文件管理工具主要原因有三个。第一这是一个很适合练习 C/Qt 桌面开发的真实项目。它不只是简单窗口和按钮而是涉及文件系统、远程协议、任务队列、配置管理、日志、异步任务和 UI 状态同步。第二我希望通过这个项目搭建一个比较清晰的桌面软件工程结构而不是把所有逻辑都堆在窗口类里。第三我希望它是一个可以长期迭代的小工具。先完成最核心的文件管理和传输能力再逐步完善体验和功能。所以 DirBridge 的目标不是一开始就做成一个“大而全”的工具而是先把主流程做扎实能连接能浏览能上传下载能管理任务能稳定地继续迭代。二、DirBridge 是什么DirBridge 是一个面向 Windows 桌面场景的远程文件管理工具。它的核心目标是提供类似传统 FTP/SFTP 客户端的双栏文件管理体验左侧是本地文件面板右侧是远程文件面板可以连接 FTP / SFTP 服务器可以上传、下载、拖拽传输文件可以同时管理多个远程会话可以查看传输队列、进度、速度和日志简单来说DirBridge 想解决的是这样一个问题用一个清晰、直接、可维护的桌面工具在本地文件系统和远程服务器之间建立一座桥。这也是项目名 DirBridge 的含义Directory Bridge(目录桥)。三、当前已经支持的功能目前 DirBridge 已经完成了第一阶段 MVP 的主要能力。1. 本地文件浏览DirBridge 提供本地文件面板可以浏览本机目录结构查看文件和文件夹信息。本地面板支持常见文件管理操作例如进入目录返回上级刷新目录查看文件列表右键操作文件或文件夹在没有远程会话时本地文件面板可以占满主要区域连接远程站点后再切换成本地和远程双栏显示。2. FTP / SFTP 远程目录浏览DirBridge 目前支持访问 FTP / SFTP 远程目录。连接远程站点后远程文件面板可以显示服务器上的目录和文件并支持浏览远程目录进入子目录返回上级目录刷新当前目录查看远程文件大小、类型、修改时间等信息远程文件列表采用详细信息视图更适合文件管理工具的使用场景。3. 站点配置管理DirBridge 支持保存和加载站点配置方便重复连接常用服务器。站点信息可以按分组展示也支持最近会话记录。这样在日常使用中不需要每次都手动输入协议、主机、端口、用户名和远程路径。当前站点管理主要包括保存站点加载站点编辑站点属性按分组管理站点记录最近连接过的会话4. 多远程会话 TabDirBridge 支持同时打开多个远程会话。每个远程会话都使用独立的 Tab 管理并且每个会话都有自己的状态独立的连接状态独立的远程路径独立的远程文件面板独立的远程后端实例独立的会话名称这样就可以同时连接多个服务器或者连接同一服务器的不同目录。关闭、断开或重连某一个远程会话时不会影响其他已经打开的远程会话。5. 上传、下载和拖拽传输DirBridge 支持本地与远程之间的基础文件传输。当前已经支持单文件上传单文件下载本地文件拖拽到远程面板上传远程文件拖拽到本地面板下载本地文件夹上传远程文件夹下载远程面板内部拖拽移动这些操作都会进入统一的传输队列而不是直接阻塞界面。6. 全局传输队列DirBridge 底部提供全局传输队列用来展示上传和下载任务。传输队列会显示名称状态进度大小本地路径传输方向远程路径速度估计剩余经过时间这样即使同时连接多个远程会话也可以在一个统一的位置查看所有传输任务。7. 目录传输聚合进度文件夹上传和下载是远程文件管理工具中很常见的需求。如果只把文件夹里的每个文件都拆成独立任务用户很难判断整个文件夹传输了多少。因此 DirBridge 对目录传输做了聚合显示。目录传输会显示为一个文件夹父任务多个子文件任务父任务负责显示整体进度子任务负责显示具体文件明细。例如上传一个文件夹时传输队列中可以看到一个文件夹任务。展开后可以查看里面每个文件的上传状态。默认情况下子任务可以折叠起来避免传输队列表格过于混乱。这个设计让目录传输更加接近用户直觉我上传的是一个文件夹所以我应该能看到这个文件夹整体传了多少。8. 日志和基础运行检查DirBridge 内部使用日志记录应用运行状态包括程序启动、站点加载、远程连接、目录加载、上传下载和错误信息等。日志既可以辅助开发调试也可以帮助后续定位用户环境中的问题。四、界面布局设计DirBridge 的主界面采用比较传统的文件管理器布局。整体结构包括顶部菜单栏快速连接区域左侧会话管理器中间本地/远程文件双栏底部传输队列和日志区域这种布局没有追求复杂炫酷而是优先考虑文件管理工具最重要的几点信息清晰操作路径短状态可见多任务时不混乱对于远程文件管理工具来说用户最关心的是当前连接到哪里当前目录在哪里文件是否传输成功出错时原因是什么所以 DirBridge 的界面设计会尽量围绕这些问题展开。五、技术栈DirBridge 当前主要使用以下技术栈C17Qt WidgetsCMakelibcurlnlohmann/jsonspdlogQt Widgets 用于构建桌面界面。DirBridge 这种工具型软件更适合传统桌面控件体系例如表格、树、Tab、菜单、右键菜单、文件列表等。libcurl 用于处理远程协议访问目前主要支持 FTP / SFTP 的连接、目录读取、上传、下载和远程文件操作。nlohmann/json 用于配置文件读写站点配置、用户设置等数据都可以通过 JSON 保存。spdlog 用于应用日志方便定位连接、传输和运行时问题。CMake 用于项目构建和依赖组织。DirBridge 当前主要面向 Windows MinGW Qt 6 环境进行验证。六、项目结构设计DirBridge 在代码结构上尽量按职责分层而不是让 UI 直接承担所有逻辑。当前源码结构大致如下src/ ├── app/ Qt 应用入口 ├── ui/ Qt Widgets 界面 ├── core/ 纯 C 业务模型和调度 ├── protocol/ libcurl 等协议封装 ├── config/ JSON 配置读写 └── logging/ spdlog 日志封装大致分层思路是app层负责应用启动、命令行参数分发和主窗口创建。ui层负责界面展示和用户交互。core层负责文件模型、站点模型、传输任务和队列调度。protocol层负责封装 FTP / SFTP 等远程协议实现。config层负责配置读写。logging层负责日志初始化和日志写入。这样做的好处是UI 层不需要直接关心 libcurl 的调用细节远程协议实现也不会和窗口控件绑定在一起。项目后续继续扩展时各层职责会更清晰。七、开发中重点解决的几个问题1. 不让远程操作阻塞界面远程连接、目录加载、上传下载和递归目录处理都可能比较耗时。如果这些操作直接在 UI 线程中执行界面就会卡住用户体验会很差。因此 DirBridge 在迭代过程中逐步把耗时操作放到后台执行例如远程连接文件上传文件下载目录传输准备本地递归删除远程递归删除这样即使正在执行传输任务主界面也可以继续操作。2. 目录传输不能只显示零散文件文件夹传输和单文件传输不同。用户上传一个文件夹时心里关注的是“这个文件夹传完了吗”而不是只看到几十个零散文件任务。因此 DirBridge 为目录传输设计了父子任务结构父任务表示整个目录子任务表示目录中的具体文件父任务聚合子任务进度子任务可展开查看这样传输队列既能显示整体状态也能保留详细信息。3. 多远程会话之间不能互相干扰远程文件管理工具经常需要同时连接多个服务器。如果所有远程状态都放在一个全局对象里很容易出现状态混乱例如A 会话断开影响 B 会话当前路径被其他会话覆盖上传下载任务不知道属于哪个远程连接DirBridge 使用远程会话模型来隔离这些状态。每个远程 Tab 都有自己的会话 id、站点配置、远程后端、文件面板和当前路径。传输任务中也会记录相关路径和方向方便在全局传输队列中追踪来源和目标。八、当前状态和后续计划DirBridge 当前仍处于 MVP 阶段但主流程已经基本跑通。已经完成的主要方向包括Qt Widgets 主界面本地文件面板远程文件系统抽象FTP / SFTP 远程目录浏览站点配置保存和加载多远程会话 Tab远程文件操作上传下载拖拽传输全局传输队列目录传输聚合进度日志和基础配置Windows 发布包准备DirBridge 后续会优先完善基础体验而不是盲目增加大量高级功能。目前比较明确的方向包括优化真实 FTP / SFTP 环境下的稳定性完善 Windows 发布包和安装包体验优化远程刷新、路径跳转等可能阻塞界面的流程改进传输失败、取消、重试等异常路径体验继续完善传输队列的可用性根据实际使用反馈评估远程编辑、目录同步等功能一些高级功能会放到后续阶段再考虑例如远程编辑文件夹比较目录同步SSH 终端插件系统当前阶段还是先把远程文件管理这个核心场景做稳。九、项目地址如果你也对 C/Qt 桌面开发、远程文件管理工具或者 FTP/SFTP 客户端实现感兴趣欢迎关注 DirBridge。项目地址GitHubhttps://github.com/shy117/DirBridge也欢迎提出建议、反馈问题或者一起交流桌面工具开发中的工程实践。总结DirBridge 是我正在开发的一个 Windows 远程文件管理工具目标是提供类似 Xftp 的本地与远程双栏文件管理体验。它目前已经完成了本地文件浏览、FTP/SFTP 远程目录浏览、站点配置、多远程会话、上传下载、拖拽传输、传输队列和目录聚合进度等基础能力。后续我会继续围绕稳定性、易用性和真实场景体验进行迭代。如果你也在做 C/Qt 桌面项目或者对远程文件管理工具的实现感兴趣欢迎关注这个项目。