附件上传与下载问题排查指南

一、前置操作：补丁更新

在开始排查问题前，请先完成以下补丁更新步骤，排除已知问题干扰：

• 前端：优先安装最新前端补丁
• 后端：优先建议安装后端合集补丁，若无合集补丁通过以下链接检查是否存在相关补丁。若存在，请先安装对应补丁再进行后续问题排查。

补丁参考链接：http://help.primeton.com/productcs/patches/

---

二、上传失败类问题

上传失败诊断流程

1. 前端控制台Network查看请求
2. 检查文件大小限制配置
3. 验证上传地址是否正确
4. 查看后端应用日志
5. 检查网络和防火墙

2.1 上传时报错405 Not Allowed

现象：上传时报错405 Not Allowed
原因：上传地址配置错误（配置成了服务器相对路径）
解决方案：
修改其值为默认接口：/api/lowcode/models/attachments/actions/upload
• 或自定义后端API接口（需符合接口规范）

2.2 上传超过10MB文件报超限

现象：上传超过10MB文件报超限
原因：文件大小限制未调整
解决方案：
前端：修改组件文件大小限制
后端（application-afc.properties）：
afc.attachments.file-max-size=

三、文件预览类问题

3.1 点击文件无预览反应

现象：点击文件无预览反应
原因：文件格式不支持或预览服务未配置
解决方案：
检查项：
• 文件格式是否在支持范围内
• 首选项中OnlyOffice预览服务是否配置 注：默认支持格式：docx、xlsx、pdf、txt、jpg、png、jpeg

四、文件显示类问题

4.1 PC端需多次刷新图片才显示，移动端正常

现象：PC端需多次刷新图片才显示，移动端正常
原因：双节点+nginx轮询，请求打到不同节点
解决方案：
调整架构使附件请求路由到同一节点或配置nginx会话保持

4.2 移动端附件不显示/图片不回显

现象：移动端附件不显示/图片不回显
原因：配置或数据加载问题
检查项：
1:组件展示模式是否选择"图片"
2:主子表级联深度配置是否正确
3:子表修改后需在主表刷新子表格

4.3 视图中多附件有时显示有时不显示

现象：视图中多附件有时显示有时不显示
原因：数据或接口问题
检查项：
1:确认附件是否存在
2:检查接口参数传递及响应

4.4 多附件需要直接显示所有文件

现象：多附件需要直接显示所有文件
原因：配置问题
检查项：
附件组件高级-扩展属性添加：isViewVertical: true，并设置字段折行

五、文件下载类问题

问题现象	原因	解决方案/补丁
点击下载报错	权限、存储或接口问题	排查项： • 文件是否存在 • 存储模式（db/local）application-afc.properties中：afc.attachments.persistence-mode= • 浏览器控制台错误 • 后端日志
需要控制附件可见但不可下载	权限控制需求	方案： 1. 新增数据权限，关联附件实体 2. 开启流程权限 3. 为角色赋权 4. 或使用组件"权限码控制"
需要批量下载/打包下载	新需求	临时方案： • API单个下载：this.Api.downloadAttachment(attachmentId, fileName) • 自定义开发批量下载
需要隐藏下载按钮（表格模式）	界面需求	CSS隐藏：.attach-download-btn {display: none !important;}

---

六、文件删除类问题

问题现象	原因	解决方案/补丁
未保存表单，删除附件立即生效	产品设计：附件删除和表单保存是两个独立事务	当前版本如此，需用户注意操作流程
需要控制只能删除自己上传的附件	权限控制需求	"允许删除"事件中添加判断： if (this.Context.user.employeeId == file.createUser) { callback(true); } else { callback(false); }
本地存储模式删除接口未删除物理文件	存储配置或接口调用问题	排查： • 确认存储模式配置（application-afc.properties） • 验证删除接口调用是否正确 • 检查文件权限 删除接口：/api/lowcode/models/attachments/{attachmentId}