1. 从一个真实需求说起为什么Java程序需要直接读共享文件夹很多做企业级应用开发的朋友都遇到过这类场景财务部门在内部文件服务器上放了一个共享目录每天有专人往里丢对账单、发票扫描件或者报表文件业务系统需要定时把这些文件抓过来做解析、入库、归档。文件服务器用的是常见的SMB/CIFS共享协议Windows环境下映射成网络驱动器就能直接访问但Java程序跑在Linux服务器上没有图形界面也没法映射网络驱动器这时候就得靠代码直接通过SMB协议去读写远程共享目录。这个需求听起来简单实际落地时会踩到不少坑认证方式选NTLM还是Kerberos、SMB1和SMB2/SMB3的兼容性、中文文件名乱码、大文件传输超时、连接池复用、共享目录权限不足等等。我前后在几个项目里都处理过这类问题从最早用JCIFS踩了一堆坑到后来换成SMBJ中间积累了一些经验这里系统性地梳理一遍希望能帮到正在做类似需求的同行。本文适合有一定Java基础、需要在服务端程序里访问远程共享目录的开发者。不管你是要做文件同步、批量导入、还是定时抓取核心思路是相通的。我会从协议选型讲到代码实现再到实际部署中那些文档里不会写的细节尽量把每个为什么都讲清楚。2. SMB协议与Java生态的库选型JCIFS还是SMBJ2.1 SMB协议版本演进带来的兼容性问题SMBServer Message Block协议是Windows网络文件共享的核心协议经历了SMB1、SMB2、SMB3几个大版本。SMB1是上世纪80年代的设计性能差、安全性弱微软从Windows Vista开始逐步弱化到Windows Server 2019之后默认禁用。SMB2从Vista/2008开始引入SMB3从Windows 8/2012开始增加了加密、多通道等特性。这个版本差异对Java开发者意味着什么如果你用的库只支持SMB1而目标服务器已经禁用了SMB1那连接会直接失败报错信息往往还很含糊比如Logon failure或者Connection refused排查起来很费劲。所以选库的第一原则是必须支持SMB2/SMB3。2.2 JCIFS与SMBJ的对比Java生态里访问SMB共享主要有两个库老牌的JCIFS和较新的SMBJ。对比项JCIFSSMBJ维护状态基本停止更新2016年后活跃维护SMB协议支持仅SMB1SMB2、SMB3认证方式NTLMNTLM、KerberosAPI风格较繁琐简洁现代大文件支持一般良好依赖无额外依赖需要SLF4JJCIFS最大的问题是只支持SMB1在新版Windows服务器上基本没法用。我早期项目用JCIFS后来服务器升级后全部迁移到SMBJ迁移过程虽然有些API要改但整体值得。SMBJ的API设计更符合现代Java习惯支持try-with-resources异常体系也更清晰。提示如果你的目标服务器是Windows Server 2016及以上或者Linux上的Samba 4.x强烈建议直接用SMBJ不要碰JCIFS。2.3 Maven依赖与版本选择SMBJ的依赖很简单在pom.xml里加dependency groupIdcom.hierynomus/groupId artifactIdsmbj/artifactId version0.13.0/version /dependency版本选择上0.13.0是相对稳定的版本修复了早期版本的一些连接泄漏问题。注意SMBJ依赖SLF4J做日志如果你的项目还没引入日志实现需要补一个比如logback或log4j2否则启动时会看到SLF4J的警告。另外SMBJ底层用了BouncyCastle做加密相关处理某些版本会传递依赖进来如果项目里有安全扫描要求可能需要显式排除或升级BouncyCastle版本。这个细节在做安全合规的项目里容易被忽略等到扫描报告出来才发现。3. 用SMBJ读取共享目录的完整代码实现3.1 建立连接与认证的核心逻辑先看最基础的连接代码。SMBJ的连接建立涉及几个关键对象SMBClient、Connection、Session、DiskShare。层级关系是Client管理连接Connection代表到服务器的TCP连接Session代表认证后的会话DiskShare代表某个共享目录。import com.hierynomus.smbj.SMBClient; import com.hierynomus.smbj.auth.AuthenticationContext; import com.hierynomus.smbj.connection.Connection; import com.hierynomus.smbj.session.Session; import com.hierynomus.smbj.share.DiskShare; public class SmbReader { public static void main(String[] args) throws Exception { SMBClient client new SMBClient(); try (Connection connection client.connect(192.168.1.100)) { AuthenticationContext ac new AuthenticationContext( username, password.toCharArray(), DOMAIN); Session session connection.authenticate(ac); try (DiskShare share (DiskShare) session.connectShare(shared)) { // 后续操作 } } } }这里有几个点值得展开。AuthenticationContext的第三个参数是域如果是工作组环境非域控可以传null或者空字符串。我遇到过传空字符串在某些Samba服务器上认证失败的情况改成null就好了这个差异跟服务器实现有关建议两种都试一下。connectShare返回的是Share接口需要强转成DiskShare才能做文件操作。如果共享名不存在或者没权限这里会抛异常异常信息里通常包含具体原因比如STATUS_ACCESS_DENIED或STATUS_BAD_NETWORK_NAME。3.2 遍历目录与文件过滤拿到DiskShare之后遍历目录用list方法import com.hierynomus.msfscc.fileinformation.FileIdBothDirectoryInformation; for (FileIdBothDirectoryInformation info : share.list(data)) { String fileName info.getFileName(); if (..equals(fileName) || ...equals(fileName)) { continue; } long size info.getEndOfFile(); System.out.println(fileName - size bytes); }注意list返回的结果里包含.和..两个特殊条目必须过滤掉否则后续处理会出错。这个坑我第一次用的时候踩过遍历时把.当成文件去读直接报错。文件过滤通常按扩展名或修改时间。SMBJ的FileIdBothDirectoryInformation提供了getLastWriteTime()方法返回的是FileTime对象可以转成Java的Instant或Date。按时间过滤时要注意时区问题服务器返回的是UTC时间本地比较时要统一时区否则会出现明明刚放进去的文件却过滤掉了这种诡异现象。3.3 读取文件内容的两种方式读取文件内容有两种方式一次性读入内存和流式读取。小文件几MB以内可以直接读import com.hierynomus.smbj.share.File; import java.io.InputStream; try (File file share.openFile(data/report.csv, EnumSet.of(AccessMask.GENERIC_READ), null, SMB2ShareAccess.ALL, SMB2CreateDisposition.FILE_OPEN, null)) { try (InputStream is file.getInputStream()) { byte[] content is.readAllBytes(); // 处理content } }大文件必须用流式读取避免OOM。getInputStream()返回的流支持标准的read操作可以配合BufferedInputStream和缓冲区循环读取。我处理过几百MB的日志文件用流式读取配合8KB缓冲区内存占用稳定在几MB。openFile的参数比较多AccessMask.GENERIC_READ表示只读SMB2ShareAccess.ALL表示允许其他进程同时访问SMB2CreateDisposition.FILE_OPEN表示文件必须已存在。如果文件不存在会抛STATUS_OBJECT_NAME_NOT_FOUND异常需要捕获处理。注意读取完一定要关闭流和File对象用try-with-resources是最稳妥的方式。我见过因为没关流导致连接池耗尽、后续请求全部超时的案例排查了大半天才发现是资源泄漏。4. 实际部署中那些文档不会告诉你的坑4.1 中文文件名乱码的根因与解决中文文件名乱码是SMB访问里最常见的问题之一。根本原因是SMB协议在传输文件名时用的字符编码跟Java默认编码不一致。SMBJ内部用的是UTF-16理论上不会有问题但实际中如果服务器端配置了非UTF-8的编码或者客户端JVM的file.encoding不是UTF-8就可能出现乱码。解决办法分两步第一确保JVM启动参数加上-Dfile.encodingUTF-8第二如果还是乱码检查服务器端的Samba配置unix charset和dos charset要设置正确。Windows服务器一般没这个问题主要是Linux上的Samba。我遇到过一次特殊情况文件名里包含特殊符号比如#、在SMBJ里能正常列出但用openFile打开时路径解析出错。后来发现是路径拼接时没有做转义SMBJ对路径里的特殊字符处理跟本地文件系统不一样需要用share.openFile时传入正确的相对路径不要自己拼接绝对路径。4.2 连接超时与重试策略网络共享的稳定性远不如本地磁盘连接超时是家常便饭。SMBJ默认的连接超时是30秒读超时也是30秒在生产环境里往往不够用。可以通过SMBClient的配置调整SMBClient client new SMBClient( SmbConfig.builder() .withTimeout(60, TimeUnit.SECONDS) .withSoTimeout(120, TimeUnit.SECONDS) .build());withTimeout是连接超时withSoTimeout是socket读超时。大文件传输时读超时要设大一些否则传到一半就断了。重试策略上我建议对连接建立和文件读取分别做重试。连接建立失败通常是网络抖动或服务器临时不可用重试2-3次基本能恢复文件读取失败可能是文件被占用或权限变化重试前最好先重新建立连接。重试间隔用指数退避比如1秒、2秒、4秒避免短时间内大量重试把服务器打挂。4.3 连接复用与性能优化每次操作都新建连接的开销很大SMB握手、认证、建立会话加起来可能要几百毫秒。如果程序需要频繁访问共享目录必须做连接复用。SMBJ的SMBClient是线程安全的可以全局共享一个实例。但Connection和Session不是线程安全的多线程环境下需要每个线程独立建立Session或者用连接池。我一般的做法是全局一个SMBClient每个线程用自己的Connection和Session用完关闭。如果并发量不大也可以用一个Session加同步锁但性能会受影响。对于批量读取场景还有一个优化点尽量用share.list一次性列出目录然后在内存里过滤而不是对每个文件单独调用share.fileExists。后者每次都是一次网络往返文件多了性能急剧下降。我做过对比1000个文件的目录一次性list加内存过滤比逐个检查快几十倍。5. 从读取到写入共享目录的完整操作能力5.1 写入文件与目录创建读取之外写入也是常见需求。写入用share.openFile配合AccessMask.GENERIC_WRITE和SMB2CreateDisposition.FILE_OVERWRITE_IFtry (File file share.openFile(output/result.txt, EnumSet.of(AccessMask.GENERIC_WRITE), null, SMB2ShareAccess.ALL, SMB2CreateDisposition.FILE_OVERWRITE_IF, null)) { try (OutputStream os file.getOutputStream()) { os.write(hello smb.getBytes(StandardCharsets.UTF_8)); } }FILE_OVERWRITE_IF表示存在就覆盖不存在就创建。如果要追加内容用FILE_OPEN_IF配合AccessMask.GENERIC_WRITE然后通过file.getOutputStream()写入时会从当前位置追加但要注意SMBJ的追加语义跟本地文件流不完全一样稳妥的做法是先读出来再整体写回或者用FILE_OPEN_IF打开后手动seek到末尾。创建目录用share.mkdir(newdir)如果目录已存在会抛异常需要先判断share.folderExists(newdir)。删除用share.rm和share.rmdir删除非空目录会失败需要递归删除。5.2 文件移动、重命名与属性读取文件移动和重命名用share.rename或share.move。rename是在同一目录内改名move可以跨目录。这两个操作在SMB协议里都是原子性的比复制删除可靠得多。读取文件属性大小、修改时间、创建时间通过share.getFileInformation(path)返回的FileAllInformation包含完整属性。注意修改时间返回的是UTC展示给用户时要转成本地时区。我见过因为没转时区导致文件时间显示差8小时的bug用户以为文件没更新其实是时区问题。5.3 权限与访问控制的实际处理共享目录的权限分两层共享级别权限和文件系统级别权限。SMBJ连接时用的是账号的权限如果账号对某个子目录没权限list会抛STATUS_ACCESS_DENIED。处理方式是在遍历时对每个子目录做try-catch跳过无权限的目录而不是让整个遍历失败。for (FileIdBothDirectoryInformation info : share.list(data)) { if (info.getFileAttributes().isDirectory()) { try { // 递归处理子目录 } catch (SMBApiException e) { if (e.getStatus() Status.STATUS_ACCESS_DENIED) { log.warn(跳过无权限目录: {}, info.getFileName()); continue; } throw e; } } }这种跳过无权限的策略在实际项目中很实用因为共享目录的权限往往由多个部门管理程序账号不可能对所有子目录都有权限。6. 踩坑排查实录一次连接失败的完整定位过程6.1 现象描述与初步判断有一次生产环境突然报错所有SMB操作全部失败异常信息是com.hierynomus.mssmb2.SMBApiException: STATUS_LOGON_FAILURE。这个错误字面意思是登录失败但账号密码明明没改过前一天还正常。初步判断有几个方向账号密码被改、账号被锁定、服务器策略变化、网络问题。先确认账号密码运维说没动过再试手动用同样的账号从Windows机器访问共享能正常打开说明账号本身没问题。6.2 逐步排查的完整链路既然账号没问题那问题就在程序侧或网络侧。排查步骤检查程序配置确认配置文件里的账号、密码、域没被误改。对比了git记录没变化。检查网络连通性从应用服务器telnet文件服务器的445端口通。检查SMB协议版本用smbclient -L命令Linux下测试发现能列出共享但认证时报错。查看服务器日志运维查了文件服务器的安全日志发现大量来自应用服务器IP的失败登录记录账号被临时锁定了。根因找到了程序里有个定时任务每隔几秒就新建一次连接而且密码配置里有个隐藏字符从某个文档复制时带进来的导致认证一直失败失败次数多了账号被锁定。锁定后即使密码正确也登录不了形成恶性循环。6.3 修复方案与预防措施修复分两步第一联系运维解锁账号第二修正配置里的隐藏字符并把连接改为复用模式避免频繁认证。预防措施上我后来加了几个改进连接失败时记录详细日志包括服务器返回的status code方便定位对认证失败做特殊处理连续失败3次就暂停一段时间避免触发账号锁定配置文件里的密码用专门的配置中心管理避免复制粘贴带入隐藏字符。这个案例的教训是SMB的错误信息往往很笼统STATUS_LOGON_FAILURE可能是密码错、账号锁、域错、协议不匹配等多种原因必须结合服务器端日志一起看才能快速定位。7. 生产环境下的稳定性设计建议7.1 连接池与资源管理生产环境不建议每次操作都新建连接。我的做法是封装一个SmbConnectionPool内部维护一组Connection用的时候借出用完归还。池的大小根据并发量定一般5-10个够用。借出时检查连接是否还活着可以用connection.isConnected()死了就重建。资源管理上所有实现了AutoCloseable的对象Connection、Session、DiskShare、File、InputStream都必须确保关闭。我习惯用try-with-resources层层嵌套虽然代码看起来有点深但能保证不泄漏。7.2 监控与告警指标SMB操作需要监控几个关键指标连接建立耗时、文件读取耗时、失败率、当前活跃连接数。这些指标可以用Micrometer或Dropwizard Metrics暴露出来接入Prometheus做告警。特别要监控的是认证失败次数这个指标异常升高往往意味着账号被锁或密码过期。还有连接超时次数升高说明网络或服务器有问题。我一般设置阈值认证失败5分钟内超过3次告警连接超时5分钟内超过10次告警。7.3 大文件传输的断点续传思路SMB协议本身支持随机读取所以断点续传是可行的。思路是记录已读取的字节数失败后重新打开文件用file.getInputStream()配合skip跳过已读部分继续读取。SMBJ的File对象有seek方法可以直接定位。不过断点续传的实现复杂度不低要考虑文件在传输过程中被修改的情况可以用修改时间做校验。如果业务允许更简单的方案是把大文件分片每片单独传输失败只重传失败的分片。8. 一些零散但实用的经验补充关于SMBJ的日志默认会输出不少DEBUG信息生产环境建议把com.hierynomus的日志级别调到WARN否则日志文件增长很快。但排查问题时临时调到DEBUG能看到协议交互的细节很有帮助。关于共享目录的路径分隔符SMBJ统一用正斜杠/不要用反斜杠\虽然后者在某些情况下也能工作但跨平台时容易出问题。关于文件锁如果共享目录里的文件正在被Windows用户打开编辑SMBJ读取时可能报STATUS_SHARING_VIOLATION。处理方式是捕获这个异常等待几秒后重试。如果文件是Excel正在编辑可能一直锁着需要跟业务方约定好文件写入完成的标志比如写完后改名或生成一个.done文件。关于性能SMB协议的网络往返是主要瓶颈。批量操作时尽量合并请求比如用share.list一次列出而不是逐个fileExists。如果要做大量小文件传输可以考虑先打包成zip再传能显著减少往返次数。最后说一个我个人的习惯所有SMB操作都包一层自己的工具类把异常转换成业务异常把重试、日志、监控都封装在里面。这样业务代码只需要调用smbUtil.readFile(path)不用关心底层的连接管理和异常处理。这个封装在项目初期多花点时间后期维护会轻松很多。
