NC附件本地保存与上传：生产级文件中转引擎实现

1. 项目概述：为什么“NC传输附件的本地文件保存和文件上传”是高频刚需场景

在某企业级协同平台的实际交付中，我连续参与了5个不同行业客户的系统集成项目，其中NC传输附件的本地文件保存和文件上传代码这个需求，几乎100%出现在二期深化阶段。它不是那种写完就扔的Demo功能，而是真正卡在业务流转咽喉处的“毛细血管级”能力——比如财务共享中心需要把扫描件自动落盘归档、工程监理系统要将现场照片同步至本地NAS再触发OCR识别、医疗影像平台需在离线环境下暂存DICOM文件后批量回传。这些场景共同指向一个核心矛盾：NC系统本身不提供标准的、可编程控制的附件落地路径，而业务又强烈要求文件必须可控、可审计、可追溯。

你可能已经试过NC自带的“附件管理器”，但很快会发现它像一个黑盒：文件存在数据库BLOB字段里，无法直接用脚本扫描、不能被第三方工具索引、备份恢复极慢、权限粒度粗到只能控制“有/无附件查看权”。而真实业务要的是——当用户在NC表单里点“上传合同扫描件”时，系统不仅要存进NC，还要同时：

• 自动按“部门_日期_单据号”规则生成本地路径（如D:\nc_attachments\finance\20240615\PO20240615001.pdf）；
• 保留原始文件名与扩展名（避免NC重命名导致后续解析失败）；
• 记录完整操作日志（谁、何时、从哪个单据、上传了什么文件、MD5校验值）；
• 支持断点续传（大文件上传中途断网不重来）；
• 兼容NC 6.5/7.0/7.2多个版本的API签名机制。

这正是本项目代码的价值锚点：它不是教你怎么点鼠标上传，而是给你一套可嵌入NC二次开发框架、可独立部署为微服务、可对接任何存储后端（本地磁盘/SMB共享/MinIO/阿里云OSS）的生产级文件中转引擎。关键词“NC传输附件”“本地文件保存”“文件上传代码”背后，实际是三个技术层的咬合：NC前端事件钩子（捕捉上传动作）、NC服务端中间件（解密/解包/路由）、跨系统文件协议桥接（HTTP/FTP/SMB）。接下来我会把这三层怎么拆、怎么焊、怎么测，掰开揉碎讲清楚。

2. 整体设计思路：为什么放弃NC原生附件，选择“双轨制”落地策略

2.1 核心矛盾倒逼架构重构

先说一个血泪教训：某制造企业曾坚持用NC原生附件存30万份设备图纸（平均8MB/张），结果半年后系统响应延迟从1.2秒飙升到17秒。DBA查出罪魁祸首是Oracle的LOB段争用——每次打开单据，NC都要从BLOB字段读取所有附件元数据，哪怕你只看一张图。这暴露了根本问题：NC的附件模型是“强耦合+弱管控”，而现代业务需要“松耦合+强治理”。

我们最终采用的“双轨制”方案（NC存元数据 + 本地存实体文件），不是为了炫技，而是基于四个刚性约束推导出的唯一解：

1. 合规性约束：等保2.0要求“重要业务数据须本地化存储并可独立审计”，NC数据库属于“应用系统层”，不符合“基础设施层”存储定义；
2. 性能约束：实测对比显示，100MB文件通过NC BLOB上传耗时≈本地磁盘直写+HTTP API通知NC元数据的2.3倍（因BLOB需分块加密+事务日志刷盘）；
3. 运维约束：客户IT部门明确拒绝开放NC数据库直接写权限，但允许在应用服务器上配置指定目录的读写权限；
4. 扩展约束：后续要接入AI合同审查服务，该服务要求文件以标准SMB路径提供，而非NC内部ID。

提示：所谓“双轨制”不是简单复制文件，而是建立元数据映射关系。例如NC单据IDPO20240615001在NC数据库中只存一条记录：{file_id: "f_9a3b", file_path: "D:\\nc_attachments\\po\\20240615\\PO20240615001.pdf", md5: "d41d8cd98f00b204e9800998ecf8427e"}，实体文件完全脱离NC数据库生命周期。

2.2 技术选型逻辑：为什么用Java Servlet而非NC插件或JavaScript

看到标题里“代码”二字，很多人第一反应是写个NC插件。但我在某能源集团项目踩过坑：NC插件运行在NC容器内，受其类加载器隔离，调用java.nio.file写本地磁盘时，路径解析会诡异变成C:\ncserver\bin\D:\nc_attachments\...（因为NC启动脚本里-Duser.dir=C:\ncserver\bin覆盖了JVM默认工作目录）。后来改用纯前端JS方案，又遇到浏览器沙箱限制——<input type="file">选中的文件路径在Chrome里永远是C:\fakepath\xxx.pdf，根本拿不到真实路径。

最终锁定Java Servlet + NC WebService回调组合，理由很实在：

• Servlet部署灵活：可独立打包成WAR丢进Tomcat（与NC共用同一台服务器），也可部署在专用文件服务节点，通过内网HTTP通信；
• 路径控制精准：ServletContext.getRealPath("/")能稳定获取Web应用根目录，配合配置文件里的attachment.base.path=D:/nc_attachments，彻底规避路径拼接风险；
• NC集成成熟：NC 7.0+已内置nc.itf.uap.rest.RestClient，调用自建Servlet的REST接口比调用自定义插件更稳定（插件热部署常引发NC容器类冲突）；
• 调试友好：Servlet日志可直接输出到catalina.out，而NC插件日志分散在nc.log和appserver.log里，排查文件写入失败时效率差3倍以上。

实测数据：在NC 7.2环境，Servlet方案平均上传耗时比NC原生附件低41%，大文件（>50MB）优势更明显（因支持分片上传，NC原生最大单次请求限制为32MB）。

2.3 安全边界设计：如何防止“本地文件保存”变成任意文件写入漏洞

这是所有类似方案的生死线。某政务系统曾因未校验文件名，被攻击者上传webshell.jsp到NC应用目录，导致整个OA沦陷。我们的防护是四层过滤：

1. 文件名净化层：用正则[^a-zA-Z0-9\u4e00-\u9fa5._-]替换所有非法字符，强制删除..、/、\等路径遍历符号；
2. 扩展名白名单层：仅允许.pdf,.docx,.xlsx,.jpg,.png,.zip等12种业务必需格式，且用Apache Tika库二次校验文件魔数（Magic Number），防“jpg伪装成jsp”；
3. 路径锁定层：所有文件必须写入预设基目录（如D:/nc_attachments），写入前调用Paths.get(basePath, generatedPath).toRealPath()验证是否仍在基目录内；
4. 权限隔离层：Windows下为nc_attachments目录设置ACL，仅tomcat_service用户有写权限，禁用继承；Linux下用chown tomcat:tomcat /opt/nc_attachments && chmod 750 /opt/nc_attachments。

注意：NC前端传来的文件名永远不可信！必须用服务端生成的UUID+时间戳重命名（如f_9a3b_20240615143022.pdf），原始文件名仅存入NC元数据表的original_name字段供业务查询。

3. 核心细节解析：本地保存与上传代码的7个关键实现点

3.1 文件接收：为什么用Apache Commons FileUpload而非Spring MultipartFile

NC前端调用Servlet时，发送的是标准multipart/form-data请求，但NC 6.5的HTTP客户端不支持Content-Disposition: form-data; name="file"; filename="xxx.pdf"里的filename*编码（RFC 5987），导致中文文件名乱码。Spring Boot的MultipartFile依赖Servlet 3.0+的request.getPart()，而NC 6.5内嵌的Jetty 8只支持Servlet 2.5。

我们退回Apache Commons FileUpload 1.5（兼容Servlet 2.4+），手动解析：

// Servlet doPost方法内 DiskFileItemFactory factory = new DiskFileItemFactory(); factory.setRepository(new File(System.getProperty("java.io.tmpdir"))); // 指定临时文件目录 ServletFileUpload upload = new ServletFileUpload(factory); upload.setHeaderEncoding("UTF-8"); // 关键！解决NC传中文名乱码 List<FileItem> items = upload.parseRequest(request); for (FileItem item : items) { if (!item.isFormField()) { String fileName = item.getName(); // 此时fileName已是正确中文 // 后续执行文件名净化、白名单校验... } }

实测效果：NC 6.5传采购合同_张三_20240615.pdf，服务端接收到的fileName为完整字符串，无乱码。而用Spring方案，getOriginalFilename()返回?????.pdf。

3.2 本地路径生成：业务规则驱动的动态目录树

客户要求按“部门_年月_单据类型”三级目录存储，但NC单据头信息里没有“部门”字段，只有pk_org（组织主键）。我们通过NC提供的OrgCache缓存获取组织全路径：

// 从NC请求参数中提取pk_org和billtype String pkOrg = request.getParameter("pk_org"); String billType = request.getParameter("billtype"); // 调用NC内部API（需引入nc-base.jar） OrgVO orgVo = OrgCache.getInstance().getOrgVO(pkOrg); String deptName = orgVo.getUnitname(); // 如"华东大区_财务部" // 生成目录：D:\nc_attachments\华东大区_财务部\202406\purchase_order String datePart = LocalDate.now().format(DateTimeFormatter.ofPattern("yyyyMM")); String basePath = "D:/nc_attachments"; String subPath = String.format("%s/%s/%s/%s", basePath, deptName.replaceAll("[^\\w\\u4e00-\u9fa5]", "_"), datePart, billType.toLowerCase().replace("_", "") ); File dir = new File(subPath); if (!dir.exists()) { dir.mkdirs(); // 确保目录存在 }

这个设计让运维人员能直接在文件服务器上按部门分类浏览，审计时用dir /s /b *.pdf命令5秒列出所有财务部PDF，比查NC数据库快10倍。

3.3 断点续传实现：基于文件MD5分片校验的轻量方案

NC用户常上传百兆级扫描件，网络波动导致重传痛苦。我们没用复杂的WebSocket长连接，而是用最朴素的HTTP分片：

• 前端JS将文件切为2MB每片，按file_id_part_001命名；
• Servlet接收每片时，计算该片MD5并与前端传来的part_md5比对；
• 所有分片存入临时目录D:/nc_attachments/tmp/，文件名含file_id；
• 最后一片上传完成后，触发合并：

// 合并逻辑（简化版） String fileId = "f_9a3b"; File tmpDir = new File("D:/nc_attachments/tmp/" + fileId); File[] parts = tmpDir.listFiles((dir, name) -> name.startsWith(fileId + "_part_")); Arrays.sort(parts, Comparator.comparing(File::getName)); // 按part_001, part_002排序 File targetFile = new File("D:/nc_attachments/.../f_9a3b_20240615.pdf"); try (RandomAccessFile raf = new RandomAccessFile(targetFile, "rw")) { for (File part : parts) { try (FileInputStream fis = new FileInputStream(part)) { byte[] buf = new byte[8192]; int len; while ((len = fis.read(buf)) != -1) { raf.write(buf, 0, len); } } } } // 合并后校验整文件MD5，与前端传的total_md5比对

实测：100MB文件在30%丢包率网络下，平均重传次数从12次降至1.3次（仅最后一片失败时重传）。

3.4 NC元数据写入：绕过NC事务的异步安全写法

直接在Servlet里调用NC的BDOPubService写数据库，会卡住HTTP线程。我们用@Async+消息队列解耦：

// Spring配置 @EnableAsync @Configuration public class AsyncConfig { @Bean(name = "taskExecutor") public Executor taskExecutor() { ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor(); executor.setCorePoolSize(5); // 避免并发写NC库锁表 executor.setMaxPoolSize(10); executor.setQueueCapacity(100); executor.setThreadNamePrefix("nc-meta-writer-"); return executor; } } // 异步写入方法 @Async("taskExecutor") public void saveNcMetadata(String fileId, String ncBillId, String originalName, String filePath) { try { // 获取NC数据库连接（通过NC提供的DataSource） DataSource ds = NcDataSourceFactory.getDataSource(); JdbcTemplate jt = new JdbcTemplate(ds); jt.update("INSERT INTO nc_attachment_meta (file_id, bill_id, original_name, file_path, create_time) VALUES (?, ?, ?, ?, ?)", fileId, ncBillId, originalName, filePath, new Date()); } catch (Exception e) { // 写入失败时，将任务写入Redis延时队列，5分钟后重试 redisTemplate.opsForList().rightPush("nc_meta_retry_queue", JSON.toJSONString(Map.of("fileId", fileId, "ncBillId", ncBillId))); } }

这样即使NC数据库瞬时不可用，文件已成功落盘，业务不中断，元数据最多延迟5分钟同步。

3.5 权限校验：NC用户身份与文件操作的强绑定

不能让A部门用户通过构造URL下载B部门文件。我们在Servlet里复用NC的LoginContext：

// 从NC请求头中提取sessionid String sessionId = request.getHeader("NC-SESSION-ID"); // 调用NC认证服务验证session LoginContext loginCtx = LoginContextFactory.getLoginContext(sessionId); if (loginCtx == null || !loginCtx.isValid()) { response.sendError(HttpServletResponse.SC_UNAUTHORIZED, "NC session expired"); return; } // 获取当前用户可访问的组织范围（NC多组织权限模型） String[] accessibleOrgs = loginCtx.getUser().getAccessibleOrgs(); // 从文件路径反推所属组织（如D:/nc_attachments/华东大区_财务部/...） String deptInPath = extractDeptFromPath(filePath); if (!Arrays.asList(accessibleOrgs).contains(deptInPath)) { response.sendError(HttpServletResponse.SC_FORBIDDEN, "No permission to access this department's files"); return; }

这套机制让文件服务器彻底成为NC权限体系的延伸，无需单独维护权限表。

3.6 日志审计：满足等保要求的全链路操作留痕

等保2.0要求“所有文件操作行为可追溯到具体操作人”。我们日志包含7个必填字段：

字段	示例	说明
timestamp	2024-06-15T14:30:22.123+0800	ISO8601带时区
operator_id	U_882345	NC用户主键
operator_name	张三	NC用户姓名
bill_id	PO20240615001	关联单据ID
file_id	f_9a3b	服务端生成文件ID
action	UPLOAD_SUCCESS	枚举值：UPLOAD_START/UPLOAD_SUCCESS/UPLOAD_FAIL/DOWNLOAD_START等
file_info	{"size":1048576,"md5":"d41d8cd9...","path":"D:/nc_attachments/..."}	JSON结构化详情

日志写入独立的nc_file_audit.log，每日滚动，保留180天。审计员用grep "UPLOAD_SUCCESS.*张三" nc_file_audit.log即可导出该员工所有上传记录。

3.7 错误处理：NC环境特有的3类致命异常应对

在NC服务器上跑代码，会遇到普通Java项目没有的坑：

1. NC类加载器冲突：当Servlet引用commons-lang3，而NC自身jar包里有老版本commons-lang，会报NoSuchMethodError。解决方案：在WEB-INF/web.xml中添加：

<context-param> <param-name>org.apache.catalina.loader.WebappClassLoader.delegate</param-name> <param-value>true</param-value> </context-param>

强制优先加载WEB-INF/lib下的jar。

2. NC数据库连接池耗尽：NC默认HikariCP最大连接数20，异步写元数据时并发超限。我们在application.properties中显式配置：

spring.datasource.hikari.maximum-pool-size=50 spring.datasource.hikari.connection-timeout=30000

3. NC JVM内存溢出：上传大文件时，DiskFileItemFactory的内存阈值默认10KB，超阈值即写入临时文件，但NC服务器临时目录空间不足。我们改为：

DiskFileItemFactory factory = new DiskFileItemFactory(); factory.setSizeThreshold(1024 * 1024); // 1MB内存阈值 factory.setRepository(new File("D:/nc_attachments/tmp")); // 指向有100GB空间的专用目录

4. 实操过程：从零部署到上线的完整步骤与避坑指南

4.1 环境准备：NC服务器上的5项必要检查

在动手写代码前，必须确认NC服务器状态，否则90%的问题都源于环境：

1. 确认NC版本与JDK匹配：

   • NC 6.5 → 要求JDK 1.6+（实测JDK 1.8兼容）；
   • NC 7.0/7.2 → 必须JDK 1.8+，且JAVA_HOME指向JDK而非JRE（NC启动脚本会检查bin/java.exe是否存在）；
   • 检查命令：echo %JAVA_HOME%（Windows）或echo $JAVA_HOME（Linux），然后%JAVA_HOME%\bin\java -version。

2. 验证NC数据库连接：
   NC安装目录下config\datasource.xml里有数据库配置，用相同参数测试连通性：

   # Windows下用SQLPlus测试（Oracle为例） sqlplus nc_user/nc_pass@//127.0.0.1:1521/orcl # 成功后执行：SELECT COUNT(*) FROM nc_attachment_meta; （确认表存在）

3. 检查磁盘空间与权限：

   • 目标目录D:/nc_attachments需有≥50GB空闲空间；
   • 右键目录→属性→安全→编辑→添加tomcat_service用户（Windows服务账户）→勾选“修改”“写入”；
   • Linux下执行：df -h /opt/nc_attachments && ls -ld /opt/nc_attachments。

4. 确认NC WebService已启用：
   访问http://nc-server:8080/nc/webService/，应返回NC的WebService WSDL描述页。若404，需在NC管理控制台→系统管理→基础配置→WebService服务中启用。

5. 备份NC配置文件：
   备份config\datasource.xml、config\log4j2.xml、webapps\nc\web-inf\web.xml，避免修改出错无法回滚。

实操心得：某电力项目因跳过第2步，发现NC数据库用的是达梦DM8，而我们的代码默认连Oracle，上线当天所有文件上传报ORA-00942错误（表不存在），紧急重写DAO层耗时6小时。务必先连通再编码！

4.2 代码部署：WAR包构建与Tomcat集成的3个关键配置

我们的Servlet打成WAR包，与NC共用同一Tomcat（NC 7.2默认用Tomcat 8.5）。部署步骤：

1. 修改pom.xml排除NC冲突依赖：

   <dependency> <groupId>com.sun.xml.bind</groupId> <artifactId>jaxb-impl</artifactId> <version>2.3.3</version> <exclusions> <exclusion> <groupId>javax.activation</groupId> <artifactId>activation</artifactId> </exclusion> </exclusions> </dependency> <!-- 排除原因：NC自带jaxb，版本冲突会导致XML解析失败 -->

2. web.xml中注册Servlet与Filter：

   <!-- 防止NC的Filter拦截我们的请求 --> <filter-mapping> <filter-name>NCFilter</filter-name> <url-pattern>/file/*</url-pattern> <dispatcher>REQUEST</dispatcher> <dispatcher>ERROR</dispatcher> <dispatcher>FORWARD</dispatcher> <dispatcher>INCLUDE</dispatcher> <dispatcher>ASYNC</dispatcher> </filter-mapping> <!-- 我们的Servlet映射 --> <servlet> <servlet-name>FileUploadServlet</servlet-name> <servlet-class>com.ncfile.FileUploadServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>FileUploadServlet</servlet-name> <url-pattern>/file/upload</url-pattern> </servlet-mapping>

3. Tomcatserver.xml增加NC专用Connector：

   <!-- 在<Engine>节点内添加 --> <Connector port="8081" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" maxPostSize="209715200" <!-- 200MB，支持大文件 --> maxSavePostSize="-1" <!-- 禁用POST数据缓存 --> URIEncoding="UTF-8"/>

   这样NC前端调用http://nc-server:8081/file/upload，不与NC主端口8080争抢资源。

4.3 NC前端集成：3行JS代码注入到NC表单

NC表单的附件上传按钮是标准HTML<input type="file">，我们通过NC的“自定义JS”功能注入：

1. 进入NC表单设计器→右键附件控件→属性→“自定义JS”；
2. 粘贴以下代码（适配NC 7.2）：

// 获取当前单据主键和组织ID var billId = this.getParent().getPkValue(); var pkOrg = this.getParent().getFieldValue("pk_org"); // 绑定文件选择事件 this.getElement().onchange = function(e) { var file = e.target.files[0]; if (!file) return; // 创建FormData var formData = new FormData(); formData.append("file", file); formData.append("bill_id", billId); formData.append("pk_org", pkOrg); formData.append("bill_type", "purchase_order"); // 根据表单类型硬编码 // 发送至我们的Servlet fetch("http://nc-server:8081/file/upload", { method: "POST", body: formData, headers: { "NC-SESSION-ID": top.window.ncSessionId // NC全局session } }) .then(res => res.json()) .then(data => { if (data.success) { alert("附件已保存至本地，NC元数据同步完成"); } else { alert("上传失败：" + data.message); } }); };

注意：NC 6.5需用top.window.NC_SESSION_ID，NC 7.2用top.window.ncSessionId，大小写敏感！某汽车项目因此调试2天。

4.4 上线验证：5个必测场景与预期结果

部署后，必须按顺序执行以下验证，缺一不可：

测试场景	操作步骤	预期结果	常见问题
1. 中文文件名上传	上传采购合同_张三_20240615.pdf	本地路径为D:\nc_attachments\..._张三_20240615.pdf，NC元数据表original_name字段值正确	若乱码，检查Servlet的upload.setHeaderEncoding("UTF-8")是否生效
2. 超大文件分片	上传200MB ZIP文件	临时目录出现f_xxx_part_001到f_xxx_part_100，合并后MD5与源文件一致	若合并失败，检查RandomAccessFile写入权限及磁盘空间
3. 权限越界访问	A部门用户构造URL访问B部门文件路径	返回HTTP 403 Forbidden，日志记录No permission to access...	若能访问，检查extractDeptFromPath()逻辑是否准确提取部门名
4. NC数据库宕机	停掉NC数据库服务，上传文件	文件仍成功落盘，日志记录nc_meta_retry_queue入队，数据库恢复后5分钟内自动重试	若上传直接失败，检查@Async配置是否生效
5. 并发上传压力	20个用户同时上传50MB文件	所有文件落盘成功，NC元数据100%写入，Tomcat线程数峰值≤15	若OOM，检查DiskFileItemFactory内存阈值是否调高

实测数据：在4核8G NC服务器上，该方案支撑200并发用户稳定上传，CPU占用率≤65%，磁盘IO等待时间<5ms。

5. 常见问题与排查技巧实录：12个真实故障的根因与解法

5.1 “文件上传后本地找不到，但NC元数据已写入”

现象：NC单据里显示附件已上传，但D:/nc_attachments目录下无对应文件，日志无ERROR。
根因：DiskFileItemFactory.setRepository()指定的临时目录空间不足，文件被写入系统临时目录（如C:\Users\Administrator\AppData\Local\Temp），而合并时tmpDir.listFiles()找不到分片。
解法：

1. 检查setRepository()路径是否有足够空间；
2. 在Servlet开头加日志：log.info("Temp dir: {}", factory.getRepository().getAbsolutePath());；
3. 统一将临时目录设为D:/nc_attachments/tmp，与业务目录同盘。

5.2 “上传成功但NC前端提示‘文件损坏’”

现象：文件落盘正常，但NC打开附件时报“无法读取文件内容”。
根因：NC前端下载附件时，调用的是NC内置的FileDownloadServlet，它从NC数据库BLOB读取，而我们的方案只写了元数据，没动BLOB字段。
解法：在NC表单的“附件下载”按钮事件里，重写下载逻辑：

// 替换NC默认下载 this.getElement().onclick = function() { var fileId = getNcMetadata("file_id"); // 从NC元数据表查file_id window.location.href = "http://nc-server:8081/file/download?file_id=" + fileId; };

然后在Servlet的/file/download接口里，根据file_id查file_path，用response.getOutputStream()流式输出文件。

5.3 “同一文件多次上传，本地生成多个副本”

现象：用户反复点上传，D:/nc_attachments下出现f_9a3b_20240615.pdf、f_9a3b_20240615_1.pdf等。
根因：未做文件去重，每次上传都生成新UUID。
解法：在保存前计算文件MD5，查NC元数据表是否已存在相同MD5：

String fileMd5 = DigestUtils.md5Hex(inputStream); String sql = "SELECT COUNT(*) FROM nc_attachment_meta WHERE file_md5 = ?"; int count = jt.queryForObject(sql, Integer.class, fileMd5); if (count > 0) { // 查出已有file_id，直接返回成功，不重复保存 String existId = jt.queryForObject("SELECT file_id FROM nc_attachment_meta WHERE file_md5 = ?", String.class, fileMd5); return Response.success(existId); }

5.4 “NC服务器重启后，上传功能失效”

现象：Tomcat重启后，/file/upload返回404。
根因：WAR包未设置为自动部署，或webapps目录下WAR包被NC更新脚本覆盖。
解法：

1. 将WAR包重命名为nc-file-service.war（避免NC识别为系统组件）；
2. 在conf/catalina.properties中添加：autoDeploy=true；
3. 检查webapps目录下是否有nc-file-service文件夹，若无则手动解压WAR。

5.5 “Linux服务器上文件路径分隔符错误”

现象：Windows开发正常，Linux部署后路径变成D:/nc_attachments/...（冒号非法）。
根因：硬编码了Windows路径分隔符。
解法：全部用File.separator：

String subPath = String.format("%s%s%s%s%s%s%s", basePath, File.separator, deptName, File.separator, datePart, File.separator, billType);

5.6 “上传进度条卡在99%不动”

现象：前端显示上传99%，但实际已完成，无回调。
根因：NC前端JS的fetch未处理response.bodyUsed，导致流未消费完，连接挂起。
解法：在fetch().then()里强制读取响应：

fetch(url, {method:"POST", body:formData}) .then(res => { if (res.ok) { return res.text(); // 必须消费响应体，否则连接不释放 } });

5.7 “NC日志里大量WARN：Unable to find a @SpringBootApplication”

现象：NC后台日志刷屏，但功能正常。
根因：Spring Boot的spring-boot-autoconfigure包被加载，试图扫描@SpringBootApplication。
解法：在pom.xml中排除：

<exclusion> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-autoconfigure</artifactId> </exclusion>

5.8 “文件上传后，NC单据审批流卡住”

现象：上传成功，但单据无法提交审批。
根因：NC审批流监听的是NC原生附件字段变更事件，而我们的方案未触发该事件。
解法：在异步写入元数据后，调用NC的EventPublisher发布自定义事件：

EventPublisher.publish(new AttachmentUploadedEvent(billId, fileId)); // NC审批流监听此事件，触发后续流程

5.9 “多台NC服务器集群下，文件路径不一致”

现象：A服务器上传的文件，B服务器无法下载。
根因：各服务器本地路径不同，未统一存储。
解法：将D:/nc_attachments改为SMB共享目录：

• Windows：\\file-server\nc_attachments；
• Linux：mount -t cifs //file-server/nc_attachments /opt/nc_attachments -o username=xxx,password=yyy；
• 代码中basePath配置为共享路径，所有NC节点读写同一位置。

5.10 “上传速度极慢，1MB文件耗时2分钟”

现象：网络正常，但上传缓慢。
根因：NC服务器防火墙开启“深度包检测”，对HTTP POST体进行病毒扫描。
解法：联系运维关闭该策略，或改用HTTPS（SSL卸载后不扫描）。

5.11 “NC用户登出后，仍能通过URL下载文件”

现象：用户登出NC，但用之前拿到的file_id还能下载。
根因：下载接口未校验NC session有效性。
解法：在/file/download接口开头加入：

String sessionId = request.getHeader("NC-SESSION-ID"); if (sessionId == null || !LoginContextFactory.isValid(sessionId)) { response.sendError(HttpServletResponse.SC_UNAUTHORIZED); return; }

5.12 “文件名含特殊字符，如‘