简介Devart SecureBridge v11.0.1 Professional 控件包专为Delphi与CBuilder开发者设计聚焦SSH/SSL加密通信、身份验证与授权防护适用于需要安全网络传输的桌面及服务器应用开发。压缩包共938个文件约2.86MB内含153个PAS源文件、123个INC头文件、86个DPK工程文件及DFM窗体资源便于在IDE中直接编译安装同时提供Source、Demos、Include、Lib等目录分别对应组件源码、示例程序、类型声明和库文件配合Readme系列文档与安装说明图片开发者可快速理解集成步骤。目前已有32人学习浏览适合具备Delphi基础、希望为项目添加安全通信能力的开发者。整体来看这份资源既包含完整组件实现与调用范例又保留工程配置、历史更新记录及许可协议能为实际开发中的加密通道搭建、证书管理、身份校验和防未授权访问提供直接参考是构建安全网络应用的实用工具包。1. 为什么Delphi 13.1要单独装一套SecureBridge控件做 Delphi 桌面或 FMX 项目的人迟早会遇到一个尴尬业务要求连 SSH 服务器、走 SFTP 拉文件或者给 TCP 客户端加一层 SSL而 VCL 自带组件里没有能直接拖出来用的成品。标题里的 Devart SecureBridge v11.0.1 Professional就是专门补这个缺口的第三方控件包。它把 SSH2、SFTP、SSL/TLS 这几个协议封装成可设计期的组件你在 Delphi 13.1 中装好之后不需要自己维护 OpenSSL API 或加密细节只需要拖组件、填主机名、写业务逻辑就能把安全通信链路跑起来。这篇文章的读者是准备在 Delphi 13.1 环境里集成 SecureBridge、或者从老版本 Delphi 迁移上来的从业者。新手可以直接照着第三章和第四章做最小可用实例老手可以重点看第五章的避坑清单和第六章的验证技巧。我会按“组件是什么、怎么装、怎么用、出问题怎么查”的顺序讲所有路径和属性名都基于常见的 SecureBridge 11.x 用法你在自己的环境里遇到差异时以实际安装到 IDE 里的版本为准。2. 拆开SecureBridge v11.0.1专业包组件清单与选型逻辑拿到一个名为“Delphi 13.1控件之Devart SecureBridge v11.0.1 Professional.7z”的压缩包第一件事不是急着解压而是想清楚里面大概放了什么、你的项目要用其中的哪些模块。SecureBridge 虽然被通称为“控件”但它并不是一个组件而是一组安全通信组件。我见过不少同事一上来就把整个包全部编译一遍最后组件面板多出一堆用不上的图标自己却不知道哪一个才是 SFTP。先记住一个基本分工SSH 层负责建立加密连接和认证SFTP 层负责文件操作SSL 层负责给普通 TCP 通信加 TLS。三者可以独立存在也可以组合。下面把常见的几个类逐个讲清楚。2.1 核心组件TScSSH、TScSFTP、TScSSL 谁管哪一段最常见的组件是 TScSSH。它是一个 SSH2 客户端负责连接远程 SSH 服务器、交换密钥、完成用户认证并维持底层通道。如果你只是想在 Delphi 里执行远程命令比如登录 Linux 服务器跑一个 shell 脚本TScSSH 是最底层的主干它的 HostName、Port、UserName、Password 或 KeyStorage 属性决定它连到哪、用谁的身份连。连接成功后TScSSH 会处于 Active 状态之后才能干实际的活儿。TScSFTP 是建立在 SSH 之上的 SFTP 客户端。SFTP 和 FTP 完全不同它走的是 SSH 的 channel不是传统的 21 端口也不需要额外开启数据连接。TScSFTP 负责列目录、上传、下载、删除、重命名这类文件操作。你在设计期看到的典型属性是字符集、超时、重试次数和父级 SSH 连接。它在界面上通常表现为“必须挂在一个已连接的 SSH 通道上”的形式所以业务代码里的顺序一定是“先连 TScSSH再通过 TScSFTP 操作文件”。TScSSL 则解决另一类需求客户端与服务器之间跑的是标准 TCP 协议但需要加 SSL/TLS 加密。比如设备通信、工业协议上传、对接某个 HTTP API你可以在套接字之上包一层 TScSSL 通道让流量变成 TLS。它适合的场景更偏向传统 SSL/TLS而不是 SSH 体系。除了这三个经常一起出现的还有 TScSSHChannel 和 TScSshExec。前者表示一条独立的 SSH 会话通道可以用来承载多个并发流后者用于在远程主机上执行命令并读取输出。如果你的业务只是“远程跑命令”加“收文件”那就是 TScSSH TScSshExec TScSFTP 三件套。下面这张表是我选型时常用的对照组件英文定位常见属性/方法适合场景TScSSHSSH2 客户端HostName/Port/UserName/Connect/Disconnect建立 SSH 连接、维持通道TScSFTPSFTP 客户端父级 SSH 连接、ChangeDir/Get/Set文件传输与远端文件管理TScSSLSSL/TLS 客户端Certificates/ValidateServerCert/Start给自定义 TCP 协议加 TLSTScSshExec远程命令执行CommandText/Execute/Output在远程主机跑命令取输出TScSSHChannelSSH 子通道ChannelType/Open/Close复用同一连接做并发会话2.2 选型SSH和SSL不是一选一很多新手把 SSH 和 SSL 当成同一种东西都是加密都能安全传输。实际上它们面对的是不同应用层协议。SSH 是一个从会话层做加密的完整协议常见用法是替代 telnet、执行命令、传文件而 SSL/TLS 工作在 TCP 之上为任意应用层协议提供加密、身份认证和完整性校验。SecureBridge 把两者都封装了但你在自己的业务里要选对入口。我一般会按三个问题来做选型。第一服务端是 Unix/Linux 机器已经有 SSH 服务且需要连续执行命令、通过 SFTP 拉取日志和文件那直接用 SSH 体系无需额外搭建服务。第二你的程序要连接的是某个云服务的 API目标地址是 HTTPS且协议是基于 TCP 的自定义数据那该走 TScSSL因为它能直接做 TCP 客户端 TLS/SSL。第三你需要访问的是数据库、消息队列这类端口服务端只提供了 TLS 加密、没有 SSH 服务那还是选 SSL。选错之后最常见的现象是在 SecureBridge 里用 TScSSH 去连一个 443 端口结果服务器根本不回应 SSH banner连接会一直在握手阶段超时。选 SFTP 时还有一个容易混淆的点SFTP 和 FTPS 不是一回事。FTPS 是 FTP over SSL走 21 端口、有控制连接和数据连接SFTP 走 SSH 的 22 端口只有一条加密连接做所有文件操作。SecureBridge 这两类都支持但如果你把向 FTP 服务器用的参数填给 SFTP比如把端口写成 21TScSFTP 连接时会立刻失败因为 SSH 服务器不会在 21 端口返回 SSH 版本标识。2.3 版本适配从XE到Delphi 13.1包里的版本号为什么重要SecureBridge 是老牌商业控件支持过不同时期的 Delphi 版本。标题里写“Delphi 13.1”说明这个包主要面向较新的 IDE 环境。老代码升上来时最容易出问题的不是业务逻辑而是包的编译环境。在 Delphi 12 之前IDE 内部有一套平台相关的包编译规则控件包的.dproj会保存编译参数从老版本直接打开新版本的包时IDE 往往会提示升级或重新编译如果包源码里含有针对旧 RTL 的条件编译分支新版本可能会触发部分代码不兼容。我见过有人从 xe10.3 rio 时代就用 SecureBridge当时安装的版本是 9.x 或 10.x。升到 Delphi 13.1 之后他们直接复制了旧项目的.dcu目录而不重新编译结果是能打开设计器但一编译就提示“F2046: File not found”或“duplicate unit”之类的错误。原因很简单DCU 是有版本绑定的Delphi 编译器不会混用不同版本的元数据。解决办法是把 SecureBridge 源码目录和输出目录加进 Library Path然后重新编译一次整个包不要用旧 DCU 去糊弄。版本号还有一个值得注意的点v11.0.1 是 SecureBridge 的产品版本它内部可能同时提供 VCL 和 FMX 两个分支。FMX 工程用的单元名或条件编译可能与 VCL 不同。如果你用的是 Delphi 13.1 的 FMX 框架不要在 VCL 设计期包里找跨平台支持通常要另外打开带 FMX 标识的包进行安装。我的建议是安装前先列一下包根目录找到LIB\Win32、LIB\Win64、LIB\FMX这类命名再决定把哪一层加进编译路径。3. 把SecureBridge装进Delphi 13.1从解压7z到组件面板出现安装流程没有太多玄学核心是三步把 7z 解压到固定目录、给 IDE 加 Library Path、编译并安装设计期包。每一步漏了都会在后续编译期给出莫名其妙的错误。下面是我通常的做法。3.1 解压与目录规划别把控件丢进Program Files下载下来的文件名是.7z说明压缩比高解压后可能需要保持长路径。我建议先单独建立一个纯英文目录例如D:\Components\Devart\SecureBridge\不要放进C:\Program Files因为那个目录下 Delphi 编译时经常遇到目录权限和空格问题。用 7-Zip 解压7z x D:\Downloads\Delphi 13.1控件之Devart SecureBridge v11.0.1 Professional.7z -oD:\Components\Devart\SecureBridge -y这行命令的x表示保留压缩包里的目录结构-o后面是输出目录-y表示覆盖已存在文件。参数注意点-o后面直接跟路径中间不要加空格路径如果包含空格建议把整个-o参数用引号包起来。输出之后检查根目录下是否至少有一层Source或Lib目录这决定了后续的 Library Path 怎么填。解压完成后不要急着双击任何安装脚本。先看一眼目录清单重点关注有没有.dpk或.dproj文件、有没有Win32/Win64/FMX子目录。这个包既然写的是 Professional通常包含全套源码或至少运行时单元如果是只有 DCU 的版本后续就无法修改底层代码排查问题会有点黑匣子感。3.2 添加Library Path让IDE找得到DCU和设计期代码在 Delphi 13.1 中Library Path 是查找单元的最重要路径。你要把两类目录加进去一是源码目录也就是.pas文件所在的位置二是编译输出目录也就是.dcu最终生成的位置。添加方式是在 IDE 菜单Tools Options Language Delphi Library里操作同时在Platform下拉框分别修改 Win32、Win64 以及你实际使用的目标平台。这里给一个可复现的最小批处理用于把路径设置成环境变量方便 IDE 和命令行工具同时引用echo off set SB_ROOTD:\Components\Devart\SecureBridge set SB_SOURCE%SB_ROOT%\Source set SB_OUT%SB_ROOT%\Lib\Win64\Release echo SecureBridge root: %SB_ROOT% echo Source path : %SB_SOURCE% echo DCU output : %SB_OUT%这个脚本本身不写注册表只是定义变量。实际使用中我会把%SB_SOURCE%加进 IDE 的 Library Path把%SB_OUT%作为包工程的输出路径。如果你还要跑命令行编译可以在rsvars.bat之后调用同一个环境变量这样编译脚本也能引用统一路径。添加路径时有一个容易被忽略的参数Search path和Browsing path的顺序会影响编译速度但不会影响正确性。如果你有多版本 SecureBridge 同时存在必须把当前版本放最前面否则 IDE 会优先命中旧版本的单元。3.3 编译设计期包并Install组件面板上出现彩色图标设计期包通常是一个.dpk文件名字里会带Design、Dsn或RS字样。并不存在一个固定的文件名需要你在解压目录中自己找。在 Delphi 13.1 中我一般这样操作在Project Manager面板里右键选择Add existing project定位到刚解压路径中的设计期包确认包工程的目标平台与当前项目一致比如 Win32 还是 Win64编译设计期包成功后包名会出现在Installed packages列表如果同一包同时提供运行时包和设计期包先编译运行时包再编译设计期包顺序颠倒会导致“Cannot load package: module not found”一类的错误。如果这步编译报错不要怀疑是 SecureBridge 坏了。绝大多数原因是 IDE 的 Library Path 里没有加入源码目录导致编译.dpk时找不到ScSSH.pas等单元。此时直接看错误信息里的文件名再回到 3.2 补路径反复迭代即可。安装结束后打开一个新 Delphi 工程Tool palette里应该出现以TSc打头的组件。随便拖一个TScSSH到窗体能拖出来、属性编辑器里能看到HostName、Port说明设计期包安装成功。若拖不出来往往是安装过但 IDE 缓存未刷新重启 IDE 后再试。如果你以后要在 CI 上自动构建就不能依赖 IDE 手工安装包。常见做法是调用 MSBuild 直接编译包的 dprojcall %ProgramFiles%\Embarcadero\RAD Studio\13.1\bin\rsvars.bat msbuild D:\Components\Devart\SecureBridge\packages\SecureBridge_R.dproj /t:Build /p:ConfigRelease /p:PlatformWin64参数说明rsvars.bat是 RAD Studio 提供给命令行的环境变量导入脚本/t:Build表示执行编译/p:ConfigRelease选择 Release 配置/p:PlatformWin64指定目标平台。如果包内有条件编译标签比如{$IFDEF DELPHI13_1}需要保证当前编译工具版本能识别否则会跳过部分单元。这里要很注意不同版本包的 dproj 文件名不同上面的示例命名需要你用dir *.dproj替换成真实文件名。Win32 和 Win64 的 DCU 必须分开编译不能指望一份输出通吃。提示设计期包安装成功只代表你能拖组件了。真正编译运行时程序时还需要把运行时包的输出目录加入 Library Path或直接在工程里引用运行时包。很多新手在这里忽略导致设计期能拖组件、运行期一编译就报找不到 DCU 的错误。4. 用SecureBridge写一个最小的SFTP客户端关键属性与事件安装完成后的第一步是设计一个最小可运行的 SFTP 客户端。这个示例满足“连上服务器、列出目录、上传一个文件、下载一个文件”四个动作。代码我放在 VCL 窗体的按钮事件里方便你直接粘贴到 Delphi 13.1 工程中。4.1 先建一个可用的SSH通道在窗体上放TScSSH组件名保持默认ScSSH1。创建连接前设置目标主机、端口、用户名和认证信息ScSSH1.HostName : sftp.example.com; ScSSH1.Port : 22; ScSSH1.UserName : delphi_app; ScSSH1.AuthMethods : [amPassword, amPublicKey]; ScSSH1.Password : your-password; try ScSSH1.Connect; except on E: EScSecureBridgeError do ShowMessage(连接失败: E.Message); end;代码说明AuthMethods指定按什么顺序尝试认证。amPassword对应密码amPublicKey对应密钥文件如果两个都列出客户端会先尝试第一个可用的方法。Password是明文属性只适合测试环境生产环境建议用KeyStorage加载私钥避免明文密码出现在反编译结果里。Connect是阻塞方法在事件里直接调用时会卡住 UI如果服务器连接慢会表现为界面无响应。这里还有一个容易踩的细节SecureBridge 的连接是基于 socket 的Port类型是Word如果填了字符串会直接编译不过。官方文档中 SSH 默认端口是 22但不少企业服务器改过端口一定要从配置中心读取不要写死在代码里。4.2 用TScSFTP列目录和传输文件连接成功之后把ScSFTP1绑定到这条 SSH 连接上。SecureBridge 的 TScSFTP 一般有一个用于指定父级 SSH 连接的属性安装到你的版本后属性名可能是SSHConnection或ParentSSH我习惯在设计期直接在下拉框里选择。然后写按钮事件ScSFTP1.BeginUpdate; // 批量操作前挂起通知降低刷新开销 try ScSFTP1.ChangeDir(/home/delphi_app/inbox); ScSFTP1.GetFileList(ScSFTP1.Directory, *.csv, true); ScSFTP1.UploadFile(D:\reports\report_2025.csv, /home/delphi_app/inbox/report_2025.csv); ScSFTP1.DownloadFile(/home/delphi_app/outbox/data.zip, D:\downloads\data.zip); finally ScSFTP1.EndUpdate; end;逻辑说明BeginUpdate/EndUpdate是控件常用的批量操作抑制方法能够减少多次操作时的刷新开销ChangeDir切换远端目录GetFileList参数中第一个是目录名第二个是通配符第三个true表示是否递归子目录。UploadFile第一个参数是本地路径第二个是远端路径DownloadFile方向相反。如果GetFileList之后没有刷新 UI检查EndUpdate是否与BeginUpdate成对出现。我在项目中见过一次异常发生时更新没有恢复后续所有文件列表都是空的。GetFileList返回后文件对象放在ScSFTP1.FileList里。你可以遍历它做批量处理但不要直接释放 FileList 里的对象因为它们由组件内部管理擅自释放会造成后续访问内存错误。4.3 关键事件认证、证书校验、进度回调SecureBridge 不是把 SSH 完全做成黑匣子它把几个关键节点暴露成了事件。最常见的是证书校验事件和传输进度事件。证书校验的事件签名里会有一个Accept参数默认是 False。如果你连的是自签名服务器不处理这个事件连接会在校验阶段被强制断开procedure TForm1.ScSSH1ValidateServerCert(Sender: TObject; const AInfo: TScCertificateInfo; var Accept: Boolean); begin if AInfo.Fingerprint AA:BB:CC:DD:EE:FF:00:11:22:33 then Accept : True else Accept : False; end;这个例子把指纹做成了白名单。AInfo.Fingerprint是服务器证书指纹你第一次连接时可以把它记录下来之后固定比对。不要直接Accept : True忽略证书校验否则中间人攻击时你的程序也会照常连接这是很多内部工具后来被审计指出来的挖坑点。生产环境至少校验证书链和指纹二选一。进度事件方面如果你想知道上传一个 100MB 文件完成了多少可以在上传进度事件里读取ABytesProceed和ABytesTotal更新一个 ProgressBar。但注意事件是在接收者线程里触发的VCL 下要用Synchronize或TThread.Queue包裹否则进度条会不定时崩。这一点和 Delphi 多线程的通用规则一样控件属性不能跨线程直接写。4.4 把耗时操作放进线程而不是阻塞主界面很多 Delphi 开发者把Connect、UploadFile直接放在按钮事件里小文件没问题一旦传输大文件或者连接缓慢整个窗口就卡住。我通常把完整的传输流程包在一个TThread子类里type TFileUploadThread class(TThread) private FHost: string; FUser: string; FPassword: string; FLocalFile: string; FRemoteFile: string; protected procedure Execute; override; end; procedure TFileUploadThread.Execute; var LocalSSH: TScSSH; LocalSFTP: TScSFTP; begin LocalSSH : TScSSH.Create(nil); try LocalSSH.HostName : FHost; LocalSSH.UserName : FUser; LocalSSH.Password : FPassword; LocalSSH.Connect; LocalSFTP : TScSFTP.Create(nil); try LocalSFTP.SSHConnection : LocalSSH; LocalSFTP.UploadFile(FLocalFile, FRemoteFile); finally LocalSFTP.Free; end; finally LocalSSH.Disconnect; LocalSSH.Free; end; end;这段代码的重点是SecureBridge 控件实例在线程内创建、使用和释放是最不容易踩线程坑的方式。不要从主线程把一个已经连好的TScSSH传给工作线程做上传很多“偶发假死”就是这么来的。TScSFTP的SSHConnection属性名在不同版可能略有差异但方向一致保证父连接在 SFTP 对象之前创建并且在线程结束时先释放 SFTP 再断开 SSH。另一个血泪经验是在线程里调用控件事件时事件里的Synchronize可能在主线程空闲前等待退出线程前要主动Disconnect否则 socket 资源会残留。具体表现为进程退出后句柄数缓慢上涨。解决方法是给线程体加Terminated检查在finally中确保断开。5. SecureBridge避坑清单安装失败、证书校验、事件不触发、路径中文、并发连接下面这些是我在实际项目中看过的 SecureBridge 相关翻车记录。每一条都是先描述现象再给原因和解法新手按顺序排除能省很多时间。5.1 现象安装后组件面板里没有 TSc* 图标这个问题最常见。原因分两半要么设计期包根本没编译成功要么编译成功了但 IDE 没有加载它。如果是前者打开包工程编译一次错误信息会提示缺少哪个单元多半是 Library Path 没指到源码目录如果是后者去Components Install Packages检查当前工程类型FMX 工程看不到 VCL 包VCL 工程看不到 FMX 包这是包工程目标平台和项目不匹配导致的。解决方式很简单在包工程上点Install或确认Runtime Packages列表里勾选了运行时包。初次安装后必须重启 IDEDelphi 对包缓存比较顽固不重启的话即使图标出现也可能拖不了。5.2 现象SFTP 连接报 “Connection closed” / “Bad file descriptor”这个报错经常出现在从 Delphi 12 升到 13.1 的项目中。原因通常不是 SecureBridge 本身坏了而是你打开了旧工程自带的.dproj里面记录的平台配置和当前工具版本不一致导致编译出的程序用了旧的 RTL 包。解决方法是先Project Clean然后删除生成的__history和Win32\Debug目录关闭 IDE 重开再重新编译。如果仍然报这个错检查Tools Options Environment Variables里是否有多个Path变量把新版本 RAD Studio 的bin放到最前面避免它加载旧版borlndmm.dll。5.3 现象TScSSL 一直握手失败服务端日志显示证书校验不通过SecureBridge 默认要求服务器提供客户端可验证的证书链。如果你使用企业内部自签名 CA必须把该 CA 证书放进ScSSL1.CertificateStore的信任列表或者处理OnValidateServerCert事件。代码里简单的做法是从CAChain参数中取出证书指纹并加入白名单但更稳的做法是在系统证书库里安装 CA然后让 SecureBridge 使用系统存储。我之前就在一个工控项目里踩过对接的设备只提供过期的自签名证书我直接忽略校验跑通了联调结果上线三个月后设备证书更换客户端完全连不上才知道应该把证书轮换机制设计进去。5.4 现象上传文件成功但下载文件名和内容在 Windows 下乱码SFTP 文件名默认使用 UTF-8而 Windows 缺少本地化处理的旧代码会把字节当成 ANSI 解析。SecureBridge 通常提供字符集相关的属性比如TScSFTP.Encoding或FileList.Name的转换开关。解决方式是显式设置ScSFTP1.Encoding : ecUTF8属性名以实际版本为准并且在本地保存文件时不要手工拼接路径改用SysUtils.TFileHelper或ExpandFileName。远程目录里中文文件名乱码多半是客户端 charset 没指定不要幻想自动识别服务器不会在 header 里告诉你编码。5.5 现象回调事件不触发上传不报错但进度条不动这可能是同步阻塞模式下的正常现象。SecureBridge 的同步方法执行期间会进入内部消息循环回调事件不一定按你预期频率触发如果你调用UploadFile后一直等待事件往往到最后才一次性触发。解决方法是改用异步模式或把进度刷新动作拆成定时器用Timer每 200ms 读取一次组件内部的传输计数。另一个可能原因是同一个TScSSH同时被多个线程调用事件被抢占表现为偶发不回调。这种情况只能把连接对象按线程隔离一个TScSSH实例只服务一个会话不能省。6. 验证SecureBridge通信链路的3个技巧抓包与自签名证书业务的真金白银压实到“能连”还不够还要能验证这条链路没有被人为降级或中间人介入。我习惯在联调阶段做三件事组件日志、协议抓包、证书校验验证。第一开启 SecureBridge 的日志接口。TScSSH 或 TScSSL 通常提供一个日志属性或回调事件例如LogFile或OnPacketEvent。我在测试时会把日志写到D:\Temp\sb_debug.log然后观察 SSH 握手和 SFTP 的关键消息。日志里能看到客户端发送的SSH_MSG_KEXINIT和服务器返回的 banner如果这里出现异常就不用花时间在上层排错。第二用 Wireshark 抓 22 端口或 443 端口包。抓包时在过滤器里写ssh或tls关注 ClientHello、ServerHello、ChangeCipherSpec。对纯 SSH 流量Wireshark 只能看到加密后的内容但至少能确认连接确实建立、没有退化到明文。对 TScSSL 封装的自定义 TCP 服务抓包更有效你能看到完整的 TLS 握手且能检查证书是否就是测试服务器那份。第三自签名证书验证。这个技巧最适合自己搭测试环境用openssl req -x509 -newkey rsa:2048 -nodes -keyout server.key -out server.crt -days 365生成临时证书然后在 SecureBridge 端强制校验指纹。第一次先接受打印Fingerprint再把该指纹写回白名单代码然后故意改证书再一次确认客户端拒绝连接。这个步骤能验证你的证书校验代码不是摆设。这三招做完SecureBridge 的链路基本就透明了。从 xe10.3 rio 时代一路走过来我在 SSH/SFTP 上最大的教训就是“能连通不自然等于安全”组件默认行为只是尽力而为真正的边界要自己检查。希望今天的记录能帮你在 Delphi 13.1 下把 SecureBridge 装明白、用顺手少踩几个我已经替你趟过的坑。本文还有配套的精品资源点击获取